Tokens aren't enough: what I learned teaching AI my design system
I spent months making a design system usable by AI. My first attempt failed, but not because anything was missing.
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.
That exercise revealed the larger gap. The components described what could be built, but the finished screens revealed how the system made decisions.
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. For each noticeable choice, ask why it works that way. The answer is often more useful than another exported file.
Start with the decisions that shape the whole screen: what receives attention, what stays quiet, and how the page establishes hierarchy. Component details become useful once that larger logic is clear.
The part I did not expect
At first, documenting all this felt slightly uncomfortable. It can seem like you are reducing design judgment to 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.
