Design systems with AI: the system is the contract agents build against

For most of my career, a design system was a set of agreements held together by people. Designers knew which button to use because they’d been in the review where we decided. Engineers knew not to invent a new grey because someone would notice in code review. The written documentation was always a little behind the shared understanding, and that was fine, because the people carried the gap.

Agents don’t carry the gap. They honor exactly what is written down and improvise everything else. Once agents write a meaningful share of your UI, the design system stops being a library people browse and becomes a contract that machines build against. That changes how you write it, how you enforce it, and what you still need a human for.

A component library is a set of agreements

I’ve built atomic systems for a long time: at Boxbee, tagged component libraries before Figma dominated; at Plume, Sketch and Zeplin systems spanning the consumer app, web, email and brand, and later Figma. In every case, the library held the parts. The agreements about how to use them lived in conversation.

An agent reading your library sees the parts and none of the conversation. It will happily put a destructive action in a secondary button, nest a card inside a card, or pick the nearest-looking color because nothing told it not to. The work of an AI-era design system is moving those unspoken agreements onto the page, in language specific enough to act on.

Write "when not to use"

Most component docs explain when to use a component. Agents need the opposite more. Given a vague request, an agent reaches for the nearest match, and the nearest match is often wrong.

Good "when not to use" notes are short and concrete:

  • Don’t use the alert banner for success messages; use inline confirmation.
  • Don’t put more than one primary action in a view.
  • Don’t use a card to group a single line of text.

Each line closes off a mistake you’ve seen at least once. I treat every recurring agent error as a missing rule and write it down the same day. Over a few weeks the doc gets noticeably shorter in places and much sharper in others.

Tokens only from the root

The most effective rule I run is also the bluntest: no new colors, fonts, radii or shadows. Every value comes from a defined set of tokens. If a design seems to need something new, that’s a design decision for a person, not an improvisation for an agent.

On this portfolio, the palette, type families, radii and the one highlight effect are defined once at the root of the stylesheet, and every page draws from them. Cards have no strokes; emphasis is a soft teal glow. A new shade of grey is a change to the system, reviewed as a system change, never a one-off in a component. That discipline is what keeps a site largely built by agents looking like one site.

Tokens also make agent output reviewable. A change that adjusts spacing or color is a small, legible diff against a named value, not a pile of hard-coded numbers. If you’ve read my old essay on why great UIs run on grey, this is the same idea at the system level: restraint is a rule, not a mood.

Rules as checks, not just prose

Written rules are necessary and not sufficient. The rules that matter most should fail something when broken.

The clearest example on this site is width. Every page except the homepage shares one content column, and nothing inside it is allowed to break out sideways. That rule exists because content kept escaping the column, page after page, until it became the most repeated complaint in review. Now every release has to show evidence that nothing scrolls horizontally and that new content sits inside the column at six standard viewport widths, from small phones to desktop, with the menu both open and closed. If that evidence is missing, the release doesn’t go.

Location privacy works the same way. Certain place names can never appear in copy, metadata or the machine-readable files agents read. That is a standing ship gate today, checked on every go-live. An automated build test to enforce it is queued; until it lands, the check is part of every release review.

The build itself runs a test suite and fails closed: structural regressions, missing metadata, banned terms in published writing. The specific checks matter less than the principle. If a rule is important enough to complain about twice, it’s important enough to automate.

One gate per change

Agents produce a lot of change, quickly. The temptation is to review in batches, or to trust a green build. I’d rather have one gate per release, tied to the exact change being shipped. A reviewer, human or agent, checks that specific version against the rules and either passes it or sends it back with notes. Nothing goes to production that wasn’t the thing that was checked.

Fail closed is the important part. If the gate can’t verify something, the answer is no, not "probably fine."

What still needs a human eye

None of this replaces judgment. Rules catch violations. They don’t catch mediocrity. The things I still review personally:

  • Composition. A page can follow every rule and still have no hierarchy. Agents are good at assembling compliant parts and weak at deciding what matters most on the screen.
  • Taste. The difference between acceptable and good is rarely a rule. It’s usually subtraction: one fewer element, one less color, a tighter line.
  • When to break a rule. Sometimes the system is wrong. Deciding that, and updating the system so the exception becomes the new rule, is design leadership, not maintenance.

That’s where the quality bar comes in, and it’s a separate discipline from the rules themselves.

A short checklist

If agents are writing UI against your system, start here:

  1. List the ten mistakes you’ve seen agents make most. Write a "when not to use" rule for each.
  2. Freeze the token set. New values require a person and a review.
  3. Pick the two rules that matter most and make them fail the build.
  4. Gate every release on the exact change, and fail closed when evidence is missing.
  5. Keep composition and taste reviews human, and write down what you learn from them.

The pipeline view of all this, from research to ship, lives in AI action stacks. The system view is simpler: if you want agents to build like your team, write down what your team already knows, then make the important parts impossible to ignore.

Related Agentic UX patterns: plan, progress, interrupt, hand offTesting agent products before users do: scripted failure cases as the new usability testWhen AI is the UI, design moves underneath

See more workGet in touch