diff --git a/.claude/skills/design-handoff/SKILL.md b/.claude/skills/design-handoff/SKILL.md index 0b9a086..2a2c597 100644 --- a/.claude/skills/design-handoff/SKILL.md +++ b/.claude/skills/design-handoff/SKILL.md @@ -1,17 +1,151 @@ --- name: design-handoff -description: 将 HTML 原型转换为结构化设计交付包（截图 + SPEC.md + Token 映射），供新会话 LLM 高保真实现 +description: 设计交付编排器 — 调用 huashu-design 设计原型、解析生成 SPEC、再调用 huashu-design 实施代码，覆盖从需求到实现的完整流程 --- -# 设计交付 Skill (design-handoff) +# 设计交付编排器 (design-handoff) -将 huashu-design 生成的 HTML 原型转换为结构化设计交付包，使新会话中的 LLM 能够高保真还原 UI 实现。 +编排 huashu-design 完成从需求到代码实现的完整流程： +1. 调用 huashu-design 设计 HTML 原型 +2. 解析原型生成 SPEC.md + 截图 + Token 映射 +3. 调用 huashu-design 根据 SPEC 实施代码 ## 触发词 - `design-handoff` - `设计交付` - `handoff` +- `设计并实现` +- `从设计到代码` + +--- + +## 输入模式 + +### 模式 A：从需求开始（完整流程） + +用户提供功能需求描述（无 HTML 文件），skill 执行 7 步完整流程。 + +**输入示例：** +``` +/design-handoff 患者端家庭档案管理页面，包含家庭成员列表、添加/编辑/删除操作 +``` + +### 模式 B：从原型开始（仅解析+实施） + +用户提供已有 HTML 原型文件路径，跳过 Step 0，从 Step 1 开始。 + +**输入示例：** +``` +/design-handoff docs/design/mp-13-family-profile.html +``` + +--- + +## 核心流程（7 步） + +### Step 0: 设计原型（仅模式 A） + +调用 huashu-design 生成 HTML 原型： + +``` +Skill("huashu-design", "设计 {用户需求描述}。要求：1) 使用 HMS 设计系统 Token（const T = {...}）2) 包含 IosFrame 设备框 3) 每个页面用 .screen-wrap 包裹 4) 输出到 docs/design/ 目录") +``` + +**关键要求传递给 huashu-design：** +- 使用项目 Token 系统（`const T = { pri: ..., bg: ..., r: ... }`） +- 每个页面/状态用 `.screen-wrap` 包裹并配中文 label +- 使用 `IosFrame` 组件呈现 +- 输出为单文件 HTML，保存到 `docs/design/mp-{编号}-{名称}.html` + +**完成后获得：** HTML 原型文件路径，进入 Step 1。 + +### Step 1: 解析 HTML 原型 + +调用 `scripts/parse-prototype.mjs` 解析 HTML 文件： + +```bash +node .claude/skills/design-handoff/scripts/parse-prototype.mjs +``` + +**输出（stdout JSON）：** +- `tokens`: T 对象所有键值对（如 `{"T.pri": "#C4623A", ...}`） +- `inlineStyles`: 内联样式值收集（按 CSS 属性分组） +- `screens`: 每个屏幕的标签和组件名 +- `components`: 所有组件函数定义列表 +- `variant`: `"patient"` 或 `"doctor"`（根据 T.pri 值自动检测） + +**若脚本不存在：** LLM 自行解析 HTML，提取 T 对象和 DOM 结构。 + +### Step 2: 截图 + +调用 `scripts/extract-screenshots.mjs` 生成截图： + +```bash +node .claude/skills/design-handoff/scripts/extract-screenshots.mjs <输出目录> +``` + +**输出：** PNG 文件到输出目录，文件名由中文标签自动翻译为英文。 + +**若脚本不存在：** 指导用户手动截图，保存到 `docs/design/{原型名}/screenshots/`。 + +### Step 3: Token 匹配 + +调用 `scripts/match-tokens.mjs` 进行三层 Token 匹配： + +```bash +node .claude/skills/design-handoff/scripts/parse-prototype.mjs > /tmp/parse-result.json +node .claude/skills/design-handoff/scripts/match-tokens.mjs /tmp/parse-result.json .design/tokens.yml +``` + +**三层匹配算法：** +1. **别名直查** — 在 `aliases.prototype_keys` 中查找已确认映射（支持值条件匹配，区分 patient/doctor variant） +2. **值精确匹配** — 按 CSS 属性上下文消歧（borderRadius→radius, fontSize→typography） +3. **色彩模糊匹配** — RGB 欧几里得距离 < 30 视为近似 + +**若脚本不存在：** LLM 自行读取 tokens.yml 执行匹配。 + +### Step 4: 组件映射推断 + +读取 `defaults/components.yml`，按 DOM 特征推断组件映射。 + +### Step 5: 交互推断 + +调用 `scripts/infer-interactions.mjs` 推断交互行为： + +```bash +node .claude/skills/design-handoff/scripts/infer-interactions.mjs .claude/skills/design-handoff/rules/interaction-rules.yml +``` + +### Step 6: 组装 SPEC.md + +将前 5 步数据组装为 SPEC.md，输出到 `docs/design/{原型名}/SPEC.md`。 + +### Step 7: 实施代码（全流程自动） + +调用 huashu-design 根据 SPEC 实施代码： + +``` +Skill("huashu-design", "请根据以下设计规格实现代码。 + +设计规格文件: docs/design/{原型名}/SPEC.md +截图参考: docs/design/{原型名}/screenshots/ +Token 映射: docs/design/{原型名}/tokens.json + +实现要求： +1. 严格按照 SPEC.md 中的 Token 值（var(--tk-*))）设置样式 +2. 使用映射的组件库组件（参见 SPEC.md 组件清单） +3. 实现所有交互行为（参见 SPEC.md 交互行为章节） +4. 未匹配的 Token 需确认后补充到 .design/tokens.yml +5. 遵循项目代码规范（CLAUDE.md）") +``` + +**关键要求传递给 huashu-design：** +- 读取 SPEC.md 中的 Token 映射，用 `var(--tk-*)` CSS 变量 +- 使用组件库中已有组件（ContentCard, PrimaryButton, SectionTitle 等） +- 实现交互行为（点击、滚动、表单提交等） +- 输出到正确的页面目录（如 `apps/miniprogram/src/pages/xxx/`） +- 遵循长者模式适配要求 --- @@ -21,265 +155,29 @@ description: 将 HTML 原型转换为结构化设计交付包（截图 + SPEC.md ### 1. 输入验证 -确认输入文件为 huashu-design 产物，须同时满足： -- 文件为 `.html` 格式 -- 包含 React + Babel 的 script 标签（`