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
| Type | Examples |
|---|---|
| Colour | Brand, neutral, text, surface, border, status colours |
| Typography | Font family, size, weight, line height, letter spacing — often combined into composite text styles |
| Spacing | 4, 8, 12, 16, 24, 32… |
| Sizing | Icon sizes, control heights, avatar sizes |
| Radius | none, sm, md, lg, full |
| Border | Widths and styles |
| Elevation / shadow | shadow-1, shadow-2, shadow-3 |
| Motion | Durations and easing curves |
| Opacity, z-index, breakpoints | Overlay 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
: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-buttonbreaks 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.
[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-fastTheming 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 token | Light theme | Dark theme |
|---|---|---|
| color-surface | gray-0 (#FFFFFF) | gray-950 (#121212) |
| color-text-primary | gray-900 | gray-50 |
| color-action-primary | blue-500 | blue-300 |
| color-border | gray-200 | gray-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:
- 1Designers manage tokens as variables in Figma (or with a plugin like Tokens Studio).
- 2Tokens are exported or synced as JSON to a Git repository.
- 3A build tool such as Style Dictionary transforms the JSON into platform outputs: CSS variables, SCSS, iOS Swift, Android XML/Compose, JavaScript.
- 4Apps import those outputs. A change to the JSON updates every platform.
{
"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
- Define primitives: a 9-step blue scale, a 10-step grey scale and a spacing scale.
- Define 10 semantic colour tokens (text, surface, border, action, error…).
- Map them for a light and a dark theme.
- Create them as Figma variables with Light and Dark modes.
- 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.
