tl;dr
Write a one-line description for every token, by the job it does.
For tokens that have names but no descriptions. Each one gets a $description you can paste into your token file.
Why
I used AI to write the descriptions for my tokens. It’s quick across a whole token file, as long as I check what it guesses, because I know what each token is for and the model doesn’t.
Agents pick tokens by reading about them. A line that says when to use a token, and when not to, helps more than a clever naming scheme.
How to use it
- Paste a group of tokens at a time (all text colours, all spacing).
- Correct anything that guesses wrong; you know the intent, the tool doesn't.
- Add the descriptions to your token source, not to generated files.
Prompt
The drop: Token Description Writer
A prompt to paste, with blanks to fill
Write a description for each design token below.
- One sentence: what it's for, by role ("text for errors and destructive actions")
- Then "Don't use for:" one common misuse
- Base it on the token's name, value and group. If the purpose isn't clear, write [ASK] instead of guessing.
Output as JSON with the token path and "$description".
Tokens:
[paste]