Oct 10, 2026

7 min read

Your Design System Has a New Reader: AI Agents

I gave four AI agents the same prompt. The two with no system agreed on one colour. The two with a system agreed on 21. What building Weave taught me about writing a design system that machines can read.

Introduction

AI stopped making bad screens a while ago. Now it makes someone else’s.

When I asked a coding agent to build the same dashboard twice, both runs looked fine. They also picked the same arbitrary indigo and the same made-up product name. I chose neither. The model was not the problem. It had nothing to build from, so it decided for itself, and it will decide again next session.

That is a design system problem, not an AI problem. So I built Weave, a design system meant to be read by two kinds of reader: engineers and AI agents. Here is what I learned.

1. Agents don’t need taste. They need rules they can look up.

I ran four agent builds from one dashboard prompt. Two had nothing to read. Two had Weave.

The two without a system used 17 and 37 distinct colours, and shared exactly one. The two with Weave agreed on 21 values. Layout still varied, because the brief was open, but almost nothing else did.

Two runs each is a small test. The gap is not subtle, though. Agents are not short of ability. They are short of decisions they can find.

2. Give one system two doors

Engineers and agents read differently, so one system needs two entrances.

  • Engineers get a link: a live Storybook where they open a component, set its props with real controls, and use it as they see it.

  • Agents get a file: AGENTS.md, which loads before the first line of code.

The file is short and blunt. It has three kinds of rule:

  • The layer rule: components touch semantic and component tokens only.

  • Negative constraints: no raw hex, no primitives, no arbitrary margins.

  • A fallback protocol: if a pattern is missing, compose it from what exists, then log the gap.

The negative constraints did more work than any guideline. Telling an agent what never to do is easier to follow, and easier to check, than describing good taste.

3. Encode decisions in tokens, not in memory

Weave has three token layers. Primitives are raw values, like teal-700. Semantic tokens are named by job, like primary. Component tokens cover one usage, like an input border. Components never touch a primitive.

That one rule is why dark mode is automatic: it re-points the semantic layer at different primitives, and everything follows.

It is also where accessibility lives. Teal-700 carries white text at 6.27:1. Teal-600 is 4.21:1 and fails. So primary points at teal-700, and nobody, human or agent, has to remember why. The rule is encoded, not remembered.

4. Let a machine audit your docs, then audit the machine

I asked an agent to audit Weave against its own documented rules and change nothing. It found that my docs promised a 44px tap area on two controls. The code drew 32px, with nothing in the CSS to make the target bigger.

No linter catches that, because there is no bad code to flag. No design review catches it either, because the docs say it is handled. I wrote that claim myself. A machine found it.

The same audit reported 41 failures. 39 were imaginary: it checked see-through dark mode colours against a white background. It noticed, logged the cause, and then made the same mistake in the next audit.

So automated findings need checking, not trust. I read every finding against the source before accepting it.

5. Build a real screen to find what’s missing

Auditing finds what contradicts itself. Building finds what is missing.

When agents built a working dashboard using nothing but Weave, I logged every place the system fell short. There were 18 gaps. Some were simple, like cards fixed at 600px that should fill their parent. Some were whole missing pieces, like a calendar and a stat tile, which both builds invented differently. I have fixed 10. Of the 8 still open, six are docs that describe a slightly different system from the one that exists.

6. Scope your gates so they stay switched on

My first accessibility gate was strict. It failed 173 stories, mostly because a lone component has no main landmark. A gate that fails everything gets switched off, and then it protects nothing.

So I scoped it to the checks that make sense at component level. Less strict on paper, far more useful in practice.

What this means for designers

For years, a design system’s audience was people who could ask a question when something was unclear. Agents can’t ask. They read what is written and act on it, at speed, across every screen.

That raises the bar for the people who own the system. Decisions have to be explicit, written where a machine can find them, and checked against the code, because drift hides in the docs. Figma is still where I decide things. It is not where they become true.

Key Takeaway

A design system is no longer read only by people. Write rules an agent can look up, encode decisions in tokens instead of memory, and check every rule against the code, because a rule only holds if something checks it.

Be the first to know about every new letter.

Stay ahead in the world of web design with expert insights, industry trends, and practical tips.

No spam, unsubscribe anytime.