Design Spec Prototyper

---
name: design-spec-prototyper
description: 将 `design.md` / `DESIGN.md` 等有证据支撑的设计规格，**配合设计稿图片或截图**，转为高保真、无障碍且响应式的 UI 原型。规格提供品牌令牌、组件规则与字体（持续沉淀的产品事实），图片提供本次页面的实际构图，两者同时参考。适用于用 HTML/Tailwind、React、Next.js、Vue 或其他前端技术栈设计并实现原型的场景；在线独立原型默认可使用 Google Fonts；仅在规格缺少 UX 或实现指导时结合你自己已装的设计类 skill。
---

# 设计规格原型生成器

构建可直接进入实现阶段的原型。**两类输入要同时参考**：设计规格给品牌令牌与规则，设计稿图片给本次页面的实际构图。规格中已观察到的值，比通用设计建议拥有更高证据优先级。

## 输入与默认值

1. 找齐两类输入，未指定时都在当前项目中搜索：

   | 输入 | 给什么 | 缺了怎么办 |
   |---|---|---|
   | `design.md` / `DESIGN.md` | 品牌令牌、组件规则、字体、证据边界——**持续沉淀的产品事实** | 只有图没有规格 → 先走 `web-design-extractor` 把图变成规格 |
   | 设计稿图片 / 截图 | 本次页面的实际构图：分区、元素顺序、层级、间距节奏 | 只有规格没有图 → 走「规格内的构图证据」（见下），并在交付说明里写明证据来源与限度 |
   | 参考图（**不属于本页**，例如竞品页截图） | 视觉语言参考：配色倾向、质感、动效风格 | **不能当构图依据**——见下 |

   两者都没有时，要求用户提供。

   **只有规格没有图时，构图证据由规格自己承担，但要说清是哪一种：**

   - 规格里的分区顺序如果本来就是从**页面 DOM 顺序或接口数据顺序**提取的，那它是
     `[OBSERVED]` 级别的构图证据，可以直接照着排列分区。走 `web-design-extractor` 的
     URL 路线（而不是截图路线）时，通常就是这个情况。
   - 如果规格里的顺序只是**写规格的人总结出来的**，那它是 `[INFERRED]`，照做可以，
     但交付说明里必须点出来。
   - 两种情况都**拿不到**的：各分区的视觉比重（谁更抢眼）、间距节奏的具体数值、
     断点行为。这些一律标未知，不要靠「常见做法」补一个上去。

   区别在于**能不能往上追到来源**。追得到就照着做，追不到就标未知——不要为了页面好看而假装知道。

   **图不是本页的时候——这是最容易做错的一步。**

   手上有一堆截图，但它们是**参考站 / 竞品页**的（`web-design-extractor` 的输入），
   不是本页的设计稿。这种情况下构图证据**回退到 `prd.md`**：

   | | 以谁为准 |
   | --- | --- |
   | 分区顺序、元素顺序、层级 | **只以 `prd.md` 第 5 节的用户流程为准** |
   | 配色倾向、质感、动效风格 | 可以参考图，但**页面结构一律不得照搬** |

   交付说明里**必须写明构图来源**（PRD 第 5 节 / 设计稿 / 规格）。

   照抄参考站的构图会得到一张与 PRD 完全不符的页面——**而且评审时看不出来**，
   因为页面本身做得挺好看。这是这条链路里少数「错得很漂亮」的失败模式。

   **顺带一条**：读规格时，如果里面有「适用性 / 边界 / 重建规则」这类章节，**必须读完**。
   规格的作者可能已经写明了「这个页面不能当模板」——而流程里没有任何一步会自动读到那个结论。
2. 查找 `docs/product/` 中与当前项目、当前端（`c-end/` 或 `admin/`）对应的产品体验基线，以及可用的原型页壳或组件模式；没有基线时记录该缺口，不得虚构产品级规则。
3. 提取页面类型、产品上下文、目标路由、视觉令牌、布局规则、组件、响应式说明、无障碍要求和明确的未知项。
4. 使用用户要求的技术栈；未指定时，默认使用带 Tailwind 的独立 `prototype.html`。
5. 确定字体来源：`google`、`local` 或 `system`。在线独立原型默认使用 `google`；用户或设计规格可直接指定 Google Fonts 的字体族、字重和斜体。项目已有品牌字体、用户要求离线展示或网络不可控时，优先 `local` 或 `system`。
6. 确定功能名和需求目录。优先从指定的 PRD、`design.md` 所在目录或用户需求中推断 `<feature-name>`；无法唯一确定时，要求用户指定，不能创建泛化的 `outputs/` 目录。
7. 所有独立评审产物必须归档到 `docs/prd/<feature-name>/`：默认输出为 `docs/prd/<feature-name>/prototype.html`。`prd.md`、`design.md`、`prototype.html`、`demo.md` 属于同一功能的可选资产；只创建当前任务需要的文件，不得覆盖既有文件。

## 需求资产归档

独立原型是需求评审资产，不是项目根目录的临时文件。使用以下结构：

```text
docs/prd/<feature-name>/
├── prd.md             # 如已有或本次需要
├── design.md          # 设计依据，如已有或本次需要
├── prototype.html     # 本 Skill 的默认独立原型产物
└── demo.md            # 可选：项目内演示的评审结论
```

- 已有 `docs/prd/<feature-name>/` 时，使用同一目录，不创建重复功能文件夹。
- 用户指定的输出路径不在对应功能目录时，说明归档约定并要求确认；没有明确批准不得把独立原型散落到 `outputs/`、项目根目录或无关目录。
- 仅在用户明确需要项目内高保真原型时，转用 `pm-frontend-prototype`；该 Skill 的产物是项目源码中的隔离原型入口，而非本目录的默认替代。

## 字体策略

- **google（在线默认）**：仅在没有优先级更高的品牌字体时使用。用户可直接指定 Google Fonts 中的字体族、字重和样式；生成对应的 Google Fonts CSS2 链接、`preconnect` 和完整系统 fallback。只请求实际使用的字重与样式，并使用 `display=swap`。
- **local**：用于用户提供了字体文件、离线评审或必须稳定复现版式的场景。字体文件放入 `docs/prd/<feature-name>/assets/fonts/`，通过相对路径 `@font-face` 引用。**用户给了就用，不问来源**——字体授权是用户要判断的事，不是本 Skill 的判断；用户没给就用最接近的 fallback，不要自己去网上找字体文件。
- **system**：用于没有可靠字体来源、中文内容为主且网络不可控，或用户要求不依赖外部资源的场景。明确写出跨平台 fallback 栈。
- 设计规格、产品体验基线或用户已明确的字体优先于本默认值。只有截图证据时，字体名称标为 `[INFERRED]`；没有可用来源时不得假装还原了品牌字体。
- 中文字体必须有中文 fallback；只有明确指定或设计依据支持时才引入 Google Fonts 的 `Noto Sans SC` 等 CJK 字体。不得把文本转为 SVG 或图片来规避字体问题。

## 确定设计权威

按以下优先级执行：

1. **明确的用户要求**：包括明确批准的产品体验变更。
2. **已确认的产品体验基线**：当前端的产品术语、页壳、组件模式和全局交互规则。
3. **设计规格中已观察的证据**：记录的令牌、组件规则和可见结构——规格是持续沉淀的产品事实。
4. **设计稿图片中直接可见的构图**：页面分区、元素顺序、层级关系。图片用来还原**这次**的页面长相，
   不用来推翻规格里的令牌。
5. **规格推断规则**：记录为 `[INFERRED]` 的选择是合理默认值，而非不可变事实。
6. **你已装的设计类 skill（可选）**：仅在规格不完整时，提供可用性、响应式行为、替代排版、无障碍和技术栈指导。

从图片读到的信息按本仓库统一约定标注：直接可见的标 `[OBSERVED: SCREENSHOT]`，需要推断的标 `[INFERRED]`，
图片没展示的状态标 `[UNKNOWN]`——**不要替图片补它没画的东西**。

### 规格和图片冲突时，以谁为准

| 冲突的是什么 | 以谁为准 | 为什么 |
|---|---|---|
| **令牌类**——颜色、字体、圆角、间距基准 | **规格** | 规格是沉淀下来的产品事实；图片可能只是某次出稿的临时选择 |
| **构图类**——页面分区、元素顺序、层级 | **图片** | 那正是这次要还原的东西 |
| **图不属于本页**（参考站 / 竞品页截图） | **`prd.md` 第 5 节** | 参考图只能当视觉语言参考；它的页面结构不是本次要还原的东西 |

实质冲突要在交付说明里**点出来**，不要静默二选一——否则下一次迭代无从判断当初为什么这么定。

不得用通用设计建议替换已记录的调色板、排版系统或视觉方向。设计规格或外部参考与产品基线发生实质冲突时，默认保留基线；只有用户明确批准偏离时才改变，并在交付中说明是否应回写基线。

## 设计研究阶段

规格完整时直接进入构建，不必额外检索。

规格缺少可用性、响应式、排版或无障碍指导时，**推荐**用 `ui-ux-pro-max` 补齐（安装方式见仓库 README 的「配套推荐」）。装上之后用它检索设计系统与对应技术栈的指导：

```bash
# <UIUX_DIR> 换成你本机的实际安装目录，不要照抄任何写死的绝对路径
python3 <UIUX_DIR>/scripts/search.py "<产品> <行业> <页面类型> <风格>" --design-system -p "<项目名>" -f markdown
python3 <UIUX_DIR>/scripts/search.py "<页面类型> 响应式 无障碍" --stack <技术栈>
```

**没装也能跑通**：依据产品体验基线和设计规格自行判断，并在交付说明里标注哪些决定缺少依据——不要假装检索过。

这一阶段的目标是补齐规格的空白，不是替换规格：若设计规格已给出令牌值，不得将通用调色板写入原型。

## 构建原型

实现前阅读 [references/prototype-contract.md](references/prototype-contract.md)。

1. 创建语义化文档结构和明确的页面标题；为表单字段提供真实标签，并为纯图标控件提供无障碍名称。
2. 在编写组件样式前，将设计规格令牌定义为 CSS 自定义属性或目标技术栈的设计令牌。
3. 在写入排版样式前落实字体来源。`google` 使用 Google Fonts CSS2 链接和系统 fallback；`local` 使用功能目录中的相对 `@font-face`；`system` 不引入外部字体。仅使用用户或规格指定的字体，或在规格缺失时记录选择依据。
4. 先实现规格记录的桌面布局，再根据规格推导移动端行为；规格未提供断点证据时，采用保守响应式行为，并在交付说明中标注为实现推断。
5. 只构建当前页面相关组件；优先复用产品体验基线中的原型页壳、组件模式以及间距、颜色、圆角、排版、表面层级和动效值。
6. 使用一套一致的 SVG 图标集或内联 SVG；不要用 emoji 当 UI 图标。
   品牌 Logo 用**用户提供的素材文件**——凭记忆画出来的既不像，也不是我们的东西。
7. 只添加原型能够如实展示的交互；除非用户要求集成，否则登录、支付或第三方操作应使用不可执行链接或明确标记的演示处理器。
8. 添加可见键盘焦点状态、不会引起布局位移的悬停反馈、减少动态效果支持，以及移动端安全的溢出处理。
9. 在输出前确认 `prototype.html` 位于对应的 `docs/prd/<feature-name>/` 目录；若设计规格来自该目录，在原型交付说明中链接它，而不是复制出第二份规格。

## 验证与交付

1. **跑静态检查 + 四档预览检查**：

   ```bash
   node <this-skill>/scripts/preview-check.mjs <prototype.html> <截图目录>
   ```

   一次覆盖：U+FFFD 乱码、`id` 是否唯一、`aria-controls` 是否悬空、装饰性 SVG 是否标了
   `aria-hidden`、`<h1>` 数量、doctype / lang / viewport、375·768·1024·1440 四档横向溢出、
   字体实际加载情况，并各截一张图。**有 FAIL 就修完再交付，别把它带进交付说明当"已知问题"。**
2. 拿不到浏览器时脚本会以退出码 3 结束（没有 Chrome/Edge，或 Node < 22）。
   **这时不得声称完成视觉验证**——在交付说明里如实写「未能运行预览检查」。
   **「验证过」和「没验证」必须一眼能分辨**，否则审查者会把未验证当成已验证。
3. 脚本查不了、需要人眼补的：在线字体 fallback 生效时是否文字裁切、层级是否薄弱、焦点态是否可见。
4. 交付功能目录和原型文件路径、字体来源/字体族/字重/fallback（品牌字体不可用时见
   [prototype-contract.md](references/prototype-contract.md) 的替代关系声明要求）、
   **构图来源**、使用的设计规格章节与产品体验基线章节、对结果有实质影响的补充设计指导，
   以及剩余假设；将反复出现但未确认的新模式标为候选，不得自动写成全局规则。
5. 改完文件再单独扫一遍中文乱码：
   `grep -rnI $'\xef\xbf\xbd' <原型所在目录>`