Design Token Naming Conventions
Design Systems & Tokens · tokens, design systems, consistency
Updated 2026-07-28
- Name tokens for their job, not for their appearance. A value called danger survives a palette change, and one called red does not.
- Use the three layers deliberately:
- Primitive, which is the raw value with a neutral name.
- Semantic, which is the meaning, and the only layer product code should use.
- Component, which is the specific slot, for the few cases that need one.
- Keep a consistent order in the name, such as category, then role, then variant, then state, so a token can be guessed rather than searched for.
- Avoid numbers that imply an order you will later break. Inserting a value between step two and step three is why so many scales end up with a two-point-five.
- Never encode the current value in the name. A token called spacing-16 becomes a lie the day the spacing changes.
- Name states explicitly and completely, so hover, focus, active, disabled, and selected exist for every interactive role rather than being improvised per component.
- Keep the vocabulary small and enforce it. Surface, background, and canvas meaning roughly the same thing is how a system becomes unlearnable.
- Document the intent alongside the value. Two tokens with the same colour and different meanings will be merged by someone who only saw the hex.
Token names are the shared vocabulary between design and code, so ambiguity in a name becomes ambiguity in the product.
Related guides
UX Handbook