HTML 交互原型（MD 规划 + HTML 交付）

借鉴 spec-driven 思想，裁剪掉工程仪式（git 分支、特性编号、API 合约、测试用例），只保留个人画原型需要的部分。核心是：需求是文字思维，原型是体验思维，MD 承载前者，HTML 承载后者，两者是同一需求的两种投影，而不是两份各写各的文档。

核心思想

MD 是唯一事实源，HTML 是派生产物。改需求只改 MD，HTML 由 AI 重新生成/同步。这样一致性由生成过程保证，而不是靠人工同步——人工同步必然过期。

三件套（每个项目必建，放 spec/ 目录）

生成顺序

1. 确认生成目录：原型生成目录（如 <项目目录>\交互原型\）由用户指定，不许自作主张。用户没给 → 问"生成到哪个目录？"（可建议：在项目目录下建 交互原型\ 子目录），等答复后才继续。目录确定后，spec/ 与 src/ 全部生成在该目录下
2. 设计规范选型 → 导航地图 + 公共规范（一次定死，作为全部页面的"宪法"；选型未定，禁止开工）：
   • 项目的 spec/_公共规范.md 不是手写的，是拼装出来的：

     公共规范-通用.md（assets/，共享骨架：token 名/字体/间距）
     + design-specs/ 中选定的类型规范（布局 + 类型组件）
     + 项目色板替换（用户指定 / 从截图提取 / 类型默认值）
     = spec/_公共规范.md（项目专属，一次拼好）
     

   • 读 design-specs/index.md（规范清单），每次开工必问：列出清单给用户选（附推荐），等用户答复后才可继续；不得依据用户描述或材料（截图/文档）风格自动命中某套规范，无兜底
   • 用户选的规范不在库中 → 按 design-specs/index.md 的"新增一条规范"流程先配置（截图 / 设计文档 / 用户描述），登记后再开工
3. 公共资产：src/assets/style.css + mock-data.js（先落地 token，后续页面全部引用）
4. 逐页生成，每批 1-2 页：
   • 每页只加载：公共规范 + 本页 spec + 导航地图（三样都很短，上下文可控，生成第 20 页与第 1 页负担相同）
   • 每页生成前先逐条过「生成前门禁」（规范门/导航门/工程门，见下），三扇门都过才写 HTML
   • 页面跳转用相对路径 <a href="02-list.html">
   • 首次截图前创建项目级 预览截图/ 目录；所有页面截图直接写入该目录，不写在原型根目录或 src/ 中
   • 每页生成后截图回看 → 逐条过「每页验收清单」（见下）→ 迭代，改→验→改
5. 收尾：src/index.html 汇总入口 + README.md 交付说明（怎么打开、页面清单）
6. 整体验收（默认必做）：全部页面生成并收尾后，请用户完整体验——打开 src/index.html 从入口走查全部页面与主流程。用户提出的修改，按「修改已有原型（增量更新）」判定范围并修改，改完回到本步重新验收，直到用户明确通过。整体验收重点查：跨页主流程能否走通、入口/返回无断链、全部页面放在一起看是否像同一套系统。与第 3 步的区别：第 3 步期间的修改针对刚生成的页面当场迭代，本步是全部页面齐了之后的整体性验收；用户明确表示不用验收时可跳过
7. 单文件交付（默认必做）：分页面与整体验收均通过后，将全部页面、样式、脚本、Mock 数据和本地资源打包成一个可离线打开的 HTML（便于下发、评审和归档）。执行本步时先读 references/单文件交付.md，输出要求、打包边界和验证清单都在那里；用户明确不需要单文件时可以跳过

每页验收清单（生成/修改后逐条过，不攒到最后）

1. 能打开：页面无报错，浏览器正常渲染
2. 布局对：对照本页 spec，字段与信息结构无缺漏、无错位
3. 跳转通：本页所有入口与按钮的跳转目标有效，无断链
4. 状态齐：空态/加载/成功/错误等交互状态与 spec 一致
5. 风格统一：样式取自公共规范 token，与全站一致
6. 视觉签名：体现公共规范中的标志性元素，本页有没有体现，没体现就调整
7. 不落 AI 默认脸：米白底+衬线+陶土色 / 近黑底+单色点缀 / 报纸式极简——三个都是合法方向，但必须是本项目主动选定的，不是顺手默认
8. 文案基调：用户视角命名、主动语态；错误/空态写方向不写情绪

截图与视觉验收产物

• 固定目录：<原型目录>/预览截图/。一个原型项目只使用这一处截图目录。
• 命名：与导航编号及页面名一致，如 01-登录页.png、02-工单列表.png；同页不同状态可追加状态名，如 02-工单列表-空状态.png。
• 浏览器截图工具的 path 参数必须直接指向 预览截图/，禁止先写根目录再依赖收尾整理。
• 回看截图、临时对比图和最终交付预览统一放在该目录；源图片、用户参考图仍按原位置读取，不复制到预览目录。
• 截图生成后检查原型根目录：如发现散落的 .png、.jpg 或 .webp 验收图，移动到 预览截图/；移动前核对它们属于当前原型，禁止移动用户原始素材。
• README.md 的页面清单可链接最终预览截图，但HTML不得依赖截图才能正常展示。

生成前门禁（每页必过，不通过不许生成 HTML）

生成一页 HTML 前，逐条自查并说明通过与否：

1. 规范门：本页规范是否已经用户确认（清单选择）？样式是否取自公共规范 token？（选型未经确认，或按钮/表格/配色另起炉灶，均不通过）
2. 导航门：本页跳转目标是否都已在导航地图登记？（不在清单内的不生成）
3. 工程门：没有引入框架/构建工具吧？（纯 HTML+CSS+JS 单文件）

门禁意义：就像施工前看图纸，把"页面风格漂移""断链""过度工程"三个最常见问题拦在生成前，而不是生成后返工。

修改已有原型（增量更新）

用户对已生成的原型提出修改时，先判定影响范围再决定怎么改，不默认全量重做：

1. 判定影响范围：
   • 只动单页内容（某页 spec 的字段/文案/交互）→ 小改动，只改这一页
   • 动了公共规范、导航地图或跨页公共逻辑（mock-data.js 结构）→ 大改动，全局识别修改点后逐页重生成
   • 拿不准 → 按全局处理，不要赌
2. 小改动（单页增量）：只重生成受影响的那一页。加载公共规范 + 该页 spec + 导航地图；不动 style.css、mock-data.js、其他页面
3. 大改动（全局修改）：先列出所有受影响页面（改了什么 → 波及哪些页），再逐页重生成；style.css / mock-data.js 需要同步修改的一并处理
4. 变更判定门禁：公共规范或导航地图有改动时，禁止走单页增量——全站一致性靠全量重生成保证，否则风格会悄悄漂移
5. 修改后逐页过「生成前门禁」+「每页验收清单」；项目已有单文件交付版时，按 references/单文件交付.md 重新打包，禁止只改打包结果

规则（附理由）

• HTML 永远从 MD 生成，不许两边各自改——否则回到"三份文档人工同步"的旧病
• 不引入工程化：纯 HTML+CSS+JS 单文件，无框架、无构建工具、无 npm——原型不是生产代码，工程化只会增加你和模型双方的负担
• 每批 1-2 页：一次塞 30 页 spec 会上下文爆炸，质量崩
• mock 数据统一放 mock-data.js：页面从变量取数据，不硬编码在 HTML 里，改数据不用改页面
• 不塞真实业务数据：涉及真实数据（业主信息、合同金额）的交付先与用户确认合规性
• 生成必回看：页面完成即截图检查，逐条过「每页验收清单」（8 条，见上），发现问题当场改，不要攒到最后
• 不许猜：需求/字段/交互不明确时，在 spec 中标记 [NEEDS CLARIFICATION: 具体问题] 并停下来问用户，不擅自假设——猜错一个字段，返工的是整个页面；猜错的成本远高于问一句
• 分层细节管理：公共规范只放 token，页面 spec 只放本页内容，主文档保持一屏可读——把细节塞进一个文件，最后谁都读不懂，模型也会在文件里迷路

目录结构

原型名\
├── spec\
│   ├── _导航地图.md
│   ├── _公共规范.md
│   ├── 01-登录页.md
│   └── ...
├── src\
│   ├── assets\
│   │   ├── style.css
│   │   └── mock-data.js
│   ├── index.html
│   ├── 01-login.html
│   └── ...
├── 预览截图\
│   ├── 01-登录页.png
│   ├── 单文件完整交互原型-验证.png
│   └── ...
├── <原型名>-完整交互原型.html
└── README.md

输入与产出

本 skill 自身的结构

prd-html/
├── SKILL.md                  # 本文件：工作流 + 选型逻辑 + 门禁 + 规则
├── README.md                 # 给人看的说明
├── assets/                   # 通用模板（共享一份）
│   ├── 导航地图模板.md
│   ├── 页面spec模板.md
│   └── 公共规范-通用.md       # token 骨架
├── references/               # 按需读取的执行细节（渐进披露）
│   └── 单文件交付.md          # 单文件打包/验证清单（生成顺序第 6 步读）
└── design-specs/             # 设计规范库（随 skill 自由增删）
    ├── index.md              # 规范清单 + 新增/修改/删除规则
    └── 后台-通用.md           # 内置规范（类型规范可继续加）

首次使用项目时：复制 assets/ 模板到项目 spec/ 并填充；design-specs/ 按选型拼装进项目 spec/_公共规范.md。