编辑文档 - HyperFrames Frame.md 详解：3 分钟吃透视频设计 DNA 机制

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

前阵子做产品介绍视频，用 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（推荐）

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

```yaml
---
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 读：

```markdown
# Frame.md — HyperFrames Launch

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

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

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

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

### 格式 C：表格混合

适合结构化展示：

```markdown
# 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 实际生成的设计系统长这样**：

```yaml
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](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`：

```yaml
---
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 出图。结果第一版出来的是：

```html
<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 重新生成的版本：

```html
<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](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 项目的推荐做法**：

1. 复制现有 `design.md` 到 `frame.md`
2. 把所有 web-only 限制改成 video-appropriate：
   - 字号 14-16px → 60-120px
   - 阴影 / 玻璃态 → 减弱或删除
   - hover 动效 → 改成 entrance 动效
3. 加 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 读不懂

不要写：

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

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

```markdown
## 颜色
- 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？有没有自己摸索出的"土办法"？评论区聊聊。

摘要

标签多个标签用逗号分隔

分类