A token is a named decision. "#4f46e5" is a value; "color-brand-primary" is a token. Components reference tokens, not values. When the value changes — a rebrand, a theme, an accessibility fix — the component doesn't.
The cost of getting this wrong is invisible until the first rebrand, at which point you discover that 'primary blue' was hard-coded as #4f46e5 in 137 places across three repositories. The cost of getting it right is one extra layer of indirection.
Three layers, in this order
Primitive tokens are raw values: color-blue-500, space-400, radius-md. They have no semantic meaning. They're the alphabet.
Semantic tokens reference primitives and carry intent: color-bg-page, color-border-default, color-brand-primary, space-card-padding. They're the words.
Component tokens reference semantic tokens and describe specific instances: button-primary-bg, input-border-color, modal-shadow. They're the sentences.
Most systems botch the middle layer. They jump from primitive to component, and end up with a component layer that's actually a thin renaming of primitives. That defeats the point.
Name by function, not appearance
color-bg-default, not color-gray-50. The first survives a dark-mode swap; the second turns into a lie. Same for space-card-padding instead of space-16, and radius-control instead of radius-md.
Appearance-based names are fine at the primitive layer (color-blue-500 is a fact, not an opinion). They're poison at the semantic and component layers.
Round-trip with Tokens Studio
The W3C Design Tokens spec ($value, $type, $description, $extensions) is the lingua franca that lets tokens flow between Figma (via Tokens Studio) and code (via Style Dictionary, the token generator's exporters, or hand-written CSS variables).
If your tokens don't round-trip, designers and engineers maintain parallel sources of truth. That's a guaranteed drift.
Versioning tokens
Bump the major version when you remove or rename a token. Bump the minor when you add. Bump the patch when you adjust a value within the same name. Document deprecations in the changelog and keep aliases in place for at least one release.
- 01Three layers: primitive → semantic → component. Skipping the middle layer creates a system that can't theme or rebrand cleanly.
- 02Name by function (color-bg-default), not appearance (color-gray-50), at semantic and component layers.
- 03Use the W3C Design Tokens spec so Figma and code share a source of truth via Tokens Studio.
- 04Treat tokens like a public API — semver them, deprecate gracefully, document changes.
Token Generator
Generate the three-layer model end-to-end with W3C-spec Tokens Studio JSON, CSS variables, SCSS, Tailwind config, and more.
W3C Design Tokens Format
The official spec for the JSON format Tokens Studio and most token tooling exchanges.
Carbon Design (IBM)
A canonical reference for primitive-vs-semantic structure with theme-aware tokens.