hyperframes

HyperFrames

HTML 是视频的事实来源。一个合成由 HTML 文件构成，其中使用 data-* 属性设置时间，使用 GSAP 时间线控制动画，并使用 CSS 设置外观。框架负责处理片段可见性、媒体播放和时间线同步。

方法

探索（仅适用于探索性请求）

对于开放式请求（“帮我制作一个产品发布视频”“为我们的品牌创作一些内容”），如果用户尚未确定方向，应先了解其意图，再选择颜色：

• 受众 — 谁会观看？开发者？高管？普通消费者？
• 平台 — 视频在哪里播放？社交平台（15s）、网站主视觉、产品演示，还是内部场景？
• 优先事项 — 什么最重要？动画质量？内容准确性？品牌还原度？速度？
• 变体 — 用户想要多个选项，还是单个最佳方案？

对于具体请求（“添加一张标题卡”“修复第 3 个场景的时间”），跳过探索环节。

对于探索性请求，可考虑提供 2-3 种有实质差异的变体——不只是更换颜色，还可以采用不同的节奏、能量水平或结构方案。一种稳妥且符合预期，一种更具创意。不必强制提供；在适当时可将其作为一种工具。

第 1 步：设计系统

如果项目中存在 design.md 或 DESIGN.md，请先阅读（检查两种大小写形式——在 Linux 上它们是不同的文件）。这是品牌颜色、字体和约束的事实来源。使用其中的确切值，不要自行编造颜色或替换字体。任何格式都可以（YAML frontmatter、正文、表格等——只需提取其中的值）。

如果其中指定了本地找不到的字体（没有包含 .woff2 文件的 fonts/ 目录，也不是内置字体），请在编写 HTML 前提醒用户：“design.md 指定了 [font name]，但未找到字体文件。请将 .woff2 文件添加到 fonts/，否则我会改用 [closest built-in alternative]。”

如果不存在 design.md，请让用户选择：

1. 用户指定了某种风格或氛围？ → 阅读 visual-styles.md，查看其中的 8 种命名预设。选择最接近的一种。
2. 想从视觉上浏览选项？ → 运行设计选择器：阅读 references/design-picker.md，了解完整工作流。它会提供一个可视化选择器页面。用户在浏览器中配置氛围、调色板、排版和动画，然后复制生成的 design.md 并粘贴回对话中。
3. 想跳过并快速开始？ → 询问：氛围、浅色还是深色，以及是否有品牌颜色或字体。然后从 house-style.md 中选择调色板。

design.md 定义品牌，不定义视频合成规则。 视频合成规则见 references/video-composition.md 和 house-style.md。应按适合视频的比例使用品牌颜色，不要采用 Web UI 的不透明度。

第 2 步：扩展提示词

每个合成都必须执行此步骤（单场景作品和简单编辑除外）。此步骤会结合 design.md 和 house-style.md 明确用户意图，并生成一致的中间产物，供所有下游 Agent 以相同方式读取。

阅读 references/prompt-expansion.md，了解完整流程和输出格式。

步骤 3：规划

在编写 HTML 之前，先从宏观层面进行思考：

1. 内容 — 观众应该看到什么？确定叙事脉络、关键时刻和情绪起伏。
2. 结构 — 需要多少个画面？哪些是子合成，哪些是内嵌内容？各条轨道承载什么内容（视频、音频、叠加层、字幕）？
3. 节奏 — 实现前先确定场景节奏。哪些场景节奏明快，哪些需要停留？着色器在哪里出现？能量在哪一刻达到峰值？为节奏模式命名：快-快-慢-快-着色器-停留。阅读 references/beat-direction.md，了解节奏模板。
4. 时长 — 哪些片段决定总时长？转场在哪里发生？节奏如何安排？
5. 布局 — 先构建最终状态。参见下文的“先布局，后动画”。
6. 动画 — 然后按照以下规则添加动效。

按要求构建。 用户要求“一个标题卡片”，并不意味着要做“一个标题卡片 + 3 个辅助场景 + 环境音乐 + 字幕”。每个场景、每个元素、每个补间都必须有存在的理由。如果增加场景或元素确实能提升作品效果，可以提出建议——但不要擅自添加。

对于小幅修改（修正颜色、调整时长、添加一个元素），直接跳到规则部分。

编写任何合成 HTML 之前，必须确认已根据步骤 1 确定视觉识别风格。如果你正准备使用 `#333`、`#3b82f6` 或 `Roboto`，说明你跳过了这一步。

先布局，后动画

将每个元素放在它最清晰可见的时刻应处的位置——也就是元素已完全进入、位置正确且尚未退出的那一帧。首先将其写成静态 HTML+CSS。暂时不要使用 GSAP。

原因： 如果你把元素放在动画起始状态（画面外、缩放为 0、不透明度为 0），再通过补间把它们移到你认为的最终位置，那你其实是在猜测最终布局。直到视频渲染出来之前，重叠都不会显现。先构建最终状态，就能在添加动效之前发现并修复布局问题。

流程

1. 确定每个场景的主视觉帧——即最多元素同时可见的时刻。这就是你要构建的布局。
2. 为该帧编写静态 CSS。.scene-content 容器必须使用 width: 100%; height: 100%; padding: Npx;、display: flex; flex-direction: column; gap: Npx; box-sizing: border-box 填满整个场景。使用内边距将内容向内推——绝不要在内容容器上使用 position: absolute; top: Npx。当内容高于剩余空间时，绝对定位的内容容器会溢出。绝对定位仅用于装饰元素。
3. 使用 gsap.from() 添加入场动画——从画面外或不可见状态，动画至 CSS 设定的位置。CSS 位置是准确的最终位置；补间描述的是到达该位置的过程。（对于通过 data-composition-src 加载的子合成，优先使用 gsap.fromTo()——参见 references/motion-principles.md 中关于承载关键内容的 GSAP 规则。）
4. 使用 gsap.to() 添加退场动画——从 CSS 设定的位置，动画至画面外或不可见状态。

示例

/* scene-content fills the scene, padding positions content */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* Container fills any scene size (1920x1080, 1080x1920, etc).
   Padding positions content. Flex + gap handles spacing. */

错误示范——尺寸硬编码并使用绝对定位：

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// Step 3: Animate INTO those positions
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// Step 4: Animate OUT from those positions
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

当元素在不同时间共用空间时

如果同一区域中的元素 A 先退场，元素 B 后入场，那么二者在各自的主视觉帧中都应有正确的 CSS 位置。时间线的顺序可以确保它们不会同时出现在画面中——但如果跳过布局步骤，就无法发现因时间设置错误而意外重叠的情况。

什么情况属于有意重叠

分层效果（文字后方的光晕、阴影元素、背景图案）和按 z 轴堆叠的设计（卡片堆叠、纵深层次）都属于有意重叠。布局步骤的目的是发现无意重叠——两个标题相互覆盖、统计数据遮住标签，或内容溢出画面。

数据属性

所有片段

属性	必填	值
id	是	唯一标识符
data-start	是	秒数或片段 ID 引用（"el-1"、"intro + 2"）
data-duration	img/div/合成必填	秒数。视频/音频默认使用媒体时长。
data-track-index	是	整数。同一轨道上的片段不能重叠。
data-media-start	否	源媒体中的裁剪偏移量（秒）
data-volume	否	0-1（默认值为 1）

data-track-index 不会影响视觉层叠顺序——请使用 CSS z-index。

合成片段

属性	必填	值
data-composition-id	是	唯一合成 ID
data-start	是	开始时间（根合成：使用 "0"）
data-duration	是	优先于 GSAP 时间线时长
data-width / data-height	是	像素尺寸（1920x1080 或 1080x1920）
data-composition-src	否	外部 HTML 文件的路径
data-variable-values	否	子合成宿主的每个实例变量覆盖值的 JSON 对象

在根 <html> 元素上：

属性	必填	值
data-composition-variables	否	已声明变量的 JSON 数组（id/type/label/default）——用于驱动 Studio 编辑 UI，并为 getVariables() 提供默认值

合成结构

通过 data-composition-src 加载的子合成使用 <template> 包装器。独立合成（主 index.html）不使用 <template>——它们会将 data-composition-id div 直接放在 <body> 中。在独立文件中使用 <template> 会使所有内容对浏览器隐藏，并导致渲染失败。

子合成结构：

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    
    <style>
      [data-composition-id="my-comp"] {
        /* scoped styles */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // tweens...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

在根文件中加载：<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

变量（参数化组合）

无需编辑源 HTML，即可使用不同内容（标题、主题颜色、价格、字幕）渲染同一组合。

三步模式：

1. 声明 在组合的 <html> 根元素上使用 data-composition-variables 声明变量。每个条目都需要 id、type（取值为 string、number、color、boolean、enum 之一）、label 和 default。enum 条目还需要 options: [{value, label}, ...]。
2. 读取 在组合的脚本中使用 window.__hyperframes.getVariables() 读取解析后的值。返回声明的默认值、单实例覆盖值和 CLI 覆盖值合并后的结果。
3. 覆盖 在渲染时使用 npx hyperframes render --variables '{...}'（顶层），或在宿主元素上使用 data-variable-values='{...}'（针对子组合的单实例）。

<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"Title","default":"Hello"},
  {"id":"theme","type":"enum","label":"Theme","default":"light","options":[
    {"value":"light","label":"Light"},
    {"value":"dark","label":"Dark"}
  ]}
]'
>
  <body>
    <div data-composition-id="root" data-width="1920" data-height="1080">
      <h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { title, theme } = window.__hyperframes.getVariables();
        document.getElementById("hero").textContent = title;
        document.body.dataset.theme = theme;
      </script>
    </div>
  </body>
</html>

# Dev preview uses declared defaults
npx hyperframes preview

# Render with overrides
npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4

# Or from a JSON file
npx hyperframes render --variables-file ./vars.json

子组合的单实例值： 在通过 data-composition-src 加载的子组合中，同样可以使用 getVariables()。每个宿主元素都会传入自己的值：

<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Enterprise","price":"Custom"}'
></div>

运行时会按实例将每个宿主元素的 data-variable-values 覆盖到子组合声明的默认值上，因此可以多次嵌入同一源，并为每次嵌入使用不同的内容。

经验法则：

• 始终为每个声明的变量提供合理的 default。开发预览使用默认值——如果没有默认值，组合必须等到提供 --variables 后才能正确渲染。
• 在脚本开头读取一次变量（const { title } = ...），不要在帧循环或事件处理程序中读取——每次调用 getVariables() 都会分配一个新对象。
• 在 CI 中使用 --strict-variables，以便在遇到未声明的键或类型不匹配时立即失败。
• 变量类型会在渲染时进行验证。string、number、boolean 和 color（十六进制字符串）会检查 typeof；enum 会检查值是否在声明的 options 中。

视频和音频

视频必须设置为 muted playsinline。音频始终使用单独的 <audio> 元素：

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

时间轴约定

• 所有时间轴均以 { paused: true } 启动——由播放器控制播放
• 注册每条时间轴：window.__timelines["<composition-id>"] = tl
• 框架会自动嵌套子时间轴——不要手动添加
• 时长取自 data-duration，而不是 GSAP 时间轴长度
• 切勿创建空补间来设置时长

规则（不可妥协）

确定性： 不要使用 Math.random()、Date.now() 或基于时间的逻辑。如果需要伪随机值，请使用带种子的 PRNG（例如 mulberry32）。

GSAP： 仅对视觉属性（opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、变换）制作动画。不要对 visibility、display 制作动画，也不要调用 video.play()/audio.play()。

动画冲突： 切勿在多个时间轴上同时对同一元素的同一属性制作动画。

禁止使用 repeat: -1： 无限重复的时间轴会破坏捕获引擎。根据合成时长计算精确的重复次数：repeat: Math.ceil(duration / cycleDuration) - 1。

同步构建时间轴： 切勿在 async/await、setTimeout 或 Promise 中构建时间轴。页面加载后，捕获引擎会同步读取 window.__timelines。编译器会嵌入字体，因此字体会立即可用——无需等待字体加载。

绝不要：

1. 忘记注册 window.__timelines
2. 使用视频播放音频——始终使用静音视频 + 单独的 <audio>
3. 将视频嵌套在定时 div 中——使用非定时包装元素
4. 使用 data-layer（应使用 data-track-index）或 data-end（应使用 data-duration）
5. 对视频元素的尺寸制作动画——应对包装 div 制作动画
6. 对媒体调用 play/pause/seek——播放由框架控制
7. 创建缺少 data-composition-id 的顶层容器
8. 在任何时间轴或补间中使用 repeat: -1——始终使用有限次重复
9. 异步构建时间轴（在 async、setTimeout、Promise 中）
10. 在后续场景中对剪辑元素使用 gsap.set()——这些元素在页面加载时尚不存在于 DOM 中。应在时间轴中 data-start 时间点或之后，使用 tl.set(selector, vars, timePosition)。
11. 在正文文本中使用 <br>——强制换行不会考虑实际渲染的字体宽度。自然换行的文本再加上 <br> 会产生多余的换行，导致重叠。应使用 max-width 让文本自然换行。例外：每个词都刻意单独占一行的短显示标题（例如 130px 字号的 "THE\nIMMORTAL\nGAME"）。

场景转场（不可妥协）

每个多场景合成都必须遵循以下所有规则。违反任何一条都会导致合成出错。

1. 始终在场景之间使用转场。 不要使用跳切，没有例外。
2. 始终为每个场景使用入场动画。 每个元素都必须通过 gsap.from() 动画进入。不得让任何元素以完整形态直接出现。如果一个场景有 5 个元素，就需要 5 个入场补间。
3. 除最后一个场景外，绝不要使用退场动画。 也就是说：转场触发前，禁止使用任何让不透明度变为 0、让 y 移出屏幕、让缩放变为 0 或其他任何“退场”效果的 gsap.to()。转场本身就是退场。转场开始时，离场场景的内容必须完全可见。
4. 仅限最后一个场景： 最后一个场景可以让元素淡出（例如淡出至黑屏）。只有这个场景允许使用 gsap.to(..., { opacity: 0 })。

错误 — 转场前使用退场动画：

// BANNED — this empties the scene before the transition can use it
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// transition fires on empty frame

正确 — 仅使用入场动画，由转场处理退场：

// Scene 1 entrance animations
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// NO exit tweens — transition at 7.2s handles the scene change
// Scene 2 entrance animations
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

动画规范

• 首个动画延后 0.1-0.3s 开始（不要在 t=0 开始）
• 让入场补间使用不同的缓动效果——每个场景至少使用 3 种不同的缓动效果
• 不要在同一场景内重复入场动画模式
• 避免在深色背景上使用全屏线性渐变（H.264 会出现色带——请使用径向渐变，或纯色背景 + 局部辉光）
• 渲染视频中的标题至少为 60px，正文至少为 20px，数据标签至少为 16px
• 对数字列使用 font-variant-numeric: tabular-nums

如果不存在 design.md，请遵循 house-style.md 中的默认美学规范。

字体排版与资源

• 内置字体： 在 CSS 中填写所需的 font-family，编译器会自动嵌入受支持的字体。
• 自定义字体： 如果 design.md 指定的字体不是内置字体，用户必须在 fonts/ 目录中提供 .woff2 文件。如果缺少这些文件，请在编写 HTML 前发出警告。文件存在时，添加指向本地文件的 @font-face 声明。
• 为外部媒体添加 crossorigin="anonymous"
• 对于动态文本溢出，使用 window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })
• 所有文件都位于项目根目录，与 index.html 并列；子合成使用 ../

编辑现有合成

• 读取实际文件，不要猜测。 编辑、扩展或创建配套合成时，读取现有源文件。不要凭记忆还原十六进制颜色代码，也不要猜测 GSAP 缓动模式。合成本身就是规范——从中提取精确值。
• 按照读取到的内容匹配现有字体、颜色和动画模式
• 只更改请求的内容
• 保留无关片段的时间安排

输出检查清单

快速（立即运行，并等待结果）：

• npx hyperframes lint 和 npx hyperframes validate 均通过
• 如果存在 design.md，确认设计符合要求

较慢（向用户展示预览时并行运行）：

• npx hyperframes inspect 通过，或每个报告的溢出都已明确标记为有意溢出
• 已处理对比度警告（参见下方的质量检查）
• 已验证动画编排（参见下方的质量检查）

质量检查

视觉检查

hyperframes inspect 会在无头 Chrome 中运行合成，沿时间轴定位，并通过时间戳、选择器、边界框和修复提示，标出视觉布局问题。在 lint 和 validate 之后运行：

npx hyperframes inspect
npx hyperframes inspect --json

失败通常表示文本溢出气泡或卡片、固定尺寸标签无法容纳动态文案，或文本移出了画布。可通过增大容器尺寸或内边距、减小字号或字间距、设置实际的 max-width 让文本在容器内换行，或对动态文案使用 window.__hyperframes.fitTextFontSize(...) 来修复。

对于内容密集的视频，使用 --samples 15；对于特定的主视觉帧，使用 --at 1.5,4,7.25。默认会折叠重复的静态问题，避免 Agent 上下文被大量信息淹没。如果溢出是入场或退场动画中的有意设计，请为该元素或其祖先添加 data-layout-allow-overflow。如果装饰元素不应接受审计，请为其添加 data-layout-ignore。

hyperframes layout 是同一项检查的兼容别名。

对比度

hyperframes validate 默认会执行 WCAG 对比度审计。它会定位到 5 个时间戳，对页面截图，对每个文本元素后方的背景像素进行采样，并计算对比度。未通过时会显示警告：

⚠ WCAG AA contrast warnings (3):
  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)

如果出现警告：

• 深色背景：调亮未通过的颜色，直到达到 4.5:1（普通文本）或 3:1（大号文本，即 24px+ 或 19px+ 粗体）
• 浅色背景：调暗颜色
• 保持在同一调色板系列中——不要另创颜色，调整现有颜色即可
• 重新运行 hyperframes validate，直到没有警告

如果需要快速迭代且计划稍后检查，可使用 --no-contrast 跳过。

设计规范遵循情况

如果存在 design.md，请在创作完成后核实作品是否遵循其中的规范。阅读 HTML 并检查：

1. 颜色 — 作品中的每个十六进制颜色值都应出现在 design.md 的调色板部分中（无论用户将其命名为 Colors、Palette、Theme 等）。标记任何自行添加的颜色。
2. 排版 — 字体系列和字重应与 design.md 中的字体规范一致。不得替换。
3. 圆角 — border-radius 值应符合声明的圆角样式（如果有）。
4. 间距 — padding 和 gap 值应处于声明的密度范围内（如果有）。
5. 层次深度 — 阴影用法应符合声明的层次深度级别（如果有）（flat = 无，subtle = 轻微，layered = 光晕）。
6. 规避规则 — 如果 design.md 中有列出应避免事项的部分（通常称为“What NOT to Do”、“Don'ts”、“Anti-patterns”或“Do's and Don'ts”），请确认作品中没有出现这些内容。

将违规项列为检查清单。交付前修复每一项。

如果不存在 design.md（仅遵循 house style 的路径），请核实：

1. 调色板一致性 — 所有场景使用相同的背景色、前景色和强调色。不得为不同场景自行添加颜色。
2. 避免随意采用默认值 — 根据 house-style.md 中的“Lazy Defaults to Question”列表检查作品。如果出现其中任何一项，必须是根据内容有意选择的，而非默认采用。

动画映射

完成动画创作后，运行动画映射以核实动画编排：

node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map

会输出一个 animation-map.json，其中包含：

• 每个补间动画的摘要："#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"
• ASCII 时间线：作品整个持续时间内所有补间动画的甘特图
• 错峰检测：报告实际间隔（"3 elements stagger at 120ms"）
• 空白时段：超过 1s 且没有动画的时段——是有意停留，还是缺少入场动画？
• 元素生命周期：首次/最后一次动画时间、最终可见状态
• 场景快照：5 个关键时间点上可见元素的状态
• 标记：offscreen、collision、invisible、paced-fast（少于 0.2s）、paced-slow（超过 2s）

阅读 JSON。检查摘要中是否有任何意外情况。逐一检查所有标记，并修复或说明原因。确认时间线呈现了预期的动画编排节奏。修复后重新运行。

小幅修改时跳过（例如修复颜色、调整一个时长）。新作品和重大动画修改时运行。

---

参考资料（按需加载）

• references/captions.md — 字幕、音频同步的字幕、歌词和卡拉 OK。自适应语气的样式检测、逐词样式、文本溢出防止、字幕退出保障、词语分组。添加任何与音频时间同步的文本时请阅读。

• references/audio-reactive.md — 音频响应式动画：将频段和振幅映射到 GSAP 属性。需要视觉效果响应音乐、人声或声音时请阅读。

• references/css-patterns.md — CSS+GSAP 标记高亮：高亮、圈选、爆发、涂鸦、描摹。结果确定，且完全可定位。添加文本视觉强调时请阅读。

• references/video-composition.md — 视频媒介规则：密度、色彩呈现、缩放、画面构图，以及将 design.md 作为品牌规范而非布局规范。务必阅读——这些规则优先于网页设计直觉。

• references/beat-direction.md — 节拍规划：概念、情绪、编排动词、节奏模板、转场决策、深度层次。多场景合成时务必阅读。

• references/typography.md — 排版：字体搭配、OpenType 特性、深色背景调整、字体发现脚本。务必阅读——每个合成都有文本。

• references/motion-principles.md — 动效设计原则、图像动效处理、GSAP 核心规则。务必阅读——每个合成都有动效。

• references/techniques.md — 11 种视觉技巧及代码模式：SVG 绘制、Canvas 2D、CSS 3D、动态排版、Lottie、视频合成、打字效果、可变字体、MotionPath、速度转场、音频响应式。规划每个节拍所用技巧时请阅读。

• references/narration.md — 节奏、语气、脚本结构、数字读法、开场白模式。合成中包含画外音或 TTS 时请阅读。

• references/design-picker.md — 使用视觉选择器创建 design.md。不存在 design.md 且用户希望创建时请阅读。

• visual-styles.md — 8 种命名视觉风格，包含十六进制调色板、GSAP 缓动特征和着色器搭配。用户指定风格或生成 design.md 时请阅读。

• house-style.md — 未指定 design.md 时使用的默认动效、尺寸和调色板。

• patterns.md — 画中画、标题卡片、幻灯片模式。

• data-in-motion.md — 数据、统计和信息图模式。

• references/transcript-guide.md — 字幕侧的转录文本处理：输入格式、强制质量检查、JS 清理、OpenAI/Groq API 回退方案、“不存在转录文本时”的处理流程。（有关 transcribe CLI 调用、模型选择规则和 .en 注意事项，请参阅 hyperframes-media 技能。）

• references/dynamic-techniques.md — 动态字幕动画技巧（卡拉 OK、clip-path、猛击、散开、弹性、3D）。

• references/transitions.md — 场景转场：交叉淡化、擦除、显现、着色器转场。能量与情绪选择、CSS 与 WebGL 的使用指导。多场景合成时务必阅读——没有转场的场景会让人感觉像硬切。

  • transitions/catalog.md — 硬性规则、场景模板，以及各类型实现代码的索引。
  • 着色器转场位于 @hyperframes/shader-transitions（packages/shader-transitions/）中——请阅读软件包源码，而非技能文件。

GSAP 模式和特效位于 /gsap 技能中。