Framework · Design systems · 3 min read
Three-tier token model
Primitive tokens hold raw values, semantic tokens name what a value is for, component tokens name one slot in one component, and aliases link them in one direction, so a mode, a rebrand or a second brand moves one link instead of every component.
A raw value with a neutral name. Says what it is, not what it's for.
color.blue.600 = #1F5FAEA purpose that points at a primitive. Modes and brands change this link.
color.action.primaryOne slot in one component. Add it only if the slot may differ.
button.primary.backgroundbutton.primary.background → color.action.primary → color.blue.600
Use it when
- You are setting up tokens for a new system, or moving a style library to variables.
- Dark mode, a second brand or a density setting is on the roadmap, and today components use raw colours.
- The token list has grown to thousands of names and nobody knows which ones to use.
How to use it
- List the raw values as primitives. Colours by hue and step, space and radius as scales. Give them neutral names that say what the value is, never what it's for. Output: the primitive set, e.g.
color.blue.600 = #1F5FAE,space.4 = 16px. - Name the decisions as semantic tokens. For every purpose the interface has (the main action, body text, a subtle surface, danger), create one token that points at a primitive. Output: the semantic set, e.g.
color.action.primary → color.blue.600. - Point components at semantics. Every colour a component uses reads a semantic token. Check the Figma library and the code for primitive colours used directly, and replace them. Output: no component reads a primitive colour.
- Add component tokens only where a slot may differ. Ask: "Will this component ever need a different value from the semantic it points to?" If yes, add
button.primary.background → color.action.primary. If no, skip it. Output: a short list of component tokens, each with a reason. - Put modes on the semantic tier. Dark mode, brands and density change where semantic tokens point. Primitives keep their values and component tokens keep their links. Output: one semantic column per mode.
- Check the direction of every alias. Component points to semantic, semantic points to primitive. A primitive never points at anything. Output: a chain you can read from any component down to a raw value.
Worked example
Harbour, the design system of the ferry company Tidewater, has a primary button. Its background token is button.primary.background, which points at color.action.primary, which points at color.blue.600 in light mode and color.blue.400 in dark mode.
| Tier | Light mode | Dark mode |
|---|---|---|
Component: button.primary.background |
→ color.action.primary |
→ color.action.primary |
Semantic: color.action.primary |
→ color.blue.600 |
→ color.blue.400 |
Primitive: color.blue.600 |
#1F5FAE |
#1F5FAE |
When dark mode shipped, only the semantic row changed. The button's token and code stayed the same. Cards don't get a component token for padding: they read space.inset.md directly, because nobody will ever theme card padding on its own.
Watch out for
- Components reading primitives.
button.background → color.blue.600works until the first mode. Then every component needs a code change. - Semantic names that describe appearance.
color.blue-buttonis a primitive in disguise. In dark mode it isn't that blue any more. - A component token for every property. Thousands of tokens nobody can navigate. Add one only when the slot may differ.
- Fixing one use by changing a primitive. Changing
color.blue.600to fix one screen changes every token that points at it.
Template
Fill one row per token you add, and keep the table next to the token file.
Tier | Name | Points to / value | Why it exists
-----------|-----------------------------|-----------------------|------------------------------
Primitive | color.blue.600 | #1F5FAE | palette step
Semantic | color.action.primary | {color.blue.600} | the main action, all products
Semantic | dark mode | {color.blue.400} | contrast on dark surfaces
Component | button.primary.background | {color.action.primary}| may differ per brand later
Check: no component reads a primitive colour? yes / no
Check: every alias points down a tier? yes / no
- Expressive Design SystemsYesenia Perez-CruzBook · 2019 (Amazon)
- Design SystemsAlla KholmatovaBook · 2017 (Amazon)
- Design Tokens Format Module 2025.10DTCG (external site)
- Overview of variables, collections, and modesFigma Help (external site)
"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.