Design Systems · Step 2 · 6 min read
Token tiers
Primitive tokens say what a value is, semantic tokens say what it's for, component tokens say where it goes. Why most systems use these three tiers, how aliases link them, how Material, Carbon and Spectrum name the same idea, and how many tiers a system really needs.
A good token system separates what a value is from what it's for.
#1F5FAEis a blue. "The colour of the main action" is a decision. If your buttons point straight at the blue, you can't change one without the other. Put a named decision in between and you can: dark mode, a rebrand, a second brand, all by moving one link. That in-between layer is the whole trick of token tiers.
What you'll be able to do after reading:
- Explain the three tiers: primitive, semantic, component
- Say why components should never read primitives directly
- Recognise the same tiers in Material, Carbon and Spectrum
- Decide how many tiers your system needs
1. Three tiers, one chain
color.blue.600 #1F5FAEcolor.action.primary button.primary.background color.blue.400 #5B95DBcolor.action.primary , dark modebutton.primary.background , unchangedcolor.coral.600 #C2412Dcolor.feedback.danger badge.danger.text space.5 24 pxNo semantic step neededbutton.primary.padding-inline space.4 16 pxspace.inset.md Used by cards, dialogs and panels directlyradius.md 8 pxradius.control Every control reads it, no component token- Primitive tokens hold raw values:
color.blue.600 = #1F5FAE,space.4 = 16px,radius.md = 8px. They describe the palette and the scales. They say nothing about use. - Semantic tokens name a purpose and point at a primitive:
color.action.primary → color.blue.600,space.inset.md → space.4. This is the layer designers mostly work with. - Component tokens name a slot in one component and point at a semantic (or, sometimes, a primitive):
button.primary.background → color.action.primary.
The link from one token to another is called an alias, or a reference. The W3C Design Tokens Community Group format writes it with curly braces: "$value": "{color.blue.600}" (DTCG, Format Module 2025.10). Figma calls it the same thing: a variable that references another "is also called aliasing" (Figma Help, Overview of variables, collections, and modes).
2. Why the middle tier matters
Look at the second row of the figure. In dark mode, color.action.primary points to color.blue.400 instead of color.blue.600. The button's own token didn't move. Neither did the button's code. Every component that uses color.action.primary changes at once.
Without the semantic tier you'd have two bad options: give the button two background tokens and teach every component about dark mode, or change color.blue.600 itself to a lighter blue in dark mode, which makes the name a lie.
The middle tier is also where meaning lives. "Danger" can be coral today and red after a rebrand. Code that says color.feedback.danger stays right; code that says color.coral.600 becomes wrong.
3. The same idea in public systems
The tiers have different names, but the shape is the same:
| System | Tier 1 | Tier 2 | Tier 3 |
|---|---|---|---|
| Adobe Spectrum | Primitive (aka global), e.g. blue-800 |
Semantic, e.g. accent-background-color-default |
Component-specific, e.g. tooltip-maximum-width |
| Material Design 3 | Reference, e.g. --md-ref-typeface-brand |
System, e.g. --md-sys-color-primary |
Component, e.g. --md-filled-button-container-shape |
| IBM Carbon | Palette, e.g. $blue-60 |
Theme tokens, e.g. $interactive, $text-primary |
Component tokens, e.g. $button-primary |
| Harbour | color.blue.600 |
color.action.primary |
button.primary.background |
Sources: Spectrum, Design tokens, Material Web, Theming ("each component token maps to a system token, which has a concrete reference value"), Carbon, Themes (in the White theme, $interactive "calls the IBM Design Language color palette token $blue-60"), Carbon, Color tokens (component tokens "should never be used for anything other than their own component").
Carbon puts the rule well: theme tokens "are universal and never change across themes"; only their values do.
4. How many tiers?
Three is common, not compulsory. Spectrum's own definitions leave room: semantic tokens "define how design decisions are used throughout the system", and component tokens are for decisions "that apply to a specific component".
Use this test for a component token: will this component ever need a different value from the semantic token it points to? If the button background will always be color.action.primary, a component token is cheap insurance. If a card's padding is always space.inset.md and nobody will ever theme it separately, skip it, as the figure does for cards and for radius.control.
And the reverse: button.primary.padding-inline points straight to space.5, because there's no shared purpose a semantic token would add. Not every row needs every tier.
What you should not skip: components never read primitives directly for colour. That's the link that makes modes and brands possible.
5. Common mistakes
- Components reading
color.blue.600directly, so dark mode needs code changes. - Semantic names that are really primitive names in disguise:
color.blue-button. - A component token for every property of every component, thousands of tokens nobody can navigate.
- Changing a primitive's value to fix one use, and breaking all the others.
- Aliases that point the wrong way: a primitive pointing at a semantic.
6. Vocabulary
| Term | Meaning |
|---|---|
| Primitive token | A raw value with a neutral name: color.blue.600 = #1F5FAE |
| Semantic token | A purpose that points at a primitive: color.action.primary |
| Component token | A slot in one component: button.primary.background |
| Alias | A token whose value is another token |
| Tier | One level of the chain from raw value to component |
7. Try it (no tools needed)
- Take three colours from a product you know: the main button, the error text, the page background.
- For each, write a primitive name (by hue and step) and a semantic name (by purpose).
- Now imagine dark mode. Which semantic tokens would point somewhere else? Which primitives would you need to add?
Reflection questions: Which of your colours had no clear purpose when you tried to name it? What does that tell you?
8. If you already practise
- Lint for skipped tiers: search the codebase and the Figma library for primitive colour tokens used directly in components.
- Mark primitives as private where your tools allow it. Figma can hide variables from publishing, so other files only see the semantic set (Figma Help, Create and manage variables).
- Review each new component token with the test from section 4. Delete the ones that have never differed from their semantic.
Checklist
Learn more
- Adobe Spectrum: Design tokens
- Material Web: Theming · Material Design 3, Design tokens
- IBM Carbon: Themes · Color tokens
- Design Tokens Community Group: Format Module 2025.10
Books, courses and videos to go deeper
- Expressive Design SystemsYesenia Perez-CruzBook · A Book Apart, 2019 (Amazon)
- Design SystemsAlla KholmatovaBook · Smashing Media, 2017 (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Naming tokens · Themes and modes · Colour, type and spacing as tokens · Motion tokens · What a design system is · Multi-brand and multi-product systems · Three-tier token model