Marcus Andrey Study
Ler em português Library

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 fan deck of seven swatch strips on one rivet, each strip cut into chips, the way a paint fan holds a whole scale. Point at a strip: it takes the bright edge and stays in place, while the strips either side turn away from it round the rivet, the nearest first. That's this step: a token is one named step on a scale everyone shares, so people pick a value instead of mixing their own. This step has five lessons: token tiers, naming tokens, colour, type and spacing as tokens, themes and modes, and tokens from Figma to code.Illustration: Marcus Andrey, drawn with Hairline (MIT, Lucas Marques).

A good token system separates what a value is from what it's for. #1F5FAE is 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.primarybutton.primary.background
color.blue.400 #5B95DBcolor.action.primary, dark modebutton.primary.background, unchanged
color.coral.600 #C2412Dcolor.feedback.dangerbadge.danger.text
space.5 24 pxNo semantic step neededbutton.primary.padding-inline
space.4 16 pxspace.inset.mdUsed by cards, dialogs and panels directly
radius.md 8 pxradius.controlEvery control reads it, no component token
Three tiers in Harbour, each one pointing to the next. Primitives say what a value is, semantic tokens say what it's for, component tokens say where it goes. In dark mode only the link between primitive and semantic changes: the button's own token never changes. Not every row needs all three tiers.Tier names as in Adobe Spectrum (primitive, semantic, component-specific); Material calls them reference, system and component. Diagram: Marcus Andrey, CC BY 4.0.
  • 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.600 directly, 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)

  1. Take three colours from a product you know: the main button, the error text, the page background.
  2. For each, write a primitive name (by hue and step) and a semantic name (by purpose).
  3. 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

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

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

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close