remotion-video-design

name

remotion-video-design

description

Use when starting a new Remotion video project, adding scenes to an existing video, or converting a script into a video. Handles creative direction, script review, scene planning, pronunciation pre-check, segment-based voiceover generation, subtitle-based timeline calculation, and produces a complete design spec. Required before remotion-video-development. Also handles voiceover generation and timeline alignment via remotion-tools scripts.

Remotion Video Design

Overview

Before writing code, resolve the three biggest sources of rework: creative direction, assets, and timing. This skill guides a structured dialogue through 6 phases, each with a gate requiring user confirmation.

Core principle: 80% of video rework comes from "unknowns" — direction unknown, assets unknown, layout unknown. Resolve all three before coding.

File-first workflow: Save deliverable files as early as possible. Users edit real files faster than they describe changes in conversation. When a phase produces a file, generate the first draft, save it to disk, then tell the user to open and edit it directly.

Skill Pipeline: best-practices (reference) → design (this skill) → development → review

When to Use

• Starting a new Remotion video project
• Adding new scenes to an existing video
• Converting a script/text document into a video

Do NOT use for:

• Minor tweaks to existing scenes (use remotion-video-review)
• Technical Remotion questions (use remotion-best-practices)
• Screen recording / live demo videos (use OBS + 剪映)
• Real people / camera footage (use 手机 + 剪映)

Pipeline position: First step in video creation. Output feeds into remotion-video-development.

Process Flow

digraph design {
    rankdir=TB;
    "Phase 0: Creative Direction" [shape=box];
    "Direction OK?" [shape=diamond];
    "Phase 1: Scene Planning" [shape=box];
    "Assets Ready?" [shape=diamond];
  "Phase 2: Estimated Timeline" [shape=box];
    "Phase 3: Design System" [shape=box];
    "Style OK?" [shape=diamond];
    "Phase 4: Layout + Timing" [shape=box];
    "Phase 5: Doc + Review" [shape=doublecircle];

    "Phase 0" -> "Direction OK?";
    "Direction OK?" -> "Phase 0" [label="no"];
    "Direction OK?" -> "Phase 1" [label="yes"];
    "Phase 1" -> "Assets Ready?";
    "Assets Ready?" -> "Phase 1" [label="no"];
    "Assets Ready?" -> "Phase 2" [label="yes"];
    "Phase 2" -> "Phase 3";
    "Phase 3" -> "Style OK?";
    "Style OK?" -> "Phase 3" [label="no"];
    "Style OK?" -> "Phase 4" [label="yes"];
    "Phase 4" -> "Phase 5";
}

Phase 0: Creative Direction

Goal: Determine "what this video should feel like."

0.1 Video Type Assessment

Video Type	Remotion?	Alternative
概念讲解/技术分享	YES	-
信息汇总播报	YES	-
产品吐槽/评论	YES	-
操作演示教程	PARTIAL (片头+概念部分)	OBS + 剪映做录屏部分
日常 Vlog	NO	手机 + 剪映

If Remotion is not suitable, recommend alternatives and stop.

0.2 Theme & Mood

Discuss with the user:

1. 目标受众？（开发者/产品经理/普通用户）
2. 情绪基调？（严肃专业/轻松幽默/吐槽讽刺/科普教育）
3. 视觉风格？（紧凑高密度/松散留白/现代简约/温暖复古）
4. 配色方向？（冷色科技/暖色亲切/高对比度/低饱和度）
5. 节奏？（快节奏信息轰炸/慢节奏详细讲解）

Open assets/style-gallery.html in browser — 20 种预设视觉风格，支持标签筛选（暗色/亮色/科技/教育/吐槽/播报等），每种风格附带适合的视频类型说明和 theme.ts 配色常量。让用户从中选择或混搭。

如果预设风格都不合适，再讨论定制方案。

0.3 Script Review

Read text.md / voiceover-text.json. Evaluate and suggest:

Check	What to Look For
口播自然度	句子太长、嵌套太多 → 建议拆短句
信息密度	每场景建议 1-2 个核心观点，≤ 5 个视觉元素
节奏感	是否有高低起伏？全是信息轰炸还是缺少实例？
场景切分点	话题转换、情绪变化、信息块切换处适合切场景
书面语 vs 口语	"首先我们需要了解" → "先说说什么是…"

Present concrete adjustment suggestions. User confirms final script.

Save script to voiceover-text.json — user can edit this file directly for wording tweaks.

Script Formatting Rules

voiceover-text.json 的文本必须遵循以下规则，确保 TTS 生成质量和字幕可读性：

R1: 字幕长度 ≤ 30 字

每句话（句号/问号/感叹号分隔的一段）内部，以逗号分隔的子句不应超过 30 个字。字幕系统会在逗号处进一步切分，超过 30 字的子句会导致字幕在视频中过长，阅读困难。

// BAD: 无逗号分隔的 45 字长句
"检测到对话上下文超出目标模型的窗口时自动切换到指定的大上下文模型"

// GOOD: 在逗号处分隔，每段 < 30 字
"检测到上下文超出模型窗口时，自动切换到大上下文模型"

R2: 无标点长句用 "-" 断句

对于连续的复杂短语（特别是列举、术语堆叠），如果没有自然的标点分隔，用半角连字符 "-" 插入微停顿，帮助 TTS 正确断句：

// BAD: TTS 会连读
"Claude Code 截断历史后残留孤儿 tool result 的问题"

// GOOD: "-" 产生微停顿
"Claude Code 截断历史后 - 残留孤儿 tool result 的问题"

R3: 句尾双句号

voiceover-text.json 中每句话的结尾必须是两个句号 。。。单个句号在某些 TTS 引擎中会被视为文本的一部分而非句尾，导致最后一个词被吞掉。双句号确保 TTS 引擎正确识别句子结束。

// BAD: 最后一词可能被吞
"欢迎试用和反馈。"

// GOOD: 双句号保证完整
"欢迎试用和反馈。。"

✋ Gate: User confirms creative direction and script is finalized.

Git checkpoint:

[ ! -d .git ] && git init  # initialize if needed
git add -A && git commit -m "init: creative direction + script finalized"

Phase 1: Scene Planning

Goal: Determine "how many scenes, what each covers, what assets needed."

1.1 Scene Structure

Determine scene count (typical: 3-8 for 1-5 min video) and each scene's purpose:

| Scene | Duration | Purpose      | Key Visuals         |
|-------|----------|--------------|---------------------|
| 1     | ~10s     | Hook         | Title + tagline     |
| 2     | ~30s     | Context      | 3 info cards        |
| 3     | ~45s     | Detail       | Screenshot + text   |

Information density rule: each scene ≤ 5 visual elements. If more, split the scene.

1.2 Asset Planning

ASSET CHECKLIST:
[ ] voiceover-text.json — finalized script (Phase 0 output)
[ ] Screenshots — which screens, ASCII filenames
[ ] Images/icons — cards, backgrounds, decorations
[ ] Video clips — short embedded clips (if any)
[ ] Data — numbers/data for charts or comparisons

User collects assets. Don't proceed until all confirmed available.

1.3 Pronunciation Pre-check

Scan voiceover text for TTS-prone words. Check ~/.claude/tts-rules/tts-replacements.json for existing rules.

Pattern	Examples	Risk
English brands	Kimi, GLM, DeepSeek	Letter-by-letter reading
English + numbers	K2.5, GPT-4	Number mangled
Hyphenated compounds	llm-simple-router	Wrong pauses
All-caps abbreviations	API, TTS, LLM	Spelled out
Mixed zh/en	"一个月200块"	Number confusion

Suggest rules for uncovered words. User confirms → add to tts-replacements.json.

✋ Gate: User confirms scene plan is reasonable and assets available.

Git checkpoint: git add -A && git commit -m "design: scene plan + asset list confirmed"

Phase 2: Estimated Timeline

Goal: Produce a usable timeline for coding, without waiting for TTS audio generation.

Key insight: Audio generation takes time (API calls per sentence × N scenes) and costs money. But coding can start immediately with character-ratio estimated subtitles. The timeline refinement happens later, after scenes are coded.

Why "estimate first, audio later" is better than "audio first":

1. Parallelism: Coding and audio generation are decoupled — scenes can be coded while audio is not yet ready
2. Faster iteration: Layout/animation issues found during coding don't require audio regeneration
3. Less waste: If a scene's text changes during mockup review, no audio needs regeneration
4. Same quality: Final subtitles use precise TTS timestamps — the estimate is only a temporary scaffold

2.1 Estimated Timeline Calculation

Use character-ratio to estimate per-scene frame counts:

语速: 5 字/秒 (adjustable)
缓冲: 45 帧 (1.5s silent gap between scenes)

scene_frames = ceil(char_count / chars_per_sec * FPS) + buffer_frames
total_frames = sum(scene_frames) + (N-1) * transition_frames

Save to docs/timeline-estimated.md.

2.2 Estimated Subtitle Segmentation

Use estimateSubtitles() from src/utils/subtitle.ts to split voiceover text into subtitle segments with estimated frame positions:

• Level 1: split at sentence-ending punctuation (。！？)
• Level 2: split at commas/顿号 within long sentences
• maxChars: 30 (per subtitle line, strict limit for readability)

This produces subtitle data that scenes can use immediately for <Subtitles> component.

2.3 Theme.ts Estimated Durations

Populate SCENE_DURATIONS in theme.ts with estimated frame counts. These will be replaced with actual values after audio generation.

✋ Gate: Estimated timeline looks reasonable (total duration in expected range).

Git checkpoint: git add -A && git commit -m "design: estimated timeline + theme.ts initialized"

Phase 3: Design System

Goal: Derive visual constants from Phase 0 creative direction.

Produce src/styles/theme.ts:

Category	Must Define	Source
Colors	bg, primary, secondary, text, error, success	Phase 0 mood
Font sizes	xs through hero (6 levels)	Phase 0 density
Spacing	xs through xl (4 levels)	Phase 0 compact/spacious
Scene durations	Per-scene frame counts (estimated)	Phase 2 estimation
Image map	ASCII filename constants	Phase 1 asset list

One-frame verification: Render Scene 1 with npx remotion still. Show to user.

Generate theme.ts from the selected style gallery colors. User can open and edit this file directly to tweak individual colors.

✋ Gate: User says "visual feel is right."

Git checkpoint: git add -A && git commit -m "design: theme.ts visual system confirmed"

Phase 4: Layout & Timing

Goal: Define per-scene layout and animation timing.

4.1 Layout Spec

For each scene, produce:

sceneN:
  voiceover: "exact text"
  layout:
    type: vertical | horizontal | grid
    regions:
      - name: "title area"
        type: flex-column
        content: [title_text, divider]
      - name: "main area"
        type: horizontal-split
        left: [element_list]
        right: [element_list]
        alignment: flex-start | flex-end | center | stretch
  elements:
    - id: elem1
      type: text | card | image | bar-chart | block | video
      content: "..."
      style: { fontSize, color, fontWeight }
      timing: { enter: frameN, animation: fadeIn | bounce | typewriter }

Layout principles:

• Flex flow for ordered content, absolute ONLY for overlays
• alignItems: "flex-end" for bottom alignment
• margin: "0 auto" + fixed width for centering
• macOS title bar for screenshot containers

4.1.1 Layout Templates & Hard Rules

读取 layout-templates.md（本 skill 目录下） 获取完整的 14 种布局模板和硬性规范。

该文件定义了：

• §0 硬性规范: 画布(1536×864)、间距(SP 变量)、标题区(80px)、内容区(flex:1)、对齐规则、卡片规范、字号底线、动画规范
• §2 十四种模板 (T1-T14): 每种模板含 ASCII 布局图 + 硬性参数
• §3 速查表: 一张表看清所有模板的布局参数
• §4 决策树: 根据内容类型快速选择模板
• §5 多样性规则: 相邻不同、同模板≤2次、开合结构

核心硬规则摘要

规则	值	检查方法
内容区	1536×864 + margin auto	grep width/height
间距	只用 SP.xs/sm/md/lg/xl	lint 脚本
标题区	80px + FS.title + 居中	grep
字号	正文≥24px, 标题≥40px, 最小18px	lint 脚本
卡片	白底+2px border+12px圆角+40/24 padding	对照规范
对齐	按模板类型固定（见速查表）	lint 脚本

截图零留白

截图在 macOS 窗口框内必须紧密贴合，上下不能有空白间距。

.window-content { line-height: 0; }
.window-content img { width: 100%; height: auto; display: block; }

禁止 object-fit: contain 在固定高度容器中、flex: 1 在截图容器上。宁可裁切不要留白。

4.2 Scene Final-Frame Mockups

For PPT-like static scenes (info cards, comparisons, title cards), generate HTML mockups showing each scene's final frame — what the viewer sees after all animations complete.

Why: HTML mockup iterates in seconds (write → browser refresh), vs Remotion code iterates in minutes (code → tsc → render). For layout-heavy scenes, the final frame IS the main visual.

How:

1. Create one HTML file per scene: docs/mockups/scene{N}-final.html
2. Use the style's color palette (from Phase 0 selection) as inline CSS
3. Include all elements visible at the scene's last frame
4. Use fixed 1920×1080 viewport dimensions
5. User opens files in browser, gives feedback on layout/spacing/sizing

Scope: Only for scenes where layout is the primary concern. Skip for pure animation scenes (kinetic text, transitions).

4.3 Timeline Mapping

Map animation triggers to estimated timeline:

• Use character-ratio within the estimated frame budget per scene
• Animation aligns with sentence/phrase boundaries from estimateSubtitles()
• All T constants are estimated — they will be refined after audio generation

scene_start_buffer = 30  // frames before first subtitle
active_frames = SCENE_DURATION - buffer_frames
animation_frame = scene_start_buffer + (chars_before / total_chars) * active_frames

4.4 Template Reuse Assessment

Mark which components can be reused across videos:

• Reusable: title cards, transition animations, info cards, closing screens
• Video-specific: unique data visualizations, specific screenshots

Reusable components → extract to shared modules during development.

Phase 5: Design Doc + Review

Save to docs/video-design.md:

• Creative direction summary (mood, tone, style keywords from Phase 0)
• Per-scene layout spec (structured YAML from Phase 4)
• Timeline reference (link to timeline-auto.md)
• Asset list with filenames (from Phase 1)
• Template reuse plan (from Phase 4.3)

Review

1. Self-review checklist:

   • Every voiceover segment has a corresponding animation
   • Every image asset is referenced by ASCII filename
   • Layout uses flex flow (not absolute) for ordered content
   • No objectFit: cover or objectFit: contain in fixed-height containers for screenshots
   • Screenshot containers use line-height: 0 + height: auto for zero whitespace
   • Voiceover text and page text are semantically consistent
   • Information density per scene ≤ 5 visual elements
   • TTS pronunciation fixes documented
   • All content within 80% viewport (1536x864 for 1920x1080)
   • All spacing uses SP variables (no hardcoded numbers) — run layout-lint.py
   • Title area is 80px, FS.title, centered (for T4-T14 templates)
   • Content area uses flex: 1 with minHeight: 0 (no fixed height)
   • Font sizes meet minimums: body ≥24px, titles ≥40px, code ≥20px
   • Card style: white bg + 2px border + 12px radius + SP.lg/SP.md padding
   • Layout type matches template spec (see layout-templates.md §3 alignment table)
   • No 3+ consecutive scenes with identical layout structure
   • No subtitle line exceeds 30 characters
   • Voiceover text has double-period endings (。。) at every sentence
   • Long compound phrases split with "-" for TTS breath marks

2. Independent reviewer — dispatch subagent using design-reviewer-prompt.md

Transition

After design review passes and user approves:

→ Invoke remotion-video-development to implement scenes.

If Remotion handles only partial content (e.g., title cards + data viz, but demo parts need screen recording):

→ Suggest hybrid workflow: Remotion renders programmatic parts as MP4 segments, OBS records demo parts, FFmpeg concatenates:

ffmpeg -f concat -safe 0 -i filelist.txt -c copy output.mp4

Git checkpoint: git add -A && git commit -m "design: video-design.md complete"

Deliverables

Phase	Output Files
Phase 0	voiceover-text.json (finalized script), selected style from assets/style-gallery.html
Phase 1	Assets in public/images/
Phase 2	docs/timeline-estimated.md, estimated SCENE_DURATIONS in theme.ts
Phase 3	src/styles/theme.ts
Phase 4	docs/mockups/scene{N}-final.html (per-scene final-frame mockups)
Phase 4-5	docs/video-design.md

Red Flags

• User says "just start coding" → Resist. List what's unknown.
• No voiceover audio yet → Use estimated timeline (Phase 2). Audio generation happens in development phase after scenes are coded.
• User describes layout as "move X a bit" → Ask for structured description.
• Images with Chinese filenames → Rename to ASCII.
• Script has 10+ paragraphs for one scene → Split into multiple scenes.