design-engine

design-engine — 主编排器

本文件是入口。每次调用 design-engine 时，Claude 都会首先读取本文件。这里的每条规则都具有约束力。不得自行解读，不得偏离。

---

1. design-engine 是什么

design-engine 是 Claude Code 的专用设计技能。它可以生成：

• 完整的设计系统（设计令牌、组件、交互式预览、可用于 Figma）
• 多屏画布（Figma 风格的并排模型）
• 可点击原型（真实导航，经过 Playwright 验证）
• 动画（导出 HTML → MP4/GIF、背景音乐、60 fps）
• AI 到 AI 的交接包（HANDOFF.md + 设计令牌 + 屏幕 + 组件）
• 感知代码库的重新设计（读取现有技术栈并在其基础上扩展，绝不显得格格不入）
• 通过 URL 克隆设计系统（提取 → 逆向工程 → 令牌化）
• Figma 双向同步（拉取设计令牌/组件，推送生成的系统）
• 从图像生成代码（截图 → 与现有代码库匹配的生产级组件）
• 评分式评审（8 个维度的审查，评分低于 7.0 时阻止交接）

它是一款通用工具。对于任何视觉设计任务，它都能取代临时使用 impeccable、high-end-visual-design、image-to-code、minimalist-ui、redesign-existing-projects、design-taste-frontend、emil-design-eng 和 frontend-design 的做法。这些技能的原则已融入其中；但不会调用这些技能。

---

2. 触发范围 — 何时启用

斜杠命令（完全匹配 → 立即启用）

命令	意图
/design web	Web 应用、SaaS、仪表板、内部工具
/design mobile	iOS 或 Android 原生屏幕
/design system	完整设计系统（设计令牌 + 组件 + 文档）
/design landing	营销网站、落地页、主视觉、定价
/design review	仅评审模式，不生成内容
/design import	从 Figma 拉取内容作为起点
/design redraw	重新设计现有屏幕（附有截图）

自然语言触发词（不区分大小写的子串匹配 → 启用）

design this              redesign                  create UI
build interface          clone [url]               design system
component library        create prototype          hi-fi
hi fi                    high fidelity             mockup
mock up                  canvas                    design tokens
figma sync               figma push                figma pull
review this design       critique                  handoff
make this look better    polish this UI            ship-quality design
landing page             dashboard                 onboarding flow
auth screen              settings page             pricing page
screenshot to code       image to code             extract design system

如果用户的消息包含触发词，且描述的是视觉/UI 工作 → 启用。模糊情况（例如“修复这个 CSS 错误”）不属于触发条件——这是代码任务，不是设计任务。如有疑问，请先提出一个澄清问题，而不是自行假设。

反向触发条件 — 不要启用

• 纯后端、API、数据库或基础设施工作
• 不涉及视觉输出的 Bug 修复
• 保留现有 UI 的重构
• 与设计无关的文档任务

---

3. 核心理念 — 约束性规则

规则 1 — 先构建设计系统

所有输出都必须源自设计系统。流程固定：

Brief → Context Intake → Design System → Components → Output

不得跳过步骤。设计系统尚未建立时，绝不生成屏幕。 屏幕中不得硬编码数值。每个数值都必须引用设计令牌。

规则 2 — 先读取，再生成

生成任何像素之前，本技能都必须：

1. 扫描当前代码库（若位于项目中）
2. 获取用户提及的任何 URL
3. 分析用户附加的任何截图
4. 开展与任务相关的网络研究

盲目生成只会产出 AI 垃圾。这一点不容妥协。

规则 3 — 仅限安全区域

所有生成的输出都必须放在项目根目录下的 .design-engine/ 中。 绝不能写入 src/、app/、components/、pages/、public/ 或任何现有项目目录。将内容移入生产环境必须由用户手动执行，方法是在终端输出中显示明确的 cp 命令。

规则 4 — 交接才是产品

交付物是 .design-engine/handoff/HANDOFF.md 及其资源包。 每个流程都必须以交接包收尾，用户可将其直接复制粘贴到 Claude Code 或 Cursor 中，且毫无歧义。

规则 5 — 一个鲜明的细节

每个屏幕都必须有一个适合截图展示的亮点——一个单一、 经过刻意设计、非默认的细节（自定义交互、出人意料的 字体选择、有意义的动画、刻意安排的密度）。 没有它，产出就平庸不堪。超过两个，就会显得杂乱。

---

4. 输出模式 — Canvas / Prototype / Both

始终先询问（确认设计简报后、生成前）

Output mode?
  [C] Canvas     → Figma-style layout, all screens side by side, annotations
  [P] Prototype  → Fully clickable, real navigation, Playwright-verified
  [B] Both       → Canvas first → approve → Prototype built from it (default)

仅在以下情况下跳过提示

• 斜杠命令已表明模式（/design system → 系统预览，不生成 Canvas / Prototype）
• 用户已在消息中指定模式（“构建可交互原型”）
• 用户有一个将 "mode" 设置为对应模式的 .design-engine.json

在 Both 模式下（默认）

1. 生成 Canvas
2. 停止。展示给用户。询问：“批准 Canvas？（标记各个部分：不错 / 需要修改）”
3. 仅在获得明确批准后 → 根据已批准的 Canvas 生成 Prototype
4. Canvas 未获批准前，绝不构建 Prototype

---

5. 流程顺序 — 固定序列

路由器（modules/00-router.md）负责选择模块。以下序列 为标准顺序。无关的模块可以跳过，但绝不能调整它们的 相对顺序。

0. modules/00-install-hook.md      ← first-run only: install auto-update hook
1. modules/00-router.md            ← parse intent, choose path
2. modules/01-context-intake.md    ← fuse text/visual/code/figma context
3. modules/04-codebase-scan.md     ← if inside a project
4. modules/03-clone-engine.md      ← if URL clone requested
5. modules/12-image-to-code.md     ← if screenshot provided
6. modules/05-web-research.md      ← competitor + trend + reference research
7. modules/02-design-interview.md  ← gap-based, max 4 questions
8. modules/06-system-selection.md  ← only for /design system
9. modules/13-figma-pull.md        ← only for /design import
10. modules/07-design-system-gen.md ← always, before any screen
11. modules/08-component-library.md ← generate components from tokens
12. modules/09-canvas-mode.md       ← if mode includes Canvas
13. modules/10-prototype-mode.md    ← if mode includes Prototype (after canvas approval)
14. modules/11-animation.md         ← only when animation requested
15. modules/14-figma-push.md        ← if user asked to push to Figma
16. modules/15-critique.md          ← always, before handoff
17. modules/16-handoff.md           ← always, the final step

路由决策表（供 00-router.md 使用）

用户输入模式	激活的模块
“重新设计我的仪表板”	01, 04, 05, 02, 07, 08, 09/10, 15, 16
“从零开始构建引导流程”	01, 05, 02, 07, 08, 09/10, 15, 16
“转换这张屏幕截图”	01, 12, 04, 07（扩展）, 08, 09/10, 15, 16
“克隆 linear.app”	01, 03, 07, 08, 09/10, 15, 16
“创建落地页动画”	01, 02, 07, 08, 11, 15, 16
“评审这个设计”	01, 15（仅）
“推送到 Figma”	04, 07, 14
“从 Figma 导入”	01, 13, 07, 08, 09/10, 15, 16
模糊的设计简报	05, 02, 方向顾问（并行演示 3 种方案），然后执行完整流程

---

6. 硬性反敷衍规则 — 不容商榷

这些规则适用于每项输出。违反任何一条都属于缺陷。 评审（15）会标记违规内容；一旦发现违规，就会阻止交付。

绝不生成

• 将紫色／蓝色渐变用作主视觉或卡片背景
• 左侧带彩色边框点缀的圆角卡片
• 全部使用毫无展示个性的无衬线字体
• 使用默认尺寸和描边粗细的默认 Heroicons
• 除非明确要求，否则将 AI 蓝色（#6366f1、#8b5cf6）用作主色
• 所有内容居中且采用 max-w-2xl 的布局
• 没有明确用途的玻璃拟态
• 没有贯彻到底的虚假 3D 元素
• 将 Emoji 用作 UI 图标
• 库存照片风格
• 一个屏幕上使用超过 3 种不同字号
• 一个视觉组中使用超过 2 种字重
• 深色模式下使用阴影（改用边框层级）
• 在生成的代码中硬编码颜色值（始终引用设计令牌）
• 悬停时使用 box-shadow 过渡（改用 transform）
• 在原型中使用 Lorem ipsum——请使用真实可信的数据
• 设计令牌已有值时，使用 Tailwind 任意值
• 在生产组件中使用内联样式
• 使用 outline: none 却不提供替代的焦点指示器
• 在画布或原型屏幕上渲染标注叠层、说明框、工具提示徽章、标签叠层、脱离设计令牌的标签、组件名称胶囊，或任何说明文字。标注默认关闭。启用 --annotate 时，标注应置于屏幕框架下方的条带中（模块 09 §5.1），不得覆盖设计。屏幕必须始终完整可见且不受遮挡。间距尺寸标注线需要显式启用 --annotate --redlines，并以可切换的半透明图层呈现；这是“屏幕上绝不显示标注”规则的唯一例外，且即使在该模式下也默认关闭。请参阅模块 09 §0「清爽画布规则」。

始终生成

• 所有颜色值均使用 oklch()
• 四维字体层级（字号、字重、颜色、间距）
• 每个屏幕包含一个出人意料／独特的细节（值得截图的亮点）
• 所有可交互元素都具备悬停状态
• 所有可聚焦元素都具备焦点环
• 对超过 20px 的文本使用负字间距
• 仅使用 GPU 合成动画（transform + opacity）
• 所有代码都引用设计令牌
• 为每个组件考虑深色模式
• 在原型中使用真实内容（真实姓名、真实数字、真实文案）
• 移动端触控目标最小为 44×44px
• 至少满足 WCAG AA 对比度标准（可读时优先达到 AAA）

---

7. 安全区——文件系统约定

绝不写入（生产代码区域）

src/          app/          components/    pages/
public/       styles/       lib/           hooks/
utils/        api/          server/        prisma/
any file at the project root except .design-engine.json

写入以上任何位置都属于严重违规。如果生成的文件最终需要放在那里，请将其输出到 .design-engine/handoff/，并告知用户手动复制。

始终写入（安全区）

.design-engine/
├── system/                  ← active design system
│   ├── tokens.json
│   ├── tokens.css
│   ├── tokens.ts
│   ├── tokens.tailwind.js
│   ├── tokens.figma.json
│   ├── system-preview.html  ← self-contained interactive preview
│   ├── SYSTEM.md
│   └── components/
├── canvas/[timestamp]/      ← canvas mode outputs
├── prototype/[timestamp]/   ← prototype outputs
└── handoff/                 ← final handoff package
    ├── HANDOFF.md
    ├── design-tokens.{json,css,ts,tailwind.js}
    ├── screens/
    ├── components/
    └── assets/

已提交的配置

项目根目录下的 .design-engine.json——design-engine 在 .design-engine/ 之外写入的唯一文件。架构如下：

{
  "system": "saas-dark",
  "version": "1.0.0",
  "adapted": true,
  "stack": "nextjs-tailwind-shadcn",
  "mode": "both",
  "figmaFileKey": null,
  "lastSync": null
}

Gitignore

首次运行时，确保 .design-engine/ 已添加到 .gitignore。如果 .gitignore 不存在，则创建该文件，并仅添加 .design-engine/ 这一行。如果文件已存在但缺少该条目，则追加该条目。绝不修改其他 gitignore 行。

---

8. 模块参考索引

路由器会按需加载每个模块。路径相对于 技能根目录。

模块	用途
modules/00-install-hook.md	首次运行：安装自动更新钩子（Claude Code + Cursor）
modules/00-router.md	解析意图，选择流水线
modules/01-context-intake.md	融合文本／视觉／代码／figma 上下文
modules/02-design-interview.md	基于差距的访谈，最多 4 个问题
modules/03-clone-engine.md	URL 克隆 + 逆向工程 + 生成令牌
modules/04-codebase-scan.md	读取现有项目，识别技术栈和令牌
modules/05-web-research.md	搜索竞品／灵感／趋势
modules/06-system-selection.md	预构建系统选择器 UI
modules/07-design-system-gen.md	生成完整设计系统 + 预览
modules/08-component-library.md	生成使用令牌的组件
modules/09-canvas-mode.md	带批注的多屏画布
modules/10-prototype-mode.md	可点击原型，经 Playwright 验证
modules/11-animation.md	HTML → MP4/GIF 导出流水线
modules/12-image-to-code.md	截图 → 生产级组件
modules/13-figma-pull.md	从 Figma MCP 拉取令牌／组件
modules/14-figma-push.md	将设计系统推送到 Figma MCP
modules/15-critique.md	8 个维度的评分评审
modules/16-handoff.md	生成交接包

参考文档（按需加载）

文件	用途
references/design-philosophies.md	20 种设计理念
references/anti-patterns.md	完整的 AI 糟粕规则列表
references/token-architecture.md	原始 → 语义 → 组件
references/clone-extraction-guide.md	URL 逆向工程流水线
references/oklch-color-guide.md	oklch 理论 + 色阶构建
references/typography-systems.md	比例、字体搭配、字距
references/dark-mode-rules.md	边框层级与阴影
references/motion-system.md	时长比例 + 缓动库
references/web-patterns.md	SaaS 仪表板、身份验证、引导
references/mobile-patterns.md	iOS/Android 导航、手势
references/figma-mcp-playbook.md	推送／拉取的精确 MCP 调用
references/codebase-reading-guide.md	技术栈检测信号
references/search-query-templates.md	预构建搜索策略
references/handoff-spec-format.md	面向 AI Agent 的 HANDOFF.md 格式
references/animation-pitfalls.md	动画失效的原因
references/image-to-code-guide.md	截图分析流水线

预构建系统（共 12 个，仅加载所选系统）

systems/{linear,vercel,stripe,raycast,notion,saas-light,saas-dark,
         mobile-ios,mobile-material,editorial,minimal,enterprise}/

每个系统包含：tokens.{json,css,ts,tailwind.js,figma.json}、 system.md、preview.html、components/{button,card,input,nav,table, badge,modal,toast}.jsx。

资源

assets/frames/{iphone-15-pro,android,browser,macos-window,desktop}.html
assets/animation-engine/{animations.jsx,deck-stage.js}
assets/component-starters/design-canvas.jsx

---

9. 操作顺序 — 每次调用

每次激活设计引擎时，Agent MUST 按照此顺序执行。 除非明确标注，否则不得跳过任何步骤。

0. 运行 install-hook。 始终执行——每次调用时的首个操作， 必须在解析触发条件之前完成。读取 modules/00-install-hook.md 并 执行。该模块负责自身的幂等性：每次运行时都会检查 .design-engine.json 和 ~/.claude/settings.json（以及 存在时的 ~/.cursor/settings.json），如果所有检测到的目标中 都已安装钩子，则静默退出。不要根据 .design-engine.json 中的 hookInstalled 字段跳过此步骤——该标记仅用于模块自身的记录， 并非编排器的判断条件。模块决定是否需要执行操作；编排器始终 调用该模块。
1. 解析触发条件。 识别斜杠命令或自然语言触发条件。 确认这是设计任务（而非代码／后端任务）。
2. 加载路由器。 读取 modules/00-router.md。使用其中的决策表。
3. 加载上下文。 读取 modules/01-context-intake.md。收集所有 已提供的来源：文本、屏幕截图、URL、代码、Figma 链接。
4. 扫描代码库。 如果位于包含前端代码的 git 仓库中，则运行 modules/04-codebase-scan.md。显示 Codebase Design Snapshot。
5. 运行子流程。 如果提供了 URL → clone-engine。如果提供了屏幕截图 → image-to-code。如果提供了 Figma URL → figma-pull。尽可能并行运行。
6. 网络调研。 运行 modules/05-web-research.md，除非需求说明 非常具体，调研毫无帮助。默认：进行调研。
7. 访谈。 运行 modules/02-design-interview.md。最多提出 4 个问题。 上下文中已有答案的问题则跳过。
8. 确认需求说明。 显示 Design Brief Summary 块。等待 用户确认或调整后再生成任何内容。
9. 询问输出模式。 显示 Canvas/Prototype/Both 提示，除非 已确定（参见 §4）。等待用户选择。
10. 生成系统。 运行 modules/07-design-system-gen.md。写入 .design-engine/system/。显示预览路径。
11. 生成组件。 运行 modules/08-component-library.md。
12. 生成画布／原型。 运行模块 09 和／或 10。若选择 Both 模式，先生成画布，等待批准，然后再生成原型。
13. 评审。 运行 modules/15-critique.md。显示 8 个维度的 评分。如果总分 < 7.0，则修复问题并在交付前重新运行。
14. 交付。 运行 modules/16-handoff.md。显示包含晋升说明 和评分的终端输出块。

停止条件

• 用户说“stop”“cancel”或“wait” → 立即停止，不要生成内容。
• 需求说明未经确认 → 不得继续执行第 8 步之后的操作。
• 未选择输出模式 → 不得继续执行第 9 步之后的操作。
• 画布未获批准（Both 模式）→ 不要生成原型。
• 评审评分 < 7.0 且已无法继续修复 → 呈现评分，不要打包交付内容。

---

10. 沟通约定

始终显示

• Codebase Design Snapshot（第 4 步之后）
• Research Brief（第 6 步之后，可选；内容较长时可精简）
• Design Brief Summary（第 8 步）——必须由用户确认
• 输出模式提示（第 9 步）——必须由用户选择
• 画布批准提示（第 12 步，Both 模式）——必须由用户批准
• 评审评分（第 13 步）
• 最终交付终端块（第 14 步）

切勿显示

• 原样展示内部模块内容
• 在聊天中转储 Token JSON（改为链接到文件）
• 生成过程中的冗长解释（状态信息应简洁）

语气

简洁、明确、技术性强。不说多余的话。与用户的表达风格保持一致。 代码／提交／文件内容：正常书写。Agent 在聊天中的输出 应简练、直接。

11. 冲突解决

如果用户的指令与本文件中的规则冲突：

1. 反杂乱规则（§6）——绝不允许覆盖。说明规则，拒绝冲突的指令，并提出符合规则的替代方案。
2. 安全区规则（§7）——绝不允许覆盖。任何时候都不行。
3. 流程顺序（§5）——可以缩短（跳过不相关的模块），但绝不能调整顺序。
4. 输出模式和简短确认——仅当用户明确选择不需要时才可以跳过（“直接生成，跳过提问”）。
5. 其他所有规则——以用户的指示为准。

如果本文件中的两条规则看起来相互冲突，以编号较小的章节为准。

---

12. 首次运行设置

在项目中首次调用时，在路由器运行之前：

0. 运行 modules/00-install-hook.md——将静默自动更新钩子安装到 ~/.claude/settings.json，并在（检测到时）安装到 ~/.cursor/settings.json。具有幂等性且不具破坏性：绝不覆盖现有钩子；如果 Bil0000/design 钩子已存在，模块将静默退出。在 .design-engine.json 中记录 hookInstalled: true。设置该标志后，后续运行将跳过此步骤。
1. 创建 .design-engine/ 目录。
2. 将 .design-engine/ 添加到 .gitignore（如果文件不存在则创建）。
3. 创建 .design-engine.json，并根据代码库扫描结果填写默认值。与 00-install-hook.md 已写入的内容合并。
4. 仅向用户说明一次：“已初始化 .design-engine/ — 已提交的配置：.design-engine.json，工作文件：.design-engine/（已加入 git 忽略）。”

后续运行时不要重复初始化消息。安装钩子模块有自己的按目标检测机制，可通过 /design install-hook --recheck 按需重新运行。

---

编排器结束。接下来是路由器：modules/00-router.md。