🎴 design-playbook

Agents ship UI nobody can verify. This plugin makes them prove it.

⚡ One command, three artifacts

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

One pass — MCP tools bundled, zero extra config — lands three 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, or any of 29 supported agents: see 🌐 Install on other agents.

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

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

The agent never quietly grades its own homework:

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

A full pass against SwarSight — a real third-party workbench, one ask, every key artifact kept:

1 · ux-spec — six-layer spec before any UI	2 · ui-picker — decision report before code
3 · ui-evaluator — point-back + recirculate closure	Result — all six gates green

Live human-confirm gate (preview*) — the generated prototype renders inside a review workbench: the spec's acceptance criteria sit in a checklist beside it (your ticks are recorded with the decision), and you can click elements, drag highlight boxes, sketch, or measure spacing to anchor feedback — then sign off or send it back for another round:

Full artifacts — spec, decision report, point-back critique, preview human-confirm demo, the live self-test surface: showcase/.

🔁 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

Eight model-invoked skills (/design-playbook:<name>):

Commands: design-io (full pipeline) · ux-spec (spec only) · ui-review (accept only) · run-review (cross-run) · run-status (phase + resume narration) · doctor (install health)

🎚️ 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.

Full matrix and re-entry semantics: docs/specs/ui-ux-vnext/loop-prototype.md.

🔌 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. Full capability matrix: docs/specs/2026-08-28-multi-platform-adapter.md.

🔗 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 — planned: 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. Not shipped yet, not a cloud Workspace, never a second run-state authority.
• 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. The showcase is a demonstrated pass, not 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.