design-playbook

design-playbook

Evidence-backed UI delivery for coding agents.

✅ Review UI against declared criteria and evidence

Agents cannot grade their own UI. design-playbook makes them prove it, criterion by criterion: required evidence missing leaves the criterion blocked, and skipping the evaluator still produces an audited: false skeleton — never an audited Pass.

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. Findings point back to their owning declarations, blocking findings recirculate for repair, and evaluator review never replaces the named human's semantic approval.

Every finding points back to its declaration	The spec exists before any UI

Current stage

[!NOTE] As of 2026-09-26, this project is in maintainer self-use and maintenance with bounded exceptions. 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.

Dated exceptions recorded in ADR-0045: the read-only frontend scope report (2026-09-25) and the Preview visual-editing capability (2026-10-09, local validation only). They do not reopen recruitment, catalog submission, or release, and no measured time-saving is claimed.

⚡ 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>/:

🎬 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 details, 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.

The marketplace catalog lives at the repo root (not the package):

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

Version SSOT: packages/design-playbook/package.json and packages/design-playbook/.claude-plugin/plugin.json stay version-locked; the sibling bundle, root catalog, README badges, and generated Codex snapshot follow them.

📸 Evidence, not promises

Acceptance records keep their evidence limits visible:

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 control shell also carries a bounded visual-editing capability (resize, drag move, text and colour edits through the inspector; local validation only, no source writer). 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.

The repo also carries design-playbook-workbench, a separate single-maintainer, loopback-only local design-asset workbench authorized under ADR-0045; it is not part of the installable plugin and ships nowhere yet.

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