HyperFrames 变更日志视频中的可视化路由表：从 visualization-registry 读懂"用画面代替文字"的决策体系

在 HyperFrames 的仓库本地技能（.claude/skills/）中，changelog-video 技能负责把每周的 changelog markdown 变成一支约 45–60 秒的品牌化 1080×1080 视频。其中 references/visualization-registry.md 是整个技能的决策中枢：它是一张"show, don't tell"的路由表，决定每一个 changelog 主题该用哪种可视化手法来"演出来"，而不是用文字列表念出来。读完本文，你能掌握这套四级路由（ui-recreate / ui-analog / terminal / checklist）的完整判据、每类表面（surface）的 mock 解剖与动作编排（choreography）、已验证的类比（analog）清单，以及如何在技能流水线中正确使用并扩展这张注册表。

一、注册表解决什么问题：每个主题必须"演出来"

SKILL.md 中定义了这条技能的第一指令（prime directive）：visualize, don't list —— 每个主题都必须用"真实 UI 的动画 mock 或忠实类比"来演绎这次变更在体验层面做了什么，永远不用文字要点（text bullets）代替。

技能管线在步骤 2（Visualization routing）要求：对每个主题，先查 visualization-registry.md 选定表面（surface），并写下一行决策记录：

theme → surface → mock 将依次执行的 2-4 个动作，每个动作绑定一句脚本

如果注册表中没有匹配的表面、也不存在忠实的类比，就只能落到 checklist 场景——文档明确警告："don't invent fake UI for something we can't represent honestly"（不要为我们无法诚实表达的东西发明假 UI）。

这正是注册表存在的意义：它把"什么变更该用什么画面"从每次即兴判断，沉淀为可复用、可评审的决策依据。

二、四级路由：从最强到最弱的可视化层级

注册表开篇给出的路由表（Classes, strongest first）有严格的优先级顺序：

1. ui-recreate —— 这次变更发生在"我们能够忠实模拟的表面（surface）"上。直接复刻真实 UI 区域并让它演出来。
2. ui-analog —— 没有精确对应的真实表面，但存在诚实的 UI 隐喻（panel、meter、pipeline），且这个隐喻的行为（behavior）本身就是这次变更。
3. terminal —— 变更是一个 CLI 命令/标志位；那就把它打出来（type it），展示执行结果。
4. checklist —— 非视觉化内容（修复清单、依赖版本升级等）。最后手段（last resort）。

其中有一条红线贯穿全部四级：

Never invent UI that implies a screen that doesn't exist — an analog must depict the behavior (speed, batching, caching), not a fake product page.

即：永远不要发明出暗示"存在某个不存在的屏幕"的 UI。类比必须刻画行为（速度、批处理、缓存），而不能是伪造的产品页面。这条原则在后文"质量约束"一节还会展开。

三、ui-recreate：七个"已知表面"的解剖与编排

注册表的核心资产是 Known surfaces (ui-recreate) 表格：七个已经在过往 changelog 视频中验证过的真实 UI 表面，每个都包含两列可复用的"配方"——Mock anatomy（mock 的解剖结构）与 Proven choreography（已验证的动作编排）。当某个新主题命中这些表面时，直接照配方复用，无需重新推导。

1. Studio 编辑器 / 时间线

• 解剖：玻璃质应用框架（glass app frame）——标题栏（交通灯圆点、等宽字体的应用名、Export 药丸按钮）、带渐变美术的预览条、标尺 + 刻度、轨道（lanes）、播放头（playhead）、带等宽字体标签的片段（clips）。
• 编排：片段掉落/堆叠进轨道；拖拽到边缘/播放头时吸附（snap），伴随绿色吸附线闪烁；框选（marquee）→ 整组移动 → 整组缩放；播放头拖动（scrub）驱动预览美术（用 hue-rotate 模拟画面变化）。

2. Inspector / 设计面板

• 解剖：面板内含等宽字体（MONO）分区标题（INSPECTOR / VARIABLES）、键值行、发丝线分隔（hairline dividers）、虚线空槽（dashed empty slot）。
• 编排：绑定药丸（{{ var }}）飞入属性槽；数值切换用"遮罩滑动"（masked slide：旧值向上出、新值向上入）；画布上画出选中框。

3. 画布 + 元素

• 解剖：迷你舞台卡片、虚线选中框、一个实时文本元素。
• 编排：文本随面板编辑同帧更新（text updates same-frame with panel edits），绿色下划线脉冲（green underline pulse）标记"实时预览时刻"。

4. 变体渲染（Variant renders）

• 解剖：小卡片：展示字体标题 + 等宽文件名。
• 编排：沿对角线依次飞出（cascade out diagonally），交错延迟（stagger）≤ 0.15s。

5. Storyboard 视图

• 解剖：一排场景缩略图，带等宽场景标签。
• 编排：缩略图如瀑布般落位（file in as a waterfall）；其中一张被拖拽重排。

6. 终端 / CLI

• 解剖：玻璃条带，等宽字体 19-20px，$ 提示符调暗（dim）。
• 编排：逐字打出（stagger 0.02s/字）；结果行在一个 0.3–0.5s 的停顿（beat）之后落地。

7. 渲染面板（Render panel）

• 解剖：RENDER 标题、大号 tabular-nums 帧计数器、进度条（绿色填充即"高光时刻"）、状态芯片（status chips）。
• 编排：进度条 + 计数器以 power2.in 推进——慢到快的加速曲线读起来就是"更快了"；状态芯片随旁白（VO）关键词落位。

注意最后一行把"叙事"编码进了缓动函数本身：用 power2.in（slow→fast）表达性能提升，这正对应文档"analog must depict the behavior"的原则。这类缓动选择与技能体系中 cut-the-curve 的缓动目录一致（见 cut-the-curve SKILL.md，其中同样使用 power2.in/power2.out 表达"软光学感而非动量感"的过渡）。

四、ui-analog：八种"已验证类比"配方

当变更没有精确的真实表面对应时，用 Proven analogs (ui-analog) 表。每一行给出：变更类型 → 类比画面 → 行为刻画方式：

变更类型	类比画面	行为刻画
色彩分级 / LUT	素材美术旁放滑块行（标签 + 轨道 + 旋钮）	每个旋钮移动都在同一帧重新过滤画面（因果关系，causal）
渲染/导出速度	渲染面板的计数器 + 进度条	缓动本身讲故事；若论断是数字，再加 before/after 时间芯片
批处理（帧、请求）	一排小刻度（ticks）	方括号围绕分组画出；刻度向簇内微移（nudge into clusters）
缓存	两条相同的请求行	第一行跑满整条进度；第二行瞬间短路到 ✓，带一个 cache 芯片
导入/转译管线（如 Figma→HF）	源工件卡片变形/停泊（docks）进 HF comp 卡片——源工件是纯 DOM/CSS mock（不调 Figma API、不用 token、不拉取任何数据）	分阶段：源卡片 → 抽取芯片（tokens、components、motion）的"飞行/箭头" → 组装成 comp；芯片即载体（carriers）
单次通过 / 去重	N 条并行项行坍缩到一条共享轨道	各行滑入同一根条；计数芯片递减
并发上限 / 锁	芯片队列穿过一道闸门	前 k 个通过，其余等待；闸门芯片显示上限值
错误呈现（toast、原因）	表面角落长出一张 toast 卡片	操作微妙地失败 → toast 滑入，等宽字体显示原因文本

两个值得注意的设计细节：

• Figma→HF 管线行特意声明"NO Figma API, no tokens, nothing fetched"——类比画面只 mock 源工件的外观与转译过程，绝不暗示存在真实的远程调用。这是"不发明不存在的屏幕"红线在具体条目上的落位。
• "芯片即载体"（chips are the carriers） 与 motion-doctrine 的 Carriers 概念直接呼应：motion-doctrine SKILL.md 指出"眼睛跟随物体而非抽象"，最强接缝会把一个具体载体以匹配的位置和速度交给下一个镜头。注册表里的 chips、binding pill、draggable thumbnail 都是同一套语法。

五、checklist 场景：作为最后手段的严格规格

当内容真的无法视觉化（可靠性修复清单、依赖版本升级）时，checklist 场景有精确的"克制度"规格：

• 玻璃卡片（glass card），≤6 行等宽字体条目；
• 绿色 ✓ 打勾动画落在每个条目对应的 VO 词上：back.out(1.5)、时长 0.3s，外加行亮度脉冲（row brightness pulse）；
• 超过 6 项的条目直接砍掉——它们只存在于结尾"完整 digest 链接"中（"Items beyond 6: cut, they live in the digest link"）。

这与 SKILL.md 步骤 1 的编辑预算一致：全片 45–60s，每主题 9–12s、最多 3 个口播条目，30 条 changelog 也要压缩到 ≤14 个口播节拍。checklist 的 6 行上限是"cutting is the job"这一编辑纪律在画面层的具体化。

六、扩展注册表：新表面的登记协议

注册表末尾的 Adding a surface 一节定义了它自身的维护协议：

When a new UI area ships, add a row here (anatomy + choreography) the first time it's mocked, so the next changelog reuses it instead of re-deriving it.

即：每当产品上线一个新的 UI 区域，在第一次为它做 mock 时，就把该表面的"解剖 + 编排"登记成一行，让下一次 changelog 直接复用而不是重新推导。这使得注册表是一个随产品演进而增长的知识资产：本周的即兴方案，下周变成表中的既定配方。

七、在流水线中的位置：路由决策如何被下游消费

把注册表放回 SKILL.md 的完整管线中，它处于"解析剪辑（步骤 1）"之后、"两层脚本（步骤 3）"之前：

1. 步骤 0 · Bootstrap：先把技能的资产（assets/fonts 中的 TT Norms Pro / ABC Solar Display / TT Norms Mono 字体、bg-pattern.mp4 背景、bgm.mp3）与 examples/master-skeleton.html 骨架复制到项目，再开始写任何 composition HTML。注册表表格里反复出现的 "glass frame / panel / glass card" 解剖，正是从这套骨架继承品牌 token（奶油色底、克制的品牌绿、玻璃卡片）得到的。
2. 步骤 1 · Parse + editorial cut：提取周范围、头部统计、主题与条目，按故事序排列（旗舰特性 → 产品表面 → 性能 → 可靠性）。
3. 步骤 2 · Visualization routing：逐主题查注册表，产出 theme → surface → sequenced actions 一行决策。若选中 terminal 类，动作编排就套用第三节的"终端/CLI"行（逐字打出 + 0.3–0.5s 停顿后结果落地）；选中 ui-analog 则套用对应类比配方。
4. 步骤 3 · 两层脚本：按 references/script-voice.md 的"spoken/display 双层契约"写 token 行。examples/script-tokens.json 给出了样例：裸字符串表示 display 与 spoken 相同，对象（如 { "display": "JSON", "spoken": "jay-sawn" }）表示两层分叉。其中"Teach the simple command"规则与路由表协同：若特性有一行调用方式（斜杠命令、CLI one-liner），脚本逐字念出、mock 同时展示输入过程——"命令是结果的可见原因"，这通常是 terminal 类路由的触发条件。
5. 步骤 4–6 · VO / 构建 / 门禁：TTS 生成旁白后，用 scripts/align-captions.mjs 把 spoken 层词级时间戳映射回 display token 生成 captions.json（该脚本用 Levenshtein 模糊匹配吸收 TTS 时间戳噪声，无法吸收的差异会打印 MISMATCH，每条都必须解决）；随后按 motion-doctrine 的顺序完成 ledger.json → seam-stamp → 内部节拍对齐 VO 词 → seam-gate 校验，最终由 hyperframes check 与帧级抽检把关。

从源码结构看，注册表本身是"人（Agent）读的决策表"而非可执行代码——仓库中没有任何脚本 import 它；它的约束力来自 SKILL.md 流程强制在写脚本前先路由（"Route every theme/item through references/visualization-registry.md BEFORE writing the script"）。这正是仓库本地技能体系（.claude/skills/ 只在本仓库内生效，区别于可分发的 skills/，见 .claude/skills/README.md）的一种知识组织方式：把编排经验固化成 Markdown 表格，供 Agent 每次开工时查阅。

八、质量约束：注册表如何防止"画面失信"

把全文的原则收敛成几条可检查的约束，正好对应 SKILL.md 的反模式表：

反模式	注册表给出的替代
用要点幻灯片讲 UI 变更	mock 真实表面"演出来"（ui-recreate 七表面配方）
给无法表达的内容做假 UI	诚实的 checklist 场景（≤6 行、超项砍给 digest 链接）
类比画成伪造产品页	类比只刻画行为（speed / batching / caching），Figma 管线行明确零真实调用

配套的品牌纪律同样服务于"诚实感"：每个场景只用一次品牌绿高光（one green moment per scene，#5ef17c）；渲染面板行中"绿色填充 = 高光时刻"即此约束在配方中的体现。

小结

visualization-registry.md 用不到一屏的篇幅完成了三件事：给"什么变更用什么画面"一个四级优先级判据；为七个真实表面和八种类比沉淀了可复用的"解剖 + 编排"配方；并用一条红线（不发明不存在的屏幕、类比必须刻画行为）保证画面叙事不失信。对维护者而言，理解它的关键是把它当作技能流水线的决策中枢：每周 changelog 的每个主题先在这里路由，再进入两层脚本、VO 对齐与接缝门禁——而"第一次 mock 就登记新表面"的协议，保证这张路由表会随产品演进持续增厚。