The dumbest, most common failure in agent-built UI goes like this. The agent needs an error state. It scans your tokens, finds colors.red.500, and uses it, because red means error on most of the internet and your system gave it nothing better to go on. It looks right. Sometimes it even is right. And your semantic layer, the place where your actual decisions live, just became decorative.
The failure isn't intelligence. It's missing information. The agent had access to every value in your system and none of your meaning. Values tell a consumer what exists. Meaning tells it what things are for. The gap between those two is where nearly every "the AI almost got it" story lives, including mine: we shipped part of our platform on a tokenized style guide without an enforced meaning layer, and the agent got it 80 percent right, slipping precisely where meaning had to be exact.
Think about what a raw palette actually communicates to a machine. colors.red.500 says: a red exists, medium lightness, position 500 on a ramp. It does not say: this red is for destructive actions only. It does not say: the brand red is a different red, never use them interchangeably. It does not say: error text uses the darker shade for contrast, error backgrounds the lighter tint. Those aren't aesthetic trivia. They're the load-bearing decisions of your visual language, and in most systems they exist only in prose guidelines and the heads of senior designers. A human junior absorbs them by osmosis and code review. An agent gets neither.
The fix is the semantic layer done for real: a tier of tokens that encode role, not appearance. color.feedback.danger references red.600. color.brand.primary references red.500. color.text.error, color.surface.danger.subtle, color.border.destructive: each one a decision with a name, aliasing down to primitives. When the agent needs an error state now, it doesn't reach for what looks right. It looks up what is right. The guess isn't improved. It's eliminated.
The test for whether your semantic layer is real or ornamental: could someone build a correct interface using only semantic tokens, never touching a primitive? If yes, your meaning layer is complete enough to carry an agent. If they'd have to dip into raw grays and reds to finish, an agent will have to guess in exactly those places, and it will guess from everyone else's conventions, not yours.
Where do the semantics come from? You've already made these decisions; they're just stored in the wrong format. The guidelines page that says "use red sparingly, only for destructive actions" is a semantic token wearing a prose costume. So is every code review comment that says "that should be the muted foreground, not gray.500." Migrating meaning into data is mostly translation, and the inventory is shorter than teams expect: feedback states, text roles, surface roles, border roles, interactive states. Two dozen semantic tokens carry most products.
Two failure modes to dodge while you build it. Half-semantics: a semantic tier that exists but isn't enforced, so half the codebase references color.feedback.danger and half still hits red.500 directly. An agent reading that split learns that meaning is optional. Lint primitives out of application code; primitives are for the token file, semantics are for use. And synonym sprawl: danger here, error there, destructive in the new package. Machines don't know those are the same concept. One concept, one word, forever.
Encode the roles and something better than correctness shows up: your system starts teaching. Every query an agent makes returns a decision with its reasoning attached in the description field. The design system stops being a reference the consumer might consult and becomes the environment the consumer thinks inside. That's the real difference between a paint store and a design language. One sells you materials. The other tells you what they're for.
The free starter kit at tokenstoagents.ai/kit includes the semantic-layer checklist: the roles to cover, the naming grammar, and the lint rule that keeps primitives out of app code.