agentic-design-system

# Agentic Design System

![Agentic Design System logo](./demos/public/brand/ads-mark.png)

Design governance for coding agents that build UI.

[See the live workshop](https://agentic-design-system.vercel.app) · [Read the design philosophy](./PHILOSOPHY.md)

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:

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

Verify what was installed:

```bash
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:

```text
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:

```markdown
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](./docs/INSTALL.md) for exact per-agent commands, destination
paths, activation instructions, updates, and a no-CLI fallback. The fuller
[`templates/agents-snippet.md`](./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:

```bash
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](./docs/INSTALL.md#no-cli-install).

## The loop

```text
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`](./skills/agentic-design-system) routes the task, defines the outcome, and orders the gates.

### Core pack

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

### Production and reference gates

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

### Creative pack

- [`design-variations`](./skills/design-variations) creates 3–5 structurally distinct directions in one disposable browser artifact before production implementation.
- [`whimsical-design`](./skills/whimsical-design) is opt-in for personality, delight, and expressive marketing work.
- [`world-build`](./skills/world-build) is opt-in for immersion and atmosphere.
- [`web-animation-design`](./skills/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`](./workflows/create-design-workflow.md) as the entrypoint.

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

A source checkout includes the full template set under [`templates/`](./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`](./templates/outcome-template.md)
- [`project-identity-template.md`](./templates/project-identity-template.md)
- [`reference-intake-contract.md`](./templates/reference-intake-contract.md)
- [`grader-report-template.md`](./templates/grader-report-template.md)
- [`run-report-template.md`](./templates/run-report-template.md)

## Rendered verification

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

```bash
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>
```

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.

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`](./testing/TESTING.md#frozen-adjacent-action-regression).

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

```bash
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:

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

See [`workflows/decision-provenance.md`](./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/`](./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](./docs/INSTALL.md)
- [Claude Code](./integrations/claude-code.md)
- [Codex CLI](./integrations/codex.md)
- [Cursor](./integrations/cursor.md)
- [OpenClaw](./integrations/openclaw.md)
- [Hermes](./integrations/hermes.md)

## MCP server (v0.2)

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`.

```bash
npx --yes ads-mcp@0.2.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. P