Nobody gets excited about naming design tokens. Yet those names become the shared language between design and code, and a confusing one is repeated thousands of times.

Use layers

Raw values, such as specific colours and sizes, live in one layer. Purpose-based tokens, such as surface, text, and action, point to those values.

Components use the purpose layer only. That indirection is what lets a system change its look without changing its parts.

Make names predictable

A good name can be guessed. If one token is called text-primary, the next person should be able to guess text-secondary without searching.

Pick an order for category, role, and state, and keep it everywhere.

If you have to look a token up, the name is not doing its job.
Interface cards showing a token-based design system
Names are the interface of a design system.

A few rules we keep

Short rules written down early save long discussions later. They also make reviews faster, because a name either follows the pattern or does not.

The rules should be visible to everyone who adds tokens, not only to the person who wrote them.

  • Name by purpose, not appearance.
  • Keep one order: category, role, state.
  • Avoid abbreviations nobody agreed on.
  • Document every new token with its use.