Sections
Agentic Design System — a flower bed printed through a coarse dither

Your design system is documented for people.

An agent is not a person. It cannot ask a colleague, and it cannot tell this does not exist from I have not found it yet, so it invents a component and moves on, confidently.

ADSA — agentic design system audit — scores your system out of 45 on how well an agent can use it, writes the report, and fixes what it can.

GitHub Support this project

MITno dependenciesruns locally

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.

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.

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 9/45

   1/5 █····  Agent instructions
   1/5 █····  Machine surface
   1/5 █····  Docs coverage
   1/5 █····  Docs freshness
   1/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
$ 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`
  create guidelines/design-tokens.md — created; replace the example rows
  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

   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: 9 → 23 (+14)

example/design-system · 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.

.adsa/report.html

The real file, running. Scroll it, open a dimension, tick something off. Generated from the example system in this repository — one file, 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.

Not a percentage. Nine wedges, one per dimension, each sized by its share and coloured by its level. Hover a row to find its wedge.

1 — nothing to follow 3 — partly there 5 — done, and enforced

  1. Agent instructionsWhen an agent opens this repo, does anything tell it how to use the system?AGENTS.md, 20 lines. Contains an import rule, a lookup command, token rules, a list of what is forbidden, a check to run before finishing.
    5/5
  2. Machine surfaceCan an agent query the system, or must it read files and guess?.mcp.json registers adsa.
    5/5
  3. Docs coverageDoes every component a consumer can import have a guide?3 of 6 importable components have a guide (50%). Undocumented: Badge, Modal, Table.
    1/5
  4. Docs freshnessIf a guide drifts from the code, does anything notice?4 guides, 7 code blocks, 0 with a prop table. 1 import in the guides names a symbol this repo does not export.
    1/5
  5. TokensAre colour, spacing, radius and motion documented as named decisions?Token documentation: guidelines/design-tokens.md. 2 raw palette classes in guide examples.
    3/5
  6. PatternsIs there anything above component level — how a real page is assembled?Components only. Nothing describes how a page is assembled.
    1/5
  7. 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
  8. VerificationCan an agent check its own work before calling it done?0 test files, 0 stories. CI: .github/workflows/adsa.yml.
    3/5
  9. Gap handlingWhat happens when the system genuinely does not have the thing?A list of known absences exists: GAPS.md. The agent instructions tell the agent to stop and ask instead of inventing.
    3/5

Those are the example system's real scores, the same run as the report above. npx adsa-cli rubric prints what 1, 3 and 5 mean for every dimension.

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.

  1. agent-ready41/45enforced, and held there
  2. agent-ready31/45a real design system, today
  3. agent-ready23/45the example, after fix --all
  4. agent-ready9/45the same example, before

Four bands, cut at 85%, 60% and 35% of the maximum. The colour is the verdict; the number is the argument.

$ npx adsa-cli badge
![Agent-ready 23/45](https://img.shields.io/badge/agent--ready-23%2F45-a16207)
  • 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 --gate exits non-zero when the score drops below the committed one, and --min sets 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
GitHub Support this project