🎴 design-playbook

给 coding agent 的 Design I/O — 用声明 + 契约让 UI 生成可控、可验收、可回流。

不是又一套风格/色板库。与 ui-ux-pro-max + frontend-design 互补；本插件管链路与验收。

✨ 它是什么

Claude Code / Codex 插件。每次跑同一条可预测链路 — Design I/O：design-baseline? → reference-intake? → ux-spec? → plan? → (native-craft?) → ui-picker → (preview*) → fill → craft-guard → (observe*) → ui-evaluator，验收把每个问题指回所属声明，blocking 必须回流直到闭环。? 为条件入场：已有产品的 UI 修改先跑 design-baseline?，有截图/URL/设计稿/产品类比时再跑 reference-intake?；preview*/observe* 仅在对应可选 MCP 工具（preview_prototype / execute_capture_plan）存在时运行，否则跳过直进下一阶段。

• 声明 （什么是好）：spec · domain · craft · design · components · template
• 契约 （怎么进链路）：skill（时机）· evaluator（验收 + 回流）

🎬 试一把：/design-playbook:design-io <需求> — 一次通过产出 spec.md、决策报告与 point-back 台账，落在 .scratch/<run>/（产物形态见 showcase/01-spec.md）。真实项目实跑：showcase/ 是对 SwarSight 的一次完整 Design I/O 实测 — spec、决策报告、point-back 评审 + 闭环回流轨迹。

📦 安装

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

Codex 安装细节、marketplace 不可用时的 [mcp_servers.*] 直配 fallback、preview 前置条件（系统 Chromium + python）：见 packages/design-playbook/codex/AGENTS.md。preview*/observe* 仅在对应 MCP 工具注册后运行，否则编排器静默跳过（不是报错）。

claude --plugin-dir <绝对路径>/packages/design-playbook      # 开发加载，免安装
/plugin marketplace add <仓库根绝对路径>                     # 本地 marketplace
/plugin install design-playbook@design-playbook

codex plugin marketplace add <仓库根绝对路径>
codex plugin add design-playbook@design-playbook

调用一律带命名空间：/design-playbook:design-io <需求>。裸 /design-io 仅 --plugin-dir 开发态别名。

🧩 Skills 与命令

八个 model 触发 skill（/design-playbook:<名>）：

命令：design-io（全链路）· ux-spec（只出 spec）· ui-review（只验收）· run-review（跨 run 复盘）· run-status（阶段与恢复叙述）· doctor（安装面健康）

🎚️ Run 档位（P1/P2/P3）

每个 run 在 plan.md run-profile 块声明档位——流程重量与变更后果成正比。代理按声明触碰面判据初判、用户一次确认；升档自动（纠偏信号一出现即升档并补走新增环节），降档需用户。

完整矩阵与重入语义见 docs/specs/ui-ux-vnext/loop-prototype.md。

🔗 与生态组合

🔌 适配器（v0.3+ 随主插件打包）

Preview / Evidence MCP 运行时已放进主插件（packages/design-playbook/mcp/ + 带 ${CLAUDE_PLUGIN_ROOT} 的 .mcp.json）。marketplace 安装后即可注册两个工具， 无需第二包。orchestrator 仍会探测；宿主无 MCP 工具时跳过对应步骤。

文档：preview · evidence

🗂️ 目录结构

.claude-plugin/marketplace.json   ← 仓库根 catalog（source: ./packages/design-playbook）
packages/design-playbook/         ← 公开插件（skills、commands、mcp/、examples、showcase）
packages/design-playbook/mcp/     ← 打包的 Preview + Evidence MCP 运行时
packages/design-playbook-preview/ ← 兼容 launcher + 文档（G5）
packages/design-playbook-evidence/← 兼容 launcher + 文档（G6）
docs/agents/  docs/adr/           ← 工程壳（tracker、workflow、决策）
CONTEXT.md  .scratch/             ← 词汇表、spec、票、dogfood 日志

运行产物落在你项目的 .scratch/<run>/ 下——见package README与 SKILL.md steps 3、5、8。

维护脚本： scripts/doctor.py（安装健康检查）、packages/design-playbook/scripts/run_status.py（从 run 产物推导 status/resume）、scripts/release.py（发版门禁）、scripts/validate.py（静态插件表面）。

仓库根 = GitHub 门面 + 工程壳 · package = 唯一运行时表面 · product-* 维护命令只留根，绝不进 package。

📄 许可

MIT（原创内容）。见 LICENSE + NOTICE。不主张任何第三方 playbook 内容的权利。