Components render wrong
The guide says one thing, the built types say another, and nobody notices until an agent follows the guide exactly. In the audit that started this tool, five of eight guides had drifted from the actual types.
Three failures, one cause
Every team that lets agents write UI meets at least one of these. They look like three separate problems and they are not.
The agent invents components
It needs a <PageHeader />, cannot find one, and writes an
import for it anyway. Nothing in the repository ever said the system does not have that.
Two screens, assembled differently
Components say what exists. Nothing says how a page is put together, so each session decides again from the beginning.
A person who cannot find a component asks someone.
An agent cannot, so it fills the gap with <PageHeader /> silently.
More documentation cannot fix an absence. Only writing the absence down does.
Measure, fix, measure again
A report tells a team it has a problem. The distance between two runs tells them the fix worked. That loop is the whole product, and everything else is detail.
01
Score it
Nine dimensions, each 1, 3 or 5, each quoting the files that produced the number, so you can argue with the reading rather than the verdict.
02
Fix what can be fixed
Five fixes write files. Five write a task brief for your agent. Prop-table generation and example compilation need your own build, and a generic codemod would do that job badly, so those arrive as briefs that carry the traps rather than just the goal.
03
Prove it moved
score.json is committed, so the next run compares against the last one and CI fails when the number
drops. Documentation debt cannot land quietly beside a feature.
$ npx adsa-cli audit @acme/ui 1.4.0 — agent readiness 11/45 not ready 1/5 Agent instructions 1/5 Machine surface 1/5 Docs coverage 1/5 Docs freshness 3/5 Tokens 1/5 Patterns 1/5 Accessibility documentation 1/5 Verification 1/5 Gap handling Next: npx adsa-cli fix agents-md · 9 more in the report 11/45 sits above 0 of the 13 public design systems measured with this rubric.
$ npx adsa-cli fix --all create AGENTS.md — design-system section added create GAPS.md — created; fill in the real absences create .mcp.json — adsa server registered note restart your MCP client, then run `adsa doctor` skip guidelines/design-tokens.md — token documentation already exists create .github/workflows/adsa.yml — gates the score on every pull request create .adsa/fixes/coverage-gate.md — brief for your agent create .adsa/fixes/prop-tables.md — brief for your agent create .adsa/fixes/examples-check.md — brief for your agent create .adsa/fixes/a11y-docs.md — brief for your agent create .adsa/fixes/patterns-doc.md — brief for your agent Hand these briefs to your agent, then re-run `adsa audit`.
$ npx adsa-cli audit @acme/ui 1.4.0 — agent readiness 23/45 gaps to address 5/5 Agent instructions 5/5 Machine surface 1/5 Docs coverage 1/5 Docs freshness 3/5 Tokens 1/5 Patterns 1/5 Accessibility documentation 3/5 Verification 3/5 Gap handling Since the last run: 11 → 23 (+12) Next: npx adsa-cli fix tokens-doc · 7 more in the report
example/design-system-as-found · rubric 1.0 · every character is real output
A report you can argue with
One self-contained HTML file, a markdown twin, and a machine-readable score. This is the real output, not a mockup.
Two real files, running. The same six components, audited before the documentation work and after it — 11/45 and 45/45, both in this repository. Scroll them, open a dimension, tick something off. One file each, no dependencies, opening from disk, offline, years from now.
- The evidence, not just the score. Every dimension lists the files and counts that produced its number.
- A to-do list that runs. Each item is a command, ordered cheapest first, with the points it is worth.
- What is missing, by name. Undocumented exports, and imports naming components the system does not have.
- A badge and a CI gate, both reading the same committed score, so a drop shows up in a diff.
Nine dimensions, forty-five points
Each is scored 1, 3 or 5. A dimension that genuinely does not apply, like page patterns in a primitives-only library, is skipped, and a skip lowers the maximum instead of the score.
11/ 45
The example system in this repository, on its first run. Nine wedges, one per dimension, each sized by its share and coloured by its level — not a percentage. Hover a row to find its wedge.
agent-ready11/45
what the README badge says today
1 — nothing to follow
3 — partly there
5 — done, and enforced
First run · as found
- Agent instructionsWhen an agent opens this repo, does anything tell it how to use the system?No AGENTS.md, CLAUDE.md or equivalent in the repository.1/5
- Machine surfaceCan an agent query the system, or must it read files and guess?No MCP server, no docs CLI, no llms.txt, no published skills: an agent has to read files.1/5
- Docs coverageDoes every component a consumer can import have a guide?3 of 6 importable components have a guide (50%). Undocumented, first few: Badge, Modal, Table.1/5
- Docs freshnessIf a guide drifts from the code, does anything notice?4 guides, 7 code blocks, 0 with a prop table. No guide is marked as generated, so every table is hand-maintained.1/5
- TokensAre colour, spacing, radius and motion documented as named decisions?Token documentation: guidelines/design-tokens.md. Motion documented; spacing documented.3/5
- PatternsIs there anything above component level — how a real page is assembled?Components only. Nothing describes how a page is assembled.1/5
- Accessibility documentationDo the guides say which keys a component answers to, and what name it needs?0 of 4 guides carry a keyboard or accessibility section (0%).1/5
- VerificationCan an agent check its own work before calling it done?0 test files, 0 stories. No test, typecheck or lint script.1/5
- Gap handlingWhat happens when the system genuinely does not have the thing?Nothing lists what the system deliberately does not have. No stop-and-ask rule, so an unlisted gap gets filled silently.1/5
Real scores from three real runs, in the repository as example/design-system-as-found,
example/design-system and example/design-system-ready — 11, 23 and 45 out of 45.
npx adsa-cli rubric prints what 1, 3 and 5 mean for every dimension.
Where the field actually is
A score out of 45 means nothing until you know what 45 is worth. So here is the answer, measured rather than asserted: 13 public design systems, audited with this rubric, each at the commit named beside it.
agent-ready35/45
Astryx Meta
CLI-first, and the only one of these whose CI checks its own guides against its own code.
@astryxdesign/core
agent-ready25/45
shadcn/ui
The registry is the distribution: components arrive as source, and the docs arrive with them.
v4
agent-ready21/45
BoardUI
Ships its catalog, its patterns and its motion rules as an agent skill rather than a website.
npx boardui add + skill
agent-ready15/45
Untitled UI
The documentation is excellent, and none of it is in the repository an agent works in.
@untitledui/react
The other 9, in fullHide them again
-
Chakra UI29
/45chakra-ui/chakra-ui@67abe9f · @chakra-ui/react -
React Spectrum Adobe25
/45adobe/react-spectrum@4693fcc · @react-spectrum/s2 -
HeroUI23
/45heroui-inc/heroui@98553ce · @heroui/react -
Polaris Shopify23
/45Shopify/polaris@3f7954a · @shopify/polaris -
Mantine21
/45mantinedev/mantine@61049ec · @mantine/core -
Base UI MUI19
/45mui/base-ui@9f4551b · @base-ui/react -
Carbon IBM19
/45carbon-design-system/carbon@12277c6 · @carbon/react -
Primer GitHub17
/45primer/react@4dc92ec · @primer/react -
Radix Primitives WorkOS13
/45radix-ui/primitives@f7ecd5a · radix-ui
45 is nobody's score. The best-documented public design system reaches 35, and the middle of the field is in the low twenties. That is why the bands are cut at 31, 24 and 15 rather than at tidy percentages — a scale whose passing grade nobody has ever reached tells you nothing about your own repository.
This is not a ranking of design systems. It measures one thing: what a coding agent can find in the repository it is working in. A system whose documentation lives on an excellent website scores low here and may well be the better system for people. Untitled UI and Radix are near the bottom of this list and near the top of most people's.
$ npx adsa-cli reference the same table, printed from the tool — and every row reproducible with $ npx adsa-cli audit <your clone of it>
The number that changes minds
A score says how well documented a system is. The experiment says what an agent actually built with it.
Give an agent a real page to build using only your system, in a fresh session. Then count what it imported that does not exist. Nobody argues with that list.
This is the same measurement that produced the two rounds below: the first run against an undocumented system, the second after the fixes, with a written list of what the system deliberately does not have.
$ npx adsa-cli eval score ./page --system . against @acme/ui — 1 file, 8 imports, 5 components used invented: 3 PageHeader — src/settings.tsx FormRow — src/settings.tsx Toggle — src/settings.tsx forbidden packages: lucide-react raw palette: 2, first bg-gray-50 at settings.tsx:11 3 of 8 imports name components that do not exist, 1 import from a package the system forbids, 2 raw palette classes.
3/8
components invented, round one
0/24
components invented, round two
Put the number where it gets noticed
The score is committed to the repository, so the badge in your README reads the same file the gate in CI reads.
- agent-ready45/4531 and up — the example, fully documented
- agent-ready29/4524 to 30 — Chakra UI, the second-best measured
- agent-ready23/4515 to 23 — the example after
fix --all, and most of the field - agent-ready11/45below 15 — the same example on its first run
The bands are cut where the measured field sits, not at tidy percentages: thirteen public design systems run from 13 to 35 out of 45, so agent-ready starts at 31. The colour is the verdict; the number is the argument.
$ npx adsa-cli badge 
- Paste it in the README. A static shields.io URL, so nothing has to run for it to render.
- Or let it follow the file. Every audit also writes
.adsa/badge.json, a shields endpoint, for a badge that changes when the committed score does. - Gate it.
npx adsa-cli audit --gateexits non-zero when the score drops below the committed one, and--minsets a floor. Documentation debt stops landing quietly beside a feature.
What it will not do
A tool that overstates itself gets run once. These are the edges, stated before you install it.
It does not phone home
Everything runs locally against files on your machine. Nothing is uploaded, and there is no account. Read the source.
It does not write your patterns
Page-level patterns come from pages you already have, and no tool can invent them for you. The brief tells your agent how to write them from real screens.
It knows React best
Detection is built for React, TypeScript and markdown guides. Vue and Svelte are detected but less well covered, and it says so rather than scoring you badly for it.
It does not replace judgement
The score is a starting point. The skill exists because reading five guides yourself still finds things no counter can, like rules written as prose an agent cannot act on.
Find out in about a minute
No install, no config. Point it at the repository that holds your design system and read the report it writes.
$ npx adsa-cli audit $ npx adsa-cli fix --all $ npx adsa-cli audit # the delta is the deliverable