What Are Design Tokens?

Design tokens are named, platform-agnostic design decisions — the atomic values that define the look and feel of your UI. Instead of a designer writing "use the purple color" and a developer hardcoding #7C3AED, both reference the same token: color.brand.primary.

Tokens store values for:

  • Colors (background, text, border, interactive)
  • Typography (font families, sizes, weights, line heights)
  • Spacing (margins, paddings, gaps)
  • Border radii and shadows
  • Motion (durations, easing curves)
  • Z-index levels

Why Tokens Matter at Scale

Without tokens, design decisions are scattered across Figma files, Sass variables, inline styles, and component props. When your brand color changes, you're hunting through dozens of files. Tokens centralize that decision.

With tokens properly implemented:

  • A single token value change propagates everywhere — code and design.
  • Theming (dark mode, white-label products) becomes a token-swap operation.
  • Designers and developers share a common vocabulary.
  • Audits and accessibility checks are simpler with named, traceable values.

The Three-Tier Token Architecture

A robust token system typically uses three layers:

  1. Global (Primitive) Tokens — Raw values with no semantic meaning.
    color.purple.500: #7C3AED
  2. Semantic (Alias) Tokens — Named by purpose, referencing global tokens.
    color.action.primary: {color.purple.500}
  3. Component Tokens — Scoped to a specific component.
    button.background.default: {color.action.primary}

This layering means you can retheme your entire product by changing a handful of semantic tokens, without touching any component code.

Defining Tokens in JSON

The most common format for storing tokens is JSON, popularized by tools like Style Dictionary:

{
  "color": {
    "brand": {
      "primary": { "value": "#7C3AED", "type": "color" },
      "secondary": { "value": "#F0ABFC", "type": "color" }
    },
    "text": {
      "base": { "value": "#1E1B2E", "type": "color" },
      "muted": { "value": "#6B7280", "type": "color" }
    }
  },
  "spacing": {
    "sm": { "value": "0.5rem", "type": "dimension" },
    "md": { "value": "1rem", "type": "dimension" },
    "lg": { "value": "2rem", "type": "dimension" }
  }
}

Transforming Tokens into CSS Variables

Tools like Style Dictionary or Token Pipeline compile your token JSON into platform-specific outputs — CSS custom properties, iOS Swift constants, Android XML, and more. A single JSON source, many outputs:

/* Generated CSS output */
:root {
  --color-brand-primary: #7C3AED;
  --color-brand-secondary: #F0ABFC;
  --color-text-base: #1E1B2E;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
}

Tokens in Design Tools

Figma supports tokens through plugins like Tokens Studio for Figma. This lets designers apply and manage tokens directly on design components, ensuring pixel-perfect alignment with what developers actually ship. When a token changes in your JSON source, both the Figma designs and the codebase update in sync.

Getting Started

  1. Audit your existing UI for repeated values (colors, spacings, type sizes).
  2. Define primitive tokens for all raw values.
  3. Map semantic tokens that reference your primitives.
  4. Use a build tool (Style Dictionary) to generate CSS output.
  5. Replace hardcoded values in components with token references.
  6. Sync with your design team using a shared token format.

Conclusion

Design tokens aren't just a developer convention — they're a shared language between design and engineering. Investing in a token architecture early pays off enormously as your product, team, and component library grow. Start small, stay consistent, and let tokens do the heavy lifting.