Skip to content
NewTemplates & toolkits are on the way — join the waitlist
Hecham Gazhi

Design Systems · Lesson 03 / 13

Design tokens

Everything about design tokens: what they are, token types, the three tiers (primitive, semantic, component), naming conventions, theming, the W3C token format and how tokens flow from Figma to code.

4 min read · 5 quiz questions

What is a design token?

A design token is a named value that stores a design decision: color-action-primary = #146ef5, space-4 = 16px, radius-md = 8px. Instead of hard-coding values in hundreds of places, designers and developers reference the token's name.

Tokens are the bridge between design and code. The same names exist in Figma (as variables) and in code (as CSS variables, iOS/Android constants, JSON). When a value changes, it changes everywhere that uses the token.

Example · Why tokens save time

A company changes its brand blue. Without tokens, someone searches the codebase for #146ef5 — and misses the places that use #146EF5, rgb(20,110,245) or a slightly different blue someone picked by eye.

With tokens, the team updates one value — color.blue.500 — and every button, link and focus ring updates, in design and in code.

Types of tokens

TypeExamples
ColourBrand, neutral, text, surface, border, status colours
TypographyFont family, size, weight, line height, letter spacing — often combined into composite text styles
Spacing4, 8, 12, 16, 24, 32…
SizingIcon sizes, control heights, avatar sizes
Radiusnone, sm, md, lg, full
BorderWidths and styles
Elevation / shadowshadow-1, shadow-2, shadow-3
MotionDurations and easing curves
Opacity, z-index, breakpointsOverlay opacity, layer order, screen widths

The three tiers

Most mature systems organise tokens in layers, where each tier references the one below:

1. Primitive (global, core) tokens

The raw palette of available values, with names that describe the value itself: blue-500, gray-100, space-4, font-size-16. They say nothing about how a value is used. Components should not use them directly.

2. Semantic (alias) tokens

Names that describe purpose: color-text-primary, color-surface, color-action-primary, color-border-error, space-inset-md. They point to primitives. This is the layer most components use, and the layer you remap for themes.

3. Component tokens (optional)

Values specific to one component: button-primary-background, input-border-radius. They point to semantic tokens and give fine-grained control. Many teams skip this tier until they need it, because it multiplies the number of tokens.

Live preview

1. Primitive

blue-500

#146ef5

2. Semantic

color-action-primary

→ blue-500

3. Component

button-primary-bg

→ color-action-primary

Examplecss
:root {
  /* 1. primitives */
  --blue-500: #146ef5;
  --blue-600: #0d5ad6;
  --gray-0:   #ffffff;
  --gray-900: #0f0f0d;

  /* 2. semantic */
  --color-action-primary:       var(--blue-500);
  --color-action-primary-hover: var(--blue-600);
  --color-surface:              var(--gray-0);
  --color-text-primary:         var(--gray-900);

  /* 3. component */
  --button-primary-bg:       var(--color-action-primary);
  --button-primary-bg-hover: var(--color-action-primary-hover);
}

.button-primary { background: var(--button-primary-bg); }
.button-primary:hover { background: var(--button-primary-bg-hover); }

Naming tokens

Names are the API of your design system. A common structure goes from general to specific:

Do

  • Use a consistent order and separator (dots or dashes).
  • Name semantic tokens by purpose: text, surface, border, action.
  • Use predictable scales: sm/md/lg or 100–900.
  • Document every token with its value and usage.

Don't

  • Name semantic tokens by colour: color-blue-button breaks when the brand changes to green.
  • Mix naming styles: textPrimary, text-secondary, TEXT_MUTED.
  • Create a token for every one-off value.
  • Let components reference primitives directly.
Exampletext
[category]-[concept/property]-[variant]-[state]

color-text-primary
color-text-secondary
color-action-primary-hover
color-border-error
space-inset-md
radius-control
motion-duration-fast

Theming with tokens

Because components use semantic tokens, you can create themes — light, dark, high contrast, or different brands — by remapping only the semantic layer.

Semantic tokenLight themeDark theme
color-surfacegray-0 (#FFFFFF)gray-950 (#121212)
color-text-primarygray-900gray-50
color-action-primaryblue-500blue-300
color-bordergray-200gray-800

The same idea supports multi-brand systems: one set of components, several brand themes that map semantic tokens to different primitives.

Token formats and the pipeline

Tokens are usually stored in JSON. The W3C Design Tokens Community Group has published a specification for a shared format, using keys like $value and $type, with references written in curly braces:

  1. 1Designers manage tokens as variables in Figma (or with a plugin like Tokens Studio).
  2. 2Tokens are exported or synced as JSON to a Git repository.
  3. 3A build tool such as Style Dictionary transforms the JSON into platform outputs: CSS variables, SCSS, iOS Swift, Android XML/Compose, JavaScript.
  4. 4Apps import those outputs. A change to the JSON updates every platform.
Examplejson
{
  "color": {
    "blue": {
      "500": { "$type": "color", "$value": "#146ef5" }
    },
    "action": {
      "primary": { "$type": "color", "$value": "{color.blue.500}" }
    }
  },
  "space": {
    "4": { "$type": "dimension", "$value": "16px" }
  }
}

Common mistake: Keeping tokens in two places that are updated by hand — one in Figma, one in code. They will drift apart. Pick one source of truth and automate the rest.

Key takeaways

  • Tokens are named design values shared by design tools and code.
  • Use tiers: primitives (raw values) → semantic (purpose) → component (optional).
  • Components should use semantic tokens; that's what makes theming possible.
  • Name tokens consistently, by purpose, from general to specific.
  • Store tokens in one source of truth (often W3C-format JSON) and generate platform outputs with tools like Style Dictionary.

Exercise

Build a token set

  1. Define primitives: a 9-step blue scale, a 10-step grey scale and a spacing scale.
  2. Define 10 semantic colour tokens (text, surface, border, action, error…).
  3. Map them for a light and a dark theme.
  4. Create them as Figma variables with Light and Dark modes.
  5. Write the same tokens as CSS variables and style one button with them.

Test yourself

Design tokens quiz

5 questions. Score 70% or more to complete the lesson.

  1. 1.What is a design token?
  2. 2.Which token is semantic?
  3. 3.Why should components reference semantic tokens rather than primitives?
  4. 4.In W3C token JSON, what does {color.blue.500} mean?
  5. 5.What does a tool like Style Dictionary do?