# Token Description Lint

> Check your token names and descriptions the way a coding agent reads them.

- Drop: Prompt (uncommon)
- Season 1 – The AI-ready Design System
- Status: Tested (used on real work)
- Published: 2026-10-02
- URL: https://www.mlynarz.com/grist/agent-readable-tokens
- Curated by: Dawid Młynarz

**Hint:** 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

1. Paste the prompt with your token file, or the semantic tokens and their descriptions.
2. Fix what it flags. Use Token Description Writer for the tokens with no description.
3. Run it again after every batch of new tokens.

## The drop

````markdown
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]
````