skema

Skema — 主控编排器

此文件是入口。每次调用 Skema 时，活跃的编码 Agent 都会首先读取此文件。此处的每条规则都具有约束力。不作解读。不得偏离。

---

1. Skema 是什么

Skema 是面向兼容编码 Agent 的统一设计技能。它可生成：

• 完整的设计系统（令牌、组件、交互式预览、适用于 Figma）
• 多屏画布（Figma 风格的并排模型图）
• 可点击原型（真实导航，经 Playwright 验证）
• 动画（HTML → MP4/GIF 导出、背景音乐、60fps）
• 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 中的原则。除非宿主 Agent 明确要求或用户提出，否则不要调用其他设计技能。

---

2. 触发范围 — 何时激活

斜杠命令（完全匹配 → 立即激活）

主要命令：/skema <subcommand>。向后兼容的别名： /design <subcommand> 和 /design-engine <subcommand> 的作用相同。

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

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

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、数据库或基础设施工作
• 不涉及视觉输出的错误修复
• 保留现有 UI 的重构
• 与设计无关的文档任务

---

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

规则 1 — 设计系统优先

每项输出都源自一个设计系统。流程固定：

Brief → Context Intake → Design System → Components → Output

绝不跳过步骤。系统建立之前，绝不生成屏幕。 绝不在屏幕中硬编码数值。每个数值都必须引用令牌。

规则 2 — 生成前先阅读

生成任何像素之前，技能 MUST：

1. 扫描当前代码库（如果位于项目内）
2. 用户提供 URL 且网络/工具可用时，获取该 URL 的内容
3. 分析用户附上的任何截图
4. 网络/工具可用时，开展与任务相关的网络调研

盲目生成会产出 AI 垃圾内容。如果网络或浏览器工具不可用， 请继续使用已提供的上下文，并说明已跳过调研。

规则 3 — 仅限安全区域

所有生成内容都必须写入相对于当前工作目录的 .skema/。在守护进程/UI 模式下，当前工作目录已经是项目工作区（例如 .skema/projects/<id>/），因此生成的文件应放在该工作区的 .skema/ 下。

绝不要写入 src/、app/、components/、pages/、public/ 或任何现有的生产目录。将内容移入生产环境必须由用户手动执行，具体操作是通过终端输出中显示的显式 cp 命令完成。

规则 4 — 交付是产品本身

交付物是 .skema/handoff/HANDOFF.md 及其资源包。 每个工作流最终都必须生成一个交接包，用户可以直接复制粘贴给 Claude Code、Codex、Cursor 或其他兼容的编码 Agent，且没有任何歧义。

规则 5 — 一个鲜明的细节

每个屏幕都要有一个可截图展示的亮点——一个经过刻意设计、非默认的细节（自定义交互、出人意料的字体排版、具有意义的动画或刻意设计的信息密度）。没有亮点，产出就平庸。亮点超过两个，就会变得嘈杂。

规则 6 — 完整的 HTML 文件

Skema 创建的每个 HTML 文件都必须是完整、独立的文档。绝不要在任何文件中写入“参见 index.html”之类的占位文本。每个屏幕都要有自己的完整 HTML 文档。

---

4. 输出模式 — 画布 / 原型 / 两者

始终先询问（确认需求后、开始生成前）

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)

仅在以下情况下跳过提示

• 斜杠命令已指定模式（/skema system → 系统预览，不生成画布/原型）
• 用户已在消息中指定模式（“构建一个可点击的原型”）
• 用户有一个将 "mode" 设为某值的 .skema.json

在“两者”模式下（默认）

1. 生成画布
2. 停止。向用户展示。询问：“画布是否通过？（标记各个部分：不错 / 需要修改）”
3. 只有在用户明确批准后，才从已批准的画布生成原型
4. 画布获批前，绝不要构建原型

---

5. 流水线顺序 — 固定序列

路由器（modules/00-router.md）负责选择模块。以下顺序为规范顺序。与任务无关的模块可以跳过；模块的相对顺序绝不能调整。

0. modules/00-install-hook.md      ← first-run only, when host supports hooks
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, if tools available
7. modules/02-design-interview.md  ← gap-based, max 4 questions
8. modules/06-system-selection.md  ← only for /skema system
9. modules/13-figma-pull.md        ← only for /skema 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. 硬编码的 Anti-Slop 规则——不可妥协

这些规则适用于所有输出。违反其中任何一条都属于缺陷。 Critique (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「画布净空规则」。
• 指向其他文件、而非包含实际屏幕内容的占位 HTML 文件

始终生成

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

---

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

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

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

写入上述任何位置都属于严重违规。如果生成的文件最终需要放在这些位置，应将其输出到 .skema/handoff/，并指导用户手动复制。

始终写入（安全区域）

以下路径均相对于当前工作目录。

.skema/
├── 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/

已提交的配置

项目根目录下的 .skema.json——Skema 在 .skema/ 之外写入的唯一文件。 架构：

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

Gitignore

首次运行时，确保 .gitignore 中包含 .skema/。如果 .gitignore 不存在，则创建该文件，并仅写入 .skema/ 一行。如果文件已存在但缺少该条目，则追加。绝不修改其他 gitignore 行。

---

8. 模块参考索引

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

模块	用途
modules/00-install-hook.md	在受支持的环境中设置首次运行钩子
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-slop 规则列表
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 兼容性

Skema 必须兼容 Claude Code、Codex、Cursor 及兼容的编码 Agent。

• Claude Code：支持原生斜杠技能加载，可能也支持 hooks/settings。
• Codex：frontmatter 描述必须少于 1024 个字符。Hooks 或 MCP 集成可能不可用。如果不支持，请在不安装 hook 的情况下继续。
• Cursor：hooks/settings 可能有所不同。不可用时不要失败。
• 其他 Agent：遵循文件系统/输出约定；跳过不支持的 集成，并说明跳过了哪些内容。

除非缺少的能力对用户要求的输出至关重要，否则特定宿主的设置绝不能阻塞设计流程。

---

10. 操作顺序 — 每次调用

每次激活 Skema 时，Agent 必须遵循以下顺序。除非明确标注为可选，否则不得跳过任何步骤。

0. 支持时运行 install-hook。 如果当前宿主支持本地 hooks/settings，则每次调用时首先执行此操作。读取 modules/00-install-hook.md 并执行。该模块负责自身的幂等性：检查 .skema.json、~/.claude/settings.json 和 ~/.cursor/settings.json（如果存在），若已安装则静默退出。如果当前宿主未提供兼容的 hook/settings 文件，则静默跳过并继续。
1. 解析触发方式。 识别斜杠命令或自然语言触发方式。 确认这是设计任务（而非代码/后端任务）。
2. 加载路由器。 读取 modules/00-router.md。使用其决策表。
3. 加载上下文。 读取 modules/01-context-intake.md。收集所有 已提供的来源：文本、截图、URL、代码、Figma 链接。
4. 扫描代码库。 如果当前位于包含前端代码的 git 仓库中，则运行 modules/04-codebase-scan.md。显示代码库设计概览。
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. 确认需求说明。 显示设计需求摘要块。等待用户确认或调整后，再生成任何内容。
9. 询问输出模式。 显示 Canvas/Prototype/Both 选项，除非已确定 （参见 §4）。等待用户选择。
10. 生成系统。 运行 modules/07-design-system-gen.md。写入 .skema/system/。显示预览路径。
11. 生成组件。 运行 modules/08-component-library.md。
12. 生成画布/原型。 运行模块 09 和/或 10。若选择 Both 模式， 先生成画布，等待批准后再生成原型。
13. 评审。 运行 modules/15-critique.md。显示 8 个维度的评分。 如果总分 < 7.0，则修复问题并在交付前重新运行。
14. 交付。 运行 modules/16-handoff.md。显示包含 promote 指令和评分的终端输出块。

停止条件

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

---

11. 沟通约定

始终显示

• 代码库设计概览（第 4 步之后）
• 研究简报（第 6 步之后，可选；内容较长时可精简）
• 设计需求摘要（第 8 步）——必须获得用户确认
• 输出模式提示（第 9 步）——必须获得用户选择
• 画布批准提示（第 12 步，Both 模式）——必须获得用户批准
• 评审评分（第 13 步）
• 最终交付终端块（第 14 步）

绝不展示

• 原封不动展示内部模块内容
• 在聊天中粘贴 Token JSON 转储（改为链接到文件）
• 生成过程中进行冗长解释（状态说明保持简洁）

语气

简洁、陈述式、技术性。不要说废话。匹配用户的表达风格。 代码、提交、文件内容：正常编写。Agent 的聊天输出本身 应简洁直接。

---

11.5 UI 模式（结构化 JSON 输出）

设置环境变量 SKEMA_UI_MODE=true 时，以换行分隔的 JSON（NDJSON）格式输出 Skema 流水线事件。每行 Skema 事件都必须是包含 type 字段的完整有效 JSON 对象。

激活方式： 环境变量 SKEMA_UI_MODE=true。

效果： 由 Skema 控制的标准输出应为 NDJSON 事件行。某些宿主 Agent 仍可能输出工具／状态杂音、警告或包装文本。确保 Skema 事件行有效且自包含，以便 UI 客户端解析 JSON 行并忽略非 JSON 行。

终端模式： 未设置环境变量时保持不变。

UI 客户端逐行读取流，将有效的 JSON 行解析为 JSON，并忽略非 JSON 的宿主杂音。各模块会在自己的文件中说明其事件（modules/00-router.md 会先输出 pipeline_start，然后各模块在运行时输出自己的事件）。

顶层事件类型

pipeline_start, pipeline_complete
intake_start, intake_complete
question, question_answered, interview_complete, brief_confirmed
research_start, research_update, research_complete
system_selection_prompt, system_selected, blend_decisions
todo_update
file_ready
canvas_approval_needed
playwright_result
critique_ready
handoff_ready
migration_complete
reference_loaded
inspect_complete
figma_local_start, figma_local_complete

每种事件的完整架构均记录在发出该事件的模块中。

终端模式约定：未设置环境变量时，输出行为与 §11 中的说明完全一致。不要求使用 JSON。结构没有差异。

---

12. 冲突解决

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

1. 反对低质内容规则（§6）——绝不覆盖。说明规则，拒绝冲突指令，并提出合规替代方案。
2. 安全区规则（§7）——绝不覆盖。无例外。
3. 流水线顺序（§5）——可以缩短（跳过不相关模块），但绝不能重新排序。
4. 输出模式和简短确认——只有用户明确选择退出时才可跳过（“直接生成，跳过提问”）。
5. 其他所有内容——遵从用户。

如果本文件中的两条规则似乎冲突，以编号较小的章节为准。

---

13. 首次运行设置

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

0. 在支持的情况下运行 modules/00-install-hook.md——将静默自动更新钩子安装到 ~/.claude/settings.json，并在检测到时安装到 ~/.cursor/settings.json。此操作幂等且不会造成破坏：绝不覆盖现有钩子；如果 Bil0000/skema-skill 钩子已存在，模块会静默退出。在 .skema.json 中记录 hookInstalled: true。如果宿主 Agent 不支持这些设置文件，则静默跳过此设置步骤并继续。
1. 创建 .skema/ 目录。
2. 将 .skema/ 追加到 .gitignore（如果文件不存在则创建）。
3. 根据代码库扫描结果填入默认值，创建 .skema.json。与 00-install-hook.md 已写入的内容合并。
4. 仅通知用户一次：“已初始化 .skema/ — 已提交配置：.skema.json，工作文件：.skema/（已加入 gitignore）。”

后续运行时不要重复显示初始化消息。安装钩子模块会针对每个目标进行独立检测，并会通过 /skema install-hook --recheck 按需重新运行。

---

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