Report for @acme/ui

4 guides6 importable components7 code blocks read
React · TypeScript · Tailwind
2026-09-22
Not ready

There is nothing here for an agent to follow, so it will follow its own habits.

11/45 sits above 0 of the 13 public design systems measured with this rubric; Astryx leads at 35.

first run · 9 dimensions
3Components documented50% of 6
1Imports that do not existNamed in the guides, missing from the source
0Guides with keyboard docs0% of 4 guides

Documentation coverage

3 / 6
3 with a guide 3 without
BadgeModalTable

Look at these first

lowest three
Agent instructions

No AGENTS.md, CLAUDE.md or equivalent in the repository.

1/5
Machine surface

No MCP server, no docs CLI, no llms.txt, no published skills: an agent has to read files.

1/5
Docs coverage

3 of 6 importable components have a guide (50%).

1/5

The nine dimensions

11 / 45
Agent instructionsWhen an agent opens this repo, does anything tell it how to use the system?
1/5

Evidence

  • No AGENTS.md, CLAUDE.md or equivalent in the repository.

Where it sits

1No AGENTS.md or CLAUDE.md, or one that never mentions the design system.

3A file exists and names the package, but reads like a README: prose, no rules an agent can follow.

An agent with no instructions falls back on habits from other libraries: shadcn imports, raw Tailwind palette classes, a local components/ui folder.

Machine surfaceCan an agent query the system, or must it read files and guess?
1/5

Evidence

  • No MCP server, no docs CLI, no llms.txt, no published skills: an agent has to read files.

Where it sits

1Nothing. Docs are a website or markdown a human reads.

3One machine-readable entry point: llms.txt, a docs CLI, or published skills.

Reading .d.ts files burns context and teaches the agent the type, not the rule. A queryable surface answers the question the agent actually has.

Docs coverageDoes every component a consumer can import have a guide?
1/5

Evidence

  • 3 of 6 importable components have a guide (50%).
  • Undocumented, first few: Badge, Modal, Table.
  • Nothing in CI stops a new export from shipping without a guide.

Where it sits

1Under half of the exported components have a guide.

3Most have one, and nothing stops a new component from shipping without one.

A component with no guide is a component the agent will either skip or reinvent, and undocumented exports are where invented APIs come from.

Docs freshnessIf a guide drifts from the code, does anything notice?
1/5

Evidence

  • 4 guides, 7 code blocks, 0 with a prop table.
  • No guide is marked as generated, so every table is hand-maintained.
  • 1 import in the guides names a symbol this repo does not export, e.g. ButtonGroup in guidelines/button.md.
  • Nothing compares the guides to the code.

Where it sits

1Guides are hand-written prose; nothing compares them to the code.

3Prop tables or examples are generated, but regenerating is a manual step somebody has to remember.

Docs written next to the code look fine until something checks them. Guides that can only fail silently always drift.

TokensAre colour, spacing, radius and motion documented as named decisions?
3/5

Evidence

  • Token documentation: guidelines/design-tokens.md.
  • Motion documented; spacing documented.
  • 2 raw palette classes in guide examples, e.g. bg-gray-100, text-blue-600.

Where it sits

3Tokens exist and are documented, but examples still mix in raw values.

5Semantic tokens documented as tables, raw palette usage forbidden by lint, and motion and spacing covered as well as colour.

Without a token table the agent hardcodes hex values and raw palette classes, and every screen drifts a little further from the system.

PatternsIs there anything above component level — how a real page is assembled?
1/5

Evidence

  • Components only. Nothing describes how a page is assembled.

Where it sits

1Components only. Nothing describes a page.

3A pattern-to-component map: for this task, reach for these parts.

Components tell an agent what exists. Patterns tell it what to build. Without them each agent re-invents page structure from scratch.

Accessibility documentationDo the guides say how a component behaves for assistive technology — keys or gestures, focus, role and name?
1/5

Evidence

  • 0 of 4 guides carry a keyboard or accessibility section (0%).
  • No automated accessibility check found.

Where it sits

1Accessibility is not mentioned in the guides.

3Some guides mention it, written by hand and unevenly.

An agent cannot infer that behaviour from a prop table alone. On the web it ships a div that looks like a menu and answers to nothing; on mobile it ships a touchable with no accessible name and no role, silent to VoiceOver and TalkBack alike.

VerificationCan an agent check its own work before calling it done?
1/5

Evidence

  • 0 test files, 0 stories.
  • No test, typecheck or lint script.
  • No CI workflow found, so nothing runs on a pull request.

Where it sits

1Types only, or nothing. A human is the first check.

3Unit tests and lint, run by hand.

Speed is not the problem. An agent that cannot verify produces confident output nobody can audit.

Gap handlingWhat happens when the system genuinely does not have the thing?
1/5

Evidence

  • Nothing lists what the system deliberately does not have.
  • No stop-and-ask rule, so an unlisted gap gets filled silently.
  • No way for an agent to report a new gap where the next agent will read it.

Where it sits

1Nothing. The agent fills the gap silently with the nearest thing it knows.

3A written list of known absences and what to use instead.

An agent cannot tell 'this does not exist' from 'I have not found it yet', so it invents a component and moves on. More documentation cannot fix an absence.

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

What to do, in order

38 points on the table

Each row names the dimension it lifts, the score that dimension holds now, and the score it holds once the fix lands. The ones adsa writes itself come first; the rest ship as a brief for an agent to carry out.

  1. npx adsa-cli fix agents-mdAgent instructions
    15 adsa writes it
  2. npx adsa-cli fix mcp-configMachine surface
    15 adsa writes it
  3. npx adsa-cli fix ci-workflowVerification
    15 adsa writes it
  4. npx adsa-cli fix gaps-fileGap handling
    15 adsa writes it
  5. npx adsa-cli fix tokens-docTokens
    35 adsa writes it
  6. npx adsa-cli fix coverage-gateDocs coverage
    15 brief for your agent
  7. npx adsa-cli fix prop-tablesDocs freshness
    15 brief for your agent
  8. npx adsa-cli fix examples-checkDocs freshness
    15 brief for your agent
  9. npx adsa-cli fix patterns-docPatterns
    15 brief for your agent
  10. npx adsa-cli fix a11y-docsAccessibility documentation
    15 brief for your agent

thenRun npx adsa-cli audit again. The distance between the two runs is the deliverable.

Keep the score

.adsa/score.json

Commit the score, gate it in CI, and put the badge in your README so a drop shows up in a diff.

how it renders in the README

![Agent-ready 11/45](https://img.shields.io/badge/agent--ready-11%2F45-b91c1c)

History

1 run

One run so far. Commit .adsa/score.json and the next audit draws the distance between them.