🎴 design-playbook

Design I/O for coding agents — declarations + contracts that make UI generation constrained, reviewable, and recirculatable.

Not another style/palette pack. Compose with ui-ux-pro-max + frontend-design; this plugin owns the pipeline and acceptance.

✨ What it is

A Claude Code / Codex plugin. One predictable pass per run — Design I/O: design-baseline? → reference-intake? → ux-spec? → plan? → (native-craft?) → ui-picker → (preview*) → fill → craft-guard → (observe*) → ui-evaluator, where acceptance points back to the declaration that owns each failure, and blocking findings recirculate until closed. ? = conditional entry (design-baseline? for UI work in an existing product; reference-intake? when screenshot/URL/design/product analogy is present); preview*/observe* run only when their optional MCP adapter is present (preview_prototype before Fill, execute_capture_plan after craft) — otherwise skipped. preview* is a human-in-the-loop confirm gate (G5); observe* captures criterion-addressable runtime evidence into a manifest the evaluator binds to a criterion (G6).

• Declarations (what good is): spec · domain · craft · design · components · template
• Contracts (how work enters the pipeline): skill (timing) · evaluator (acceptance + recirculate)

🎬 Try it: /design-playbook:design-io <your ask> — one pass lands spec.md, a decision report, and a point-back ledger under .scratch/<run>/ (artifact shape: showcase/01-spec.md). See it run on a real project: the showcase/ folder is a full Design I/O pass against SwarSight — spec, decision report, and point-back critique with a closed recirculate trail.

📦 Install

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

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

Invoke namespaced: /design-playbook:design-io <ask>. Bare /design-io is a --plugin-dir dev alias only.

🧩 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. The agent grades against the declaration-touch checklist, the user confirms once; 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.

🔗 Stack with ecosystem

🔌 Adapters (bundled in v0.3+)

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

Docs: preview · evidence

🗂️ Layout

.claude-plugin/marketplace.json   ← repo-root catalog (source: ./packages/design-playbook)
packages/design-playbook/         ← public plugin (skills, commands, mcp/, examples, showcase)
packages/design-playbook/mcp/     ← bundled Preview + Evidence MCP runtimes
packages/design-playbook-preview/ ← compatibility launcher + docs (G5)
packages/design-playbook-evidence/← compatibility launcher + docs (G6)
docs/agents/  docs/adr/           ← engineering shell (tracker, workflow, decisions)
CONTEXT.md  .scratch/             ← glossary, specs, tickets, dogfood logs

Runs land their artifacts under .scratch/<run>/ in your project — see the package README and SKILL.md steps 3, 5, 8.

Maintainer helpers: scripts/doctor.py (install health), packages/design-playbook/scripts/run_status.py (derive status/resume from run artifacts), scripts/release.py (tag gate), scripts/validate.py (static plugin surface).

Root = GitHub front door + engineering shell · Package = only runtime surface · product-* maintainer commands stay at root, never in the package.

📄 License

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