What is Design Tokens?

What is a Design Token?

A design token is a named, platform-agnostic key-value pair that captures a single design decision—like color.brand.primary: #1A73E8 or spacing.md: 16px. The concept was introduced by Salesforce's Lightning Design System around 2014 and formalized by the W3C Design Tokens Community Group, whose draft spec (DTCG format) reached second editor's draft in 2023. Tokens sit between raw values and component code: designers define them in tools like Figma (via Variables, shipped in 2023), and build tools like Style Dictionary or Tokens Studio translate them into CSS custom properties, Swift constants, XML resources, or any other platform output. The result is a single source of truth that keeps a button's border-radius identical whether it renders in a React web app, an iOS native view, or an Android Compose layout. We've shipped token-driven design systems on 50+ projects, and the pattern consistently cuts design-to-dev handoff friction by eliminating magic numbers.

How it works

At its core, a design token system has three layers:

1. Token definition — A JSON or YAML file stores tokens in a nested structure:

{
  "color": {
    "brand": {
      "primary": { "$value": "#1A73E8", "$type": "color" },
      "secondary": { "$value": "#E8710A", "$type": "color" }
    }
  },
  "spacing": {
    "sm": { "$value": "8px", "$type": "dimension" },
    "md": { "$value": "16px", "$type": "dimension" }
  }
}

The $value and $type keys follow the DTCG spec format.

2. Transformation — A build tool reads the definition and outputs platform-specific files. Style Dictionary (v4, released 2024) is the most common. It takes token JSON and generates:

   • CSS: --color-brand-primary: #1A73E8;
   • iOS Swift: static let colorBrandPrimary = UIColor(hex: "#1A73E8")
   • Android: <color name="color_brand_primary">#1A73E8</color>

3. Consumption — Engineers reference tokens instead of hardcoded values. In CSS, that means background-color: var(--color-brand-primary). Components never contain raw hex codes or pixel values.

Tokens are typically organized in tiers: global tokens (raw palette), alias/semantic tokens (e.g., color.action.primary referencing the global token), and component tokens (e.g., button.background.default referencing the alias). This layering is what makes theming—like dark mode—trivial: you swap alias mappings, and every component updates.

When to use it

Design tokens make sense when your project crosses at least one of these thresholds:

Use tokens when:

• You maintain a design system used by more than one team or product
• You ship to multiple platforms (web + native mobile)
• You need theming support: dark mode, white-labeling, or brand variants
• Your Figma source of truth and codebase keep drifting apart
• You're building with a component library (React, Vue, Svelte) and want predictable styling

Skip tokens when:

• It's a solo-dev project with a single CSS file and no plans to scale
• You're prototyping something throwaway—tokens add a build step
• Your team hasn't agreed on design foundations yet; tokens codify decisions, they don't make them for you

Our preferred stack is Figma Variables → Tokens Studio plugin → Style Dictionary v4 → CSS custom properties (for web) with Tailwind config generated from the same source.

Design Tokens vs alternatives

CSS custom properties are an output format for tokens, not a replacement. Figma Variables are a design-side representation. Tokens are the bridge that keeps both sides in sync. The DTCG spec is specifically designed to be the interchange format between tools.

Real-world example

We built a multi-brand e-commerce platform where three retail brands shared a single Next.js codebase. Each brand had its own color palette, type scale, and spacing rhythm. We defined ~280 design tokens in DTCG-format JSON, organized into global and alias tiers. Style Dictionary v4 generated three CSS files—one per brand—totaling about 4 KB each. At runtime, the correct file loaded based on the hostname, swapping every color, font-size, and spacing value across 60+ shared React components. Adding a fourth brand later took one designer two days in Figma and one engineer half a day to wire up the new token set. Zero component code changed.