Making our design system easier for coding agents to use
An agent built our admin pages in twenty minutes and invented components. The audit that followed, and eight fixes.
I spent the last few days making our design system easier for coding agents to use.
Where it started: I gave Claude Code our design system repo and docs and asked it to build a few pages from our admin panel with our own components. Twenty minutes later the pages existed and mostly worked. Mostly: some components rendered wrong, the agent invented components that don't exist, and the patterns were inconsistent.
That was more interesting than the result. If an agent can build a working interface in twenty minutes, the question is no longer whether it can use a design system, but how well the system explains how it should be used.
The audit: I compared our system with Astryx (Meta's agent-first design system), Serendie, SmartHR, v0 DS 2.0 and Board UI on how well an agent can read them. Eight dimensions, five points each. We scored 23/40. The two lowest, API truthfulness and composition guidance, were exactly what broke: 5 of 8 guides had drifted from the actual types, and there were no page-level examples at all.
The fixes, one PR each, all in review:
- Made the documented setup honest: a one-import setup that works as written, plus a CHANGELOG.
- AGENTS.md as the single entry point: real commands, repo map, conventions, and a self-check the agent runs before saying "done". Guidelines cut from 138 lines to 48.
- Prop tables generated from the built types and checked in CI. Docs can no longer drift silently.
- An ESLint preset for consumers that catches what agents get wrong most: raw palette colours, shadcn class names, Radix, wrong icon sets, barrel imports.
- A verification loop: every story renders in headless Chromium and runs axe in CI. First run found 151 of 526 stories failing. All fixed, with only additive API changes.
- Storybook exposed through MCP, so the agent queries stories and docs instead of reading source.
- A zero-dependency CLI inside the package (docs --dense, search, doctor, init) plus an MCP server. It reads the installed package, so it works in a product repo without Storybook running.
- Motion tokens and a spacing guide, with values taken from what the components already used.
Projected score once merged: 32/40.
Still missing: page-level patterns (lists with filters, settings, detail views with drawers) derived from real Figma pages or production screens, shipped as Agent Skills. That is what stops the agent from inventing whole screens when the system already has a pattern.
What I took from this. AI generates code, design system generate understanding. It is the same components plus three things: docs generated from 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 is working. Context, rules and a feedback loop. Most of it a team can build in a few days.
I turned the method into a prompt anyone can run on their own design system. DM me and I'll send it over.
Update, 14 September: the prompt became a tool. It is called ADSA, it is open source, and the whole story, from this post to the tool, is a case on the work page.