iven/hms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(skills): design-handoff 设计稿 + spec + .gitignore 更新

Browse Source 
- mp-11-doctor-core 设计交付包（截图 + tokens）
- mp-13/mp-14 新原型 HTML
- design-handoff skill 设计规格文档
- .gitignore 排除 dist-h5/test-results/uploads 等构建产物
This commit is contained in:
iven
2026-05-18 02:13:29 +08:00
parent ded37830fe
commit 3aa71a94d2
9 changed files with 2084 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

992
docs/superpowers/specs/2026-05-17-design-handoff-skill-design.md Normal file
View File

@@ -0,0 +1,992 @@
# design-handoff Skill 设计规格
> 日期: 2026-05-17 | 状态: 草案
> 问题: HTML 原型到实际实现的翻译层缺失，新会话 LLM 无法高保真还原原型设计
> 方案: 结构化交付包（截图 + SPEC.md + Token 映射）
## 目录
1. **背景与问题** — 现状分析、核心矛盾、解决目标
2. **Skill 架构** — 触发方式、输入输出、核心流程
3. **SPEC.md 核心格式** — 页面结构、组件映射、交互规格的文档模板
4. **Token 映射系统** — 混合匹配算法、配置文件、产出格式
5. **截图提取与交互推断** — Playwright 截图、交互规则引擎
6. **多平台支持与集成** — 多平台映射、huashu-design 协作、Prompt 模板
---
## 1. 背景与问题
### 1.1 现状
项目使用 `huashu-design` skill 产出 HTML 原型稿（React inline styles + 设计 Token 对象 `T`）。目前已有 **20 个原型文件**（`docs/design/mp-*.html`），覆盖小程序访客端、患者端、医生端全部页面。
实施时的工作流是：
1. **会话 A**：调用 huashu-design → 选定设计风格 → 扩展到所有页面原型
2. **会话 B**（新会话）：拿 HTML 原型实现 Taro/React 组件代码
### 1.2 核心矛盾
会话 B 的 LLM 与会话 A 完全隔离，丢失了所有设计上下文。三层翻译丢失：
| 丢失层 | 原因 | 表现 |
|--------|------|------|
| **视觉丢失** | LLM 读 HTML 源码，看不到渲染结果 | 颜色、字号、间距与原型不一致 |
| **Token 断裂** | 原型用 `#C4623A`，代码用 `var(--tk-pri)` | 映射关系丢失，硬编码泛滥 |
| **组件错配** | 原型全是 `<div style={...}>`，代码要用组件库 | 应复用 ContentCard/PageShell 但没复用 |
| **交互缺失** | 原型暗示的按压反馈、滑动、状态切换无文档化 | 交互行为被忽略 |
### 1.3 解决目标
创建 `design-handoff` skill，在 HTML 原型完成后自动产出**结构化交付包**，让新会话的 LLM 能：
- **看到**原型渲染效果（截图）
- **知道**每个值对应哪个项目 Token（映射表）
- **选用**正确的现有组件（组件映射）
- **实现**原型暗示的交互（交互规格）
---
## 2. Skill 架构
### 2.1 触发方式
```bash
# 单个原型
/design-handoff docs/design/mp-00-visitor.html
# 批量处理
/design-handoff docs/design/mp-*.html
# 指定平台
/design-handoff docs/design/mp-00-visitor.html --platform web
```
**触发词**：`design-handoff`、`设计交付`、`handoff`
### 2.2 输入
| 参数 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| HTML 文件路径 | 是 | — | 原型文件路径，支持 glob |
| `--platform` | 否 | `miniprogram` | 目标平台：miniprogram / web / h5 |
| `--tokens` | 否 | `.design/tokens.yml` | Token 映射配置文件路径 |
### 2.3 输出目录结构
```
docs/design/
├── mp-00-visitor.html # 原始原型（不修改）
├── mp-00-visitor/ # 交付包目录
│ ├── SPEC.md # 主规格文件（LLM 消费入口）
│ ├── screenshots/ # 截图目录
│ │ ├── home.png
│ │ ├── home-slide-1.png
│ │ ├── home-slide-2.png
│ │ ├── home-slide-3.png
│ │ └── profile.png
│ ├── tokens.json # Token 映射表（机器可校验）
│ └── META.yml # 元数据
├── mp-01-login/
│ └── ...
└── .design/ # 全局配置（项目级）
└── tokens.yml # Token 映射配置
```
### 2.4 核心流程
```
输入: HTML 原型文件
│
├─ Step 1: 解析 HTML ──────────────────────┐
│ 提取 T 对象（Token 引用） │
│ 提取组件树（页面结构） │
│ 识别 IosFrame 实例（截图目标） │
│ │
├─ Step 2: 截图提取 ───────────────────────┤
│ Playwright 打开 HTML │
│ 逐 IosFrame 截图 │
│ 裁剪设备框，保留屏幕内容 │
│ │
├─ Step 3: Token 匹配 ─────────────────────┤
│ 优先级 1: 别名直查（aliases） │
│ 优先级 2: 值精确匹配 │
│ 优先级 3: 色彩模糊匹配（ΔE < 3） │
│ 产出 tokens.json │
│ │
├─ Step 4: 组件映射 ───────────────────────┤
│ 原型元素 → 项目组件库匹配 │
│ 标记需新建的组件 │
│ │
├─ Step 5: 交互推断 ───────────────────────┤
│ DOM 模式 → 交互规则匹配 │
│ 高/中/低置信度分级 │
│ │
└─ Step 6: 组装 SPEC.md ───────────────────┘
截图 + 结构 + Token + 组件 + 交互
→ 单一规格文档
```
### 2.5 Skill 文件清单
```
.claude/skills/design-handoff/
├── SKILL.md # Skill 入口
├── scripts/
│ ├── extract-screenshots.mjs # Playwright 截图
│ ├── parse-prototype.mjs # HTML 解析（T 对象 + 组件树）
│ ├── match-tokens.mjs # Token 三层匹配
│ └── infer-interactions.mjs # 交互推断规则引擎
├── templates/
│ └── spec-template.md # SPEC.md 模板
├── defaults/
│ └── tokens.yml # 初始 Token 配置
└── rules/
└── interaction-rules.yml # 交互推断规则表
```
**前置依赖**：
- Node.js ≥ 18（运行 .mjs 脚本）
- Playwright（截图提取；huashu-design 已依赖，无需额外安装）
- 项目需包含 `styles/tokens.scss` 或等效的 Token 定义文件
---
## 3. SPEC.md 核心格式
SPEC.md 是 LLM 在新会话里消费的**唯一入口文件**。设计原则：
- **自包含**：截图通过 markdown 图片引用内嵌，一个文件看全貌
- **结构化**：六个固定章节，LLM 可按需定位
- **可操作**：每个值都映射到项目 Token 或组件，不含模糊描述
### 3.1 文档结构（六个固定章节）
```markdown
# {页面名称} 设计规格
> 来源: {原型文件名} | 平台: {platform} | 页面数: {n}
## 页面索引
（截图缩略图 + 路由映射表）
## 一、Token 映射
（原型值 → 项目 Token，含匹配状态标记）
## 二、页面结构
（逐页：截图 + 布局层级描述 + 尺寸标注）
## 三、组件映射
（原型元素 → 项目组件库组件，含来源路径）
## 四、交互规格
（元素 × 交互类型 × 触发 × 反馈 × 备注）
## 五、状态变体
（加载中 / 空数据 / 错误 / 已登录等边界状态）
## 六、样式清单
（间距 / 字号 / 圆角 / 阴影的 Token 汇总）
```
### 3.2 页面索引
用表格关联截图与路由，LLM 一眼定位：
```markdown
## 页面索引
| 页面 | 截图 | 路由 |
|------|------|------|
| 访客首页 | ![home](./screenshots/home.png) | pages/index/index |
| 访客"我的" | ![profile](./screenshots/profile.png) | pages/profile/index |
```
### 3.3 Token 映射章节
三级状态标记，LLM 知道哪些可以直接用：
| 标记 | 含义 | LLM 行为 |
|------|------|---------|
| ✅ confirmed | 已确认映射 | 直接使用对应 Token |
| ⚠️ pending | 模糊匹配，待确认 | 使用但需人工复核 |
| ❌ unmatched | 无匹配 | 硬编码或新建 Token |
```markdown
## 一、Token 映射
| 原型值 | 项目 Token | 状态 |
|--------|-----------|------|
| #C4623A (T.pri) | var(--tk-pri) | ✅ |
| #F5F0EB (T.bg) | var(--tk-bg-base) | ✅ |
| 32px (轮播标题) | var(--tk-font-h1) | ⚠️ 待确认（28→32 不匹配） |
| serif 字体 | — | ❌ 无 Token，硬编码 font-family |
```
### 3.4 页面结构章节
每个页面一个子节，**以截图开头**，紧跟布局层级：
```markdown
### 2.1 访客首页
![首页全貌](./screenshots/home.png)
布局层级（从上到下）：
1. **轮播区域** (height: 280px)
- 容器: `<Swiper>` (Taro)，autoplay + circular
- 3 张品牌轮播：渐变背景 + 装饰圆 + 标题文案 + 指示点
- 指示点: 活跃 24×4 白色，非活跃 8×4 半透明白
2. **健康资讯** (padding: 20px → var(--tk-gap-lg))
- 标题行: SectionTitle，serif 18px bold + "更多›"
- 文章卡片 ×2: ContentCard variant="default"
- 左侧配图 110px 宽，右侧标题 15px + 摘要 13px
3. **登录引导** (padding: 28px 20px 40px)
- CTA: PrimaryButton size="large"，阴影 var(--tk-shadow-btn)
```
每个元素标注：**用什么组件** + **尺寸/间距的 Token 引用** + **视觉特征**。
### 3.5 组件映射章节
表格形式，明确"用哪个组件"：
```markdown
## 三、组件映射
| 原型元素 | 推荐组件 | 来源 | 备注 |
|----------|---------|------|------|
| 文章卡片 | ContentCard | @components/ui/ContentCard | variant="default" |
| 区块标题 | SectionTitle | @components/ui/SectionTitle | action="更多›" |
| CTA 按钮 | PrimaryButton | @components/ui/PrimaryButton | size="large" |
| 页面容器 | PageShell | @components/ui/PageShell | padding="md" safeBottom |
| 功能卡片 | — | 需新建 | 3 列等宽圆形图标卡片 |
| 轮播 | Swiper | @tarojs/components | autoplay circular |
| TabBar | Taro TabBar | 框架配置 | 原型不实现 |
```
来源列使用 `@components/` 前缀，LLM 可直接 `import`。"需新建"标记让 LLM 知道这个需要从头写。
#### 组件映射推断规则（H4 修复）
组件映射通过 DOM 结构特征推断，规则定义在 skill 中：
| 原型 DOM 特征 | 推断组件 | 匹配依据 |
|--------------|---------|---------|
| 容器 + borderRadius + boxShadow + 内含标题+正文 | ContentCard | 卡片结构 |
| 容器 + 左侧竖线装饰 + 标题文本 + 可选右侧链接 | SectionTitle | 区块标题结构 |
| 按钮 + 主色背景 + 白色文字 + 高度 44-56px | PrimaryButton | CTA 按钮特征 |
| 按钮 + 边框 + 透明背景 | SecondaryButton | 次按钮特征 |
| 页面最外层容器 + padding + 滚动 | PageShell | 页面壳结构 |
| 圆形小容器 + 内含数字/文字 + 配色背景 | StatusTag | 标签/徽章 |
| 列表行 + 左图标 + 中间双行文字 + 右箭头 | ListItem | 列表项结构 |
| 未匹配上述任何规则 | — (需新建) | 标记为"需新建" |
推断失败时默认标记为"需新建"，不强制匹配错误组件。
### 3.6 交互规格章节
五列表格，覆盖触发 → 反馈 → 生命周期：
```markdown
## 四、交互规格
| 元素 | 交互 | 触发 | 反馈 | 备注 |
|------|------|------|------|------|
| 轮播 | 自动播放+滑动 | 页面显示 | 3s 切换 | useDidShow 启动，useDidHide 暂停 |
| 文章卡片 | 点击跳转 | onPress | activeFeedback="bg" | 跳转文章详情 |
| CTA 按钮 | 点击登录 | onPress | loading 态 | 跳转登录页 |
| 功能卡片 | 点击跳转 | onPress | opacity 反馈 | 各卡跳不同服务页 |
| 资讯区域 | 下拉刷新 | onPullDownRefresh | — | 无数据时显示功能引导 |
```
### 3.7 状态变体章节
覆盖边界场景，避免实现时遗漏：
```markdown
## 五、状态变体
- **无数据**: 资讯为空 → 显示功能引导卡片（3 个固定入口）
- **加载中**: LoadingCard layout="card" count=2
- **已登录**: 自动跳转 HomeDashboard（不由本页处理）
- **网络错误**: ErrorState + onRetry 重新加载
```
### 3.8 样式清单章节
Token 维度的汇总，便于 LLM 快速查表：
```markdown
## 六、样式清单
间距: 页面 padding 20px (--tk-gap-lg), 卡片 padding 16px (--tk-gap-md)
字号: 标题 18px (--tk-font-nav), 正文 15px (硬编码), 摘要 13px (--tk-font-cap)
圆角: 卡片 16px (--tk-card-radius), 按钮 14px (--tk-radius-lg)
阴影: 卡片 (--tk-shadow-sm), 按钮 (--tk-shadow-btn)
```
---
## 4. Token 映射系统
### 4.1 全局配置文件
项目级配置 `.design/tokens.yml`，所有原型共享。**首次运行自动生成**，从项目代码库扫描：
- `styles/tokens.scss` → CSS 运行时 Token（`--tk-*`）
- `styles/variables.scss` → SCSS 编译时变量（`$pri`, `$r` 等）
生成后可手动微调，后续运行直接读取。
配置文件结构分为五个 Token 类别 + 一个别名映射区：
```yaml
# .design/tokens.yml
version: 1
updated: 2026-05-17
# 色彩 Token — 从 tokens.scss 中 --tk-pri 等提取
colors:
- token: --tk-pri
value: "#C4623A"
- token: --tk-pri-l
value: "#F0DDD4"
# ...
# 字号 Token — 从 tokens.scss 中 --tk-font-* 提取
typography:
- token: --tk-font-h1
value: "28px"
note: 页面标题 serif bold
# ...
# 间距 Token — 从 tokens.scss 中 --tk-gap-* 提取
spacing:
- token: --tk-gap-md
value: "16px"
# ...
# 圆角 Token — 从 tokens.scss 中 --tk-card-radius 等提取
radius:
- token: --tk-card-radius
value: "16px"
# ...
# 阴影 Token — 从 tokens.scss 中 --tk-shadow-* 提取
shadow:
- token: --tk-shadow-sm
value: "0 1px 4px rgba(45,42,38,0.04)"
# ...
# 原型 Token 别名 — 手动或自动积累的映射
aliases:
prototype_keys:
T.pri: --tk-pri
T.priL: --tk-pri-l
T.bg: --tk-bg-base
T.card: --tk-bg-card
T.r: --tk-card-radius
T.rSm: --tk-radius-sm
# ...
```
### 4.2 三层匹配算法
从原型 HTML 中提取的每个 Token 引用，按以下优先级匹配：
```
优先级 1: 别名直查
原型中 T.pri → 查 aliases.prototype_keys → --tk-pri ✅
预估覆盖率: 最高（已有 aliases 的常用 Token）
特点: 零歧义，直接确认
优先级 2: 值精确匹配（按 CSS 属性上下文消歧）
原型中 #C4623A → 仅在 colors 类别中查找 → --tk-pri ✅
原型中 borderRadius: 16px → 仅在 radius 类别中查找 → --tk-card-radius ✅
原型中 padding: 16px → 仅在 spacing 类别中查找 → --tk-gap-md ✅
预估覆盖率: 中等（值恰好一致的 Token）
特点: 按 CSS 属性类别过滤，避免同值多 Token 歧义
优先级 3: 色彩模糊匹配（仅颜色类）
原型中 #C4623B → 与 colors 中各值算色差 ΔE
ΔE < 3 → 视为近似色 → ⚠️ pending 待确认
预估覆盖率: 较低（设计迭代中微调的色值）
特点: 仅限色彩，必须人工确认
未匹配: ❌ unmatched
无任何匹配结果
需人工决定: 新建 Token / 硬编码 / 忽略
```
**值归一化规则（M4）**：
- `"16px"` 和 `"16"` 视为相同（去除 px 后缀比较数值）
- `"#C4623A"` 和 `"c4623a"` 视为相同（大小写不敏感）
- 不支持 `rem`/`em` 转换，遇此单位标记为 pending
### 4.3 首次运行流程
```
/design-handoff docs/design/mp-00-visitor.html
Step 0: 格式校验（C3 弹性检查）
- 检查文件是否为合法 HTML
- 检查是否包含 React/Babel 脚本标签（huashu-design 特征）
- 检查是否包含 T 对象定义（const T = { ... }）
- 任何检查失败 → 输出清晰错误信息并终止
- 缺少 T 对象: "未检测到设计 Token 对象 (T)，请确认是否为 huashu-design 产物"
- 缺少 React: "未检测到 React 渲染环境，无法解析原型"
Step 1: 检查 .design/tokens.yml
→ 不存在: 自动扫描项目 SCSS 文件生成
- 解析 tokens.scss → 提取所有 --tk-* 变量及值
- 解析 variables.scss → 提取所有 $ 变量及值
- 生成 .design/tokens.yml
→ 存在: 直接使用
Step 2: 解析 HTML 中的 Token（C2 提取方式）
方式: 静态解析 T 对象定义 + 内联 style 值
- 用正则匹配 "const T = { ... }" 提取完整对象定义
- 解析 T 对象的每个 key-value 对（如 T.pri: '#C4623A'）
- 扫描内联 style 中的硬编码值: fontSize, padding, borderRadius 等
- 不依赖 React 运行时，纯文本解析
- 值归一化规则: "16px" 和 "16" 视为相同; 不支持 rem/em 转换
Step 3: 三层匹配
- 匹配时按 CSS 属性上下文消歧（H1 修复）
- borderRadius / radius 相关属性 → 只匹配 radius 类别 Token
- padding / margin / gap → 只匹配 spacing 类别 Token
- fontSize / fontWeight → 只匹配 typography 类别 Token
- color / background → 匹配 colors 类别 Token
- 如果同值多 Token 且无属性上下文 → 标记为 ⚠️ pending
- 产出 tokens.json
Step 4: 处理未确认项
- pending + unmatched 项在终端列表展示
- 用户确认后更新 aliases
- 后续原型自动复用已确认的映射
```
### 4.3.1 .design/ 目录管理
- `.design/` 目录**提交到 git**（tokens.yml 是团队共享的项目级配置）
- `.design/config.yml`（个人偏好配置，如 auto_handoff）可加入 `.gitignore`
- 首次生成 tokens.yml 后建议立即提交，作为团队基线
### 4.4 产出文件 `tokens.json`
```json
{
"source": "mp-00-visitor.html",
"platform": "miniprogram",
"generated": "2026-05-17T10:30:00Z",
"tokens": {
"T.pri": {
"value": "#C4623A",
"mapped": "var(--tk-pri)",
"match": "alias",
"status": "confirmed"
},
"fontSize:32": {
"value": "32px",
"closest": "var(--tk-font-h1)",
"closestValue": "28px",
"match": "fuzzy",
"status": "pending",
"note": "原型 32px vs 最近 Token 28px (--tk-font-h1)，差 4px"
},
"T.serif": {
"value": "Georgia, 'Times New Roman', serif",
"mapped": null,
"match": "none",
"status": "unmatched",
"note": "项目无字体族 Token，需硬编码或新建"
}
},
"summary": {
"total": 18,
"confirmed": 13,
"pending": 2,
"unmatched": 3
}
}
```
**字段说明**：
| 字段 | 说明 |
|------|------|
| `value` | 原型中的原始值 |
| `mapped` | 匹配到的项目 Token（null 表示未匹配） |
| `match` | 匹配方式：alias / exact / fuzzy / none |
| `status` | 状态：confirmed / pending / unmatched |
| `note` | 补充说明（模糊匹配的差异原因等） |
### 4.5 映射积累效应
每次运行 `/design-handoff` 并确认 pending 项后，映射自动写入 `aliases`：
```
第 1 次运行: 13 confirmed + 2 pending + 3 unmatched
→ 确认 2 个 pending → aliases 新增 2 条
第 2 次运行: 15 confirmed + 1 pending + 2 unmatched
→ 确认 1 个 pending → aliases 新增 1 条
第 N 次运行: 18 confirmed + 0 pending + 0 unmatched
→ 全部自动匹配，无需人工干预
```
随着项目推进，手动确认越来越少，最终趋近全自动。
---
## 5. 截图提取与交互推断
### 5.1 截图提取
#### 5.1.1 提取流程
使用 Playwright（huashu-design 已内置 `verify.py` 依赖 Playwright）：
```
1. Playwright 启动浏览器，打开 HTML 原型文件
2. 等待 React + Babel 渲染完成（检测 #root 内有子元素）
3. 遍历所有 IosFrame 实例，逐个截图
4. 裁剪设备框（12px padding + 54px 状态栏 + 34px 底部指示器）
5. 输出到 screenshots/ 目录
```
#### 5.1.2 IosFrame 定位规则
原型 HTML 中 `screen-label` 和 `IosFrame` 是**兄弟节点**，不是父子关系：
```html
<div class="screen-wrap">
<span class="screen-label">访客首页 — 完整页</span> <!-- 兄弟节点 -->
<IosFrame time="9:41" battery={85}> <!-- 兄弟节点 -->
<GuestHome />
</IosFrame>
</div>
```
定位方式：
```
1. 查找所有 class="screen-wrap" 的容器
2. 每个容器内:
- <span class="screen-label"> 的文本 → 截图文件名
- <IosFrame> 实例 → 截图目标
3. 如果容器无 screen-label → 使用序号命名 (screen-1.png, screen-2.png)
```
如果原型未使用 screen-wrap + IosFrame 结构，进入降级方案（见 5.1.4）。
#### 5.1.3 文件命名规则
| 规则 | 示例 |
|------|------|
| 使用 screen-label 文本 | `访客首页 — 完整页` → `home.png` |
| 轮播编号保留 | `访客首页 — 轮播 1` → `home-slide-1.png` |
| 中文翻译为英文简写 | `我的` → `profile`, `登录` → `login` |
| 同名页面加序号 | `home-2.png`, `home-3.png` |
翻译映射表内置在 skill 中（覆盖项目已有的 20 个原型中出现的所有中文标签）。
#### 5.1.4 降级方案
当原型未使用 IosFrame 时（如早期部分原型或 Web 端原型）：
1. **整页截图**：截取完整渲染页面
2. **手动标注**：用户通过 `--crop "x,y,w,h"` 参数指定裁剪区域
3. **CSS 选择器**：通过 `--selector ".screen-content"` 指定截图目标
### 5.2 交互推断
#### 5.2.1 推断策略
从原型 HTML 的 DOM 结构推断交互行为。不做运行时分析，纯静态代码模式匹配。
推断规则存储在 `rules/interaction-rules.yml` 中，按 DOM 模式匹配。
#### 5.2.2 内置规则表
```yaml
# rules/interaction-rules.yml
rules:
- id: swiper-autoplay
name: 自动轮播 + 手动滑动
patterns:
- "连续多个子元素含渐变背景 + 底部指示点（宽窄交替）"
- "Swiper / swiper / carousel 关键词"
infer:
interaction: "自动播放 + 手动滑动"
trigger: "页面显示"
feedback: "3s 间隔自动切换"
lifecycle: "useDidShow 启动，useDidHide 暂停"
confidence: high
- id: card-tap
name: 卡片点击跳转
patterns:
- "卡片容器含标题+摘要+配图"
- "onClick / onPress 事件"
infer:
interaction: "点击跳转"
trigger: "onPress"
feedback: "activeFeedback 按组件类型自动选择"
confidence: high
- id: form-submit
name: 表单提交
patterns:
- "输入框 + 按钮在同一容器内"
- "input / textarea + button 组合"
infer:
interaction: "表单提交"
trigger: "onPress（按钮）"
feedback: "loading 态 + 禁用重复提交 + 错误提示"
confidence: high
- id: list-scroll
name: 列表滚动加载
patterns:
- "列表容器含多个重复结构子元素"
- "overflow: auto / scroll"
- "3 个以上同类卡片连续排列"
infer:
interaction: "下拉刷新 + 上拉加载"
trigger: "onPullDownRefresh / onReachBottom"
feedback: "分页加载"
confidence: medium
- id: tab-switch
name: 标签页切换
patterns:
- "多个平行区域 + 选中态样式差异"
- "tab / segment / filter 关键词"
- "一组按钮样元素，其中一个高亮"
infer:
interaction: "标签页切换"
trigger: "onPress（tab 项）"
feedback: "选中态样式切换 + 内容区切换"
confidence: high
- id: static-decoration
name: 静态装饰
patterns:
- "渐变背景 + 装饰圆/波浪/几何图形"
- "无事件绑定"
- "position: absolute + opacity < 1"
infer:
interaction: "无（纯装饰）"
trigger: "—"
feedback: "—"
confidence: high
- id: login-cta
name: 登录/注册 CTA
patterns:
- "按钮含 '登录' / '注册' / '立即' 文案"
- "主色按钮 + 阴影"
infer:
interaction: "点击触发登录流程"
trigger: "onPress"
feedback: "PrimaryButton loading 态"
guard: "GuestGuard 拦截未登录态"
confidence: high
- id: empty-fallback
name: 空数据降级
patterns:
- "条件渲染: data.length > 0 ? ... : ..."
- "占位符文字 '暂无' / '空'"
- "硬编码的固定内容（非 API 数据）"
infer:
interaction: "无数据时显示替代内容"
trigger: "数据加载完成且为空"
feedback: "EmptyState 组件或固定引导卡片"
confidence: medium
```
#### 5.2.3 置信度分级
| 级别 | 阈值 | 处理方式 |
|------|------|---------|
| **high** (≥80%) | 结构明确，模式唯一 | 直接写入 SPEC.md 交互规格表 |
| **medium** (50-80%) | 结构合理但有歧义 | 写入交互规格表，标注 `⚠️ 待确认` |
| **low** (<50%) | 模式模糊，可能是静态 | 不写入交互规格，末尾单独列出 `## 待人工补充的交互` |
#### 5.2.4 推断结果示例
对 `mp-00-visitor.html` 的推断输出：
| 元素 | 推断交互 | 置信度 | 来源规则 |
|------|---------|--------|---------|
| 轮播区域 | 自动播放 3s + 手动滑动 | high | swiper-autoplay |
| 文章卡片 ×2 | 点击跳转详情 | high | card-tap |
| "更多›" 链接 | 点击跳转列表页 | high | card-tap |
| 功能卡片 ×3 | 点击跳转各服务页 | high | card-tap |
| CTA"立即登录" | 点击触发登录 | high | login-cta |
| TabBar 占位 | 无（小程序原生处理） | high | static-decoration |
| 资讯为空降级 | 显示功能引导卡片 | medium | empty-fallback |
### 5.3 截图与规格的关联机制
SPEC.md 中每个页面结构块都以对应截图开头，形成视觉-规格一一对应：
```markdown
### 2.1 访客首页
![首页全貌](./screenshots/home.png) ← LLM 读到此处时看到截图
布局层级（从上到下）： ← 对照截图理解每层
1. 轮播区域 (height: 280px) ... ← 截图中顶部渐变区域
2. 健康资讯 (padding: 20px) ... ← 截图中卡片列表区域
3. 登录引导 ... ← 截图中底部 CTA 按钮
```
LLM 无需在多个文件间跳转。**一个 SPEC.md = 视觉 + 结构 + 映射 + 交互的全景图**。
---
## 6. 多平台支持与集成
### 6.1 多平台 Token 映射
`tokens.yml` 中的每个 Token 支持按平台指定不同变量名和引用方式：
```yaml
# 单平台通用（大多数 Token，值和引用方式相同）
- token: --tk-pri
value: "#C4623A"
# 无 platforms 字段 → 所有平台统一用 var(--tk-pri)
# 多平台差异映射（值相同，引用方式不同）
- token: --tk-pri
value: "#C4623A"
platforms:
miniprogram: "var(--tk-pri)"
web: "token('color.primary')" # Ant Design Token 系统
h5: "var(--color-primary)" # H5 独立 CSS 变量体系
```
运行时按 `--platform` 参数展开对应平台的映射：
```bash
# 默认展开 miniprogram 映射
/design-handoff mp-00-visitor.html
# 展开 web 映射
/design-handoff mp-00-visitor.html --platform web
```
SPEC.md 和 tokens.json 中仅包含目标平台的映射，不混淆。
### 6.2 多平台组件映射
可选配置文件 `.design/components.yml`，定义各平台的组件对应关系：
```yaml
# .design/components.yml — 自动扫描生成，可手动调整
components:
ContentCard:
miniprogram:
import: "@components/ui/ContentCard"
props: "variant, padding, margin, activeFeedback, onPress, className"
web:
import: "@app/components/ContentCard"
props: "variant, padding, margin, onClick, className"
PrimaryButton:
miniprogram:
import: "@components/ui/PrimaryButton"
props: "children, onClick, disabled, loading, size"
web:
import: "antd/es/button"
props: "children, onClick, disabled, loading, type='primary'"
PageShell:
miniprogram:
import: "@components/ui/PageShell"
props: "padding, safeBottom, scroll, className"
web:
import: "@app/layouts/PageLayout"
props: "padding, children, className"
Swiper:
miniprogram:
import: "@tarojs/components"
tag: "Swiper"
web:
import: "antd/es/carousel"
tag: "Carousel"
TabBar:
miniprogram:
type: "framework-config"
note: "小程序原生 TabBar，在 app.config.ts 配置"
web:
import: "@app/components/AppTabBar"
note: "Web 端自定义 TabBar 组件"
```
**扫描生成规则**：
- `miniprogram` → 扫描 `apps/miniprogram/src/components/ui/` 目录
- `web` → 扫描 `apps/desktop/src/components/` 或对应 Web 目录
- 只在对应平台目录存在时才生成映射
### 6.3 huashu-design 协作方式
两种集成方式，**不修改 huashu-design 本身**：
#### 方式 A：串行调用（默认）
```
会话 1: /huashu-design → 原型 HTML（设计阶段）
会话 2: /design-handoff mp-00-visitor.html → 交付包（规格化）
会话 3: "按 SPEC.md 实现" → Taro/React 代码（实施阶段）
```
三个阶段各自独立，松耦合。用户按需调用。
#### 方式 B：自动追加（可选配置）
在 `.design/config.yml` 中开启：
```yaml
# .design/config.yml
auto_handoff: true
```
开启后，huashu-design 完成原型写入时，skill 检测到 `auto_handoff: true`，自动提示：
```
原型已生成: docs/design/mp-00-visitor.html
检测到 auto_handoff 开启。是否自动生成设计交付包？
→ 是: 立即运行 /design-handoff
→ 否: 跳过，稍后手动调用
```
### 6.4 实施 Prompt 模板
交付包生成完毕后，skill 在终端输出推荐 prompt，用户直接复制到新会话：
```
📋 实施时复制以下 prompt 到新会话：
请按设计规格实现「访客首页」页面。
设计规格: docs/design/mp-00-visitor/SPEC.md
Token 映射: docs/design/mp-00-visitor/tokens.json
目标平台: miniprogram (Taro + React)
组件库: apps/miniprogram/src/components/ui/
样式 Token: apps/miniprogram/src/styles/tokens.scss
要求:
1. 先阅读 SPEC.md 中的截图和规格
2. 按组件映射表使用现有组件，不要用 div 堆砌
3. 按 Token 映射表使用 CSS 变量，不要硬编码颜色值
4. 按交互规格表实现所有交互行为
5. 覆盖所有状态变体（加载/空数据/错误）
```
注意：SPEC.md 中的截图路径为相对路径（`./screenshots/home.png`），LLM 应使用项目根目录的绝对路径读取（如 `docs/design/mp-00-visitor/screenshots/home.png`）。
#### 批处理索引（M3 修复）
批量运行时（`/design-handoff docs/design/mp-*.html`），完成后自动在 `docs/design/` 下生成 `INDEX.md`：
```markdown
# 设计交付包索引
> 生成时间: 2026-05-17 | 原型数: 20
| 原型 | 交付包 | 页面数 | 未匹配 Token |
|------|--------|--------|-------------|
| mp-00-visitor | [SPEC](mp-00-visitor/SPEC.md) | 2 | 2 |
| mp-01-login | [SPEC](mp-01-login/SPEC.md) | 2 | 1 |
| ... | ... | ... | ... |
```
LLM 可通过 `docs/design/INDEX.md` 定位所需的交付包。
### 6.5 META.yml 元数据
每个交付包的元数据文件：
```yaml
# docs/design/mp-00-visitor/META.yml
source: mp-00-visitor.html
platform: miniprogram
generated: 2026-05-17T10:30:00Z
generator: design-handoff v1
pages:
- name: 访客首页
screenshot: screenshots/home.png
route: pages/index/index
- name: 访客"我的"
screenshot: screenshots/profile.png
route: pages/profile/index
tokens:
total: 18
confirmed: 13
pending: 2
unmatched: 3
components:
reused: 5 # 已有组件
new: 1 # 需新建组件
interactions:
total: 7
high_confidence: 6
medium_confidence: 1
```
---
## 附录 A. 交互推断规则表
完整内置规则清单（见 §5.2.2），共 8 条：
| 规则 ID | 名称 | 置信度 | 匹配模式 |
|---------|------|--------|---------|
| swiper-autoplay | 自动轮播 + 手动滑动 | high | 渐变背景 + 指示点宽窄交替 |
| card-tap | 卡片点击跳转 | high | 卡片容器 + 标题摘要配图 |
| form-submit | 表单提交 | high | 输入框 + 按钮同容器 |
| list-scroll | 列表滚动加载 | medium | 3+ 同类卡片连续排列 |
| tab-switch | 标签页切换 | high | 平行区域 + 选中态差异 |
| static-decoration | 静态装饰 | high | 渐变 + 装饰圆 + 无事件 |
| login-cta | 登录/注册 CTA | high | 按钮含登录文案 + 主色 |
| empty-fallback | 空数据降级 | medium | 条件渲染 / 占位符文字 |
扩展方式：在 `rules/interaction-rules.yml` 中追加新规则即可。
## 附录 B. Token 配置文件完整模板
见 §4.1 的 `.design/tokens.yml` 结构。首次运行时自动从以下文件扫描生成：
| 源文件 | 提取内容 |
|--------|---------|
| `styles/tokens.scss` | 所有 `--tk-*` CSS 变量 |
| `styles/variables.scss` | 所有 `$` SCSS 变量 |
| `styles/mixins.scss` | mixin 名称和用途（用于注释） |
## 附录 C. SPEC.md 完整示例（mp-00-visitor）
见 §3.2 - §3.8 的完整格式定义。以 mp-00-visitor 为实际案例，涵盖：
- 5 张截图（首页全貌 + 3 张轮播 + 我的页）
- 15+ Token 映射（11 confirmed + 2 pending + 2 unmatched）
- 7 个组件映射（5 复用 + 1 新建 + 1 框架配置）
- 7 条交互规格（6 high + 1 medium）
- 4 个状态变体（加载 / 空数据 / 已登录 / 错误）