Method and measurement
Design knowledge an agent can build against
Today AI agents write most of the frontend code. So the way a design system is delivered has to change too. The hard part is not the code. It is keeping the rules of the design system true on both sides of the handoff, while the team stays in charge.
The problem
A design system is usually written for people: a documentation site, a Figma library, a set of conventions everyone has read once. An agent has read none of it. It reaches for the nearest plausible pattern, and the nearest plausible pattern is whatever was most common in its training data, not what this team agreed.
The failure is quiet. The code compiles, the screen renders, and a review catches only part of it. What leaks through is a second design system growing inside the first one.
The double condition is what makes this hard: agents must build reliably, and the team must keep the overview. Solving only the first is how a codebase becomes unreviewable.
The contract
An agent needs the rules in a form it can act on: which components exist, which variants, which tokens. The first answer was a lookup layer built for agents, an MCP server and a command line tool, so an agent could ask instead of read.
Asking is not enough on its own, because an agent that can ask can also skip asking. So the same rules hold where the work lands: a lint rule rejects a violation in the same step, types accept only the agreed variants, and a raw colour renders nothing. A violation fails, it does not get discussed.
When each check fires
From the first keystroke to CI. The earlier a check fires, the cheaper the fix.
You type
Types, in the editor.
instant
You save a file
Before a new file: does this already exist? After any edit: lint that file.
under 1 s
You finish a step
Only the checks the edits could have broken. Blocks, and names the fix.
1–3 s
You push
Everything that runs offline: types, lint, tests, key parity, contrast, generated files.
~1 min
CI
Plus browser checks: production build, accessibility sweep, screenshot diffs.
minutes
- While the work happens, in the same step
- Once, before a push and in CI
How it was measured
The architecture is not the interesting part. Whether it holds is. So it was measured: 29 realistic build requests, such as add this panel or build this screen. Each was answered under three conditions: the agent could read the repository, could only ask the lookup layer, or had neither.
Every answer was scored the same way: does it use the parts the request asked for, does it pass lint, does it type-check. Only the first answer counts. An earlier run reported a far more flattering number and was withdrawn: it kept re-rolling a request until the agent used a tool, so it measured the best of several attempts, not what an agent does when left alone.
The result
Results by access
29 build requests, three conditions, one answer each, first draw only.
| Measure | No access | Lookup layer only | Reads the repository |
|---|---|---|---|
| Asked-for parts used | 11 % | 46 % | 76 % |
| Lint-clean output | 7 of 29 | 20 of 29 | 25 of 29 |
| Passes type check | 24 of 29 | 19 of 29 | 27 of 29 |
| All three at once | 0 of 29 | 7 of 29 | 16 of 29 |
Reading the repository, the agent used 76 per cent of the parts the request asked for. With only the lookup layer, 46 per cent. With neither, 11 per cent. Reading beat the lookups on 15 requests and lost on none.
Most lookups were never made: with the lookup layer available, the agent did not ask once in 25 of 29 requests. Per question, asking cost a fraction of reading. Per answer it saved nothing, because the question was never asked.
One question, two ways
Tokens per question, measured while the lookup layer existed. Bars are scaled per row.
What does Button do?
5× less
read the source
1,077
ask the lookup layer
206
What colour is warning?
72× less
read the stylesheet
7,579
ask the lookup layer
105
What states does Button have?
60× less
read all stories
26,113
ask the lookup layer
433
Requests in which the agent asked: 4 of 29
It answered the other ones without asking.
The type check alone would rank them differently: with nothing to read, the agent passed it more often than with the lookup layer. That is why no measure is read alone.
What changed
The lookup layer was removed. It was a second copy of the truth, and two copies drift apart. Agents that opened the source got the same answer from the thing that cannot drift, because it is what runs.
Today the rules sit where people and agents read anyway: in types, in doc comments on the components and in Storybook's docs, generated from the source. The checks stayed, and they catch a violation in the same step it is written.
How a question gets answered today
The source is the only copy, and the check answers in the same step.
A question
- Does it exist?
- What is the API?
- Which colour?
- Which rule?
Read
types · doc comments · Storybook
The source itself, not a copy of it
Write the code
Hooks check it
in the same step
Names what is wrong, and what to use instead
What the measurement taught
Findable is not adopted. Describing a rule better changed nothing. What worked was the check that rejects the violation in the same step.
Doing nothing can outscore doing the task. A prohibition only counts when the right thing was possible. Otherwise a screen that builds nothing passes.
One axis can lie. A file that builds nothing compiles cleanly.