Key takeaways
- Separate raw colors (primitives) from their meaning (semantic tokens).
- Name tokens by role, not by color.
- Dark mode becomes a remapping of semantic tokens.
A design token is a named value that stores a design decision. For color, tokens turn a pile of hex codes into a system that a whole team can use consistently.
Level 1: primitive tokens
Primitives are the raw palette, named by hue and step: --blue-500: #3b6cff. They describe what the color is, not where it is used. Generate each family with the shade scale generator.
Level 2: semantic tokens
Semantic tokens describe the job a color does: --color-text, --color-surface, --color-border, --color-action. They point at primitives:
:root {
--blue-500: #3b6cff;
--gray-950: #0c0c14;
--gray-50: #f6f6fa;
--color-action: var(--blue-500);
--color-text: var(--gray-950);
--color-surface: var(--gray-50);
}
Level 3: component tokens
Optional, and useful in larger systems: --button-bg: var(--color-action). This lets you restyle one component without touching the rest.
Name by role, not by color
A token called --color-blue becomes a lie the day your brand turns green. A token called --color-action survives the change, because only its value moves.
Dark mode as a remap
When components only use semantic tokens, dark mode means pointing those tokens at different primitives:
@media (prefers-color-scheme: dark) {
:root {
--color-text: var(--gray-50);
--color-surface: var(--gray-950);
}
}Retest every pair afterward with the contrast matrix, because passing in light mode does not guarantee passing in dark.
Document and share
Keep one source of truth, publish it to designers and developers, and explain the rules. Our post on building a brand color system covers the thinking that comes before the tokens.