Your design system now has a second audience that can't ask questionsYour design system now has a second audience that can't ask questions

An agent is the second reader of a design system. It never files a ticket, never turns up to office hours, and picks between two near-identical buttons without asking which one is primary, so everything the system needs to say has to sit somewhere that loads before the first prompt is typed.

Ambiguity used to get patched by people

For a decade, confusing systems survived because their readers could push back. An engineer who found two near-identical components asked in Slack, a designer who noticed a missing hover state filled it in from instinct, and the gaps closed one conversation at a time without anyone recording how. An agent hands the gap straight to production, which turns every ambiguity in a system into a defect that ships. The unglamorous work of making tokens carry meaning, names match, and states exist has always paid off, and with a reader that cannot ask it pays off twice, since each fix also helps the next new designer or engineer.

Figma's post on design systems and MCP reports that 68% of developers use AI to write code while only 32% of designers and developers trust the output, so the people who rely on the output are mostly checking it by hand.

Tokens that say what they are for

The practical guide on uxdesign.cc recommends a semantic layer of tokens that describe intent, so an agent knows what a value is for as well as what it is. A token named for its role gives the agent a reason to pick it, and a raw value gives it nothing to reason from, so it matches the nearest thing it can find. The decisions behind a layer like that get their own treatment in token architecture, and what keeps such a layer from decaying is the subject of what happens to handoff when the canvas is code.

Icons with a props API

Left alone, an agent picking an icon gets the library's own defaults, and a commit on 2026-09-27 put a layer above them. Every glyph now goes through one factory that adds named size tokens (2xs at 12 pixels up to 4xl at 64), four allowed weights, color tokens, duotone controls and a label prop, and that marks an icon hidden from screen readers unless it has a label. An agent asked for a small muted check has words that exist for it, and an icon it says nothing about stays silent for screen readers until someone gives it a reason to speak.

Unset props fall through to the library's defaults, so existing call sites rendered identically, and the commit records the proof: screenshots of 12 pages in both themes at desktop and phone widths matched the previous build pixel for pixel. A system with daily agent callers needs that kind of regression evidence before it changes anything an agent depends on, because the agent will use the new surface within the hour and will not mention that something looks different.

An inventory the agent can browse

The project instructions send the agent to a live inventory page, /visual-language, before it concludes that something doesn't exist. An agent that cannot find the right component builds a new one with complete confidence, so the page exists to make the right component findable. The uxdesign.cc guide names the link between Figma components and code (matching names, every state drawn, Code Connect) as what lets an agent reuse what exists, and a browsable page does the same job for a system that lives in code. Naming gets its own pass in naming conventions.

What each artifact is for

The icon API answers the question an agent asks most, which is what choices exist, and the inventory answers where the thing it wants already lives. Semantic tokens answer what a value is for, and the written rules answer what to do when none of them fit; the CLAUDE.md for this site is where those rules and their reasons live. Put your own system through those four questions and fix the one it answers worst first.