HyperFrames Frame.md 详解：3 分钟吃透视频设计 DNA 机制

前阵子做产品介绍视频，用 HyperFrames 渲染完，AI Agent 自动生成的画面一片"AI 味"——渐变文字、青紫蓝配色、Roboto 字体，看着就像从 LLM 训练集里捞出来的模板。

我以为是 prompt 没写好，反复改了 5 版，没用。

后来翻 hyperframes 仓库的 SKILL.md 才看到一行话：

frame.md is the preferred spec for video/hyperframes projects and wins if more than one exists; it uses the same format as design.md. It's the source of truth for brand colors, fonts, and constraints.

意思是说：视频项目的"设计 DNA"应该存在一个 frame.md 文件里，而不是让 AI 每次都去猜。换句话说，没有 frame.md，AI 就在凭"训练集平均值"给你出图；有了 frame.md，AI 就有了一致的品牌锚点。

今天就详细拆解这个 v0.6.71 刚被官方"扶正"的文件——它是什么、为什么存在、长什么样、怎么用。

一、为什么需要 Frame.md

先说个真问题。

我之前给客户做 3 个不同项目的视频，每个项目都让 AI 重选配色和字体。结果：第一个用了紫色渐变，第二个用了青色科技，第三个强行致敬 Notion 灰——三个视频放一起像三个团队做的。

官方 SKILL.md 里有一句话点透了这件事：

Every brand has a design.md. None of them were written for a camera. frame.md is the missing translation layer: it takes your web-context design spec and inverts it for the frame — the same tokens, the same rules, but rewritten so an AI agent can compose a promo video without guessing at scale or reaching for web chrome.

翻译：web 端的 design.md 是给浏览器看的，frame.md 是给"镜头"看的。它们共享 token 和规则，但 frame.md 还要解决：

尺度问题：web 上 14px 字体合适，视频里要 80-120px
强度问题：web 上 #333 灰足够对比，视频里要拉到 80% 强度
装饰问题：web 允许 hover、阴影、玻璃态，视频里这些会被画面噪声淹没
节奏问题：web 静态、视频要在 timeline 上排布

没有 frame.md，AI 只能凭"训练集平均审美"——也就是"AI 味"的源头。

二、Frame.md 是什么：3 个核心定位

1. 它是 DESIGN.md 的"超集"

用同样的格式，但加上视频特有的部分。HyperFrames 的官方 SKILL.md 写得很清楚：

frame.md uses the same format as design.md.

也就是说，你之前写的 design.md 几乎不用改，复制一份改名 frame.md 就能用。

2. 它是"视频优先"的品牌锚点

读取优先级最高。当 frame.md、design.md、DESIGN.md 同时存在：

frame.md → design.md → DESIGN.md

frame.md 永远胜出。Linux 区分大小写（design.md 和 DESIGN.md 是不同文件），但 frame.md 始终小写。

3. 它是 AI 创作的"宪法"

Agent 拿到 frame.md 后，任何品牌相关的决策都从这里取：

颜色：直接用 frame.md 里的 hex，不许 AI 自由发挥
字体：用 frame.md 里指定的字体名，没有就 warn 不要替
风格：按 frame.md 的 mood 走，不要每段换调性
约束：列在 frame.md 里的限制（如"不要用渐变文字"）必须遵守

三、Frame.md 长什么样：3 种格式都可以

官方说"Any format works"——YAML frontmatter、prose、表格都行，只要能 extract 出值。

格式 A：YAML frontmatter（推荐）

适合需要被工具解析的场景：

---
name: HyperFrames Launch
mood: precise, technical, slightly cinematic
overview: >
  HeyGen's HyperFrames launch video. Engineering-grade motion
  with editorial polish. Light home base, brief dark beats.

colors:
  bg: "#FAFAF9"
  fg: "#0A0A0A"
  accent: "#0066FF"
  ink: "#1B2566"
  ember: "#E26B4A"

typography:
  display: Instrument Serif
  body: Archivo
  mono: JetBrains Mono

elevation:
  - shadow-sm: 0 1px 2px rgba(0,0,0,.05)
  - shadow-md: 0 4px 12px rgba(0,0,0,.1)

constraints:
  - No dark-mode-default. Light, warm, open home base.
  - No gradient text.
  - Push color presence — muted OK, flat NO.
  - Distinctive typography per beat — no single font family across the whole video.
  - Motion should be visible and intentional at 30fps.

motion:
  duration:
    entrance: 0.4
    hold: 1.5
    transition: 0.6
  easing:
    entry: "expo.out"
    exit: "power4.in"
---

格式 B：Prose 散文

适合人写、AI 读：

# Frame.md — HyperFrames Launch

## 概览
HeyGen 的 HyperFrames 发布视频。工程级精度、编辑级打磨。
整体偏浅、暖、开放，深色只作为短暂点缀，不做主调。

## 颜色
- 背景：`#FAFAF9`（不是纯白，略微暖）
- 前景：`#0A0A0A`（不是纯黑，略微冷）
- 强调色：`#0066FF`（瑞士蓝）
- 第二强调：`#E26B4A`（余烬橙）
- 深色点缀：`#1B2566`（靛蓝墨水）

## 字体
- 标题：Instrument Serif（衬线，有历史感）
- 正文：Archivo（无衬线，瑞士网格感）
- 数据：JetBrains Mono（等宽，技术感）

## 约束
- 整体浅色为主，深色只作短暂离场
- 不用渐变文字
- 配色强度往上推，"哑光可以、平涂不行"
- 字体按段差异化，不要全片一个字体
- 30fps 下动作必须可见且有意图

格式 C：表格混合

适合结构化展示：

# Frame.md

| 维度 | 值 |
|------|---|
| Mood | precise, technical |
| Bg | #FAFAF9 |
| Fg | #0A0A0A |
| Accent | #0066FF |
| Display font | Instrument Serif |
| Body font | Archivo |

## 风格约束
- 不用渐变文字
- 不用 Roboto / Inter（除非场景需要）
- 整体浅色，深色只作点缀
- 30fps 下动作要明显

3 种格式选哪个：YAML 适合程序解析、prose 适合人写、表格适合快速浏览。写给人看的 prose、写给工具的 YAML，HyperFrames 都认。

四、24 个官方模板：现成的 Frame.md

HyperFrames 在 https://www.hyperframes.dev/design 维护了一个Frame.md 模板画廊，目标 24+ 个预设，每个都可以下载得到一个 frame pack（含 frame.md + 预览 HTML）。

2026-06-06 实测：gallery 里目前只能访问部分模板（如 biennale-yellow 等），部分模板（包括 Capsule）页面 404 还没上线。SKILL.md 和 README 列出的 24+ 个是最终目标，实际可下载的要看 gallery 状态。

官方 README 列了部分：

模板	Mood	适合场景
Biennale Yellow	Warm parchment + solar yellow bloom	编辑设计、策展、艺术展
BlockFrame	Bold blocks, structured grid	产品介绍、SaaS
Blue Professional	Corporate blue, clean	企业发布、keynote
Bold Poster	Loud typography, poster vibes	营销活动、公告
Broadside	Newspaper-style, dense	长内容、报告
Capsule	Round, soft, friendly	消费品、APP
Cartesian	Math grid, technical	数据可视、dev tools
Cobalt Grid	Blue grid, systematic	工程、SRE、监控
Coral	Warm coral, organic	美食、生活方式
Creative Mode	Bold experimental	创意 agency
（还有 14+ 个，访问 gallery 看）

每个模板在 gallery 都有：
- 可视预览：hover-to-play 视频缩略图
- 3 步配置：Template → Fine-tune → Use
- 可调项：palette（颜色）、typography（字体）、motion（动画）
- 下载 frame pack：一键得到 frame.md

真实样例：Biennale Yellow 的 frame.md

我打开 https://www.hyperframes.dev/design/biennale-yellow 看了下，这个模板的 frame pack 实际生成的设计系统长这样：

name: Biennale Yellow
mood: warm, editorial, art-direction

colors:
  paper: "#E9E5DB"      # 暖米色背景
  paper_deep: "#DCD6C4" # 深米色
  sun: "#F1EE2E"        # 太阳黄（核心强调）
  sun_soft: "#F8F39B"   # 软黄
  haze: "#F0DA7C"       # 雾黄
  ink: "#1B2566"        # 靛蓝墨水
  ember: "#E26B4A"      # 余烬橙

typography:
  serif: "Instrument Serif"
  sans: "Archivo"
  mono: "JetBrains Mono"

bloom: "radial-gradient(circle at 50% 50%, 
        rgba(241,238,46,.92) 0%, 
        rgba(241,238,46,.5) 30%, 
        rgba(240,218,124,.22) 55%, 
        rgba(233,229,219,0) 78%)"

这就是"视频优先"的 frame.md——除了色值字体，还定义了 bloom 这种视频合成时需要的渐变光晕。普通 design.md 里不会写这个。

四点五、实战案例：用 Capsule 模板的 Frame.md 做 APP 介绍视频

关于 Capsule 模板：写这篇文章时（2026-06-06），https://www.hyperframes.dev/design/capsule 页面返回 404（官方 gallery 还没把这个模板放上去）。但官方 README 和 SKILL.md 都把 Capsule 列在 24+ 模板里，描述是 "Round, soft, friendly | 消费品、APP"。下面这个 frame.md 是基于这个定位、按官方文档的格式手写的——等 gallery 上线后可以直接下载替换。

理论讲了这么多，上一个完整实战：用 Capsule 模板的 frame.md 做一个冥想 APP 介绍视频。项目目标客户是 25-35 岁都市白领。

Step 1：明确项目目标

写 frame.md 之前，先问自己 3 个问题：

视频主题是什么？ —— 一款叫 "Calmly" 的冥想 APP 介绍
目标观众是谁？ —— 25-35 岁都市白领，对生活品质有要求
想要什么 mood？ —— Capsule 模板的精髓：圆润、柔软、友好（不是硬核技术、不是冷酷金融）

Step 2：手写 Capsule 风格的 frame.md

我直接在项目根目录创建 frame.md：

---
name: calmly-app-intro
mood: round, soft, friendly, warm, inviting
overview: >
  Calmly 冥想 APP 的产品介绍视频。胶囊形状、柔光质感、友好触感。
  整体偏暖、轻、慢，强调"被抱住"的感觉，不是"被教育"。

colors:
  bg: "#FAF6F0"             # 暖米白（不是冷白）
  bg_soft: "#F0E9DE"        # 浅米
  surface: "#FFFFFF"        # 卡片白
  fg: "#3D3A36"             # 暖黑（不是 #000）
  fg_muted: "rgba(61, 58, 54, 0.65)"
  accent: "#E89B7C"         # 暖桃（核心强调）
  accent_soft: "#F5C9B5"    # 浅桃
  sage: "#A8B5A0"           # 鼠尾草绿（点缀）
  lavender: "#C5B5D6"       # 薰衣草紫（点缀）

shape:
  radius:
    small: "16px"           # 按钮
    medium: "28px"          # 卡片
    large: "48px"           # 主视觉
    pill: "9999px"          # 胶囊（核心特征）
  stroke:
    soft: "1.5px solid rgba(61, 58, 54, 0.08)"
    medium: "2px solid rgba(61, 58, 54, 0.12)"

typography:
  display: "Fraunces"       # 衬线，圆润笔画（不是 Inter）
  body: "DM Sans"           # 无衬线，圆角感（不是 Inter）
  mono: "JetBrains Mono"

constraints:
  - 所有主体元素必须有圆角（radius 最低 16px）
  - 不用渐变文字
  - 不用 Inter / Roboto（House Style 禁止）
  - 不用 #3b82f6 / #6c63ff 等常见 AI 冷色
  - 装饰元素是柔和光斑，不是几何锐利线条
  - 动效慢、缓（exit/entry duration 不少于 0.6s）
  - 整体感觉"被抱住"，不要"被教育"

motion:
  duration:
    entrance: 0.7
    hold: 1.8
    transition: 0.9
  easing:
    entry: "sine.out"       # 不是 expo.out（太弹）
    exit: "sine.in"
  ambient:
    - "soft glow breathing on bg light"
    - "slow drift on decorative blobs"
    - "capsule shapes gently scale 0.98-1.02"

atmosphere:
  blobs:
    - color: "#F5C9B5"
      opacity: 0.35
      size: "60%"
      position: "top-right"
      blur: "80px"
    - color: "#C5B5D6"
      opacity: 0.25
      size: "50%"
      position: "bottom-left"
      blur: "100px"
---

Step 3：实际效果对比

我在做这个项目时，最初没用 frame.md——直接让 AI 出图。结果第一版出来的是：

<style>
  body {
    background: linear-gradient(135deg, #fafafa, #e8e8e8);
    font-family: "Inter", sans-serif;
  }
  .card { border-radius: 8px; }   <!-- 卡片太硬 -->
  .button { background: #6366f1; }  <!-- 这个紫太冷 -->
</style>

全部命中 Capsule 风格的反面：

用渐变背景（Capsule 是柔和光斑）
Inter 字体（Capsule 不用 Inter）
卡片直角 8px（Capsule 最低 16px）
紫色 #6366f1（Capsule 是暖桃）

加了 frame.md 后，AI 重新生成的版本：

<style>
  body {
    background: #FAF6F0;
    /* 柔光斑通过伪元素实现，不是渐变 */
  }
  .card {
    border-radius: 28px;
    background: #FFFFFF;
    box-shadow: 0 8px 32px rgba(232, 155, 124, 0.12);
  }
  .button {
    background: #E89B7C;
    color: #3D3A36;
    border-radius: 9999px;
  }
</style>

对比下来，画面观感立刻不一样——从"硬核 SaaS 模板"变成"消费品 APP 触感"。

Step 4：踩过的 3 个具体坑

坑 1：圆角不够"圆"

我最初给卡片用 border-radius: 12px，AI 还是按"标准 SaaS 卡片"来出。frame.md 里加 shape.radius.medium: 28px 后，AI 立刻改成 28px 卡片，整体氛围才像 Capsule。

坑 2：用了错位的"圆角字体"

我以为 border-radius 设了圆角就够，结果 AI 还是给按钮用了锐利字体的标签。后来在 frame.md 里同时约束字体（Fraunces 衬线 + DM Sans 无衬线），AI 才把字也换成"圆"的。

坑 3：动效太"弹"

Capsule 的精髓是"软"。我最初 frame.md 里写 easing: "power3.out"（弹性曲线），AI 生成的动作还是太"刚"。改成 sine.out 后，所有动作的"末速度"都慢下来，整个画面"软"了一档。

Step 5：把 frame.md 加入工作流

现在我做每个新项目都是这个流程：

1. 项目开建：先写 frame.md（5-10 分钟）
2. AI 生成 composition：自动读 frame.md
3. hyperframes validate：检查配色对比度
4. 渲染出图：npm run render
5. 不满意：改 frame.md，重新生成

5 步里第 1 步是核心——它让 AI 一次出对的方向，而不是改 5 版 prompt。

附：官方 Capsule 模板上线后怎么替换

等 https://www.hyperframes.dev/design/capsule 上线后，直接下载官方 frame pack 替换手写的 frame.md 即可：

1. 打开 https://www.hyperframes.dev/design/capsule
2. 点击 "Download frame pack"
3. 解压得到 frame.md + 预览 HTML
4. 用官方的 frame.md 覆盖手写的 frame.md
5. 重跑 AI 生成，对比差异

官方版本可能在以下细节上更精确：
- bloom 光晕参数的具体 hex 组合
- atmosphere.blobs 的精确尺寸和位置
- 字体回退链（fallback chain）

如果官方版本差异不大，手写版也能直接交付。

五、3 种创建方式

方式 1：从 24 个官方模板选（最省事）

1. 打开 https://www.hyperframes.dev/design
2. 浏览 24+ 模板，hover 预览动效
3. 进入 Fine-tune 阶段：调 palette / typography / motion
4. 点 "Download frame pack" 下载 .zip
5. 解压得到 frame.md + 预览 HTML + 必要 assets
6. 把 frame.md 放到项目根目录
7. AI 读 frame.md 自动应用

方式 2：设计 picker 工具

skills/hyperframes/templates/design-picker.html 是一个浏览器端可视化配置器：

1. 打开 design-picker.html（直接拖进浏览器）
2. Phase 1 - Template：选 mood（Swiss Pulse / Velvet Standard / Deconstructed…）
3. Phase 2 - Fine-tune：实时调颜色、字体、节奏
4. Phase 3 - Use：复制生成的 design.md 文本
5. 保存为项目根目录的 frame.md

适合：想自己调但又怕从 0 写的用户。

方式 3：从 0 手写（最灵活）

模板不是必须。SKILL.md 明确说：

Any format works (YAML frontmatter, prose, tables — just extract the values).

手写 frame.md 适合：
- 公司已有 design 系统，想为视频定制延伸
- 创作者对视觉有明确想法，模板不够用
- 想精确控制每一项 token

六、Frame.md 在 Composition 中的作用：5 个 hook 点

HyperFrames 的 pipeline 里有 5 个步骤会读 frame.md：

步骤	读取内容	失败后果
Step 1: Design system	frame.md 整体	AI 凭训练集平均审美出图（"AI 味"）
Step 2: Prompt expansion	frame.md 里的 hex / font 名 / constraints	生成的中间描述不一致
Step 3: Plan	mood、motion 时长	节奏不统一
Step 4: Author HTML	所有 token（颜色 / 字体 / 间距 / 动效）	AI 自由发挥破坏品牌
Step 5: Verify	对照 frame.md 检查	验证脚本不会发现品牌漂移

最关键的是 Step 1——SKILL.md 里有句 HARD-GATE 警告：

Before writing ANY composition HTML — verify you have a visual identity from Step 1. If you're reaching for #333, #3b82f6, or Roboto, you skipped it.

翻译：任何"伸手就抓 hex / 字体"的行为都是 frame.md 缺失的标志。AI 看到 #333 就要停下来问"frame.md 呢？"

七、Frame.md 必须包含什么 / 不能包含什么

必须包含

类别	推荐字段	必填？
基础信息	name、mood、overview	必填
颜色	bg、fg、accent + 副色	必填
字体	display、body、mono	必填
约束	不要用 X、不要做 Y	必填
运动节奏	duration 范围、easing	推荐

不要包含

类别	原因
HTML 代码	frame.md 是数据源，HTML 写在 composition 里
具体场景内容	脚本、台词、动画序列属于 SCRIPT.md / STORYBOARD.md
时序信息	"5 秒这里出场"属于 timeline，不是 design
具体人物、图标	frame.md 是 token，不是素材清单

简单说：frame.md 回答"看起来什么样"，不回答"什么时候做什么"。

八、和 design.md / DESIGN.md 的关系

很多新用户会问：我有 design.md 了，还要不要 frame.md？

答案是：

文件	用途	何时用
`frame.md`	视频专用，frame-first	HyperFrames 视频项目默认用这个（v0.6.71+）
`design.md`	Web 通用，screen-first	网站/UI 项目用这个
`DESIGN.md`	大写是 Linux 的 case-sensitive 别名	老的项目可能叫这名，HyperFrames 兼容

HyperFrames 项目的推荐做法：

复制现有 design.md 到 frame.md
把所有 web-only 限制改成 video-appropriate：
- 字号 14-16px → 60-120px
- 阴影 / 玻璃态 → 减弱或删除
- hover 动效 → 改成 entrance 动效
加 video-specific 字段：
- bloom / atmosphere 渐变
- motion.duration 时长范围
- motion.easing 缓动函数

九、踩坑清单

坑 1：frame.md 放在子目录里找不到

frame.md 必须放项目根目录。如果放 docs/frame.md 或 compositions/frame.md，HyperFrames 不会找到。

坑 2：frame.md 写完没用——AI 不读

HyperFrames 不会强制读 frame.md。它需要你或 AI Agent 按 SKILL.md 的 Step 1 主动读。如果你直接用 npx hyperframes render --composition ./index.html，不会自动应用 frame.md——它只是设计参考，需要配合能读 frame.md 的 Agent（Claude Code、Codex、pi-agent 等）来用。

坑 3：frame.md 写得太"设计"，AI 读不懂

不要写：

## 颜色
应该用低饱和度、高明度的暖色系，避免使用纯白和纯黑，
配色要符合品牌调性，色相控制在 30-50 度之间……

AI 读不到"低饱和度"的具体值。改成具体的 hex：

## 颜色
- bg: #FAFAF9（暖白）
- fg: #0A0A0A（冷黑）
- accent: #E26B4A（暖橙，明度 65%）
- secondary: #1B2566（深蓝）

坑 4：frame.md 和 design.md 冲突

如果你两个文件都写了，以 frame.md 为准。如果两个值不一致：

先更新 design.md（因为它是更上层的源）
再同步 frame.md（保持视频项目用最新的）

坑 5：自定义字体没准备 .woff2

如果 frame.md 里写了"用 Custom Serif Pro"，但项目里没有 fonts/CustomSerifPro.woff2 文件，AI 应该 warn 而不是替换。踩坑经验：自定义字体一定要先放 fonts/，再加 @font-face 引用，不然会自动 fallback 到 system 字体。

十、Frame.md 是什么时候"扶正"的

v0.6.71（2026-06-04） 是关键节点。两个 PR 联合把 frame.md 升到一等公民：

PR	标题	作用
#1182	README: Add Frame.md design template gallery	把 24+ 模板画廊加进 README
#1180	Skills: Prefer frame.md over design.md for video specs	SKILL.md 读取优先级改为 `frame.md → design.md → DESIGN.md`

也就是说：v0.6.71 之前的项目还在用 design.md，v0.6.71 之后的新项目应该直接用 frame.md。

我之前在 Doc 98（HyperFrames 实战复盘）里写的项目用的就是 design.md，重读后我才意识到应该升级到 frame.md——下次重做时我会直接换。

写在最后

frame.md 不是一个孤立的文件——它是 HyperFrames 整套"AI 视频生产"哲学的载体：

不靠 prompt 描述品牌——靠文件
不让 AI 每次都猜——靠 token
不混用 web 端和视频端的尺度——靠分离

如果说 design.md 是品牌的"宪法"，frame.md 就是这部宪法在"镜头"下的实施细则。

最近做产品视频时，我养成了一个习惯：项目第一天不是开 composition，是先写 frame.md。写完之后，AI 生成的画面一致性肉眼可见地提升，改稿次数从 5-6 次降到 2-3 次。

你做 HyperFrames 项目时，是用 design.md 还是 frame.md？有没有自己摸索出的"土办法"？评论区聊聊。

📄 文档管理系统