Border Radius Tokens

Overview

Border radius tokens define consistent corner rounding values for UI elements throughout the design system. They contribute to the visual style and brand personality while ensuring harmonious rounded corners across all components.

Architecture

Border radius tokens use a two-layer architecture where base radius values are defined in the Brand group and then applied through contextual and component-specific tokens in the App group.

How it works:

The system provides brand flexibility with application consistency:

1. Base border radius (borderRadius.base.*) defines brand-specific rounding values
2. Contextual border radius (borderRadius.context.*) references base values with semantic names
3. Component border radius (borderRadius.[component].*) assigns specific rounding to UI elements

Benefits:

• Adjust brand's corner style globally by changing base tokens
• Consistent rounding across similar components
• Semantic naming clarifies rounding intent
• Easy to switch between sharp, rounded, or highly rounded styles

Organization

Border radius tokens are organized into three categories:

Base Border Radius (Brand group): Brand-specific rounding values that define the visual style.

Contextual Border Radius (App group): Semantic radius scales referencing base values.

Component Border Radius (App group): Specific rounding values for individual UI components.

This organization allows brand customization while maintaining consistent application.

Base Border Radius

Base border radius tokens are defined in the Brand group and establish the brand's corner rounding style.

Brand Customization

Brands can override these values to achieve different visual styles:

Sharp Style (Minimal rounding):

{
  "borderRadius.base.small": "2px",
  "borderRadius.base.medium": "4px",
  "borderRadius.base.large": "6px"
}

Rounded Style (Moderate rounding):

{
  "borderRadius.base.small": "6px",
  "borderRadius.base.medium": "12px",
  "borderRadius.base.large": "16px"
}

Highly Rounded Style (Soft rounding):

{
  "borderRadius.base.small": "8px",
  "borderRadius.base.medium": "16px",
  "borderRadius.base.large": "24px"
}

Contextual Border Radius

Contextual border radius tokens reference base values and provide semantic naming.

Precise Rounding Values

For elements that need exact rounding regardless of brand:

These tokens ensure elements with specific heights/widths can have perfectly circular corners.

Component Border Radius

Component-specific border radius tokens assign rounding to individual UI elements.

Buttons & Interactive Elements

Badges & Chips

Form Inputs

Cards & Containers

Dropdown & Menus

Tables & Data

Pagination

Indicators

Usage Guidelines

Choosing the Right Token

For components: Use component-specific tokens (borderRadius.button.*, borderRadius.card.*)

For pills/circles: Use precise round tokens (borderRadius.context.round-24)

For custom elements: Use contextual tokens (borderRadius.context.medium)

For sharp corners: Use borderRadius.context.zero

Design Principles

Consistency: Use the same rounding style for similar component types

Hierarchy: Larger elements can have more prominent rounding

Brand Alignment: Border radius is a key brand characteristic—choose wisely

Touch Targets: Ensure rounded buttons maintain minimum touch target size

Common Patterns

Standard Components: Use borderRadius.context.medium for most UI elements

Pills & Badges: Use precise round tokens for perfect circles

Cards: Use borderRadius.context.medium or borderRadius.context.large

Small Elements: Use borderRadius.context.small for compact components

Accessibility

• Border radius doesn't directly impact accessibility
• Ensure rounded corners don't reduce touch target size
• Maintain sufficient contrast at corners (particularly with borders)
• Test that rounded corners render clearly on all devices

Best Practices

Do:

• Use component tokens for specific UI elements
• Use contextual tokens for custom components
• Maintain consistency across similar elements
• Test rounding across different screen sizes
• Use brand base tokens for global style changes

Don't:

• Use arbitrary radius values—always reference tokens
• Mix different rounding styles inconsistently
• Use excessive rounding that distorts content
• Forget that border radius affects visual weight
• Apply rounding that interferes with legibility

Brand Customization Example

To create a new brand with softer rounding:

// brand-example.json
{
  "borderRadius": {
    "base": {
      "xsmall": {
        "$type": "borderRadius",
        "$value": "{dimension.base.4}"
      },
      "small": {
        "$type": "borderRadius",
        "$value": "{dimension.base.8}"
      },
      "medium": {
        "$type": "borderRadius",
        "$value": "{dimension.base.16}"
      },
      "large": {
        "$type": "borderRadius",
        "$value": "{dimension.base.20}"
      }
    }
  }
}

All components automatically adopt the new rounding style without individual updates.