📐 Layout & Safe Areas (Click to Expand)
## AI Production Route
When the user asks to go from an idea, script, plot, storyboard, reference image, or rough video concept to a generated video, invoke `framevideo-ai-production` as the front half of the workflow. That skill turns creative material into Clip, Shot, and Chanjing AIGC plans.
For real Chanjing AI image/video generation:
1. Use `framevideo-ai-production` to produce Shot-level Chanjing AIGC plans.
2. Use `chanjing-digital-human/references/ai-creation.md` for Chanjing AI Creation model discovery, idempotent submission, short sync polling, download, and local asset paths.
3. Only compose with local assets under `assets/ai-creation/images/` or `assets/ai-creation/videos/`.
4. Return here to build the FrameVideo HTML composition, audio, captions, transitions, QA, preview, and render.
Do not directly insert remote Chanjing output URLs into composition HTML.
## Approach
### Discovery (exploratory requests only)
For open-ended requests ("make me a product launch video", "create something for our brand") where the user hasn't committed to a direction, understand intent before picking colors:
- **Audience** — who watches this? Developers? Executives? General consumers?
- **Platform** — where does it play? Social (15s), website hero, product demo, internal?
- **Priority** — what matters most? Motion quality? Content accuracy? Brand fidelity? Speed?
- **Variations** — does the user want options, or a single best shot?
For specific requests ("add a title card", "fix the timing on scene 3"), skip discovery.
For exploratory requests, consider offering 2-3 variations that differ meaningfully — not just color swaps, but different pacing, energy levels, or structural approaches. One safe/expected, one ambitious. Don't mandate this — it's a tool available when appropriate.
### Step 1: Design system
If a design spec exists in the project, read it first. Look in precedence order: `frame.md` → `design.md` → `DESIGN.md` (`design.md` and `DESIGN.md` are different files on Linux — check both casings; `frame.md` is always lowercase, no `FRAME.md` variant). `frame.md` is the preferred spec for video/framevideo 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. Use its exact values — don't invent colors or substitute fonts. Any format works (YAML frontmatter, prose, tables — just extract the values).
If it names fonts you can't find locally (no `fonts/` directory with `.woff2` files, not a built-in font), warn the user before writing HTML: "the spec specifies [font name] but no font files found. Please add .woff2 files to `fonts/` or I'll fall back to [closest built-in alternative]."
If no `frame.md` or `design.md` exists, offer the user a choice:
1. **User named a style or mood?** → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Pick the closest match.
2. **Want to browse options visually?** → Run the design picker: read [references/design-picker.md](references/design-picker.md) for the full workflow. This serves a visual picker page. The user configures mood, palette, typography, and motion in the browser, then copies the generated design.md and pastes it back into the conversation.
3. **Want to skip and go fast?** → Ask: mood, light or dark, any brand colors/fonts? Then pick a palette from [house-style.md](./house-style.md).
**The design spec defines the brand. It does not define video composition rules.** Those come from [references/video-composition.md](references/video-composition.md) and [house-style.md](./house-style.md). Use brand colors at video-appropriate scale — not at web-UI opacity.
### Step 2: Prompt expansion
Always run on every composition (except single-scene pieces and trivial edits). This step grounds the user's intent against the design spec (`frame.md` or `design.md`) and `house-style.md` and produces a consistent intermediate that every downstream agent reads the same way.
Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format.
### Step 3: Plan
Before writing HTML, think at a high level:
1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats.
2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions).
3. **Rhythm** — declare your scene rhythm before implementing. Which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern: fast-fast-SLOW-fast-SHADER-hold. Read [references/beat-direction.md](references/beat-direction.md) for rhythm templates.
4. **Timing** — which clips drive the duration, where do transitions land, what's the pacing.
5. **Layout** — build the end-state first. See "Layout Before Animation" below.
6. **Animate** — then add motion using the rules below.
**Build what was asked.** A request for "a title card" is not a request for "a title card + 3 supporting scenes + ambient music + captions." Every scene, every element, every tween should earn its place. If additional scenes or elements would genuinely improve the piece, propose them — don't add them.
For small edits (fix a color, adjust timing, add one element), skip straight to the rules.
📐 Layout & Safe Areas (Click to Expand)
### Layout Before Animation Principle
**Build the end state first.** Position every element where it should be at its **most visible moment** - fully entered, correctly placed, not yet exiting. Write this as static HTML+CSS first. No GSAP yet.
**Why:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing. Overlaps are invisible until render. By building the end state first, you see and fix layout problems before adding motion.
**The process:**
1. **Identify the hero frame** - the moment when most elements are simultaneously visible
2. **Write static CSS** for that frame
3. **Add entrances with `gsap.from()`** - animate FROM offscreen/invisible TO the CSS position
4. **Add exits with `gsap.to()`** - animate TO offscreen/invisible FROM the CSS position
**Example:**
```css
/* Step 1-2: Build the readable end state */
.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; }
```
```javascript
// 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);
// Step 4: Animate OUT from those positions
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
```
### Container Patterns
**✅ Full-Scene Container (Recommended):**
```css
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
width: 100%;
height: 100%;
padding: 120px 160px; /* Safe area */
gap: 24px;
box-sizing: border-box;
}
```
**❌ Do NOT use absolute positioning for content:**
```css
/* WRONG - breaks on long text */
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
}
```
Reserve `position: absolute` for decorative elements only (particles, glows, background shapes).
### Safe Area Rules
Keep key information inside the safe area:
- **Horizontal:** ~5% from left/right edges (~96px on 1920px width)
- **Vertical:** ~5% from top/bottom edges (~54px on 1080px height)
- **Bottom (captions/CTA):** ~10% from bottom (~108px)
**What must stay safe:**
- Critical text, headlines, body copy
- Logo (unless intentionally edge-anchored)
- CTA buttons and links
- Captions and subtitles
- Presenter faces
- Product UI screenshots
- Legal/price copy
**What can extend beyond:**
- Full-bleed backgrounds
- Decorative glows and particles
- Grain and texture overlays
- Transition effects
Mark intentional overflow: ``
### Text Handling
**Natural wrapping:**
```css
.headline {
max-width: 1200px; /* Wraps at this width */
font-size: 96px;
line-height: 1.1;
}
```
**Dynamic fitting:**
```javascript
const { title } = window.__framevideo.getVariables();
const fontSize = window.__framevideo.fitTextFontSize(title, {
maxWidth: 1200,
fontFamily: 'Inter',
fontWeight: 700
});
document.getElementById('title').style.fontSize = fontSize + 'px';
```
**Avoid fixed-size text containers** - use elastic containers with padding instead.
### Common Layout Patterns
**Centered Title Card:**
```html
```
**Split Layout (Text + Visual):**
```html
```
---
### Animation Guardrails
**Timing offsets** - Never start first animation at t=0:
```javascript
// ❌ Wrong
tl.from(".title", { opacity: 0 }, 0);
// ✅ Right
tl.from(".title", { opacity: 0 }, 0.2); // 0.1-0.3s offset
```
**Vary easing curves** - Use at least 3 different eases per scene:
```javascript
tl.from("#el1", { opacity: 0, ease: "power3.out" }, 0.2);
tl.from("#el2", { opacity: 0, ease: "expo.out" }, 0.4);
tl.from("#el3", { opacity: 0, ease: "back.out(1.4)" }, 0.6);
```
Common eases: `power1.out`, `power2.out`, `power3.out`, `expo.out`, `back.out(1.7)`, `elastic.out(1, 0.3)`
**Don't repeat entrance patterns** - Each element should have unique direction or style:
```javascript
// ❌ Wrong - everything from top
tl.from("#title", { y: 60, opacity: 0 }, 0.2);
tl.from("#subtitle", { y: 60, opacity: 0 }, 0.5);
// ✅ Right - varied directions
tl.from("#title", { y: 60, opacity: 0 }, 0.2);
tl.from("#subtitle", { x: -30, opacity: 0 }, 0.5);
tl.from("#cta", { scale: 0.8, opacity: 0 }, 0.8);
```
**Performance properties** - Prefer GPU-accelerated:
- ✅ Fast: `opacity`, `x`, `y`, `scale`, `rotation`
- ❌ Slow: `width`, `height`, `top`, `left`, `margin`, `padding`, `font-size`
### Common Animation Patterns
**Stagger entrances:**
```javascript
// Stagger by time
tl.from(".item", {
y: 30,
opacity: 0,
duration: 0.5,
stagger: 0.1,
ease: "power2.out"
}, 0.5);
// Stagger from center
tl.from(".grid-item", {
scale: 0.8,
opacity: 0,
duration: 0.4,
stagger: { amount: 0.6, from: "center" },
ease: "back.out(1.4)"
}, 1.0);
```
**Sequence vs Overlap:**
```javascript
// Sequence - one after another
tl.from("#el1", { opacity: 0, duration: 0.5 }, 0);
tl.from("#el2", { opacity: 0, duration: 0.5 }, ">"); // After previous ends
// Overlap - start before previous ends
tl.from("#el1", { opacity: 0, duration: 0.8 }, 0);
tl.from("#el2", { opacity: 0, duration: 0.5 }, "<0.4"); // 0.4s after el1 starts
```
**Label-based sequencing:**
```javascript
tl.addLabel("intro", 0);
tl.from("#title", { opacity: 0 }, "intro");
tl.from("#subtitle", { opacity: 0 }, "intro+=0.5");
tl.addLabel("content", 2.5);
tl.from("#feature1", { x: -40, opacity: 0 }, "content");
```
### Scene Rhythm Templates
Declare rhythm before implementing:
- **Fast-Fast-SLOW:** Quick intro beats → hold for message (2s, 3s, 5s)
- **Build-PEAK-Resolve:** Escalating energy → climax → settle (3s, 2s, 4s)
- **Even Pulse:** Consistent rhythm (all beats 3-4s, good for instructional)
See [references/beat-direction.md](references/beat-direction.md) for more templates.
### Animation Conflicts
Never animate the same property on the same element from multiple timelines:
```javascript
// ❌ Wrong - both animate opacity
timeline1.to("#el", { opacity: 0.5 });
timeline2.to("#el", { opacity: 1 }); // Conflict!
// ✅ Right - separate properties
timeline1.to("#el", { opacity: 0.5 });
timeline2.to("#el", { x: 100 }); // No conflict
```
---
## Scene Transitions (Non-Negotiable)
**Every multi-scene composition MUST follow these 4 rules:**
### Rule 1: Always Use Transitions
No jump cuts between scenes. Every scene change needs a transition.
### Rule 2: Always Use Entrance Animations
Every element in every scene animates IN via `gsap.from()`. No element may appear fully-formed.
### Rule 3: Never Use Exit Animations (Except Final Scene)
Do NOT animate elements out before a transition. The transition IS the exit. The outgoing scene's content MUST be fully visible when the transition starts.
### Rule 4: Final Scene Only
The last scene is the ONLY scene where `gsap.to(..., { opacity: 0 })` or exit animations are allowed.
**Example:**
```javascript
// Scene 1 (0-7s)
// ✅ Entrance animations only
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 animations - transition handles it
// Transition at 7s (see references/transitions.md)
// Scene 2 (8-15s)
// ✅ Entrance animations
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
// Final scene (15-20s)
// ✅ OK to fade out on final scene only
tl.from("#s3-cta", { scale: 0.9, opacity: 0, duration: 0.5 }, 15.2);
tl.to("#s3-cta", { opacity: 0, duration: 0.5, ease: "power2.in" }, 19.5);
```
See [references/transitions.md](references/transitions.md) for transition implementation.
---
## Layout Before Animation
```css
.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. */
```
**WRONG — hardcoded dimensions and absolute positioning:**
```css
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
```
```js
// 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);
```
### When elements share space across time
If element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist — but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error.
### What counts as intentional overlap
Layered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap — two headlines landing on top of each other, a stat covering a label, content bleeding off-frame.
## Data Attributes
### All Clips
| Attribute | Required | Values |
| ------------------ | --------------------------------- | ------------------------------------------------------ |
| `id` | Yes | Unique identifier |
| `data-start` | Yes | Seconds or clip ID reference (`"el-1"`, `"intro + 2"`) |
| `data-duration` | Required for img/div/compositions | Seconds. Video/audio defaults to media duration. |
| `data-track-index` | Yes | Integer. Same-track clips cannot overlap. |
| `data-media-start` | No | Trim offset into source (seconds) |
| `data-volume` | No | 0-1 (default 1) |
`data-track-index` does **not** affect visual layering — use CSS `z-index`.
### Composition Clips
| Attribute | Required | Values |
| ---------------------------- | -------- | ----------------------------------------------------------------- |
| `data-composition-id` | Yes | Unique composition ID |
| `data-start` | Yes | Start time (root composition: use `"0"`) |
| `data-duration` | Yes | Takes precedence over GSAP timeline duration |
| `data-width` / `data-height` | Yes | Pixel dimensions (1920x1080 or 1080x1920) |
| `data-composition-src` | No | Path to external HTML file |
| `data-variable-values` | No | JSON object of per-instance variable overrides on a sub-comp host |
On the root `` element:
| Attribute | Required | Values |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `data-composition-variables` | No | JSON array of declared variables (id/type/label/default) — drives Studio editing UI and provides defaults for `getVariables()` |
## Composition Structure
Sub-compositions loaded via `data-composition-src` use a `` wrapper. **Standalone compositions (the main index.html) do NOT use ``** — they put the `data-composition-id` div directly in ``. Using `` on a standalone file hides all content from the browser and breaks rendering.
Sub-composition structure:
```html
```
Load in root: ``
## Variables (Parametrized Compositions)
Render the same composition with different content — title, theme color, prices, captions — without editing the source HTML.
**Three-step pattern:**
1. **Declare** variables on the composition's `` root with `data-composition-variables`. Each entry needs `id`, `type` (one of `string`, `number`, `color`, `boolean`, `enum`), `label`, and `default`. Enum entries also need `options: [{value, label}, ...]`.
2. **Read** the resolved values inside the composition's script with `window.__framevideo.getVariables()`. Returns the merged result of declared defaults + per-instance overrides + CLI overrides.
3. **Override** at render time with `npx framevideo render --variables '{...}'` (top-level) or with `data-variable-values='{...}'` on the host element (per-instance for sub-comps).
```html
```
```bash
# Dev preview uses declared defaults
npx framevideo preview
# Render with overrides
npx framevideo render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4
# Or from a JSON file
npx framevideo render --variables-file ./vars.json
```
**Sub-composition per-instance values:** the same `getVariables()` works inside sub-comps loaded via `data-composition-src`. Each host element passes its own values:
```html
```
The runtime layers each host's `data-variable-values` over the sub-comp's declared defaults on a per-instance basis, so the same source can be embedded multiple times with different content.
**Rules of thumb:**
- Always provide a sensible `default` for every declared variable. Dev preview uses defaults — without them, the composition won't render correctly until `--variables` is provided.
- Read variables once at the top of the script (`const { title } = ...`), not inside frame loops or event handlers — `getVariables()` allocates a fresh object per call.
- Use `--strict-variables` in CI to fail fast on undeclared keys or type mismatches.
- Variable types are validated at render time. `string`, `number`, `boolean`, and `color` (hex string) check `typeof`; `enum` checks the value is in the declared `options`.
## Video and Audio
Video must be `muted playsinline`. Audio is always a separate `
Main Message
Supporting detail
Product Feature
Explanation