HyperFrames 组件质量门槛（Component Quality Bar）：从缺陷证据到可复现的注册表审计标准

HyperFrames 组件质量门槛（Component Quality Bar）：从缺陷证据到可复现的注册表审计标准

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

本文是 HyperFrames 注册表（registry）贡献流程的核心质量标准说明，完整解读仓库内skills/hyperframes-registry/references/component-quality-bar.md中定义的审计规则：一个目录组件（catalog component）凭什么可以发布、凭什么会被砍掉，以及多人并行审计时如何得出相同结论。读完本文，你将掌握两遍式审计流程（机械 pass + 视觉 pass）、F1–F5 致命缺陷与 X1–X8 可修复缺陷的判定标准、重复项的存活规则、豁免条款（N1–N7）以及可直接抄用的逐项核对清单，能够在自己的注册表评审中给出有证据、可复现的裁定。

一句话规则：安装文件才是产品

在 HyperFrames 中，注册表项（registry item）分为两类：block是独立子合成（有自己的尺寸、时长和时间线，以data-composition-src挂载进宿主合成）；component是效果片段（无独立尺寸，直接粘贴进宿主 HTML）。注册表项是作者安装进自己合成并最终发布出去的运动原语（motion primitive）。目录页面是营销，安装到本地的文件才是产品。

因此，质量门槛文档规定了一条铁律：

评估对象永远是该项目自身的<name>.html单独挂载（mounted alone）时的表现，而不是demo.html，也不是目录页面——因为这两者都携带了作者实际上拿不到的脚手架。

对应到仓库结构，被评估的文件就是 registry/blocks/ 与 registry/components/ 下每个子目录里的主 HTML 文件，例如 registry/blocks/bar-chart-race/bar-chart-race.html。而demo.html（component 才有）只服务于两个目的：CI 预览管线用它生成缩略图和预览视频，以及作为使用参考——它不会被hyperframes add安装，详见 demo-html-pattern.md。

**The one rule（唯一规则）**全文如下：

一个项目只有在「作者安装的文件，单独挂载在它为之设计的地面上，渲染出它名字承诺的主题、并按描述的方式运动」时才配得上存在。任何无法满足这一点、又无法被修成其他项目尚未实现之物的东西，都会被砍掉。

这条规则本身就是审计的宪法：一切标准均源于真实缺陷，而非审美偏好。

审计如何运行：两遍式流程与挂载台架

审计分两遍，顺序固定。机械 pass 几乎零成本，可在数秒内扫过所有项目；视觉 pass 消耗浏览器与人的眼睛，只花在机械 pass 无法裁决的项目上。机械信号永远是候选（candidate），不是裁决（verdict）。

文档特别强调：hyperframes check不是视觉闸门——它会让渲染出空画面的合成通过（空渲染是合法渲染，不产生错误、警告或布局发现）。任何标准都不得单独依赖check。这与贡献流程中hyperframes check --no-contrast（0 控制台错误）的验证步骤互补，后者只是构建期下限，见 contributing.md。

挂载台架（The mount harness）

一个正常工作的项目可能因为台架搭错而得到假裁决，这三种错误全部是台架的错：

1. 两种形态、两种挂载方式。去掉 HTML 注释后，若文件含data-composition-id，它是子合成，须用data-composition-src="./<name>.html"挂到 clip 上；若不含，它是 snippet，直接内联进class="clip"的 div。把子合成内联会形成「文档套文档」，渲染成纯黑——看起来和死项目一模一样。
2. 使用项目自己的地面。取走其demo.htmlbody 规则的背景。一个墨色默认#18181b的 snippet，在自己#f7f7f8的地面上是 16:1 的大标题，在深色舞台上却是不可见的 1.5:1 污点。舞台不是证据。
3. 加载 GSAP 并注册一个暂停的根时间线，然后用hyperframes snapshot . --at 0.05,1.2,2.5,4.0 --no-end截图并阅读 contact sheet（快照帧联系表由 CLI 捕获管线生成，见 packages/cli/src/capture/contactSheet.ts）。

另外一条算术规则：项目自身data-duration短于台架时长时，末几帧必然空白——这是算术，不是缺陷。

致命缺陷（Fatal）：直接砍掉

Fatal 意味着缺陷底下没有任何值得保留的东西：要么不重写一个完全不同的项目就无法修复，要么修出来的东西目录里已经存在。必须引用具名证据；没有证据的致命裁决无效。

• F1 未实现自己的描述。标记中找不到该项目名称与描述所承诺的主题物。不是「渲染得差」，而是「文件里压根没有这个东西」。文档举的实例是ecosystem-constellation、hero-device-assemble和terminal-to-browser-deploy实为同一文件，只是空卡片 div 配了不同标题。自查方法：读完标记后，把名称换成任何其他项目的名称——如果文件里什么都不用改，说明名字只是贴在通用外壳上的标签。证据：具名主题没有任何元素（星座里没有节点、终端部署里没有终端）。
• F2 冗余重复。与另一个存活项目同时共享运动指纹（motion fingerprint）和标记骨架（markup skeleton）。指纹是去掉选择器后的 gsap 调用列表（保留 props、时长与 ease）；骨架是剥离 class 与文本后的标签序列。文档记录：一种 wipe 目前以相同 props、时长、easing 发布了 8 次，一种 word-stagger 发布了 7 次。证据：两个哈希都与兄弟项匹配，且兄弟项按下方 tie-break 规则胜出。
• F3 渲染不出任何东西。帧全空白，或具名主题从未出现，且项目已在自身地面、按 recipe 正确挂载。证据：四帧全空 + 成因（缺失兄弟资产、控制台ReferenceError、主题从未进入视口）。帧捕获工件实时渲染正常属误报，须在真实页面确认后再记录。
• F4 描述说的是另一个项目。帧显示承诺的事件从未发生：wipe 从不揭开第二面板、图表从不绘制系列。这不是措辞差异。
• F5 无法被做成可定位（seekable）。第 N 帧确实依赖第 N-1 帧，没有闭式解也没有有界回放，且做成可定位会变成另一种效果。极罕见——大多数累加器都有平凡改写，只有确认没有改写时才动用此条；用种子化、索引派生的替换Math.random()是 X7，不是 F5。证据：同一时间戳经不同 seek 路径到达的两张快照不一致。

可修复缺陷（Fixable）：保留并修复

真实缺陷，但项目有别的项目覆盖不了的存在理由，且修复有界。必须记录具体修复方案，绝不允许写「需要打磨」。

• X1 没有自己的时间线。没有__timelines注册，导致安装后的工件渲染为静止帧，而目录页看起来正常——因为生成器把 demo 的时间线移植进了预览。文档量化：213 个新组件中有 97 个处于此状态。修复：把末尾Timeline integration:recipe 折叠进一个真正的<script>，构建暂停时间线并注册；单元素项目约需 10–15 分钟。仅在没有任何可折叠的运动（通常同时是 F1）时才升级为致命。

• X2 名称声称了代码没有的技术。只 grep 代码区域，绝不 grep 文档头——头部的散文充满你正在找的词语，会给没有该技术的项目报匹配。判定表：

  名称模式	必须包含
  spring-*	elastic、back.、bounce或自定义 spring ease
  mask-*、*-mask*	mask或clip-path
  frosted*、*glass*	backdrop-filter
  *3d*、*depth*、*orbit*、*camera*	perspective、rotateX、rotateY、translateZ
  *-draw、*-trace、*stroke*	stroke-dash或pathLength

  修复：补上技术，或重命名——重命名往往是诚实的修复。

• X3 不可读。在 1920×1080 自身地面上：文本低于 4.5:1，或主题最小有意义特征小于约 24px。修复：按 placeholder-material.md 做一步值调整；文本永不落到 L1 以下。

• X4 占位渐变。用紫蓝调色板充当内容的占位。修复：单色色阶。目录已整体完成，新出现即回归而非历史缺陷。

• X5 硬编码墨色、无主题 token。项目自身文本或主题上出现字面量颜色且无var(--...)回退链，作者放到相反主题上就会消失。修复：经主题 token 路由，字面量作回退。

• X6 没有自己的标记。文件只有<style>和<script>，挂载即空盒。修复：自带示例标记，或在registry-item.json中声明为 attachment snippet 并给 demo 一个宿主元素。

• X7 未种子化随机。散点来自Math.random()而非元素索引。修复：改为由索引派生。贡献规范中 VFX 块要求使用mulberry32种子化 PRNG，正是为规避本条，见 templates.md。

• X8 声明了兑现不了的边界。数字变量没有min/max，控件给出项目表达不了的值，或默认值永远无法回归。修复：声明真实边界，或用数字字段替代滑块。反例可对照 registry/blocks/bar-chart-race/registry-item.json：其barCount声明"min": 3, "max": 12, "step": 1、periodDuration声明"min": 0.4, "max": 6，都是有界可兑现的正面示例。

重复项：谁存活

一个 group = 共享 F2 两个哈希的项目集合。恰好存活一个，按序裁决：

1. 名称真正描述共享运动者优先。一个 directional wipe 被其余成员借用，则保留 directional wipe。
2. 其次是有主题专属标记者。更多「只对该名称有意义」的元素，而不是更多元素。
3. 再其次是已在origin/main上的。移除已发布项目会破坏安装。
4. 绝不保留名称声称了共享实现没做的事的成员。frosted-glass-wipe没有backdrop-filter，spring-scale-in没有 spring，mask-reveal-up没有 mask——三者都不是幸存者。此类成员同时是 F2 和 X2，而 X2 无法在不破坏 group 的前提下修复。若所有成员都不诚实，保留最朴素的名字。

若 group 内每个成员都过不了 F1，整个 group 全部砍掉。不要为了软化计数而保留幸存者——十二个名字贴在一个空卡片外壳上是同一个坏项目，保留其中一个等于保留了坏项目。

同运动、真不同主题不算重复：柱状图、折线图和仪表盘填充可以共享一个 stagger——主题才是项目。

永不砍（Never cut）豁免条款

豁免是逐条的，不是 blanket 保护——受保护项目仍需回答其他所有行。

• N1 承重颜色：仅豁免 X4。chromatic-aberration-wipe（RGB 分离就是效果本身）、confetti（多色即庆祝）、matrix-decode（绿色即身份）、mesh-gradient-bg（渐变即主题）、multi-device-splay；us-map的渐变是序数 choropleth 色阶，属于承载数据的颜色。
• N2 真实产品描绘：豁免 X4 与 F1。Figma mock 里的 Figma logo 不是垃圾；logo-brand-close中的 HyperFrames 字标就是主题。评判占位内容，而非被描绘的产品。
• N3 刻意静止：豁免 X1。描述不承诺运动的项目不违反 X1；样式片段或被动 overlay 允许静止。
• N4 环境组：豁免 F3。作为背景而非镜头的项目不因平静而违反 F3。帧间 PSNR 可区分二者：环境组 45 或更高，真正在跑的东西为 17–24。对照描述评判。
• N5 静止态即 recipe 的from态：豁免 F3。confetti发布的.particlespan 停在 opacity 0，直到时间线将其扇出。静止不等于死亡。
• N6 附件片段：豁免 F3。文本切分器按设计没有标记，按 X6 定级。
• N7 已在origin/main上的 36 个项目：不在审计范围内。

机械首轮 pass 信号表

视觉 pass：裁决必需

从合成（而非 demo）渲染跨时长的至少四帧，按上述台架规则挂载，然后看。任何未得全绿的项目，记录前须在真实目录页确认。逐项记录：失败的条目、所见证据、致命或可修复。未经查看的项目不算通过。

校准：规则被真实帧修正

十项用本评分表评分、渲染并查看帧，其中三项修正了评分表本身而非反过来：

校准迫使的三处修正，全部是误砍：

• spring-scale-in首评 X3（约 1.5:1），那是台架的深色舞台而非项目——由此得出「使用项目自己的地面」。
• confetti首评 F3，其静止态是 recipe 的from态——由此得出 N5。
• char-slam-explode首评 F3（四帧全黑），它是子合成却被内联——由此得出两种形态规则。

一个砍掉正常工作的项目的评分表是错的，即使该裁决很顺手。

逐项核对清单

按序执行，命中首个 fatal 即停：

• 按项目形态正确挂载，使用自身地面，加载 GSAP 与暂停根时间线
• F1：标记包含具名主题
• F2：运动指纹与标记骨架未同时与幸存者共享
• F3：应用 recipe 后渲染出内容，或被 N3–N6 豁免
• F4：帧展示了描述承诺的事件
• F5：第 N 帧由第 N 帧计算而来
• X1–X8 记录具体修复方案
• 裁决引用条目指定的证据，而非印象

从标准到工程：这些规则在仓库中的落点

质量门槛不是孤立文档，它与注册表生态互相印证：构建侧，contributing.md 定义了 lint/check/render/snapshot 验证链与「placeholder 内容必须单色」的硬性要求；材质侧，placeholder-material.md 给出 ink 四档透明度色阶（L1 72% / L2 45% / L3 18% / L4 8% + hair 14%）与「text 永不低于 L1」的对比度下限，X3、X4、X5 的修复方案都指向它；模板侧，templates.md 的 caption/VFX/component 模板内嵌了暂停时间线注册、mulberry32种子化 PRNG、tl.eventCallback("onUpdate", renderScene)（禁用 requestAnimationFrame）等规避 X1/X7/F5 的既定模式。审计时遇到的每一个缺陷，几乎都能在这三份配套文档里找到对应修复。

适用前提说明：本文全部条款均基于本仓库当前内容（截至当前 checkout）。F1–F5、X1–X8、N1–N7 的编号与判据以 component-quality-bar.md 原文为准；其中引用的项目名（如ecosystem-constellation、terminal-to-browser-deploy）来自审计时分支上的历史实例，当前目录（registry/blocks、registry/components）中的实际条目以现状为准。执行审计前，请先完整阅读该原文档，确保多人并行时对同一项目得出同一裁决。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes