Safe starting point
Name by role
A basic token set
Applies to All viewports
A token is a named design decision. Start with a small set named for what each value is for, and reference tokens in components, never raw values.
- Spacing
- space-1, space-2, space-3. Steps on your spacing scale.
- Radius
- radius-sm, radius-md, radius-lg. Two or three values tied to component size.
- Colour
- bg-default, bg-subtle, text-primary, text-secondary, border-default, action-primary, feedback-error, feedback-success. Named by role, pointing at palette values.
- Elevation
- elevation-0, elevation-1, elevation-2. One per level on your elevation ladder.
Why?
Named decisions can be changed in one place, checked for consistency and handed to engineering without translation.
Common mistakes (3)
- One-off values typed directly into components.
- Tokens named after the value, such as blue-500 used for links, so a rebrand breaks the name.
- More tokens than decisions.
Senior designer note“A design system is useful because it reduces decisions, not because it gives you more tokens.”
Official guidanceSGDSGOV.UK
- SGDS
Five layers: raw values, primitive, simplified semantic, granular semantic and component-specific tokens. Start with simplified semantic tokens when the UI role is clear.
SGDS, Token architecture(opens in a new tab)Design-system convention
- GOV.UK
Functional colours are named by use; only use them in the context they were designed for.
GOV.UK Design System, Colour(opens in a new tab)Design-system convention