iven/hms

Files

iven b0892706c8 fix(skills): Step 7 改为 design-handoff 自行实施，不再调用 huashu-design

原因: huashu-design 是纯设计 skill，加实施模式会导致人格冲突、
SKILL.md 膨胀、约束倒灌。design-handoff 已有 SPEC+截图+Token 映射，
直接在当前会话实施代码更自然。

2026-05-18 01:54:17 +08:00

7.4 KiB

Raw Blame History

name, description

name	description
design-handoff	设计交付编排器 — 调用 huashu-design 设计原型、解析生成 SPEC，再由本 skill 根据 SPEC 实施代码，覆盖从需求到实现的完整流程

设计交付编排器 (design-handoff)

编排从需求到代码实现的完整流程：

调用 huashu-design 设计 HTML 原型
解析原型生成 SPEC.md + 截图 + Token 映射
根据 SPEC 直接实施代码（不调用 huashu-design）

触发词

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 文件：

node .claude/skills/design-handoff/scripts/parse-prototype.mjs <html文件路径>

输出（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 生成截图：

node .claude/skills/design-handoff/scripts/extract-screenshots.mjs <html文件路径> <输出目录>

输出： PNG 文件到输出目录，文件名由中文标签自动翻译为英文。

若脚本不存在： 指导用户手动截图，保存到 docs/design/{原型名}/screenshots/。

Step 3: Token 匹配

调用 scripts/match-tokens.mjs 进行三层 Token 匹配：

node .claude/skills/design-handoff/scripts/parse-prototype.mjs <html> > /tmp/parse-result.json
node .claude/skills/design-handoff/scripts/match-tokens.mjs /tmp/parse-result.json .design/tokens.yml

三层匹配算法：

别名直查 — 在 aliases.prototype_keys 中查找已确认映射（支持值条件匹配，区分 patient/doctor variant）
值精确匹配 — 按 CSS 属性上下文消歧（borderRadius→radius, fontSize→typography）
色彩模糊匹配 — RGB 欧几里得距离 < 30 视为近似

若脚本不存在： LLM 自行读取 tokens.yml 执行匹配。

Step 4: 组件映射推断

读取 defaults/components.yml，按 DOM 特征推断组件映射。

Step 5: 交互推断

调用 scripts/infer-interactions.mjs 推断交互行为：

node .claude/skills/design-handoff/scripts/infer-interactions.mjs <html文件路径> .claude/skills/design-handoff/rules/interaction-rules.yml

Step 6: 组装 SPEC.md

将前 5 步数据组装为 SPEC.md，输出到 docs/design/{原型名}/SPEC.md。

Step 7: 实施代码

根据 Step 1-6 产出的 SPEC.md、截图和 Token 映射，在当前会话中直接实施代码。

实施流程：

读取 SPEC.md — 获取 Token 映射、组件清单、交互行为、未匹配项
读取截图 — 对照截图确认视觉还原度
创建/修改文件 — 在 apps/miniprogram/src/pages/ 下实现 Taro 页面
验证 — pnpm build 编译通过 + 长者模式适配

实施规则：

样式使用 var(--tk-*) CSS 变量，不硬编码数值
使用组件库已有组件（ContentCard, PrimaryButton, SectionTitle 等），参见 defaults/components.yml
交互行为按 SPEC.md 第 4 节实现
遵循 CLAUDE.md 中的小程序代码规范
长者模式：字号 ≥ 22px，间距按 elder 值
未匹配的 Token 需与用户确认后再补充到 .design/tokens.yml
新建组件时遵循 feedback-component-consistency 原则：不适配则新建，不外部覆盖

前置检查

执行任何步骤前，必须完成以下检查：

1. 输入验证

模式 A（从需求开始）： 无需输入文件验证，直接进入 Step 0。

模式 B（从原型开始）： 确认输入文件为 huashu-design 产物：

文件为 .html 格式
包含 React + Babel 的 script 标签
包含 Token 定义块（const T = {）

2. Token 配置文件初始化

检查 .design/tokens.yml 是否存在：

存在 → 直接使用
不存在 → 从 defaults/tokens.yml 复制

输出目录结构

docs/design/
  mp-00-visitor.html          # 原始原型（Step 0 产物或已有文件）
  mp-00-visitor/              # 交付包目录
  ├── SPEC.md                 # 设计规格文档（Step 6 产物）
  ├── screenshots/            # 截图目录（Step 2 产物）
  │   ├── home.png
  │   └── profile.png
  ├── tokens.json             # Token 匹配结果（Step 3 产物）
  └── META.yml                # 元数据

META.yml 格式

prototype: {原型文件名}
source: {HTML文件路径}
variant: patient | doctor
generated_at: {ISO 8601}
tokens:
  matched: {数}
  unmatched: {数}
components:
  total: {数}
  mapped: {数}
  new: {数}
interactions: {数}

终端输出

完成全部步骤后：

============================================================
设计交付完成: {原型名}
输出目录: docs/design/{原型名}/
模式: {完整流程 | 仅解析}
Variant: {patient | doctor}
Token 匹配: {matched}/{total} ({unmatched} 未匹配)
组件: {total} ({new} 需新建)
交互: {数} 项
下一步: 根据 SPEC 实施代码（Step 7）
============================================================

待确认项交互

完成 Step 1-6 后，若有 pending 或 unmatched Token，需与用户交互确认后再进入 Step 7。

脚本说明

脚本	用途
`scripts/parse-prototype.mjs`	解析 HTML 原型为结构化 JSON
`scripts/extract-screenshots.mjs`	Playwright 截图（裁掉设备框）
`scripts/match-tokens.mjs`	三层 Token 匹配
`scripts/infer-interactions.mjs`	交互行为推断

降级策略： 每个脚本缺失时，LLM 自行执行对应步骤。

模板与规则

文件	用途
`templates/spec-template.md`	SPEC.md 模板
`defaults/tokens.yml`	Token 注册表 + 别名映射
`defaults/components.yml`	组件映射规则
`rules/interaction-rules.yml`	交互推断规则

7.4 KiB Raw Blame History Unescape Escape