Radius

Radius provides a shared scale for controlling the roundness of component and interface element corners.

The scale uses fixed values rather than fluid values. Corner radius generally represents the shape of an element rather than a relationship that needs to change with viewport size.

Radius scale

The radius scale contains nine named sizes:

--radius-3xs: 0.125rem;
--radius-2xs: 0.25rem;
--radius-xs: 0.375rem;
--radius-s: 0.5rem;
--radius-m: 0.75rem;
--radius-l: 1rem;
--radius-xl: 1.25rem;
--radius-2xl: 1.5rem;
--radius-3xl: 1.75rem;
--radius-4xl: 2rem;

The scale names describe relative size:

3xs < 2xs < xs < s < m < l < xl < 2xl < 3xl < 4xl

They do not prescribe a specific component or use.

For example, --radius-m is not automatically a card radius and --radius-xs is not automatically an input radius. Choose the value according to the shape required by the component and the surrounding interface.

Default radius

--border-radius provides the default radius used by components that do not require a more specific value.

--border-radius: var(--radius-s);

This keeps the existing --border-radius API while connecting it to the shared radius scale.

Components can continue to use:

.component {
  border-radius: var(--border-radius);
}

Use a specific --radius-* token when a component intentionally needs a different shape:

.card {
  border-radius: var(--radius-l);
}

.badge {
  border-radius: var(--radius-xs);
}

Choosing a radius

Choose the smallest radius that creates the intended shape.

Consider:

1. Size: Larger elements can usually support larger radii without appearing exaggerated.
2. Density: Compact interfaces generally benefit from smaller radii.
3. Hierarchy: Larger or more prominent surfaces may use a larger radius than controls contained within them.
4. Consistency: Related components should use the same radius unless their shape has a meaningful reason to differ.
5. Composition: The radius should fit the visual character of the surrounding interface.

Avoid assigning radius sizes according to component names. The scale should remain reusable across different interfaces.

Applying radius

Use radius tokens directly with border-radius:

.panel {
  border-radius: var(--radius-l);
}

.button {
  border-radius: var(--radius-s);
}

.tag {
  border-radius: var(--radius-xs);
}

Individual corners can use the same scale when the design requires an asymmetric shape:

.panel {
  border-start-start-radius: var(--radius-l);
  border-start-end-radius: var(--radius-l);
}

Prefer logical corner properties when the shape represents the start or end of an interface rather than a physical left or right side.

Nested surfaces

When rounded elements are nested, the inner radius may need to be smaller than the outer radius.

For example:

.card {
  padding: var(--space-2xs);
  border-radius: var(--radius-l);
}

.card-content {
  border-radius: var(--radius-m);
}

Choose the appropriate token from the scale rather than calculating a smaller radius from the outer value.

Avoid calculating radius values

Do not use calculations merely to move up or down the radius scale:

/* Avoid */
border-radius: calc(var(--border-radius) * 2);

Use the intended token directly:

border-radius: var(--radius-l);

The scale makes the intended shape explicit and allows individual values to change without depending on mathematical relationships between tokens.

Use calc() only when the calculation itself represents a real geometric requirement.

Avoid arbitrary values

Use the radius scale for recurring interface shapes:

/* Preferred */
.card {
  border-radius: var(--radius-l);
}

Avoid introducing an arbitrary value when an existing token provides the required shape:

/* Avoid without a specific reason */
.card {
  border-radius: 0.6875rem;
}

An arbitrary value can still be appropriate when:

• the shape is determined by an external asset
• a precise geometric relationship requires it
• no radius token creates the required result

Do not add another global radius token for a single local exception.

Adding or changing radius tokens

Change the radius scale when:

• recurring interface shapes cannot be represented by the existing values
• multiple components repeatedly require the same missing radius
• the overall visual direction of projects requires a different shape range

Before adding another token, confirm that the value represents a reusable step in the scale rather than a one-off component requirement.

When changing an existing radius value:

1. check components that use the token directly
2. check components using --border-radius
3. inspect nested rounded surfaces
4. verify compact and large components
5. check focus indicators and outlines around rounded controls

Do not rename radius tokens according to one component’s use. Their names should remain relative and reusable.

Accessibility

Corner radius is primarily visual, but it should not interfere with interaction or focus visibility.

Check that:

• focus indicators remain visible around rounded interactive elements
• overflow: hidden does not clip focus indicators or other required content
• rounded shapes do not reduce the effective interactive target size
• shape alone is not used to communicate state or meaning

Radius can support visual hierarchy and consistency, but it should not replace other cues required to understand or operate an interface.