HTML Mockup

单页 HTML:需求原型 / 改动汇报

这是什么

**一页 HTML 讲清一件事。**不是界面图集,是「说明书 + 图」混排:该画的画出来、规则写旁边、这次改了啥标绿色。对方打开一个链接就能看懂、能评审、能拍板。

两种用法共用同一套地基(单文件、原型目录、8008 公网链接、?v=N、颜色语义、积木库),只是骨架不同:

~/www 下已经这么出过 29 个(2026-07 起),是团队出原型的主力路子。

先选路子:这个 skill 还是写真代码

拿不准就用本 skill:半小时出一版,改起来也快。可交互原型要写框架代码、编译、部署、提交分支,一版下来成本高一个量级。

环境自举(第一次用,或链接打不开时,先跑这个)

bash ~/.claude/skills/html-mockup/assets/bootstrap.sh

它会先判断这台要不要起 8008:

没有转发通道的机器上,起了服务也只有同网段能看,还白占端口;积木库和模板直接读 assets/ 下的文件即可,不用起服务。真要局域网自用:PROTO_SERVE=1 bash .../bootstrap.sh。

起服务时它做五件事,幂等,重复跑安全:

1. 建原型根目录(默认 ~/www,已存在或已是软链则沿用)
2. 装 / 更新 _template/(起手模板)和 _blocks/(积木库)
3. 起 8008 静态服务(assets/serve.py,零依赖 stdlib,自带 no-cache)
4. 本地 curl 自检
5. 打印本机真实的 BASE_URL,末行形如 BASE_URL=https://8008--main--<workspace>--<owner>.<你的 Coder 域名>/

**永远用它打印的 BASE_URL,不要背域名。**每台机器的 workspace / owner 不同,写死的域名到别的机器上就是死链。脚本从 $VSCODE_PROXY_URI 推导,推导不出来才回落到 CODER_WORKSPACE_* 拼接。

给外部人(PM)之前必须做一次:Coder 端口转发默认 owner-only,别人打开是登录页(bootstrap 会探测并报出返回码,非 200 就是没放开)。工作区里的 coder 是精简 agent 版,没有 port-share 子命令,只能去面板改:<你的 Coder 地址>/@<owner>/<workspace> → Ports → 8008 → Share → Public。设一次就长期有效。

硬约束(环境定死的,不是风格问题)

• 单文件、零外部依赖。不引 CDN、不引 Google Fonts、不外链图片、不引 mermaid.js。端口转发带 Cross-Origin-Embedder-Policy: require-corp,跨源资源会被浏览器直接拦掉;国内网络加载 CDN 也会白屏。字体一律用系统字体栈(模板里已有),图标用 Unicode 字符(✓ ✕ › ▼ ☑ ⓘ ↻ ① ★)。
• 静态,不写交互。这是给人看的说明书,不是能点的 app。要能点就得写真代码。
• 原型目录不入 git,是孤本。机器重装、目录清理就没了 —— 需要长期留存的结论,写进 issue / PR / 知识库,别指望原型本身。
• 产物形态是 preview_html 与 8008 二选一,判定见 §4.5。默认 preview_html,只在它结构上做不到时才走 8008。

4.5 产物形态:preview_html 还是 8008(自动二选一)

**默认 preview_html。**它零部署、即时可见 —— 不用起服务、不用设 public、不用带 ?v=N、不用等对方点链接。

**只在下面四种情况让位给 8008。**前三条是 preview_html 结构上做不到的事,与内容长短无关;第四条才是体量问题:

**「短内容才能用 preview_html」这条已废除。**中等篇幅的说明、单张界面帧、几节内容、单张 mermaid 黑底卡,直接 preview_html,不要因为"看起来有点长"就预先绕道 8008。

判定顺序:先看 ①②(意图),再看 ④(体量);③ 是事后信号。①② 命中就直接 8008,不必先试 preview_html。

⚠️ 50KB 是经验估计,不是实测值 —— skill 坑表只记了"出长原型被截断过",没记在多大体量翻的车。真遇到截断时记下当时的字节数,把这里的数字换成实测值。参考:模板 9KB、积木库 22KB、26 文件改动报告 59KB。

5. 模式 A:需求原型

A1. 定名 + 查有没有旧的

ls -d ~/www/*/ | rg -i "关键词"

同一个需求已有原型就改那一份,别新建。 对方手里的链接是旧的,新建一个他打不开。 真要废弃合并,在旧目录留一个 meta refresh 跳转页(见 §8)。

新建时目录名用功能英文短名(cost_recalc、brand_purchase_min_amount、invoice_archive),不带版本号、不带 issue 号。

A2. 拉真实素材,别凭印象画

动手前必须查到位,不然画出来的东西对方一眼看出不是他那个系统:

• issue 正文和评论的原话(gh issue view)
• 现在这个界面长什么样 —— 去前端仓库找对应页面,或看对方给的截图
• 涉及的字段、状态、口径 —— 去后端仓库核实,别编字段名

术语按系统真名:「物品」不叫「商品」,「外部采购 / 调拨 / 品牌采购」用系统里的原名。

A3. 拼页面

必须从 ~/www/_template/index.html 复制起手。

⚠️ 不要照着旧页面抄 CSS。旧页面带着它生成那天的字号、宽度、缺失的 .bleed —— 抄过来就把过时样式一起继承了,而且页面看着正常,没人会发现。实测:模板已 16px,照旧页抄出来仍是 14px。 模板是唯一起点;旧页面只能抄内容结构(哪些节、什么顺序),不抄 <style>。

骨架固定这几块:

1. 页头 — 功能名 + 一句话说清这版讲什么 + 日期
2. sticky 锚点导航 — 界面超过 3 个必加,读者靠它跳
3. 「本次更新」绿框 — 第二版起必加,列这次改了几条,每条带锚点跳过去
4. 分节 — 一节一件事,.st-h 编号标题 + <small>「从哪进 / 什么时候看到」,复杂的节再加一句 .lead 副标题定调
5. 说明块 — 规则写 .hint 块里,别塞进界面冒充 UI 文案

节里放什么,从 ~/www/_blocks/index.html 抄。先按「要表达什么」选积木,别一上来就画界面 —— 很多需求用流转图 / 矩阵表 / 时间线讲比堆界面清楚得多。积木索引见 references/blocks.md。

A4. 本地验

# 有 mermaid 卡就先渲染,再验(顺序不能反,渲染会改文件)
python3 ~/.claude/skills/html-mockup/assets/render-mermaid.py <目录>/index.html
# 横向溢出:页面上看不出来,不量就发现不了
python3 ~/.claude/skills/html-mockup/assets/check-overflow.py <目录>/index.html
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8008/<feature>/

不是 200 就重跑 bootstrap.sh(Coder 工作区重启后服务会掉)。 grep -c '<svg' <目录>/index.html 要等于 .mmd 卡片数,不等就是有图没渲出来。 check-overflow.py 报撑破就照 §7「宽度」给那几个元素加 .bleed。

改已有页面时,先把它对齐到当前模板(幂等,重复跑安全):

python3 ~/.claude/skills/html-mockup/assets/align-page.py <目录>/index.html

它补两样:字号阶梯(对齐 16px 正文)、布局兜底 CSS(.bleed / .mmd 横滚 / code 断行 / table.cmp 横滚 / dd dt 的 min-width:0)。内联 SVG 一律跳过并断言前后一致。 跑完必须再跑一次 check-overflow.py —— 字号变大会把并排双栏、宽表撑得更宽。

A5. 交付链接

<BASE_URL><feature>/?v=N

• 必须给 bootstrap 打印的公网地址,不能给 localhost:8008 或内网 IP —— 对方在自己电脑上打不开。
• 改过就带 ?v=N 破缓存(每改一版 N+1)。不带的话对方看到的还是旧的。
• 能直接给锚点:.../cost_recalc/?v=3#s4 跳到第 4 个界面。
• 交付前 curl 公网地址确认 200 再发。

交付话术:永远把完整 URL 明文写出来

只要有地址,就把地址完整贴出来,不要用 [文字](url) 把它藏在链接文字后面 —— 那样读者没法复制、没法转发、也不知道自己要打开的是哪台机器的哪个原型。裸 URL 在 markdown 里本来就是可点的,明文和可点两者不冲突。

✅ 正确:地址明文,一眼能看见、能复制
   跨店分页改动汇报:
   https://8008--main--myws--alice.coder.example.com/cost_recalc/?v=2
   本次更新 3 条,顶上绿框里,点条目能跳到对应界面

❌ 错误:地址被藏起来了
   [打开改动汇报](https://8008--main--...)
   点这里查看原型

别嵌 iframe、别用 preview_html 再包一层。锚点也直接写进 URL:...?v=3#s4。

6. 模式 B:改动汇报

触发:「总结一下当前任务的所有改动」「这次改了什么」「出个变更说明」「动了哪些表 / 业务规则」。

**完整执行手册在 references/change-report.md,做之前必须读。**这里只放不能违反的铁律:

1. **不漏。**以 git diff --stat 的文件清单为唯一底账,每个文件都要出现在 S1 的 ASCII 树里(带 ±行数和一句话注释)。收尾跑覆盖率自检:底账文件数 == 树里出现的文件数,差一个都要补。
2. **逐行看,不看摘要。**每一行改动都要回答「它动了哪条原有业务规则」。没动规则的行归为「无规则影响」,也要显式说出来,不能沉默跳过。
3. 分派多个代理并行采集,六条线同时跑(diff 清点 / 数据库字段 / 业务规则逐行 / 影响面与调用方 / 文案与 i18n / 测试与风险)。手册里有现成的分工提示词。
4. **大白话优先。**每一节开头先用一句人话说结论,再上表格和图。别让读者自己从 diff 里悟。
5. 必须有的四块内容:动了哪些表字段、改了哪些原有业务规则(原规则 → 新规则 → 触发条件 → 谁受影响)、影响哪些业务点、回滚怎么做。 5.5 每条改动都要落到「页面 → 操作 → 结果」,并且把页面画出来:
   • 页面:用户实际看到的那一屏,用积木库的界面帧 / 后台外壳 / 列表页 / 小票画出来 —— 不是描述,是画。
   • 操作:在这一屏上做什么(点哪个按钮、填什么、选哪个筛选、翻到第几页)。
   • 结果:改前会怎样 → 改后会怎样。界面怎么变、数据怎么变、谁什么时候能感知到。 用户侧真的无感知时,明确写一句「用户无感知,仅 xxx 变化」,不要跳过这一节。 Why:只写"改了 xxx 函数的判断条件",读者无法验收、测试无法复现;落到页面和操作,PM 能验、测试能复现,你自己也会发现"这个改动用户其实碰不到"。
6. 图的分工:结构和清单用 ASCII(见 §7),状态流转和调用链用 mermaid 黑底(见 §7),界面变化用积木库的双栏对照。

7. 视觉规范

字号:正文 16px 起,别更小

模板的字号阶梯(2026-08-16 连上调两档,原来 14px 正文明显偏小):

中文比拉丁字母更吃字号,13~14px 的说明块在 900px 栏里读着累。加大字号还顺带把行长拉回来(14px 时 62 字/行 → 16px 时 54 字/行)。

**下限就是 16px,不要再往回调。**要更紧凑就减内容,不是缩字。

⚠️ **改字号时必须跳过内联 SVG。**mermaid 渲出来的 SVG 里节点框尺寸是渲染那一刻烤死的,字号一改文字就顶出框被裁(实测「700 个文件提交掉」变成「提交挂」、「canary 跑迁移演练」被切掉两字)。批量调字号要先把 <svg>…</svg> 抠成占位符,改完再放回去。图要变大就重跑 render-mermaid.py,不要动 SVG 里的 CSS。

宽度:按页面类型选档,同一页内不许出现断层

先按页面类型定正文栏,再谈宽内容。

<div class="wrap rep">   <!-- 模式 B 一律加 rep -->

报告档是自适应的,所以 .bleed 在它里面不再挣脱(width:100%)—— 外壳已经跟着屏幕长了,再挣脱只会让左边缘错位 49px。.bleed 只在模式 A 的 900 栏里才需要挣脱(上限 1440px)。

文字块单独收住行长:.rule dd / .uv / .say / .hint / .lead 加 max-width:52em(≈48 汉字/行)。这是自适应能成立的关键 —— 不收的话 2560 屏上正文会变成 87 汉字/行。收完的效果是「正文一列、图表更宽」,左边缘全部对齐,右边缘错开,读起来像正常文档。

实测同一页在三种屏幕上:正文栏 1216 / 1504 / 1920px,并排双栏 599 / 663 / 871px 各一屏,文字始终 48 汉字/行。

⚠️ 别单独优化每一块,要看它们上下摞在一起是什么样。

这是翻过车的:按行长把正文栏定 900、按装得下把 .bleed 定 1400,每块单独看都对,摞在同一页就是断的 —— 规则卡文字挤在 701px,紧贴的双栏铺开 1400px,左侧 250px 死白。行长规则管的是段落散文,而这类页面主体是规则卡、表格、代码引用,散文只占一小部分,用错了地方。

判断标准:同一页里最窄的内容块和最宽的内容块,差距不该超过一档(现在是 1280 vs 1440,差 160px,看不出来)。

收尾必跑(页面上看不出来,不量就发现不了):

python3 ~/.claude/skills/html-mockup/assets/check-overflow.py <目录>/index.html

多视口检测横向溢出。模板已内置这几条兜底,别删:

架构图要更高规格时（可选）

改动汇报里的配图用 mermaid 就够。只有「图本身就是交付物」（架构评审、给外部看的系统地图）才值得升级到 archify —— 它渲染前用 schema + 布局约束校验,视觉高一档,但只有 sequence 几乎零成本,workflow 中文塞不进去。

用之前读 references/archify.md(四种图型的实测成本、boundary 的坑、合并 tab 页的做法、源码引用怎么挂)。

颜色是有意义的,别乱用

读者看原型第一件事是分清「哪些是现在就有的、哪些是这次要加的」。绿色标记就是干这个的。

ASCII 图:只用半角

中文是双宽字符,和半角混排必然错位,浏览器字体一换更歪。

• 框线里只放半角:表名、字段名、文件名、类名本来就是英文,直接用。
• 中文说明放框外,或用框内右侧 # 注释 形式单独成列,不参与对齐。
• ASCII 块必须包在 <pre class="ascii"> 里(模板已带等宽字体 + 深灰底 + 横向滚动),不要放进普通 <div>。
• 树用 ├─ └─ │,箭头用 → ←,层级缩进 2 空格。

order_pay
  ├─ pay_amount        decimal(10,2)   unchanged
  ├─ discount_amount   decimal(10,2)   unchanged
  └─ coupon_deduct     decimal(10,2)   NEW      # 券抵扣额,新增

mermaid:唯一用黑底的地方,而且必须渲染成图

页面整体是浅色,只有 mermaid 图用黑底,让它在一片白里一眼跳出来。

**写完源码卡不算完 —— 必须跑渲染器。**只贴源码等于没画:手机上是一坨代码,读者不会自己粘到别处渲染。

每张图的源码第一行必须带这段主题(渲染出来才是黑底):

%%{init:{'theme':'base','themeVariables':{'background':'#0b0f14','primaryColor':'#111827','primaryTextColor':'#e5e7eb','primaryBorderColor':'#334155','lineColor':'#64748b','secondaryColor':'#1e293b','tertiaryColor':'#0f172a','fontFamily':'ui-monospace,SFMono-Regular,Menlo,monospace'}}}%%

先按积木库 _blocks 的 .mmd 卡片写源码,页面写完后收尾时跑一次:

python3 ~/.claude/skills/html-mockup/assets/render-mermaid.py ~/www/<页面>/index.html
# 多个页面可一次传多个;--force 强制重渲(改了源码后用)

它做四件事:①mmdc 渲成 SVG 内联进 HTML(SVG 是纯文本,不违反单文件约束,不需要 CDN);②源码收进 <details> 折叠,仍可复制去 issue / PR;③按 viewBox 宽度分档 —— ≤900px 撑满容器(.mmd fit),>900px 保持原尺寸 + 横向滚动 + "可左右滑动"提示(.mmd wide),这是手机上宽图不被压成蚂蚁字的关键;④幂等,重复跑只重算尺寸不重渲。

依赖是 @mermaid-js/mermaid-cli + 系统 chrome。缺依赖时它保持源码卡原样、不会改坏页面,但那样图就没画出来 —— 先装:

npx --no-install mmdc --version || npm i -g @mermaid-js/mermaid-cli   # 需要 google-chrome/chromium

渲染器内部已用 PUPPETEER_EXECUTABLE_PATH 指向系统 chrome —— 不这么做 puppeteer 会去找自己缓存的特定版本然后报 Could not find Chrome (ver. …)。

收尾自检:grep -c '<svg' 页面 的数量要等于 .mmd 卡片数;还剩几张没渲染就是几张图读者看不到。

8. 合并 / 废弃旧原型

旧目录 index.html 换成跳转页,对方手里的旧链接照样能用:

<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8">
<meta http-equiv="refresh" content="0; url=../invoice_archive/?v=7#r1">
<title>已合并</title></head>
<body style="font-family:sans-serif;padding:40px;color:#555">
原型已合并到一页,正在跳转… <a href="../invoice_archive/?v=7#r1">点此打开</a>
</body></html>

9. 坑(全是真翻过车的)

10. desktop 原型

shop 后台页(网页版)要套完整后台壳,别用移动式窄卡片:.wrap 放宽到 1180,画出左侧菜单 + 顶栏 + 内容区三段,橙色主题。参照积木 A(桌面后台外壳)。

11. 参考现成的