# Border Radii (/foundations/radii)



<div className="hd-radii">
  Use radius tokens to keep related controls and containers consistent. Start with the library component's radius, and use the shared scale when composing a new element.

  <RadiiExplorer />

  Select a token to see the same radius on a square, a field, and a button. The dimensions stay fixed; only the corners change. These are illustrative compositions, not overrides for library defaults.

  ## Radius scale [#radius-scale]

  These nine radius tokens are published in the current package. Rem-based values below assume a 16px root font size and a roundness factor of 1.

  <RadiusScale />

  <details className="hd-radius-reference">
    <summary>
      Radius values as a table
    </summary>

    | Token  | Base value | Pixels at a 16px root                                  |
    | ------ | ---------- | ------------------------------------------------------ |
    | `xs`   | 0.125rem   | 2px                                                    |
    | `sm`   | 0.25rem    | 4px                                                    |
    | `md`   | 0.375rem   | 6px                                                    |
    | `lg`   | 0.5rem     | 8px                                                    |
    | `xl`   | 0.75rem    | 12px                                                   |
    | `2xl`  | 1rem       | 16px                                                   |
    | `3xl`  | 1.5rem     | 24px                                                   |
    | `4xl`  | 2rem       | 32px                                                   |
    | `full` | 9999px     | Use for pills, or circles with equal width and height. |
  </details>

  Each specimen uses the same dimensions. The dashed box shows the space the element occupies before its corners are rounded.

  ```tsx
  import { css } from "@hashintel/ds-helpers/css";

  export const panel = css({
    borderRadius: "lg",
    backgroundColor: "bgSolid.surface",
    borderWidth: "1px",
    borderColor: "bd.subtle",
    padding: "4",
  });
  ```

  ## Shapes in context [#shapes-in-context]

  Choose the radius together with the element’s height, padding, and role. Keep the defaults when using a library component.

  <RadiusContexts />

  ## Roundness [#roundness]

  The `roundness` utility sets `--roundness-factor`, which is inherited by descendants. Each radius token is multiplied by that factor.

  <RadiusRoundness />

  <details className="hd-radius-reference">
    <summary>
      Roundness values as a table
    </summary>

    | Roundness | Factor | Result for `lg` at a 16px root |
    | --------- | ------ | ------------------------------ |
    | `none`    | 0      | 0px                            |
    | `sm`      | 0.75   | 6px                            |
    | `md`      | 1      | 8px                            |
    | `lg`      | 1.5    | 12px                           |
    | `xl`      | 2      | 16px                           |
  </details>

  Each panel uses `2xl` and its button uses `lg`. Only the roundness factor changes. The captions show the button’s resulting radius at a 16px root.

  `roundness: "none"` produces square corners, including for `full`. The preset starts at factor 1. Apply an override to a deliberate group of elements and check the result in each size variant.

  ```tsx
  import { css } from "@hashintel/ds-helpers/css";

  export const squarePanel = css({
    roundness: "none",
    borderRadius: "lg",
  });
  ```

  ## Nested elements [#nested-elements]

  Choose smaller radii for controls inside a larger rounded container when the padding calls for it. Check the visible gap between the two curves; radius alone does not guarantee that they align.

  <RadiusNesting />

  For these simple concentric shapes, an outer radius of 32px and a 16px inset leave an inner radius of 16px. Account for borders as part of the inset, and clamp a calculated inner radius to zero if the inset exceeds the outer radius.

  ## Clipping and focus [#clipping-and-focus]

  <RadiusClipping />

  Check focus rings and content clipping separately. Rounded corners can crop an image, while an overflow rule on the same container can also hide focus indicators or overlays. Preserve the behavior of [Popover](/components/popover), [Menu](/components/menu), and other floating components.

  Use the [token playground](/foundations/design-system#token-playground) to compare values and [Spacing](/foundations/spacing) to choose the gaps around them.
</div>