Development 101

Design tokens for AI codegen.

Your token file is already machine-readable. That is not the same as agent-usable. The difference is whether each value carries the rule for when to use it.

Most token sets were built for a human who will read the documentation once and absorb the conventions. An agent reads nothing once. It reads what is in front of it, every prompt, with no memory of the last screen it built.

Why a flat token file is not enough

Given --blue-500 and --gray-900, an agent has a palette and no policy. It will pick a plausible value, and plausible is how a product ends up with four blues that are almost the same. The file is readable. The decision it encodes is not.

Naming by role instead of by appearance moves the decision into the name. --color-text-primary answers a question --gray-900 only poses.

Three layers, and why the middle one matters

Palette

Raw values. Fixed per brand, referenced by nothing in your components.

Semantic

Purpose-named tokens that components use exclusively: text, surface, border, fill, accent, status. This is the layer an agent reasons with, because every name states its job.

Theme mapping

Which palette a brand and mode resolve to. Swap it and every surface follows, because nothing downstream ever referenced a hex.

What to write next to each token

A value tells the agent what the token is. A usage rule tells it when the token is wrong. The second one is what keeps a status color out of a hover state.

The rules worth stating explicitly:

• Which token carries hover, which carries selected, and that they are not the same.
• That status colors are status only, never an interaction state.
• Which tokens data visualization reads, and that it is never the accent.
• Which one is the disabled register, so low-emphasis text does not borrow it.

The test

Open a new chat window, give the agent nothing but your token layer, and ask for a settings page. If what comes back uses your tokens correctly, the layer is doing its job. If it invents a spacing value or reaches for a raw palette entry, you have found the rule you did not write down.