Tokens aren't enough: what I learned teaching AI my design system

I gave it the component files, tokens, guidelines, and setup instructions. It had the same material a new designer or engineer would receive when joining the team.

The result followed the system and still looked completely wrong.

Every color was technically correct. The typography came from the right scale. The border radii matched. But the screens did not feel like our product. The brand color filled entire headers. Cards disappeared into the canvas behind them. Several buttons competed for attention in the same place.

Nothing broke a documented rule. That was exactly the problem.

Tokens give you vocabulary, not grammar

A token file tells you which values are available. It does not explain how they should work together.

Our accent color is a strong magenta. A designer can look at it and understand that it should behave like a highlighter, not a paint bucket. It belongs on the few elements that need attention.

That judgment did not exist in the token name primary. From the AI's perspective, primary sounded like the default, so it used the color everywhere.

The system contained the ingredients, but not the logic for combining them.

The missing rules were hiding in real screens

The turning point came when I stopped adding more files and started studying the live product.

I looked at finished screens and wrote down the decisions they followed without explicitly stating them. One of the most useful was simple: the accent color should cover roughly ten percent of a screen.

Then I defined where it belonged and where it did not.

It could be used for a primary action, an active navigation indicator, a progress fill, or a focus ring. It should not be used for page backgrounds, card fills, body copy, or structural headings.

That small table improved the output more than the component library had.

Other hidden rules surfaced in the same way

The canvas, panel, and card must remain visually distinct. A card gets one primary action. Everything else steps back. Typography changes according to meaning, not only size. Disabled states use dedicated muted colors, never reduced opacity.

These were not new design decisions. They were decisions I had been making automatically and had never needed to explain.

My reviews became more useful

Before documenting those rules, every review started with basic corrections. I spent time removing unnecessary color, restoring hierarchy, and separating surfaces before I could even evaluate the flow.

Once the visual logic was explicit, the first drafts started to feel recognizably ours. They were not finished, but the conversation changed.

Instead of asking why the header was magenta, I could ask whether this was the right experience for the user. That is where I want my review time to go.

What I would document first now

If you are preparing a design system for AI, do not start by exporting everything.

Open a real product screen and look at it carefully. Write down the rules it follows that do not appear in your documentation. Look at proportion, density, emphasis, and the relationship between surfaces.

Pay special attention to negative rules. “Never use the accent as a surface fill” is more useful than a paragraph describing the brand as bold or energetic.

Tables also work better than long explanations. A direct do-and-don't comparison leaves less room for interpretation.

The part I did not expect

At first, documenting all this felt slightly uncomfortable. It can seem like you are turning design judgment into instructions for a machine.

What happened was the opposite. Naming the rules made my own judgment clearer.

I had been applying the ten-percent rule for years without calling it anything. Once I wrote it down, I could explain it in a review, teach it to another designer, and notice when the product was drifting away from it.

AI forced me to articulate the logic. The clearer design thinking stayed with me.