Border Width Tokens

Overview

Border width tokens define consistent border thickness values for UI elements throughout the design system. They establish visual weight, create boundaries, and emphasize interactive states while maintaining harmony across all components.

Architecture

Border width tokens are organized into a two-layer system where contextual width values are defined in the App group and then applied to specific components.

How it works:

The system provides semantic width scales:

1. Contextual border widths (borderWidth.context.*) define semantic thickness values
2. Component border widths (borderWidth.[component].*) assign specific widths to UI elements

Benefits:

• Consistent border weight across components
• Semantic naming clarifies thickness intent
• Easy to adjust border emphasis globally
• Clear visual hierarchy through standardized widths

Organization

Border width tokens are organized into two categories:

Contextual Border Width: Semantic width scales from none through 2xlarge.

Component Border Width: Specific border thickness for individual UI components.

This organization ensures both flexibility and consistency.

Contextual Border Width

Contextual border width tokens provide semantic thickness values for flexible application.

Usage by Context

Decorative borders: Use thin or small (0.5px) for subtle visual separation

Standard borders: Use medium (1px) for default component borders

Interactive states: Use large or xlarge (1.5-2px) for focus and active states

Indicators: Use 2xlarge (4px) for strong visual indicators

Component Border Width

Component-specific border width tokens assign thickness to individual UI elements.

Buttons & Interactive Elements

Form Inputs

Cards & Containers

Dropdown & Menus

Tables & Lists

Tabs & Navigation

Indicators & Assets

Interactive State Patterns

Border width often changes based on interaction state to provide visual feedback.

Standard State Pattern

Form Input Pattern

Inputs typically increase border width on focus:

{
  "borderWidth.form-input.inactive": "1px",  // Idle state
  "borderWidth.form-input.active": "2px"     // Focus state
}

This creates clear visual feedback without relying solely on color.

Usage Guidelines

Choosing the Right Token

For components: Use component-specific tokens (borderWidth.button.*, borderWidth.form-input.*)

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

For no border: Use borderWidth.context.none or borderWidth.context.zero

For emphasis: Use borderWidth.context.xlarge or borderWidth.context.2xlarge

Design Principles

Consistency: Use the same border width for similar component types

Visual Weight: Thicker borders create more visual emphasis

State Indication: Increase border width for focus/active states

Proportion: Ensure border width is proportional to element size

Accessibility

Focus Indicators: Use minimum 2px border width for focus states to meet WCAG requirements

Contrast: Ensure borders have sufficient contrast against backgrounds

State Communication: Don't rely solely on border width to convey state—combine with color changes

Touch Targets: Ensure borders don't reduce effective touch target size

Best Practices

Do:

• Use component tokens for specific UI elements
• Increase border width for focus/active states
• Use medium (1px) as the default for most borders
• Test border rendering on different screen densities
• Combine border width with color for state indication

Don't:

• Use arbitrary border widths—always reference tokens
• Use borders thicker than 4px except for special indicators
• Rely only on border width for critical state communication
• Forget that thick borders add to element dimensions
• Use sub-pixel borders (< 0.5px) which may not render consistently

Rendering Considerations

Sub-pixel rendering: 0.5px borders may render differently across browsers and devices

High-DPI displays: 1px borders appear thinner on retina screens

Border box sizing: Remember borders add to element dimensions unless using border-box

Mobile devices: Test border rendering on actual devices, not just emulators

Common Patterns

Standard borders: Use borderWidth.context.medium (1px)

Focus rings: Use borderWidth.context.xlarge (2px) for accessibility

Decorative divisions: Use borderWidth.context.thin (0.5px)

Status indicators: Use borderWidth.context.2xlarge (4px) for strong signals

No border: Use borderWidth.context.none explicitly rather than omitting border