Border Radius Tokens

Border radius tokens establish consistent corner rounding across design system components. While seemingly simple, radius consistency significantly impacts visual cohesion. Without tokenized border radius values, components develop inconsistent rounding that fragments the interface’s visual language. Proper border radius tokenization enables both consistency and systematic brand expression.

What Are Border Radius Tokens

Border radius tokens are design tokens that define corner rounding values. These tokens specify the radius measurement that determines how rounded element corners appear, from sharp right angles to fully circular edges.

Border radius is a key brand differentiator. Some brands favor sharp corners for a technical, precise feel. Others prefer generous rounding for warmth and approachability. Tokens capture these brand decisions and ensure consistent application.

How Border Radius Tokens Work

Border radius token systems typically define a scale of values:

{
  "border": {
    "radius": {
      "none": { "value": "0" },
      "sm": { "value": "2px" },
      "md": { "value": "4px" },
      "lg": { "value": "8px" },
      "xl": { "value": "12px" },
      "2xl": { "value": "16px" },
      "full": { "value": "9999px" }
    }
  }
}

The full value (often 9999px) creates pill shapes on elements where width exceeds height, and circles on squares.

Semantic radius tokens map scale values to purposes:

{
  "border": {
    "radius": {
      "button": { "value": "{border.radius.md}" },
      "card": { "value": "{border.radius.lg}" },
      "input": { "value": "{border.radius.sm}" },
      "avatar": { "value": "{border.radius.full}" },
      "badge": { "value": "{border.radius.full}" }
    }
  }
}

CSS application:

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

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

Per-corner tokens can be defined when different corners need different radii:

.notification {
  border-radius: var(--border-radius-lg) var(--border-radius-lg) 0 0;
}

Key Considerations

• Scale values should provide meaningful visual distinctions
• Semantic tokens prevent scale values from being used inconsistently
• Per-corner radius may be needed for specific components
• Nested elements may need radius adjustments to maintain visual alignment
• Very large radius on small elements can produce unexpected shapes
• Platform rendering differences affect radius appearance at small values
• Brand expression often lives in radius decisions
• Radius interacts with border width for visual effect

Common Questions

How should nested radii be calculated?

When elements nest inside rounded parents, inner radii need adjustment to maintain parallel curves.

The principle: inner radius equals outer radius minus the gap (padding/border) between them.

Inner radius = Outer radius - Gap

For a card with 16px radius and 12px padding containing an image:

.card {
  border-radius: 16px;
  padding: 12px;
}

.card-image {
  border-radius: 4px; /* 16 - 12 = 4 */
}

Token expressions can capture this relationship:

{
  "border": {
    "radius": {
      "card": { "value": "16px" },
      "cardInner": { "value": "4px" }  // Calculated: card - card-padding
    }
  }
}

CSS calc can compute dynamic values:

.card-inner {
  border-radius: calc(var(--border-radius-card) - var(--spacing-card-padding));
}

When the gap exceeds the outer radius, inner elements should use zero or minimal radius rather than negative values.

How should radius scales be designed?

Radius scales should provide enough options for different contexts without excessive granularity.

Linear scales (2, 4, 6, 8) provide fine control but may offer too many similar options.

Exponential scales (2, 4, 8, 16) provide clearer visual distinctions but larger jumps at higher values.

Practical scales often blend approaches:

none: 0      (sharp corners)
sm: 2px     (subtle rounding)
md: 4px     (moderate rounding)
lg: 8px     (noticeable rounding)
xl: 12px    (prominent rounding)
2xl: 16px   (very round)
full: 9999px (pill/circle)

The scale should suit the brand’s aesthetic range. A sharp, technical brand might use smaller maximum values. A friendly, rounded brand might start at larger minimums.

Evaluate scales by applying them to actual components. Do the distinctions matter in practice? Are any values redundant?

Should border radius vary by component size?

Larger components may warrant larger radius values for proportional appearance. A small tag and a large card using the same radius can look visually inconsistent.

Size-relative radius approaches include:

Explicit size variants define radius per size:

{
  "border": {
    "radius": {
      "button": {
        "sm": { "value": "2px" },
        "md": { "value": "4px" },
        "lg": { "value": "6px" }
      }
    }
  }
}

Proportional values use percentages or viewport-relative units:

.card {
  border-radius: 2%; /* Scales with card size */
}

This approach requires careful testing as percentage radius can produce unexpected results.

Semantic consistency may override proportionality. If all buttons should share the same radius regardless of size, that consistency might be more valuable than proportional variation.

The decision depends on design intent. Some systems maintain fixed radius across sizes for consistency. Others vary radius for proportion. Both approaches are valid when applied deliberately.

Summary

Border radius tokens establish consistent corner rounding that significantly impacts visual cohesion. Scale tokens provide a vocabulary of radius values, while semantic tokens map them to specific purposes. Nested element radii require calculation to maintain parallel curves. Radius scales should provide meaningful visual distinctions without excessive options. Whether radius varies with component size depends on design intent, with both fixed and proportional approaches being valid choices.