Report for @acme/ui

4 guides6 importable components7 code blocks read
React · TypeScript · Tailwind
2026-09-09
Gaps to address

An agent will produce plausible, wrong UI here more often than not.

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
Docs coverage

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

1/5
Docs freshness

4 guides, 7 code blocks, 0 with a prop table.

1/5
Patterns

Components only. Nothing describes how a page is assembled.

1/5

The nine dimensions

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

Evidence

  • 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.

Where it sits

5Short and imperative: how to look a component up, how to import, which token classes are required, what is forbidden, what to run before finishing.

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?
5/5

Evidence

  • .mcp.json registers adsa.

Where it sits

5An MCP server or CLI that ships inside the package and answers from the installed version, so answers match the version the project has.

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.
  • CI runs a documentation check.

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 imports in the guides name symbols 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?
3/5

Evidence

  • 0 test files, 0 stories.
  • No test, typecheck or lint script.
  • CI: .github/workflows/adsa.yml.
  • The agent-readiness score itself is gated in CI.

Where it sits

3Unit tests and lint, run by hand.

5Every story rendered and checked for accessibility in CI, with a baseline that can only shrink, and one documented command an agent runs before finishing.

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?
3/5

Evidence

  • A list of known absences exists: GAPS.md.
  • The agent instructions tell the agent to stop and ask instead of inventing.
  • No way for an agent to report a new gap where the next agent will read it.

Where it sits

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

5The list, plus an explicit stop-and-ask rule in the agent instructions, plus a way to report a new gap that lands where the next agent reads.

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

26 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 tokens-docTokens
    35 adsa writes it
  2. npx adsa-cli fix ci-workflowVerification
    35 adsa writes it
  3. npx adsa-cli fix gaps-fileGap handling
    35 adsa writes it
  4. npx adsa-cli fix coverage-gateDocs coverage
    15 brief for your agent
  5. npx adsa-cli fix prop-tablesDocs freshness
    15 brief for your agent
  6. npx adsa-cli fix examples-checkDocs freshness
    15 brief for your agent
  7. npx adsa-cli fix patterns-docPatterns
    15 brief for your agent
  8. 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 23/45](https://img.shields.io/badge/agent--ready-23%2F45-a16207)

History

1 run

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