Your design system isn't ready for AI agents
By Allan Leone on
A system built for humans encodes what things look like. Agents need to know why. Here are the four gaps that turn up in almost every audit, and what closing them actually involves.
Design systems were written for people who can ask a follow-up question. That assumption is load-bearing, and it quietly breaks the moment a coding agent starts consuming the system instead of a designer.
Four things go wrong. They are not exotic. Every system I have audited in the last year has at least three of them.
1. Three sources of truth that disagree
The documentation describes what someone intended two years ago. The tokens carry a decision nobody migrated. The shipped components drifted toward whatever went out under deadline pressure.
A designer handles this without noticing. They read the room, glance at what production actually does, ask in Slack, pick the version that looks right. The contradiction never surfaces because a human absorbs it.
An agent has no room to read. It resolves the conflict by picking whichever source it saw most recently, then applies that choice consistently across forty screens before anyone opens a pull request. The failure is not that it guesses. It is that it guesses uniformly and at volume.
2. Documentation that describes appearance, not intent
Most component docs say what the component looks like and which props it takes. Very few say when to use it and, more importantly, when not to.
"Use the destructive button variant for actions that cannot be undone" is a rule an agent can apply. "Destructive button: red, 40px height, uppercase label" is not a rule. It is a description, and the agent will happily use it for a cancel action that undoes nothing.
## Button, destructive
Use when: the action is irreversible and the user
cannot recover the previous state.
Do not use when: the action is reversible, or when
an undo affordance exists. Use the default variant.
Never place two destructive buttons in one view.That is three lines longer than what most systems have, and it is the difference between a rule and a swatch.
3. No distinction between what an agent may do alone
Teams tend to treat agent output as one category, which forces a binary choice between reviewing everything and trusting everything. Neither survives contact with real volume.
The version that works is a graded one. Some changes go straight in, some open a draft pull request for a human, some are only ever suggestions. Token renames and copy edits are not the same risk as a new component variant, and treating them identically is what makes review fatigue set in.
- Auto-apply: spacing corrections, token substitutions where a deprecated token has a documented successor.
- Draft for review: new component instances, layout changes, anything touching a shared pattern.
- Suggest only: new variants, new tokens, anything that would extend the system rather than use it.
4. Components documented as one monolithic thing
A single page covering every prop, state, variant and edge case is fine for a human who skims to the part they need. Fed to an agent as context, it is mostly noise competing with the twenty percent that matters for the task at hand.
Brad Frost calls the fix progressive disclosure of context. Structure the documentation so the relevant slice can be retrieved on its own rather than shipping the whole page every time.
Where to start
Not with a rewrite. Systems teams already spend a large share of their time on maintenance, and a full re-authoring pass tends to stall around the third component.
- Pick the five components that appear in the most screens. Reconcile docs, tokens and code for those five only, and make production the tiebreaker.
- Add a "use when / do not use when" pair to each of those five. Two sentences each is enough to start.
- Write down your trust levels before you need them, even informally. Which changes can an agent land without a human, and which cannot.
- Run a real task through an agent against the current docs and read what it produces. The first wrong output usually points straight at the contradiction you have been living with.
The uncomfortable part of all this is that none of it is new work. The ambiguity was always a defect. It was just being paid for quietly, by people, one Slack question at a time.
Tags: design-systems, ai, engineering