Can a coding agent use your design system?

Can a coding agent use your design system? A week ago I would have said yes without thinking. We have a component library, a Storybook and guides for most components. What else does it need? Then I checked, and the answer turned out to be less obvious.

Twenty minutes, mostly right

I gave Claude Code our design system repo at ExpoPlatform, the docs, and a few pages from our admin panel to rebuild with our own components. Twenty minutes later the pages existed and mostly worked.

Mostly: some components rendered wrong, the agent invented components that do not exist and gave them plausible names, and the patterns were inconsistent from one page to the next.

That result was more interesting than a clean one would have been. If an agent can build a working interface in twenty minutes, the question is no longer whether it can use a design system. The question is how well the system explains how it should be used. Our docs were written for people. A person can ask a colleague. A person can tell "this does not exist" from "I have not found it yet". An agent cannot do either, so when it cannot find something it makes it up and moves on.

The audit

I wanted a number, not a feeling, so I compared our system with systems that are already taking agents seriously: Astryx, Meta's agent-first design system, plus Serendie, SmartHR, v0 DS 2.0 and Board UI. Eight dimensions, five points each, and the same questions for everyone. Is there an entry point for an agent? Can it query the system, or must it read source and guess? Do the guides match the actual types? Is there anything above component level, a real page assembled from parts? Can the agent check its own work before it says "done"?

We scored 23 out of 40.

The two lowest dimensions were exactly the two things that broke in the experiment. API truthfulness: 5 of 8 guides had drifted from the actual types, so the agent was reading documentation for components that no longer looked like that. Composition guidance: there were no page-level examples at all, so it composed pages from scratch every time and got them different every time.

Eight fixes, one PR each

An audit that ends in a document changes nothing, so each finding became a pull request. All eight were reviewed, approved and merged.

1. An honest setup. A one-import setup that works exactly as written, and a CHANGELOG, because "which version am I looking at" is the first thing an agent cannot ask anyone.
2. AGENTS.md as the single entry point. Real commands, a map of the repo, the conventions, and a self-check the agent runs before reporting done. The guidelines went from 138 lines to 48, and shorter was the point.
3. Prop tables generated from the built types and checked in CI. Docs can no longer drift silently, because the build fails when they do.
4. An ESLint preset for consumers that catches what agents get wrong most often: raw palette colours, shadcn class names, Radix imports, the wrong icon set, barrel imports.
5. A verification loop. Every story renders in headless Chromium and runs axe in CI. The first run found 151 of 526 stories failing. All fixed, with only additive changes to the API.
6. Storybook exposed through MCP, so the agent asks for a story or a guide instead of reading source files.
7. A zero-dependency CLI inside the package itself: dense docs, search, a doctor and an init command, plus an MCP server. It reads the installed package, so it works inside a product repo with no Storybook running anywhere.
8. Motion tokens and a spacing guide, with the values taken from what the components already did rather than what a spec said they should do.

After the merge I ran the same audit again: 32 out of 40, up from 23.

What is still missing is the layer above components: page-level patterns, a list with filters, a settings screen, a detail view with a drawer, derived from real production screens and shipped as skills the agent can load. That is the thing that stops an agent from inventing a whole screen when the system already has one.

The post, and what people saved

I wrote this up as a post and offered the audit method as a prompt to anyone who asked.

• 62Kimpressions in two days
• 836saves
• 57comments
• 95+people asked for the prompt

The saves were the number I kept looking at. More people saved the post than reacted to it. Maybe people did not just find this interesting. Maybe they actually have this problem.

So I sent the prompt to everyone who asked, and then I read it again as if I had just received it. It was not good enough. You paste it, adapt it to your repo, and then you have to trust the answer. It cannot inspect anything. It gives you an opinion where you wanted evidence.

ADSA

So instead of improving the prompt, I built a tool. ADSA, Agentic Design System Audit, is a CLI that scans a design system repository and scores it on how well a coding agent can use it.

$ npx adsa-cli audit # score this repo, write the report$ npx adsa-cli fix --all # apply what can be applied, brief the rest$ npx adsa-cli audit # measure again

That loop is the product. The rest is detail:

• Nine dimensions, 45 points: agent instructions, machine-readable surface, docs coverage and freshness, tokens, patterns, accessibility, verification, and what happens when the system genuinely does not have the thing.
• One self-contained HTML report with the score, the findings and the recommendations. Easy to commit, easy to send to a team.
• Evidence under every score. File names, counts, the exact guides that drifted from the exact implementations. You can disagree with the reading, not just the verdict.
• adsa fix writes into the repo: AGENTS.md, generated prop tables, token docs. Changes go between markers, so running it twice does not duplicate anything.
• Monorepos, web, React Native, SwiftUI and Compose.
• An MCP server, a CI gate that fails when the score drops, and a README badge.
• Free, open source, zero dependencies.

The tool has its own site, with the rubric, the reference table of audited systems and the install command. I built it in the same week as the CLI, so people who found the post had somewhere to go that was not a DM.

Two things changed while building it.

I did not want the score to rest on my opinion, so I audited 13 public design systems at named commits and anchored the bands to that measured field. The best-documented public system reaches 35 of 45, and nobody reaches 45. A system in the low twenties is in the middle of the field rather than failing, and the report says so.

And one of the first people to try it told me the audit was wrong. He was right. His system was not built around React components at all. It was a stylesheet and a class vocabulary, because that is much easier to share between different engineering stacks. So I changed ADSA to understand that shape too. That is probably my favourite part of building it: the tool gets better when people challenge it.

What I took from this

AI generates code. A design system generates understanding. The components stay the same. What changes is three things around them: docs generated from the code rather than written next to it, a way for the agent to check its own work, and a way to query the system from wherever the agent happens to be working.

Context, rules and a feedback loop. Most of it a team can build in a few days. The whole thing here, from the first broken page to a published tool, took about a week.