Design tokens are the named, reusable values a product is built from — colours, spacing, type sizes, radii. A well-layered token system is what makes an interface look consistent and makes global change trivial. This is the backbone of any design system.
Three layers of tokens
Mature systems use three layers. Primitive tokens are raw values (<code>--blue-600: #2563eb</code>). Semantic tokens give them meaning (<code>--color-accent: var(--blue-600)</code>). Component tokens scope them to a component (<code>--button-bg: var(--color-accent)</code>). Components reference the most specific layer available, so changes flow downward predictably.
| Layer | Example | Purpose |
|---|---|---|
| Primitive | --blue-600: #2563eb | Raw palette values |
| Semantic | --color-accent: var(--blue-600) | Meaning / intent |
| Component | --btn-bg: var(--color-accent) | Per-component |
<button class="btn">Tokenised button</button>:root{--blue-600:#2563eb;--color-accent:var(--blue-600);--btn-bg:var(--color-accent)}
.btn{background:var(--btn-bg);color:#fff;border:0;padding:10px 18px;border-radius:8px}The spacing scale
A spacing scale is a fixed set of step values (e.g. 4, 8, 12, 16, 24, 32, 48, 64) exposed as tokens. Using only scale values gives a page consistent rhythm and kills magic numbers. Many teams base it on a 4px or 8px grid.
:root {
--space-1: .25rem; --space-2: .5rem;
--space-3: .75rem; --space-4: 1rem;
--space-6: 1.5rem; --space-8: 2rem;
}The type scale
A type scale is a harmonious set of font sizes derived from a ratio (e.g. 1.25, the "major third"), so headings relate proportionally. Define them as tokens and every heading on the site stays in tune. Combine with <code>clamp()</code> for fluid steps.
font-size: 15px; margin: 11px; gap: 17px;font-size: var(--text-base); margin: var(--space-4); gap: var(--space-3);Letting designers and developers each invent ad-hoc values, so the same product uses 13px, 14px and 15px text and 11px, 13px and 17px gaps. Define scales as tokens and use only those.
Layer tokens (primitive → semantic → component), base spacing on a 4/8px grid, derive type from a ratio, and forbid raw values in components. This is what makes a product look designed rather than assembled.
Define a primitive palette, semantic --color-accent and component --btn-bg, plus a spacing scale (--space-1…8). Build a button and a card using only tokens — no raw values.
1. What does a semantic token do?
2. Why use a spacing scale?
3. A type scale derives sizes from…
- Token layers: primitive → semantic → component.
- A spacing scale (4/8px based) gives consistent rhythm.
- A type scale derives sizes from a ratio for harmony.
- Forbid raw values in components — use tokens only.