Design tokens: a practical three-tier guide

What a design token is

A token pairs a name with a value: color-brand is #272DCB, space-4 is 16 px, radius-media is 8 px. Components read the name, never the value. When the value changes, everything that uses it follows, in Figma and in code.

The real benefit is a shared vocabulary: when a designer says “subtle background” and a developer writes bg-subtle, they mean the same thing, and that thing lives in exactly one place.

The trouble with flat variables

Most projects start with a list: blue-500, blue-600, grey-100, grey-900. It holds while the product is small. Then come questions with no answer: is secondary text grey-500 or grey-600? Does the button use blue-600 or brand-primary? And for dark mode, do we duplicate everything?

The problem is that one name carries two pieces of information: the value and the use. Three tiers separate them.

Three tiers, three questions

• Reference: what exists? The palette, the spacing scale, radii, typefaces. Example: --ds-ref-color-blue-600. No component reads this tier directly.
• System: what is it for? Default background, secondary text, brand colour, media radius. Example: --ds-sys-color-text-muted. The only tier that changes with the theme.
• Component: who uses it? The primary button background on hover, the badge radius. Example: --ds-comp-button-color-bg-primary-hover, pointing to a system token.

--ds-ref-color-blue-600: #272dcb;
--ds-sys-color-brand: var(--ds-ref-color-blue-600);
--ds-comp-badge-color-text-brand: var(--ds-sys-color-brand);

To change the blue everywhere, touch a reference token. To make secondary text darker, a system token. To adjust a single component, a component token. Every change has exactly one place to happen.

How to name tokens

--{namespace}-{tier}-{category}-{role}-{variant}-{state}
--ds-comp-button-color-bg-primary-hover

• Name by role, not value, from the system tier up: color-text-muted rather than grey-500. A role survives a palette change.
• Keep the order identical everywhere.
• Avoid synonyms: pick “subtle” or “light”, “default” or “base”, and stick to it.
• Use a short, project-specific namespace to avoid clashes with framework classes: on this site, mb- would have collided with Tailwind’s margin utilities, hence ds-.

Dark theme without the pain

With three tiers, a dark theme means redefining system tokens. References stay put, components too: they read roles, and roles change value.

:root { --ds-sys-color-bg-default: var(--ds-ref-color-neutral-0); }
.dark { --ds-sys-color-bg-default: var(--ds-ref-color-neutral-950); }

A classic trap: reusing the brand colour as is in dark mode. A dark blue that reads well on white becomes unreadable on black. Give every colour role a dark value and check contrast (4.5:1 minimum for text).

From file to product: Figma and code

• Figma variables handle references and modes (light, dark). One collection per tier mirrors the code.
• The standard exchange format is the W3C Design Tokens Community Group (DTCG) JSON: each token has a $type and a $value, references are written {ref.color.blue.600}.
• Style Dictionary turns that JSON into CSS, Swift, Kotlin and more. Tokens Studio syncs it with Figma.
• With Tailwind v4, an @theme inline block wires utilities (bg-brand, rounded-media) to your system tokens.

The most common mistakes

• Creating a token for every existing value instead of deciding which values to keep first.
• Letting components read reference tokens: dark mode then means editing every component.
• Naming by value at the system tier: color-blue-text lies the day the brand turns green.
• Forgetting states: hover, focus, disabled.
• Not documenting: a token nobody can find gets recreated under another name.

Where to start

1. Inventory the colours, radii, spacings and text sizes actually used in the product.
2. Decide which values to keep and write them as reference tokens.
3. Name the roles you need and wire them to those references. Around fifteen roles cover most interfaces.
4. Make your components read those roles, one by one, starting with the button.
5. Add the dark theme last: if the previous steps are done, it takes an hour.

This site’s design system follows exactly this structure. Press S, or open the Design system page, to see the tokens on the page itself.