Design Tokens

Definition

Design tokens are a way of naming the values that keep repeating across your screens — colors, spacing, corner radius — and then referencing those names in your actual code. Instead of typing 15px or a raw blue hex code in a dozen places, you define a name like --space-md or --color-accent and point to it. That way, when you change the single value behind a name, every place that uses the token updates together, all at once. Tokens add one thin layer of naming between a value and the places it is used, gathering scattered numbers into a single central list. That gathering is the whole idea of design tokens.

Why does it matter?

When hardcoded values are scattered all over your screens, changing anything later means hunting down every place that used the value and fixing each one by hand — and if you miss even one, the design ends up subtly out of sync. With tokens, switching to dark mode, rebranding to a new color, or unifying the style across several products all become a matter of editing one place. The name itself also documents the intent of a value: seeing --color-accent tells you it plays the role of the accent color, just from reading the code. Once memorizing individual values turns into working with a meaningful system, a whole team can build consistent screens on top of the same shared rules. In the end, tokens collect scattered decisions into one list, turning design from an individual's gut feeling into a promise the team shares.

Common mistakes

• Baking a color or a number straight into the token name. Name it for the role it plays, like --color-accent, rather than --blue-500. That way, when you later switch the accent to green, the name never contradicts the value and leaves people confused.
• Creating tokens but then, when you are in a hurry, typing the raw value directly again anyway. Once a few exceptions pile up, the token's meaning breaks down — you lose the whole benefit of editing one place, and you end up digging through scattered values all over again.
• Defining far too many tokens from the very start. When you name values you will never actually use, picking the right token gets more confusing, not less. It is easier to manage if you promote a value to a token one at a time, only once you see it genuinely repeating.

Practical tips

• Name tokens by the role they play, not by what value they hold. When a name reveals its use — accent, background, border — you can swap out just the value during dark mode or a rebrand without the name and its meaning ever drifting apart, which makes every change far safer and faster.
• Take the values you learned here — spacing, color, radius, shadow — and bundle them into tokens one by one. The moment you weave those individually learned concepts into a named system, scattered knowledge turns into a genuinely reusable design system of your own.
• Splitting the raw value and the name your screens reference into two layers makes everything easier to manage. Keep the base color and spacing values on the lower layer, and let role names like accent or body text point to them. Then a change that only reroutes roles, like dark mode, stays remarkably clean.

Related concepts