Design Tokens

Decisions With Names

A design token is a design decision stored as a named value. Instead of writing #EA580C in 400 places, you write color.action.primary once and reference it everywhere.

Tokens are the bridge between design and code. The same token names live in Figma (as variables), in CSS (as custom properties), in iOS and Android code, and even in email templates. Change the value once, and every platform updates.

---

The Three Tiers of Tokens

Most mature systems organise tokens in layers.

1. Primitive (global) tokens

The raw palette of available values, named by what they are:

• orange.500 = #F97316
• gray.900 = #111827
• space.4 = 16px
• radius.md = 12px

Primitives are never used directly in components. They are the ingredients.

2. Semantic (alias) tokens

Tokens named by what they do, pointing at primitives:

• color.action.primary → orange.600
• color.text.default → gray.900
• color.feedback.error → red.600
• space.inset.card → space.4

This is the layer designers and engineers use every day. Semantic names make intent clear and make theming possible.

3. Component tokens (optional)

Tokens scoped to a single component:

• button.primary.background → color.action.primary
• button.radius → radius.md

Large systems like Atlassian and Salesforce use this tier so a component can be tweaked without affecting others.

---

Why the Extra Layer Matters: Theming

Dark mode shows the power of semantic tokens:

Components only reference semantic tokens, so switching theme means swapping which primitives the semantic tokens point to. No component changes at all.

The same approach powers white-labelling. A Nigerian banking-as-a-service platform can give each partner bank its own brand colours by swapping one set of primitives, while every screen stays identical in structure.

---

Token Categories

• Colour: brand, neutrals, feedback (success, warning, error, info), surfaces, borders
• Typography: font families, sizes (from your type scale), weights, line heights, letter spacing
• Spacing: usually an 8pt scale such as 4, 8, 12, 16, 24, 32, 48, 64
• Radius: none, sm, md, lg, pill
• Elevation / shadow: levels 0 to 5
• Motion: durations (fast 150ms, base 250ms) and easing curves
• Breakpoints and z-index

---

Naming Tokens Well

A common structure is category.property.variant.state, for example color.text.subtle or color.action.primary.hover.

• Be consistent: choose bg or background and stick to it.
• Avoid colour words in semantic names: color.action.primary, not color.orange.button.
• Keep names readable. Engineers will type them hundreds of times.

---

Tools

• Figma Variables support modes (light/dark, brand A/brand B).
• Tokens Studio (a Figma plugin) syncs tokens with GitHub.
• Style Dictionary (open source, by Amazon) turns one JSON token file into CSS, iOS, Android and Flutter outputs.
• The W3C Design Tokens Community Group is standardising a JSON format so tools can share tokens.

---

Try It in the Lab

Build a three-tier token system. Edit primitive colours, spacing and radius, map semantic tokens to primitives, and switch between light and dark modes. The preview shows a real screen updating, and you can export your tokens as JSON or CSS.