Report for @acme/ui
2026-09-10
Agents can work in this system. Keep the gates that make that true.
45/45 is at or above Astryx (35), the highest of the 13 public design systems measured with this rubric.
first run · 9 dimensionsDocumentation coverage
6 / 6Every importable component has a guide.
Look at these first
lowest threeAGENTS.md, 20 lines.
.mcp.json registers adsa.
6 of 6 importable components have a guide (100%).
The nine dimensions
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?
5/5
Evidence
- 6 of 6 importable components have a guide (100%).
- CI runs a documentation check.
Where it sits
5Effectively all of them, and CI fails when a new export arrives without a guide.
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?
5/5
Evidence
- 12 guides, 18 code blocks, 6 with a prop table.
- 12 guides carry a generated marker.
- Every symbol imported in the guides exists in the source.
- CI checks the guides against the code.
Where it sits
5CI regenerates the generated parts and compiles every code block in the guides against the built package. A guide that lies turns the build red.
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?
5/5
Evidence
- Token documentation: guidelines/design-tokens.md.
- Motion documented; spacing documented.
Where it sits
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?
5/5
Evidence
- Pattern-level docs: guidelines/patterns/detail-view.md, guidelines/patterns/empty-state.md, guidelines/patterns/index.md, guidelines/patterns/list-page.md.
- A task-to-component table exists in the guides.
Where it sits
5Page-level patterns with skeleton, states and traps, loaded on demand rather than always in context.
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?
5/5
Evidence
- 12 of 12 guides carry a keyboard or accessibility section (100%).
- At least some of those sections are generated rather than hand-written.
- Accessibility checks run in CI.
Where it sits
5Every guide carries the full interaction contract for its platform — keys or gestures, focus or touch-target behaviour, role and naming requirements — generated from the primitives the component is built on.
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?
5/5
Evidence
- 1 test file, 6 stories.
- Scripts: test, typecheck, lint.
- CI: .github/workflows/adsa.yml, .github/workflows/docs.yml.
- Stories are rendered and tested in CI.
- Accessibility assertions run as part of that.
- The agent-readiness score itself is gated in CI.
Where it sits
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?
5/5
Evidence
- A list of known absences exists: GAPS.md.
- The agent instructions tell the agent to stop and ask instead of inventing.
- A gap can be reported with `gap:report`.
Where it sits
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.
What to do, in order
0 points on the tableEach 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.
- Nothing to fix.
Every dimension is at 5. Keep the gates that hold it there.
thenRun npx adsa-cli audit again. The distance between the two runs is the deliverable.
Keep the score
.adsa/score.jsonCommit 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
History
1 runOne run so far. Commit .adsa/score.json and the next audit draws the distance between them.