Design Tokens: The DNA of a Design System

Pioneered by Jina Anne at Salesforce during the creation of the Lightning Design System, design tokens are the indivisible, platform-agnostic design decisions that power a design system.

Instead of hardcoding raw values like #0052CC or 16px across dozens of CSS stylesheets, iOS Swift structs, and Android XML files, teams store these decisions as named variables in a central, version-controlled repository:

{
  "color": {
    "brand": {
      "primary": { "value": "#0052cc" }
    }
  }
}

When a token value is updated, an automated build pipeline compiles the tokens into CSS variables, iOS Swift constants, and Android XML resources, synchronizing every platform in seconds.

Mature design systems organize tokens into a three-tier hierarchy to maximize flexibility and protect against cascading breaking changes:

1. Global Tokens (Tier 1 - Primitives): Context-agnostic raw values. They describe what something is (e.g., blue-500 = #2563eb, space-16 = 1rem). Never consumed directly in product UI.
2. Semantic Tokens (Tier 2 - Alias / Contextual): Purpose-driven tokens that describe how something is used (e.g., color-bg-interactive = {blue-500}, color-text-danger = {red-600}). This layer enables themes (Light/Dark mode) by swapping references.
3. Component Tokens (Tier 3 - Scoped): Deeply specific tokens scoped to a single component (e.g., button-primary-bg = {color-bg-interactive}, modal-card-radius = {radius-lg}).

Global tokens form the raw bedrock of your design system palette. They have no opinion on how, where, or why they are used. They simply enumerate the total allowable creative materials.

Examples of Global Tokens:

• Color Scales: color-palette-blue-50, ...blue-500, ...blue-900.
• Base Units: dimension-base = 8px.
• Font Families: font-family-sans = 'Inter', -apple-system, sans-serif.
• Transition Timing: duration-instant = 100ms, duration-standard = 250ms.

Rule of Global Tokens: Never let feature squads write background-color: var(--color-blue-500) directly in a product layout! If the brand changes from blue to purple, every line of feature code will have to be rewritten.

Semantic tokens give meaning to raw primitives. They answer the question: 'What role does this token play in the user interface?'

Common Semantic Categories include:

• Surfaces / Backgrounds: color-bg-canvas (main background), color-bg-surface (cards, containers), color-bg-sunken (wells, inputs).
• Text & Icons: color-text-primary (high contrast), color-text-secondary (body copy), color-text-muted (captions, disabled).
• Status / Feedback: color-feedback-success-bg, color-feedback-danger-text.
• Interaction States: color-interactive-default, color-interactive-hover, color-interactive-pressed.

In Light Mode: color-bg-canvas = #F9FAFB and color-text-primary = #111827. In Dark Mode: color-bg-canvas = #0F172A and color-text-primary = #F8FAFC.

Component tokens tie semantic decisions directly to individual components. They are the most granular tier in the system:

{
  "button": {
    "primary": {
      "bg": { "value": "{color.interactive.default}" },
      "bg-hover": { "value": "{color.interactive.hover}" },
      "radius": { "value": "{radius.md}" },
      "padding-x": { "value": "{space.16}" }
    }
  }
}

Why use Component Tokens? Imagine executive leadership decides: 'We want all buttons to have 24px pill rounding, but cards and dialogs must keep sharp 8px corners.' Without component tokens, changing {radius.md} would accidentally round cards, dialogs, and tables as well. Component tokens provide the isolation needed for targeted styling.

Inconsistent token names like primaryColor, color_bg_main, and theme-dark-btn create massive confusion. Leading systems (like Nathan Curtis's guidelines and Salesforce Lightning) use the Category-Type-Item (CTI) taxonomy:

{namespace}-{system}-{category}-{property}-{concept}-{variant}-{state}

Let's break down a real-world token: ux-sys-color-bg-surface-elevated-hover

• Namespace: ux (identifies the design system library)
• Category: color (color, space, size, font, time)
• Property: bg (background, border, text)
• Concept / Item: surface (card, canvas, button)
• Variant: elevated (subtle, primary, elevated)
• State: hover (default, hover, active, disabled)

Following a predictable formula makes tokens searchable, auto-completable in IDEs, and self-documenting.

How do tokens stored in JSON become usable code across different programming languages?

Teams use an open-source build tool like Style Dictionary (created by Amazon). Style Dictionary ingests a single directory of JSON/YAML tokens and transforms them into native artifacts:

• For Web: CSS custom properties (:root { --color-bg-surface: #ffffff; }) or SCSS/TypeScript constants.
• For iOS: Swift structs (Color.surface) and Objective-C headers.
• For Android: XML resource files (@color/surface) and Jetpack Compose objects.
• For Flutter: Dart classes (AppColors.surface).

By automating this pipeline in CI/CD, a single token change pushed to Git builds and publishes new versioned packages for Web, iOS, and Android simultaneously.

Not all design decisions are single scalar values like a hex code or a pixel measurement. Complex design choices consist of multiple coordinated properties, known as Composite Tokens:

1. Typography Tokens: A single heading style requires coordinated font-family, font-size, line-height, font-weight, and letter-spacing.
2. Elevation / Shadow Tokens: A realistic drop shadow requires coordinated x-offset, y-offset, blur-radius, spread-radius, and shadow-color (often combining ambient and directional shadows).
3. Border Tokens: Pairs border-width, border-style, and border-color.

Composite tokens prevent desynchronization: designers cannot accidentally pick the right font size while forgetting the corresponding line height.

Design tokens reference other tokens in a chain of dependency:

{button-primary-bg}  (Component Token)
       ↓ references
{color-interactive-primary}  (Semantic Token)
       ↓ references
{blue-600}  (Global Primitive Token)
       ↓ evaluates to
#1d4ed8  (Raw Hex Value)

Rules for Healthy Token Dependency Chains:

• Never Reference Upwards: A Global token must never reference a Semantic token. A Semantic token must never reference a Component token.
• Prevent Circular References: Token A must not reference Token B if Token B references Token A.
• Limit Chain Depth: Keep chains to a maximum depth of 3–4 levels. Overly nested references make debugging CSS variables difficult.

What happens when the design system team realizes a token name is confusing and needs to be renamed (e.g., renaming color-brand to color-interactive-primary)?

If the team simply deletes the old token in the next release, every consuming frontend app using that token will break.

The Safe Token Migration Pattern:

1. Introduce the New Token: Add color-interactive-primary to the system.
2. Alias the Old Token: Keep color-brand, but point its value to {color-interactive-primary}. In the documentation and compiler, mark color-brand as @deprecated.
3. Ship Automated Codemods: Provide an automated CLI script that searches consuming repositories and renames the token automatically.
4. Remove in Next Major Version: Only remove the deprecated alias in a subsequent SemVer MAJOR release after adoption metrics show zero usages.

Consider an enterprise holding company that owns three distinct online fashion brands: 'Luxe' (minimalist, monochrome, high contrast), 'Sport' (vibrant neon greens, energetic), and 'Casual' (warm earthy pastels).

Rather than building three separate codebases or three separate component libraries, the engineering team uses token theming:

• Shared Component Library: All three brands use the exact same accessible React components (<Button>, <Modal>, <Card>).
• Brand Token Sets: Each brand provides its own Tier 1 Primitives and Tier 2 Semantic token mappings in JSON.
• Runtime Swapping: The web application simply swaps the root CSS class (<html class="theme-luxe"> vs <html class="theme-sport">), instantly transforming typography, colors, borders, and shadows without changing a single line of component code.