Agentic Design System

A design practice for coding agents.

Live workshop | Install ADS | How it works | Documentation

Coding agents can make a screen quickly. Agentic Design System helps them understand the product, choose an appropriate approach, inspect the rendered result, and revise before calling the work done.

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-review reviews product fit, hierarchy, accessibility, and rendered quality.
• ux-baseline-check covers loading, empty, error, interaction, responsive, and edge states.
• ui-polish-pass finishes spacing, alignment, typography, controls, and interaction details.

Scoped specialists

• agent-friendly-design covers semantic and machine-readable interfaces.
• visual-reference-calibration interprets supplied visual references.
• design-variations explores genuinely unresolved directions.
• web-animation-design handles motion, easing, gestures, and interruption.
• whimsical-design and world-build add 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 ads-mcp@0.3.0 setup
npx --yes ads-mcp@0.3.0 --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.

License

MIT