By the end of this lesson you can
- Explain design tokens and their tiers.
- Write token names that are clear and scalable.
- Understand how tokens flow from design to code.
The idea
Design tokens are named values that store design decisions: colours, spacing, type sizes, radius, shadows, durations. They are the shared source of truth between design tools and code.
Tiers
- Primitive (global) tokens: raw values.
blue-600: #1D4ED8,space-4: 16px. - Semantic (alias) tokens: purpose.
color-action-primary: {blue-600},space-inset-md: {space-4}. - Component tokens (optional): specific uses.
button-primary-background: {color-action-primary}.
Naming
A common pattern is category, then property, then variant, then state: color-text-secondary, color-border-input-focus. Names should describe purpose, be predictable and avoid describing appearance in semantic tokens.
From design to code
Tokens are often stored as JSON, edited in a design tool or a repository, and transformed by a build tool into CSS variables, iOS and Android values. One change updates every platform.
Why it matters in real projects
Tokens make consistency enforceable across design and every platform. They enable theming, rebrands and accessibility fixes in one place. Designers who understand tokens collaborate much more effectively with engineers and can work on any modern design system.
A realistic example
A retailer runs a website, an iOS app and an Android app. Their "primary green" differs slightly on each because values were copied by hand.
The team defines tokens in JSON: primitives for the green scale and semantics such as color-action-primary. A build step outputs CSS variables, Swift and Kotlin constants. When accessibility testing shows the green fails contrast on white, they change one primitive mapping and all three platforms update in the next release.
Step by step
Collect raw values
List the colours, spacing, radius and type values in use.
Define primitives
Name the scales, such as grey-100 to grey-900.
Define semantics
Create purpose-based tokens pointing to primitives.
Agree naming
Write a naming pattern with developers.
Apply in design
Use variables that mirror the tokens.
Trace a change
Change one primitive and follow it through to all uses.
Common mistakes
Mistake Semantic tokens named by colour ("color-blue-button").
Instead Name by purpose ("color-action-primary").
Mistake Too many component tokens too early.
Instead Start with primitives and semantics.
Mistake Design and code tokens drifting apart.
Instead Keep one source of truth and sync it.
Check your understanding
Choose an answer, then check it. There is an explanation either way.
Practice exercise
Exercise · about 1 h
Token set
Write a small token set for a product.
Steps
- Define primitive colour, spacing and radius tokens.
- Define 10 to 15 semantic tokens.
- Write them in a simple JSON structure.
- Map three components to the semantic tokens.
Deliverable
A token JSON file and a mapping table for three components.
Self-assessment
Tick each item when it is true of your exercise. Be honest; this is for you.
4 items
Summary
- Design tokens are named design decisions.
- Use primitive, semantic and optional component tiers.
- Name by purpose with a predictable pattern.
- Tokens flow from one source to every platform.
Further reading
Third-party sources, chosen for reliability. They open in a new tab.
- Design Tokens Community Group (opens in a new tab)W3C Community Group
- Design tokens (opens in a new tab)Material Design 3
Your notes
Marking complete updates your course and roadmap progress.