| 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
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":
- Parallelism: Coding and audio generation are decoupled — scenes can be coded while audio is not yet ready
- Faster iteration: Layout/animation issues found during coding don't require audio regeneration
- Less waste: If a scene's text changes during mockup review, no audio needs regeneration
- 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 alignmentmargin: "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:
- Create one HTML file per scene:
docs/mockups/scene{N}-final.html
- Use the style's color palette (from Phase 0 selection) as inline CSS
- Include all elements visible at the scene's last frame
- Use fixed 1920×1080 viewport dimensions
- 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
-
Self-review checklist:
-
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.
