What are design tokens, and how should you name them?
Name reusable design decisions clearly so design files and code can be compared.
A design token names a reusable design decision and records its value. For example, primary text colour refers to a colour value that designers and developers use for the same purpose.
Keep these basics in mind
- A value is the concrete choice, such as a colour, distance, or duration. The name explains what it represents or where it belongs.
- Reusing a named token for the same purpose is easier to manage than repeatedly entering values.
- Names should be stable and understandable. New blue and nice shadow only make sense to their original author at that moment.
- Tokens can be stored as data, represented in design tools, and used in code. Agree on how these representations correspond.
See Spectrum’s token guide for the concept and naming, and Figma’s variable guide for representation in a design tool.
Reuse a design decision
Illustrative naming changes
These names are teaching examples; actual naming follows team agreements.
| Decision | Previous description | Example token |
|---|---|---|
| Primary text colour | A darker grey | text-primary |
| Regular section padding | Separate values everywhere | section-padding |
| Error text colour | That red | text-error |
Walk through an example
Several forms need error text, so the team names the purpose
text-error
. Designers and developers record its representations. Before changing the colour, they
find pages that use it and check their backgrounds and readability. They then explain
how to adopt the change.
Limits and common misunderstandings
Tokens do not mean turning everything into a variable. One-off content usually does not need a shared rule. Changing a design-tool value does not automatically update a live website; synchronisation and release are still necessary.