Audience
Who's reading this UI and what they came to do.
Loading, empty, and error states are part of the agentic design system verification scripts.
Agentic Design System
An open-source design kit your coding agent can borrow.
Design judgment is still yours. ADS is templates, skills, and checks your coding agent reads while it works on UI. Use the whole kit, or copy one useful piece.
give this to your agent
01
intent.
Name what the user is doing, what the UI must make obvious, and the operational state the screen has to create. The builder fills this before generating anything.
templates/outcome-template.md- accomplish: what the user needs to do- notice: what the UI must make obvious first- feel: confident / calm / oriented / safe alignment check: notice → feel → accomplish
02
baseline.
What the agent reads before writing anything. Project context, hard constraints, and the states that must be in scope. A visual reference is optional and only when it actually matters.
Domain
Domain nouns, core workflows, hard constraints.
States
Loading · empty · error · focus · mobile.
References
Screenshots or sites that matter — optional.
templates/project-identity-template.md · presets/ · reference-intake-contract.md
03
rubric.
Define what good means for this specific task before the agent builds. The task-specific criteria do most of the work. The default quality lens is the floor, not the whole judgment.
task-specific criteria
- What does “done” mean for this screen?
- What must the user be able to do, decide, or trust?
- What would make this fail even if all the boxes checked?
written in outcome-template.md
+ default quality lens (floor)
- Design Quality35%
- Originality30%
- Craft20%
- Functionality15%
in grader-report-template.md
04
evidence.
Receipts, not promises. Files changed, checks run, screenshots, run report fields. The agent attaches the artifacts before saying “done.”
checks against the file the agent wrote$ python3 anti-pattern-check.py App.tsx PASS state-check PASS accessibility-check - files: list of paths changed- screenshots: desktop + mobile attached- score: judge total / 50
templates/run-report-template.md · skills/design-review/scripts/
05
grader / revision.
A separate pass scores the evidence against the rubric. Three verdicts. The builder does not ship on its own — the grader (or you) decides.
Ships. The evidence cleared the rubric.
Builder iterates against the grader's note. Regrades.
Stops out. Escalate to a human reviewer.
templates/grader-report-template.md
the loop, executed
run it for real.
The five steps aren’t a diagram — they compile to a runnable workflow. An agent builds, a headless browser captures what actually renders, deterministic gates run on that evidence, and a separate grader judges the screenshots — not the source. The builder never signs off on its own work; it revises until the evidence clears.
orders screen · gated at 390 / 768 / 1280px · from evidence.json, not sourceiter1 build → capture → gate FAIL 12 axe · 114 touch targets <44px → needs_revisioniter2 revise → re-capture → gate FAIL touch 114 → 12 · axe still 12 → needs_revisioniter3 revise → re-capture → gate axe 12 → 0 · touch 12 → 0 · overflow clean PASS every gate clears at all 3 breakpoints → satisfied verdict: satisfied — three passes; ships only once the rendered evidence clears every gate
Because the gate reads rendered evidence, it can’t be satisfied by a comment that says // handles loading, empty, error. It iterates against what actually renders and ships only when every gate clears — and if it can’t close them, it returns failed rather than rubber-stamp. The difference between “my agent got better” and a receipt you can audit.
workflows/new-page-component.mjs · docs/loop-demo/
Get started
See how it fits your setup.
The kit is plain markdown, scripts, and templates. Use the whole thing, or copy one useful piece into your repo. Open source, MIT.