🎴 design-playbook

Evidence-backed UI delivery for coding agents.

✅ Review UI against declared criteria and evidence

For a frontend or product engineer changing an existing Web UI with a coding agent, design-playbook connects the request, acceptance criteria, evidence, and repair owner. Required evidence that is missing leaves the criterion blocked. Explicitly skipping the evaluator produces an audited: false skeleton, not an audited Pass. Findings point back to their owning declarations and blocking findings recirculate for repair. Evaluator review does not replace the named human's semantic approval or guarantee independent judgment.

Two surfaces carry this:

1. Acceptance with proof — ui-evaluator + the point-back ledger: findings must cite criterion-bound evidence, and the closure trail is part of the run, not a chat summary.
2. Existing-product UI work — design-baseline discovers, validates, or drafts the project's DESIGN.md before changing a live product, so the change stays consistent with what already shipped.

Current stage

As of 2026-09-24, this project is in maintainer self-use and maintenance. Catalog submissions and participant recruitment are paused. Existing install paths remain available; internal dogfood, historical examples, and automated replays are not evidence of external adoption or repeat use. New capability specs are proposals, not implementation or release commitments. Resumption requires an explicit maintainer decision, not a date or passing internal tests.

The 2026-09-25 bounded self-use exception permits the source checkout's read-only frontend scope report. It does not reopen recruitment, catalog submission, or release, and no measured time-saving is claimed. The boundary is recorded in ADR-0045.

⚡ One command, three artifacts

The mechanism behind that proof is one pass:

/design-playbook:design-io <your UI ask>

A Design I/O run uses bundled MCP configuration, subject to host support and runtime prerequisites, and records three core artifacts under .scratch/<run>/:

1. spec.md — the six-layer declaration of what good is (intent → acceptance), written before any UI
2. Decision report — shell + component semantics, written before any code
3. Point-back ledger — every acceptance finding states which declaration it violates, plus the closure trail

🎬 Try it

Claude Code

/plugin marketplace add https://github.com/Bandersnatch0x/design-playbook.git
/plugin install design-playbook@design-playbook

Codex

codex plugin marketplace add Bandersnatch0x/design-playbook
codex plugin add design-playbook@design-playbook

Then, namespaced (bare /design-io is a --plugin-dir dev alias only):

/design-playbook:design-io <your UI ask>

On Cursor, Windsurf, Gemini CLI, Zed, or any of 30 supported agents: see 🌐 Install on other agents. Honest degradation: 22 of the 30 are the generated AGENTS.md floor (orchestrator contract + MCP install guide, commands as prompt docs) — the tier table says exactly what each tier gets.

Codex install notes, the [mcp_servers.*] fallback when a marketplace is unavailable, and preview prerequisites: packages/design-playbook/codex/AGENTS.md.

Runtime prerequisites: a supported host with the relevant MCP tools registered, Python 3 for the bundled runtimes, and a local browser for Preview. Runtime capture additionally needs Playwright with Chromium and a reachable application with the required test data and login state. See the capture setup. An unavailable optional adapter is disclosed; required proof still cannot be treated as passed merely because capture was skipped.

claude --plugin-dir <abs>/packages/design-playbook          # dev load, no install
/plugin marketplace add <abs-to-repo-root>                 # local marketplace
/plugin install design-playbook@design-playbook

codex plugin marketplace add <abs-to-repo-root>
codex plugin add design-playbook@design-playbook

📸 Evidence, not promises

Acceptance records keep their evidence limits visible:

• Point-back — every acceptance finding names the spec, domain, or craft declaration that owns it. No free-floating "looks good".
• Recirculate — blocking findings flow back to the owning stage until they close; the closure trail is part of the run artifacts.
• No silent skip — skip the audit and the result still carries the point-back skeleton, but marked audited: false, which strict validation refuses as a final result.
• Missing is not inapplicable - missing required proof is blocked; not-applicable needs an unmet applicability condition and a reason, not an unavailable capture tool.

Historical cases and journey coverage: three independent requests, plus one complete current live run (case reader) that packages the whole chain — spec, real preview confirmations, Fill, craft audit, captured evidence, review, static handoff — with a cross-run review report. The SwarSight queue case retains its specification, design decisions, and review / repair record; it predates the current plan and capture requirements.

The images below are illustrated summaries of that historical case, not raw execution captures:

1 · ux-spec — six-layer spec before any UI	2 · ui-picker — decision report before code
3 · ui-evaluator — point-back + recirculate closure	Historical result — six case checks, not the current gate matrix

Preview review workbench — inspect a design, anchor feedback, then confirm or revise. The packaged human-confirmation record belongs to a separate onboarding-form task; it is not confirmation of the queue case or of production acceptance:

Browse the three cases and their boundaries, or the complete current run for an end-to-end record that includes a resume pause point and a generated static handoff. The retry interface is another task with local mock data, not a plugin execution.

🔁 The one-pass pipeline

Declare what good is before the code exists, generate against that declaration, then accept the result against the same declaration. Every run executes the same predictable Design I/O pass:

design-baseline? → reference-intake? → ux-spec? → plan? → (native-craft?)
  → ui-picker → (preview*) → fill → craft-guard† → (observe*†) → ui-evaluator†
                              ▲                                       │
                              └────────────── recirculate ───────────┘

Six declarations own what good is (spec · domain · craft · design · components · template); two contracts govern how work enters the pipeline (skill for timing, evaluator for acceptance + recirculate).

🧩 Skills & commands

Nine skills in the package (/design-playbook:<name>):

Eight commands: design-io (full pipeline) · ux-spec (spec only) · ui-review (accept only) · run-review (cross-run) · run-status (phase + resume narration) · run-handoff (static delivery package for a reviewed run) · doctor (install health) · component-distill (cross-run proposals, no automatic promotion)

🎚️ Run profiles (P1/P2/P3)

Every run declares a tier in the plan.md run-profile block — process weight stays proportional to change consequence. Upgrades are automatic the moment a correction signal appears; downgrades need the user.

Run-profile and re-entry decisions: ADR-0029. Maintainer documentation: Chinese documentation index.

🔌 Adapters (bundled)

Preview and Evidence MCP runtimes ship inside the main plugin (packages/design-playbook/mcp/ + .mcp.json with ${CLAUDE_PLUGIN_ROOT}). Marketplace install registers both tools with no second package; the orchestrator still probes and skips steps when a host has no MCP tools.

Docs: preview · evidence

🌐 Install on other agents

npx design-playbook init <agent>
# or: python packages/design-playbook/scripts/generate_adapter.py <agent>

Claude Code is the native surface. Tier-2/3 outputs are generated adapters with honest degradation. Current inventory: adapter matrix; tier semantics: ADR-0042.

🔗 Stack with ecosystem

Not another style/palette pack — this plugin owns the delivery pipeline, evidence semantics, and acceptance loop, and composes with the rest:

🪞 Honest limits

• Multimodality — understanding screenshot content depends on the host model's vision capability. The plugin only registers images (locator + SHA-256 + metadata); a host without vision rides your text description instead.
• Run Console — shipped and experimental: a local, single-run console projecting existing run artifacts so an operator can see intent, source verdict, blocker source, and next owner without opening raw files — including a derived Repair Packet and an explicit open-console continuation from run-status. It stays local and trial-gated (no external authorization yet), is not a cloud Workspace, and never becomes a second run-state authority.
• Packaging MCP config — marketplace path includes package-local MCP runtime config; published registry packages may omit a root MCP config and need explicit host registration.
• Console loopback on Windows — local Console open uses loopback transport; dogfood saw a transport abort there, so do not treat loopback as a fixed-platform guarantee.
• Proof vs. shape — scripts/validate_run.py machine-checks the run-artifact shape and the closure trail; it does not claim every future run is automatically high-quality UI. Historical verdicts apply only to their recorded cases, not a current end-to-end run or a statistical guarantee.

📄 License

MIT (authored content). See LICENSE + NOTICE. No rights claimed over any third-party playbook corpus.

Repo layout, maintainer scripts, and the engineering shell live behind the front door: package README · docs/agents · Contributing.

GitHub Issues are for user reports and feedback. Internal specs, plans, research, and work tickets stay local and untracked; see the issue policy.

Maintainers: automated acceptance covers the required matrix and an extra-project operator replay. Its simulated review inputs are regression fixtures, not external trial evidence.

中文说明 · Showcase · Releases · Workflow