design-spec-prototyper git:20261013.fcc2ed5A

Immutable. This exact content never changes and is served at /api/v1/blob/6fd2418bd5aa3044.

---
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` 把图变成规格 |
   | 设计稿图片 / 截图 | 本次页面的实际构图：分区、元素顺序、层级、间距节奏 | 只有规格没有图 → 可以纯规格驱动，但交付说明里要注明没有构图依据 |

   两者都没有时，要求用户提供。
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` 与 `delivery.md` 属于同一功能的可选资产；只创建当前任务需要的文件，不得覆盖既有文件。

## 需求资产归档

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

```text
docs/prd/<feature-name>/
├── prd.md             # 如已有或本次需要
├── design.md          # 设计依据，如已有或本次需要
├── prototype.html     # 本 Skill 的默认独立原型产物
├── demo.md            # 可选：项目内演示的评审结论
└── delivery.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` 引用；不得下载、复制或猜测商业字体文件。
- **system**：用于没有可靠字体来源、中文内容为主且网络不可控，或用户要求不依赖外部资源的场景。明确写出跨平台 fallback 栈。
- 设计规格、产品体验基线或用户已明确的字体优先于本默认值。只有截图证据时，字体名称标为 `[INFERRED]`；没有可用来源时不得假装还原了品牌字体。
- 中文字体必须有中文 fallback；只有明确指定或设计依据支持时才引入 Google Fonts 的 `Noto Sans SC` 等 CJK 字体。不得把文本转为 SVG 或图片来规避字体问题。

## 确定设计权威

按以下优先级执行：

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

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

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

| 冲突的是什么 | 以谁为准 | 为什么 |
|---|---|---|
| **令牌类**——颜色、字体、圆角、间距基准 | **规格** | 规格是沉淀下来的产品事实；图片可能只是某次出稿的临时选择 |
| **构图类**——页面分区、元素顺序、层级 | **图片** | 那正是这次要还原的东西 |

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

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

## 设计研究阶段

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

规格缺少可用性、响应式、排版或无障碍指导时，**推荐**用 `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. 按技术栈运行静态检查：解析独立 HTML、检查输入标签、重复 ID，并确认输出中包含已记录的令牌值。
2. 本地预览可用时，在 375 px、768 px、1024 px 和 1440 px 检查结果；确认在线字体已加载，并在 fallback 生效时检查文字裁切、水平溢出、层级薄弱和缺失焦点状态。
3. 无法运行预览时，不得声称完成视觉验证；简要报告验证缺口。
4. 交付功能目录和原型文件路径、字体来源/字体族/字重/fallback、使用的设计规格章节与产品体验基线章节、对结果有实质影响的补充设计指导，以及剩余假设；将反复出现但未确认的新模式标为候选，不得自动写成全局规则。