Agentic Design System

Agentic Design System

Design governance for coding agents that build UI.

See the live workshop · Read the design philosophy

Coding agents can produce a screen quickly. Agentic Design System gives them a repeatable way to decide what the screen is for, load the right product context, review the rendered result, attach evidence, and revise before calling it done.

ADS is a repo-local skill pack. It is not a hosted design agent or a UI generator.

Install

From the project where your coding agent works, choose the agent explicitly:

npx skills add aa-on-ai/agentic-design-system --agent codex --copy --yes

Verify what was installed:

npx skills list --agent codex --json

ADS supports these release-tested installer targets:

Agent	Installer ID	Project skill directory
Claude Code	claude-code	.claude/skills/
Codex	codex	.agents/skills/
Cursor	cursor	.agents/skills/
OpenClaw	openclaw	skills/
Hermes	hermes-agent	.hermes/skills/

Replace codex in the command with the installer ID for your agent. The installer adds all ten skills and writes skills-lock.json; it does not create or replace AGENTS.md, CLAUDE.md, Cursor rules, or other project instructions.

For one task, tell your agent:

Use the agentic-design-system skill for this UI task. Define the outcome, read the project baseline, run the applicable review chain, and return rendered evidence before calling it done.

For an always-on project setup, add this to the instruction file your agent reads:

For visual or UI work, load the installed `agentic-design-system` skill first and follow its routing and rendered-verification contract.

See the canonical install guide for exact per-agent commands, destination paths, activation instructions, updates, and a no-CLI fallback. The fuller templates/agents-snippet.md is useful when you clone the repository and keep the complete skills/, workflows/, and templates/ tree in your project.

Install an exact checkout

Use this when you are reviewing a branch or local change:

git clone https://github.com/aa-on-ai/agentic-design-system.git
cd agentic-design-system
npx skills add . --agent codex --copy --yes

If npx skills is unavailable in your agent shell, use the no-CLI install.

The loop

intent → baseline → rubric → build → rendered evidence → review → revise or release

Stage	What the agent must establish
Intent	The user, situation, desired outcome, and stop condition
Baseline	Existing product rules, components, tokens, screenshots, and prior decisions
Rubric	Fixed quality gates plus criteria specific to this task
Evidence	Rendered states and breakpoints, accessibility, overflow, touch targets, and screenshots
Review	A verdict that can send the artifact back for revision

The report is part of the product. “Looks good” is not evidence.

The four weighted rubric scores remain the verdict layer. Substantial reviews also emit structured findings beneath those scores: a fixed failure category, minor/major/blocker severity, the exact state and breakpoint, a concrete target or screenshot region, and the rendered evidence. Repeated findings become candidates for a rule or gate; they do not become one automatically.

What installs

Orchestrator

• agentic-design-system routes the task, defines the outcome, and orders the gates.

Core pack

• design-review checks hierarchy, product fit, anti-patterns, accessibility, and rendered quality.
• ux-baseline-check checks loading, empty, error, interaction, responsive, and edge states.
• ui-polish-pass finishes spacing, alignment, typography, and interaction details.

Production and reference gates

• agent-friendly-design covers semantic structure and machine-readable state for public products.
• visual-reference-calibration defines what to borrow from a screenshot, site, or visual reference before code is written.

Creative pack

• design-variations creates 3–5 structurally distinct directions in one disposable browser artifact before production implementation.
• whimsical-design is opt-in for personality, delight, and expressive marketing work.
• world-build is opt-in for immersion and atmosphere.
• web-animation-design is opt-in for motion and interaction feel.

Creative skills are not a default styling layer. Their trigger rules decide when they belong.

Start a task

Use workflows/create-design-workflow.md as the entrypoint.

Need	Workflow
Route a design or review task	create-design-workflow
Review mobile or responsive UI	mobile-review
Critique finished UI from a separate context	adversarial-design-review
Check package installation	install-usability-smoke
Critique onboarding docs	readme-docs-critique
Test whether a cold agent can use ADS	cold-agent-usage-test
Trace consequential decisions to exact loaded rules	decision-provenance

A source checkout includes the full template set under templates/. The installed orchestrator bundles the five runtime templates it references: outcome, project identity, reference intake, grader report, and run report. The most useful starting artifacts are:

• outcome-template.md
• project-identity-template.md
• reference-intake-contract.md
• grader-report-template.md
• run-report-template.md

Rendered verification

Source checks are an inexpensive pre-flight. Rendered evidence is the real gate.

python3 skills/design-review/scripts/anti-pattern-check.py <file.tsx>
python3 skills/design-review/scripts/state-check.py <file.tsx>
python3 skills/design-review/scripts/accessibility-check.py <file.tsx>

node skills/design-review/scripts/capture.mjs "<running-route-url>" \
  --states default,loading,empty,error \
  --out evidence/<task>

Those commands are repo-root paths for a clone. Installed agents run the same capture through the orchestrator's scripts/run-capture.mjs wrapper. The exact path for every supported installer is in integrations/, and the install matrix executes each one.

The rendered gate blocks serious axe violations, overflow, missing main landmarks, loading/error states without the corresponding live-region semantics, CLS above 0.1, undersized touch targets, and requested states that did not actually render.

Evidence format 2 also records the visual foundation contract's rounded one-edge borders, one-edge shadow candidates, forced uppercase, typography outliers, symbol-only controls, status-dot candidates, divider count, colons, and em dashes. Those new measurements are report-only while fixture precision is established.

After a finding-driven repair, ADS also sweeps adjacent actions before a grader can return satisfied. Status and instructional copy must agree with every visible nearby primary, secondary, toolbar, and inline action in each changed state and breakpoint. An enabled-looking contradiction in a read-only, disabled, offline, permission-limited, or destructive state becomes a major cues_affordances finding.

ADS behavior changes are guarded by the frozen v1.3.1 five-case regression suite. The release gate keeps its baseline immutable and requires a new candidate packet for changes under skills, workflows, templates, routing, or judge behavior. See testing/TESTING.md.

For a meaningful modification, capture the baseline and candidate with the same states and breakpoints, then compare them:

node skills/design-review/scripts/compare.mjs \
  evidence/<task>-baseline \
  evidence/<task>-candidate

The comparison records what changed. It does not decide whether the change was good.

For substantial runs that need causal traceability, capture loaded skill/source hashes once before the build and verify 3-7 final decisions once at report time. The provenance path is deterministic, adds no model/browser/network calls, and enforces a 250ms budget per operation:

node skills/agentic-design-system/scripts/decision-trace.mjs capture --help

See workflows/decision-provenance.md for the manifest, trace, and report commands. Tiny fixes and routine polish skip this path by default.

Worked example

docs/loop-demo/ preserves a real three-pass run on an Orders screen at 390, 768, and 1280px.

• Iteration 1: 12 axe violations and 114 undersized touch targets
• Iteration 2: 12 undersized touch targets remained
• Iteration 3: zero axe violations and zero undersized touch targets

Only then did the grader return satisfied.

Agent integrations

• Canonical install guide
• Claude Code
• Codex CLI
• Cursor
• OpenClaw
• Hermes

MCP server (v0.3.0)

The repository also contains a local stdio MCP package that exposes the ADS evidence spine as three 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

The MCP server is intentionally local-first. It confines project files and run artifacts to the configured root, renders web or startup-configured SwiftUI targets, and records model-free deterministic evidence by default. Provider-neutral command adapters can add explicit visual judgment without changing the three-tool API or silently selecting a model. The SDK v2 server accepts both legacy initialization and MCP 2026-07-28 discovery, while compatible hosts can render the optional ui://ads/review MCP App. See the ads-mcp package guide and v0.3 API contract. Its official MCP Registry name is io.github.aa-on-ai/agentic-design-system.

Repository map

skills/        installable agent skills and rendered checks
workflows/     task entrypoints and review runbooks
templates/     outcome, project identity, reference, grader, and report shapes
presets/       starter baselines for common product types
testing/       package and evidence-loop smoke tests
packages/      independently runnable integrations, including ads-mcp
demos/         the public workshop site and worked UI examples
docs/          influences, current audits, and archived provenance

Historical eval fixtures are intentionally kept under docs/archive/ instead of mixed into the current product path.

Verify a source checkout

npm ci
npm run playwright:install
npm run release:check

The release gate aligns version and skill manifests, installs a clean copy for all five supported agents, and reruns comparison, render-authority, production-evidence, structured-findings, and eval-loop authority smokes.

To exercise the public GitHub shorthand rather than the local checkout:

testing/install-smoke.sh aa-on-ai/agentic-design-system
testing/install-matrix.sh aa-on-ai/agentic-design-system

Status and limits

ADS is an early public package. The skills, templates, runbooks, and rendered checks are usable now. The grader loop is workflow-driven, not a hosted service.

• Agents still need real product context. Without a configured visual judge, evaluation stops for human judgment.
• Structural checks cannot decide whether a visual direction is tasteful.
• Separate grader context is recommended when the host supports it.
• Creative passes can over-steer utility UI, so they stay opt-in.

Influences

• Intent Engineering
• Anthropic Managed Agents: Define outcomes
• Agentic Rubrics as Contextual Verifiers for SWE Agents
• Karpathy autoresearch
• DESIGN.md
• make-interfaces-feel-better

See docs/influences.md for what ADS borrows from each source.

Contributing

If you find a recurring anti-pattern, a better routing rule, or a missing verification step, open an issue or pull request.

License

MIT