Marcus Andrey Study
Ler em português Library

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.

1Primitive

A raw value with a neutral name. Says what it is, not what it's for.

color.blue.600 = #1F5FAE
2Semantic

A purpose that points at a primitive. Modes and brands change this link.

color.action.primary
3Component

One slot in one component. Add it only if the slot may differ.

button.primary.background

button.primary.background → color.action.primary → color.blue.600

Three tiers from raw value to component, linked by aliases that always point down a tier.

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.600 works until the first mode. Then every component needs a code change.
  • Semantic names that describe appearance. color.blue-button is 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.600 to 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
Source
Alias syntax: W3C Design Tokens Community Group, Format Module 2025.10. Tier names vary by system (primitive, semantic, component is the most common set).
Where to find it
Design Systems in Practice: Token tiers › Three tiers, one chain

"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Saved only on this device.

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