What AI agents need from a design system

A design system was built for people who can ask a question, read a Figma file, and remember what the team decided last quarter. An agent has none of that. It has your repository, whatever documentation it can find, and a pattern matcher. Four failure modes follow from that, and each has a specific cause.

It invents props#

You ask for a destructive confirmation dialog. The agent writes <Modal variant="danger"> and your Modal has no variant prop. TypeScript catches it, the agent tries again, and after two more attempts it writes a <div> with the right colours instead.

Cause: the prop surface is not written down anywhere the agent can read. Types help, but types say variant?: string more often than anyone admits, and they never say which combinations are valid.

It picks the wrong component#

There is a Button, a Link, an IconButton and a legacy ActionButton that nobody has removed. All four compile. The agent picks by name similarity, which means it picks the one whose name is closest to the words in your prompt.

Cause: nothing states intent, and nothing states exclusions. Without "use this for", "do not use this for" and a note that ActionButton is deprecated, all four are equally correct as far as the agent is concerned.

It rebuilds what already exists#

It writes a card, a tab bar or a dropdown from scratch, in a single file, with its own state handling, while an implemented, accessible, tested version sits in your component package.

Cause: discoverability. The component was not exported from the entry point, or it is named something the agent cannot connect to the words a person uses for it, or nothing in the repository lists what the system contains. Building it fresh is what an agent does when it cannot find the existing one.

It hardcodes visual values#

The output looks approximately right and contains #3b82f6, border-radius: 6px and a shadow nobody has seen before. It passes review because it looks close enough at a glance, and it puts one more untokenised value into the codebase.

Cause: the agent copied the nearest example it found, and the nearest example had literal values in it. Your implementation is the specification as far as an agent is concerned. Whatever is in it, is the rule.

What all four have in common#

None of them are model failures, and none are fixed by a better prompt or a larger context window. They are consequences of information a human colleague gets from conversation and an agent can only get from the system itself.

The four things an agent needs, in order:

1. Intent. What each component is for, in a sentence.
2. Constraints. When not to use it, and what to use instead.
3. A findable surface. One predictable way to discover what exists.
4. A correct example. The pattern it will copy, because it will copy one.

That list is why the AI Readiness model weights semantics and constraints as heavily as it does. They are the two an agent cannot work around and the two almost nobody writes down.