Decisions with names – Tokens and the three-layer trick

Last lesson’s mechanism – reference, not copy – applied one level down, to the decisions themselves. Instead of a button’s blue being #0D5EFF typed into fifty files, it’s a name like color-interactive-primary that fifty files reference, and the actual value lives in exactly one place. Change the one place, every reference updates. Same idea as a spreadsheet formula pointing at a cell instead of hard-coding the number – same problem, same solution, different domain. That named variable is a design token.

Why teams bother, concretely. Single-point updates: a full rebrand – every colour, font and spacing value across a product – becomes a token-file change instead of a find-and-replace across thousands of component instances (vendor case studies claim rebrand rollouts collapsing from months to days; treat the exact day-counts as marketing, but the mechanism they describe is straightforwardly true). A shared language: designers in Figma and developers in code reference the same names, closing the “designer says brand blue, developer guesses a hex” gap. Theming for free: light and dark mode become “swap the token values”, not “redesign every screen” – you can verify that one on this very page with the theme toggle in the header.

The three layers

Mature systems converge on the same architecture. Primitive tokens are the raw palette – every value the system could use (blue-500, space-4), no meaning attached yet. Semantic tokens are named by purpose (color-status-error → red-600) and are what components actually consume – because a purpose-name survives a palette swap: retire red-600 for a more accessible red, repoint the alias once, and nothing that uses the semantic name changes. A third layer, component tokens, exists for the rare case one component must diverge (button-primary-background), and good systems add those only when a real divergence appears.

Run both kinds of change yourself – repoint an alias, then rebrand the layer underneath it:

One file, four components – nobody edits the components

The panel only ever references the two semantic names. Change what the names mean.

tokens.css

Layer 1 – primitives

• plum-600
• teal-600
• clay-600

Layer 2 – semantic aliases

• accent → plum-600
• danger → clay-600

Ledger

Monthly report ready – view the breakdown

4 new

ExportDelete draft

Components referencing the two aliases: 4 · edited directly: 0 – make a change above.

Repoint accent →plum-600teal-600clay-600

Layer belowRebrand day – swap primitive values

This is not hypothetical – you’re inside one

The site you’re reading runs on exactly this machinery: one tokens.css file holds the primitives (grey and indigo scales whose step numbers encode which interface state they’re tuned for – a pattern primary-sourced to Vercel’s Geist system), the semantic aliases (--bg-raised, --text-secondary, --accent-solid), and nothing else is allowed to declare a colour. The /system page renders the whole set live – change one token and that page changes, which is the single-point-update claim, standing proof instead of promise.

One more piece of currency worth having: tokens stopped being a shared concept with incompatible per-tool formats in October 2025, when the Design Tokens Community Group shipped the first stable version of its specification (v2025.10) – “the first stable version of the Design Tokens Specification”, in the group’s own words. A vendor-neutral JSON format now moves token definitions between design tools and code pipelines. If a team tells you their tokens are stuck inside one tool, that stopped being a technical necessity in 2025.