tl;dr
Check your token names and descriptions the way a coding agent reads them.
For any system coding agents build from. They pick the wrong colour or size a lot less often.
Why
Other designers have been flagging this one online. An agent picks the wrong token when all it has is a name. Reading blue-500, it has to guess what the colour is for. Reading color-text-link, with a line saying it’s for links in running text, it mostly doesn’t.
So every semantic token gets its purpose written down. Primitives like blue-500 don’t need one, because components shouldn’t use them anyway.
How to use it
- Paste the prompt with your token file, or the semantic tokens and their descriptions.
- Fix what it flags. Use Token Description Writer for the tokens with no description.
- Run it again after every batch of new tokens.
Prompt
The drop: Token Description Lint
A prompt to paste, with blanks to fill
Check these design tokens the way a coding agent will read them.
For each semantic token, flag:
- No description, or one that only repeats the name
- A description of how it looks ("dark grey") instead of what it's for
- Two tokens whose descriptions overlap, so an agent can't tell which to pick
- A name built on a raw value (blue-500) on a token components use
Skip primitives. Components shouldn't use them, so they don't need descriptions.
Output a table: Token | Problem | Suggested description
Then list any token you couldn't judge, marked [ASK].
Tokens:
[paste your token file]