What Are Design Tokens? A Colour-First Introduction

Somewhere in a growing codebase, the colour #5B5BD6 gets typed for the forty-third time. A designer decides the brand purple should be a touch warmer. And now someone has to find all forty-three, in files nobody remembers writing. Design tokens exist so that afternoon never happens.

A token is a name for a decision

At its simplest, a design token is a name pinned to a value. Instead of writing #5B5BD6 everywhere, you write color-primary, and color-primary points to #5B5BD6 in exactly one place.

Change that one place, and every button, link and highlight that referenced the name updates at once. The forty-three edits become one. That's the whole trick — and it's a bigger deal than it sounds, because it turns a colour from a scattered fact into a single, editable decision.

Name by role, never by hue

Here's the mistake almost everyone makes first: naming the token after the colour. color-purple. It feels sensible right up to the day the brand goes teal, and now you have a token called purple holding a teal value, which is a small lie that will haunt the codebase forever.

Name tokens after their job instead. color-primary, color-accent, color-surface, color-danger. These names survive a rebrand, because a primary colour is still the primary colour whatever hue it happens to be this year. The role is stable; the value is free to change.

Two layers that save you later

Mature systems split tokens into two tiers, and it's worth doing early.

The first layer is your raw palette — the actual colours, named neutrally: blue-500, grey-100. The second layer is semantic and points at the first: color-primary = blue-500, color-border = grey-100.

Why the indirection? Because it lets you re-theme without touching a single component. A dark mode is just the semantic layer pointing at different raw colours — color-surface swings from grey-50 to grey-900 — while every button that asked for color-surface quietly follows along. Build this once and dark mode stops being a rewrite and becomes a remap.

From palette to tokens without the tedium

You don't assemble this by hand. Start from a palette you like — generate one in the Palette Generator or refine yours in the editor — then assign each colour to a role in the Token Generator. It exports the result in whatever your stack reads: CSS custom properties for the web, Figma Tokens JSON for the design side, Style Dictionary or Theo for a shared pipeline, or plain JSON to do your own thing with.

Before you commit, it's worth seeing the roles in situ. Drop the same tokens onto real buttons and cards in the UI Preview — that's where you find out your "danger" red is actually too gentle to read as danger.

Common questions

Are design tokens only for colour?

No — spacing, font sizes, radii and shadows all work as tokens too. Colour is just the most common starting point, and the most satisfying, because a rebrand becomes trivial.

Do I need a design system to use them?

Not a formal one. Even a solo project benefits: name your handful of colours by role and future-you can restyle the whole thing from one file.

What format should I export?

CSS custom properties if you're mostly building for the web; Style Dictionary or Figma Tokens if designers and developers share a pipeline. The Token Generator gives you all of them, so you're not locked in.

Tokens don't make your colours prettier. They make them manageable — one name, one decision, changed in one place. Take a palette you already trust and turn it into a named system in the Token Generator.