Naming design tokens for machine consumers
By Allan Leone on
Tokens used to be an internal convenience. A badly named one cost a moment of squinting. Now agents read them, and a name that describes appearance instead of purpose gets applied wrongly at scale.
For most of their history, design tokens were a private convenience. If one was named badly a developer would squint, work out what was meant, and use the right one anyway. The cost was seconds and it was paid by someone who understood the context.
Agents do not squint. They match on the name, and when the name lies the result is applied consistently across everything they touch.
Appearance names versus purpose names
/* Appearance. An agent has to guess the purpose. */
--color-2: #a370ff;
--gray-light-alt: rgba(0,0,0,.06);
--blue-500: #3b82f6;
/* Purpose. Nothing left to infer. */
--color-accent: #a370ff;
--color-border-subtle: rgba(0,0,0,.06);
--color-status-info: #3b82f6;Same values, very different failure rates. The second set tells a consumer what the token is for. The first only says what it currently looks like, which is exactly the fact that stops being true after a rebrand.
The tell for a bad token name is that you cannot describe when to use it without referring to a colour.
The tokens nobody can define
Every mature system accumulates tokens whose purpose nobody remembers. There is usually a --gray-3 and a --gray-alt and a --border-light that resolve to nearly the same value for reasons lost to a redesign three years ago.
These are worse than useless once agents are consuming the system, because they present a choice where no meaningful distinction exists. The model picks arbitrarily and the arbitrariness spreads.
Renames are breaking changes now
When humans were the only consumers, a rename was a find-and-replace and a mild inconvenience. With agents in the loop, any cached context, prompt file or generated code referencing the old name keeps producing it long after the rename lands.
Treat a rename the way you would treat renaming a public API method. Keep the old name as a documented alias for a period, mark it deprecated in the docs the agents read, and remove it deliberately rather than opportunistically.
Where to start
- Export your token list and try to write a one-line "use this when" for each. The ones you cannot write are the ones to fix or delete.
- Find tokens resolving to values within a few percent of each other. Merge or differentiate them explicitly.
- Rename by purpose, starting with the ten tokens used most often. Keep aliases and mark them deprecated.
- Ask an agent to build a small component using only your tokens. Where it reaches for a hard-coded value, your naming has a hole.
Tags: design-systems, engineering, ai