ADS is a repo-local skill pack. Your agent does the work; you keep the final say. It is not a hosted design agent, a component library, or a UI generator.
Start with one screen
1. Install ADS
Install the complete eleven-skill pack from the project where your agent works:
npx skills add aa-on-ai/agentic-design-system --agent codex --copy --yes
Replace codex with the installer ID for your agent:
The installer copies the skills and writes skills-lock.json. It does not edit AGENTS.md, CLAUDE.md, Cursor rules, or other project instructions. See the installation guide for verification, activation, updates, and a no-CLI fallback.
Hermes requires one additional native activation step from a Git checkout: run
hermes skills trust, then start a fresh Hermes session inside that repository. The
hermes-agent value above is the skills installer ID; hermes is the native runtime command.
2. Give your agent a real product task
Improve our account settings page. Keep our components and visual identity.
Make saving and validation clear. Show me the working result, checked on
desktop and mobile.
The orchestrator preserves the requested product, routes only the relevant guidance, and requires evidence that supports the actual completion claim. For substantial design handoffs, Ember reads that evidence and presents the scoped verdict by default.
The practice
understand → choose → work → prove → decide
The report is part of the product. Source checks help, but “looks good” is not evidence.
What is included
The agentic-design-system skill routes the task and loads only the support the task needs.
ember reads completed evidence for substantial design handoffs and presents a
concise review. It is not a second execution loop, independent reviewer, or repair agent.
Core practice
design-reviewreviews product fit, hierarchy, accessibility, and rendered quality.ux-baseline-checkcovers loading, empty, error, interaction, responsive, and edge states.ui-polish-passfinishes spacing, alignment, typography, controls, and interaction details.
Scoped specialists
agent-friendly-designcovers semantic and machine-readable interfaces.visual-reference-calibrationinterprets supplied visual references.design-variationsexplores genuinely unresolved directions.web-animation-designhandles motion, easing, gestures, and interruption.whimsical-designandworld-buildadd personality or atmosphere only when the brief calls for them.
Creative skills are not a default styling layer. Their trigger rules determine when they belong.
Evidence, not ceremony
ADS can capture requested states and breakpoints, run deterministic browser checks, and keep review findings tied to the rendered artifact.
Browser dependencies are installed into the consumer project, not bundled with the skills. After installing ADS, follow the browser runtime setup. Then capture from the consumer project:
node .agents/skills/design-review/scripts/capture.mjs "<running-route-url>" \
--states default,loading,empty,error \
--out evidence/<task>
That path matches the Codex and Cursor example above. Use .claude/skills/, skills/, or
.hermes/skills/ for the other installer targets.
The rendered gate checks serious accessibility violations, overflow, missing landmarks, state semantics, layout shift, undersized touch targets, and whether requested states actually rendered. Structural checks do not decide taste; unresolved visual judgment remains human judgment.
See the worked three-pass example, where the same screen moved from 12 serious accessibility violations and 114 undersized touch targets to zero of each before the final verdict.
Find your way around
Local MCP server
The independently runnable ads-mcp package exposes the ADS evidence spine as three local stdio tools: ads_render, ads_evaluate, and ads_trace.
npx --yes [email protected] setup
npx --yes [email protected] --root /absolute/path/to/project
It confines project files and run artifacts to the configured root and uses provider-neutral command adapters for optional visual judgment. Its MCP Registry name is io.github.aa-on-ai/agentic-design-system.
Repository map
skills/ installable skills and rendered checks
workflows/ focused design and review runbooks
templates/ outcome, reference, evidence, and report shapes
presets/ starter baselines for common product types
testing/ install, behavior, evidence, and regression checks
packages/ independently runnable integrations, including ads-mcp
demos/ the public workshop and product examples
docs/ current guides, release notes, and maintained evidence
Superseded evaluations, implementation diaries, and unused explorations are preserved in Git history. The current tree keeps supported guides and evidence referenced by the site or verification tools.
Verify a source checkout
npm ci
npm run playwright:install
npm run release:check
The release check validates metadata, installs a clean copy for all five supported agent targets, and exercises the package's render-authority, evidence, structured-finding, and evaluation-loop contracts.
The public workshop is a separate Next.js app:
npm --prefix demos ci
npm --prefix demos run dev
Limits
- Agents still need real product context.
- File placement does not prove runtime discovery or skill selection.
- Structural checks cannot decide whether a visual direction is tasteful.
- Without a configured visual judge, evaluation stops for human judgment.
- The grader loop is workflow-driven, not a hosted service.
Contributing
Recurring anti-patterns, clearer routing rules, and missing verification steps are welcome as focused issues or pull requests. For release mechanics, see RELEASING.md.