hyperframes/skills/faceless-explainer/phases/visual-design/guide.md

Visual Design (Phase 3)

Input story (Phase 2 - narrator_scripts.json) + brand design system (Phase 1b - design-system/chunks/). Design visual treatment and animation choreography for each scene, outputting section_plan.md.

This guide describes creative intent, not code. The downstream build agent (/hyperframes-core + /hyperframes-animation) translates it into HTML composition + GSAP timeline.

Flow Overview

1. All inputs are already inlined in dispatch — use them directly
2. Write ## Film Direction once (the film-level invariants — §4.1), then for each scene: choose effects from ## Effects catalog (timeline layering order; count rules in §2), decide Continuity, write anchor block + lean delta prose (≤150 words; §4.2); in prose, describe desired visual components by role ("a stat block", "a framed quote"), while the worker chooses concrete components from the ## Design chunks library
3. Run validator until exit 0

---

1. Inputs

narrator_scripts.json

• Scene-level: sceneNumber, sceneName, narrativeIntent.{type, narrativeRole, keyMessage, persuasion, emotionalBeat}, transition.{continuity, intent, sharedMotif?, description} (continuity copies directly to **Continuity:**; intent translates to **Transition:** registry type using the "Transition: translation" table only for break scenes; when intent: morph on a continue scene, sharedMotif is a prose hint for the carried element, not an anchor), assetCandidates[] (each has path + description), estimatedDuration (strip trailing "s" -> float)
• Top-level: narrativeArchetype + emotionalArc, which influence whole-film pacing

## Design chunks - Brand Input (inlined; do not read design.html)

Chunks are split by Phase 1b emit-chunks.mjs and already inlined in the dispatch ## Design chunks block: full index.json + actually present composition-hints.md / voice.md / tokens.css / easings.js (chunks absent from the preset have *_file=null and do not appear in the block).

Plan does not touch design.html or component HTML bodies.

Positioning (core): ## Design chunks is the brand's style reference library, not a contract for the plan. It only answers "what does this brand look like" - palette (tokens), motion curves (easings), DOM text register (voice), and a set of paste-ready components. Visual authority lives in ## Effects catalog (animation) and ## Design rules (design judgment); chunks only make the result look like this brand. Plan does not pre-cite components, declare surfaces, or filter components - it describes desired structures by role / purpose / intent in prose, and Phase 4b worker chooses concrete components from the full library by visual judgment.

Plan uses chunks in these ways:

1. Inspect chunks/index.json (~1-2 KB) -> get preset name + component library list (components[], each {id, file}). Only use this to know what components exist in the preset, so prose can refer to them by role ("use a stat-stamp-like number block"). No need to map each one, cite ids, or compute surfaces - worker chooses after seeing actual render.
2. Optionally inspect chunks/composition-hints.md (only when index.json.hints_file != null) -> preset's own composition / material / color preferences (background preference, 60-30-10 distribution, signature materials). Fold it into prose as style reference for palette / composition; worker uses it when implementing colors. This is taste guidance, not a hard "violation = render failure" contract.
3. Optionally inspect chunks/tokens.css (~1-2 KB) -> available role tokens in :root (--canvas / --ink / --brand-* / preset-private aliases like --paper / --blue / --cream) - informs descriptions of 30% middle layer and pain-scene palette.
4. Optionally inspect chunks/easings.js (~0.5 KB) -> whether role keys EASE.entry / emphasis / exit / drift are present, deciding which ease intents to cite in prose.
5. Optionally inspect chunks/voice.md (~0.5 KB, only when voice_file != null) -> this preset's DOM text register (strip / case / line breaks / inline <em>...). Worker receives full voice.md through a dedicated channel and applies it by default, so plan does not need to promise it scene by scene; mention it only for a special application / risk in that scene (e.g. "hero resolves as one-line UPPERCASE stacked words"). Plan does not write rewritten English copy (that is worker work).

No need to read chunks/type-roles.md -> named text role directory (worker lookup table for inline text styling). Plan does not cite role ids; it describes by role name ("hero display", "body lede").

Do not read: component HTML bodies (chunks/components/<id>.html) - Phase 4b worker owns that. Do not read legacy design.html (replaced by chunks).

Plan references by role / purpose / intent, not literal values. See §3 guidance:

Name this	Do not copy
Role (canvas / surface / accent / ink)	concrete hex (#e4ff97)
Purpose (display / body / mono)	concrete font name (Instrument Serif)
Intent (EASE.entry / DUR.med)	concrete curve (power3.out)
Component role ("a stat block" / "a framed quote")	component id / internal HTML / <style> block
Voice register ("UPPERCASE triplet")	rewritten English copy (worker work)

Do Not Read

• effects-catalog.md / rules/*.md (already embedded in dispatch as ## Effects catalog / ## Design rules)
• chunks/* from disk (already embedded in dispatch ## Design chunks)
• sidecar JSON / fonts directory under design-system/
• design-system/design.html (old contract; now replaced by chunks/)
• chunks/components/<id>.html body (plan only names role; component HTML is Phase 4b)

---

2. Hard Contracts (machine-checked)

Whole-file shape (mandatory): section_plan.md contains only an optional single-line H1 title + one ## Film Direction block (validator-required; content in §4.1) + a sequence of ## Scene N: blocks, nothing else. Film Direction is a real channel, not a preface: prep.mjs copies it into group_spec.film_direction, and the orchestrator prepends it to every scene worker's shared packet header and to the finalize dispatch. Any other content before the first ## Scene = dead bytes and a validator error. Global invariants reach workers through two real channels: 1. the ## Film Direction header (film-level rules, written once); 2. dedicated channels (voice_file / Captions flag / tokens.css / easings.js). Scene prose carries only scene-specific deltas on top of those. The "restatement" before writing (§4 Step 0) happens in your head only; never write it into the file.

Each scene in section_plan.md is one block, in the same order as narrator_scripts.json:

## Scene <N>: <sceneName>

**Effects:** [`<rule-id>`, `<rule-id>`, ...]
**Duration:** <X.XXs>
**Continuity:** break | continue
**Transition:** <type> [DIRECTION] [<dur>s] <- optional (soft); the Tier-B transition for a `break` scene, see below (omit on a `continue` scene)
**SFX:** <- optional (soft); omit entire section when unused; multi-line bullet list below
**PrimarySubjectTimeline:** <only for multi-act / dense multi-subject scenes>
**Handoff:** <only for multi-act / dense multi-subject scenes>

<prose body - first sentence is §4 item 1 emotional footnote - see §4>

Order inside the block is mandatory, and PrimarySubjectTimeline / Handoff must appear after all anchors and before prose (immediately after SFX block). Reason is mechanical: prep.mjs defines creative_brief = all text after the last recognized anchor, and it recognizes SFX but does not recognize PrimarySubjectTimeline / Handoff; therefore those two lines must come after SFX so they enter the worker brief. If placed before SFX, they get sliced away and worker never receives them. Rules: 1. all **Anchor:** lines (including SFX bullet block, PST, Handoff) are grouped at the top; 2. only then comes free prose, whose first sentence is the emotional footnote (§4 item 1, "the dividing line between real plan and generic AI output"); 3. once prose starts, no more **Anchor:** lines (interleaving = validator fatal). For multi-act scenes, the brief may start with **PrimarySubjectTimeline:** followed immediately by emotional footnote; that is expected.

validate-section.mjs enforces (hard):

• Effects: 2-5 backtick-wrapped rule ids, comma-separated inside brackets; each id must be an existing rule under hyperframes-animation/rules/ (the validator actually checks this). Normally cite only from dispatch ## Effects catalog; order is timeline-layering order.
• Duration: float seconds (source in §1)
• Continuity: break or continue; Scene 1 is always break. Copy scriptwriting transition.continuity verbatim. continue = this scene shares a worker with the previous one (a continuous run of up to 3 scenes); break = new worker. No Tier-A / Bridge requirement.
• Required anchors each stand alone on their own line, with no surrounding text; missing any required anchor -> downstream fatal -> rerun Phase 3
• PrimarySubjectTimeline + Handoff: required for multi-act scenes or scenes where action/payoff + proof/supporting subject share the frame. Missing either -> validator fatal. Position: immediately after SFX block and before prose (machine reason in template note above - they must enter creative_brief for worker). The "is this scene risky" trigger is read from the optional **Hierarchy:** anchor when present (a schema check), else inferred from the prose — see the Hierarchy anchor subsection below
• Block order: all **Anchor:** lines (including SFX bullets, PrimarySubjectTimeline, Handoff) must precede free prose; any **Word:** anchor line after prose begins -> validator fatal (interleaving makes worker brief unpredictable)
• File-level: before the first ## Scene only one H1 title + one ## Film Direction block are allowed; missing ## Film Direction -> validator fatal; Film Direction > 700 words -> fatal (it is a one-page header, not a second plan); any other preface -> fatal (see whole-file shape above)
• Per-scene prose length: target ≤150 words; > 320 words -> validator fatal. Walls of prose are almost always film-level invariants restated per scene — move them into ## Film Direction
• Transition (soft / if present): type must be a Tier-B type in the TRANSITION-REGISTRY vocabulary (crossfade / blur-crossfade / push-slide / zoom-through / squeeze); direction is only legal for a directional type (push-slide); duration 0 < dur <= 2.0s. It names how a break scene is entered; on a continue scene it is ignored because the same worker authors one shared-DOM group composition. There is no **Bridge:** anchor and no Tier-A contract.

Components (no anchor - worker chooses): plan no longer pre-cites components with a **Components:** anchor. The full component library (chunks/components/) is forwarded to worker, and worker chooses by visual judgment. Plan only names desired structures by role in prose ("a framed stat block", "a pill row of labels"), not ids or HTML - same role/purpose approach as palette/type.

Transition anchor (optional / soft - names "how a break scene is entered"):

This subsection is the authoritative writing guide for transitions (single source of truth). The later "Transition: translation" table only maps intent -> registry type; it does not restate machine rules.

• Shape: **Transition:** <type> [DIRECTION] [<dur>s], e.g. **Transition:** blur-crossfade / **Transition:** push-slide LEFT / **Transition:** zoom-through 0.3s
• Types (all Tier-B, injected by the harness onto clip wrappers after assembly; you never write GSAP): crossfade / blur-crossfade / push-slide (with LEFT/RIGHT/UP/DOWN) / zoom-through / squeeze. Full vocabulary + selection guidance in <SKILL_DIR>/../hyperframes-animation/transitions/TRANSITION-REGISTRY.md
• Use only 2-3 Tier-B types across the film (repetition = professional cohesion; see motion-language.md "transition vocabulary"). Scene 1's Transition is an opening placeholder (no previous scene, ignored) and may be omitted
• Omitting the line = accept default: the harness derives a Tier-B default from surface conflict / energy (clashing backgrounds -> blur-crossfade, high energy -> zoom-through, otherwise crossfade). Omit when uncertain; the default is usually good
• A continue scene needs no Transition anchor (see "Continue runs" below). The worker owns the entire continue run inside one shared-DOM group composition; the harness only handles Tier-B transitions between different visual clips. You only name intent; never write transition code, touch timing, or touch index.html

Continue runs (continuity: continue) — same-worker visual continuity:

• A continue scene shares a worker with the previous scene. prep.mjs groups a continuous run of up to 3 scenes (cap=3) into one worker and, when the run has 2-3 scenes, that worker writes one visual file (group_wN.html) with true shared DOM across the logical scenes.
• Use continue for 2-3 adjacent scenes that should read as one continuous shot — a process-step card that accumulates details, a logo/card family that progressively gains content, a persistent curve/counter/node graph, a growing diagram, or a camera that keeps moving. Describe the continuity in prose with an explicit carried subject: the same component family or the same diagram/data-viz primitive should persist and evolve inside the run.
• For a continue run, the prose "eye destination" sentence (§4.2 item 6) must state: what persists, what changes at this scene's segment, and what pose/state should be handed to the next logical scene. Do not describe a traditional transition at that internal seam.
• A run is at most 3 scenes; if more than 3 adjacent scenes share a stage, split into runs separated by a break. There is no Tier-A bridge, no data-bridge-id, no **Bridge:** anchor, and no wrapper transition inside the run — just mark continue where the flow is genuinely continuous.

This is the plan agent's explicit commitment about how scenes connect. It must align with the prose "eye destination" sentence (§4.2 item 6) — that sentence is human-readable creative direction; **Transition:** is only a machine instruction for break seams.

Hierarchy anchor (optional / soft — declares the scene's focal profile):

A scene that stacks competing focal claims — it is multi-act, or an action/payoff (CTA) co-exists with proof (logos / stats) — must carry **PrimarySubjectTimeline:** + **Handoff:** (see the enforces list above). validate-section.mjs decides whether a scene is "risky" in one of two ways:

• Declare it (preferred — turns the check into a schema read). Add a **Hierarchy:** anchor naming the profile from this fixed vocabulary: simple / multi-act / action / social-proof / data-proof (comma- or space-separated, e.g. **Hierarchy:** action, social-proof). Declared values are authoritative: a scene tagged simple is never treated as risky even if the prose mentions logos or a CTA, and one tagged multi-act is gated even if the prose reads calm. An out-of-vocabulary tag is a validator fatal, so a typo can't silently disable the gate.
• Omit it (fallback). When absent, the validator infers the profile from the prose (the historical keyword classifier). This still works but is fuzzier and can mis-read incidental wording — declaring the anchor removes that ambiguity.

The anchor is validator-only: prep strips it before the worker brief, so it never adds noise to scene content. Place it among the anchors, before prose (it's in the block-order anchor set).

SFX anchor (optional / soft - only write when using sound effects):

Most scenes have no SFX - in that case omit the entire **SFX:** line. Omission = "no sound effect for this scene", validator does not complain. To add SFX, write **SFX:** alone on a line + one or more bullets:

**SFX:**

- `impact-bass-1.mp3` at 0.2s, volume 0.35 — hero stamp lands
- `whoosh-short.mp3` at 4.1s — exit

(Explicit **SFX:** none is also accepted; but because it is optional, omitting the line when unused is simpler.)

No silent drop risk: once you cite a <file>.mp3, validator checks it immediately against ## SFX library - misspelled filenames are Phase 3 fatal errors you can fix on the spot, no longer silently dropped by prep.mjs. So optional is safe: not writing = explicitly unused, writing = guaranteed valid.

• <file>.mp3 must be listed in dispatch ## SFX library (misspelling = validator fatal)
• <T>s is scene-local seconds; prep.mjs adds start_s offset automatically
• volume optional, default 0.35; under narration use 0.2-0.3, pure SFX can be 0.4-0.6, 0.5+ may cover voice
• — <note> is human annotation

Placement rules:

• Impact / hit (impact-bass-* / ping / pop / glitch-* / whoosh): trigger at the exact visual point, letting decay carry into the next shot (J-cut)
• Riser / build-up (riser 10s / whoosh-cinematic 5.5s): peak at the end; if it should explode at N seconds, trigger at N - duration
• Short accent (click / click-soft / chime / sparkle / ping / whoosh-short): sync with the visual point

Less is more: most scenes have zero SFX; one cue in a scene is typical. Do not add SFX at scene transitions (the hard cut itself is the audio-visual event).

Forbidden: estimated timestamps (verify-output.mjs sfx enforces ±0.1s drift) / shortening data-duration (impact cut mid-decay = amateur feel).

Available mp3 list is in dispatch ## SFX library (each item has file / duration / purpose) - choose by purpose.

Primary / Supporting Anti-Overlap Contract

Remember one rule: only one primary subject at a time; all other visible content must be supporting.

Risk scenes must include these two lines before prose:

**PrimarySubjectTimeline:** 0-4.0s product panel primary; 4.0-7.0s proof cluster primary; 7.0-10.0s action headline primary, proof cluster supporting rail.
**Handoff:** Before the action headline enters, the proof cluster demotes to a small low-contrast rail. Camera push does not count as handoff. The new primary owns the center safe zone.

Rules:

• Multiple subjects can be on screen, but only one is primary; the rest must be supporting rail / side rail / background texture / low-emphasis chrome.
• Before a new primary enters, previous primary must exit / hide / compact / demote; camera pan / zoom / push does not count as exit.
• Action / payoff frame: primary headline / product / decision point owns the center safe zone; proof, labels, logos, stats, and card clusters, if retained, must be smaller, lower contrast, less animated, and outside primary bbox.

Continuity comes directly from scriptwriting (no inference): each scene transition.continuity in narrator_scripts.json (break | continue) - copy it verbatim into the **Continuity:** anchor. continue lands the scene in the same worker as the previous one (a continuous run of up to 3 scenes); break starts a new worker. Scene 1 is always break. Cross-scene consistency is covered in §5 "variety" soft guidance.

Transition: translating scriptwriting narrative intent to concrete registry type (this is visual-design's job - you have preset/palette/background/energy context; the scriptwriting phase does not). Each scene's transition.intent in narrator_scripts.json is one of 5 narrative intentions; translate it to a **Transition:** registry type only for break seams using the table below (full vocabulary in <SKILL_DIR>/../hyperframes-animation/transitions/TRANSITION-REGISTRY.md):

scriptwriting intent	-> **Transition:** registry type	Notes
morph (+ continuity: continue)	(no Tier-B type)	same-worker continue run; the worker writes one shared-DOM group_wN.html and authors the carried element inside that timeline — no **Transition:** / **Bridge:** anchor needed
cut	crossfade	clean cut; for high-energy moments you may omit Transition anchor and let default apply
slide	push-slide <direction>	direction matches narrative flow (forward=LEFT/RIGHT, expanding downward=DOWN)
dissolve	blur-crossfade when backgrounds clash / crossfade otherwise	inspect both scene #root backgrounds: large difference -> blur hides hard cut; similar -> normal crossfade
zoom	zoom-through	camera push / high energy

• You have visual context, so you may override: if a default translation is wrong for the preset (e.g. color clash should use blur where table says crossfade), use visual judgment - table is default, not law.
• Use only 2-3 transition types repeatedly across the film (repetition = cohesion, see motion-language.md). All harness transitions are Tier-B and occur only between different visual clips; intent narrows the choice and you pick concrete values within it.
• When uncertain, omit the **Transition:** anchor - downstream prep derives a Tier-B default from energy/color clash (see §2 Transition anchor). A continue scene needs no Transition anchor at all.

intent: morph on a continue scene is a soft hint: mark **Continuity:** continue (no Transition / Bridge anchor) and describe the carried element in prose. The one worker owning the continue run writes one group composition and authors the morph/accumulation with persistent DOM — there is no **Bridge:** anchor, no data-bridge-id contract, and no wrapper seam to hide a mismatch (see §2 "Continue runs").

If the effect you need is not in catalog: first try combining existing effects. Still insufficient -> do not invent a name; mark in phase report needed effect missing: <description>.

---

3. Design Principles (inlined in ## Design rules)

Four rule files cover plan-layer design judgment - all organized by role / intent / decision, with no hex / px / ms / code. They are already inlined in dispatch ## Design rules; read them there, not from disk. Concrete values are looked up by the build agent in /hyperframes-core + /hyperframes-animation + chunks, and plan does not copy them (see §4.1 / §4.2 item 4 and the "Name this vs do not copy" table in §1).

Four rule files:

• rules/typography.md - 7-level type role ladder / multi-dimensional hierarchy / font pairing / forbidden pairs / CJK
• rules/color-system.md - 7 palette roles / 60-30-10 / cross-scene consistency / dangerous combinations / background layering
• rules/composition.md - four canvas zones / 7 templates (film >=3 templates) / density rules / depth techniques
• rules/motion-language.md - 5 spring intents / duration tiers / beat structure / stillness-before-climax (2-3 scenes, allocated in Film Direction) / motion budget (one macro move + 1-2 live elements, subtle amplitudes) / transition vocabulary (film 2-3 types)

Choosing the 2-5 **Effects:**

Compose freely from ## Effects catalog to fit the scene's narrativeRole + keyMessage — there are no pre-baked skeletons. Free composition is the correct path for explainer scenes (concept naming, mechanism step, list item, quote, stat). To reach 2-5:

• Default-add sine-wave-loop (continuous / ambient layer) on most scenes — it fills one of the scene's secondary live slots (motion budget); plan its amplitude per rules/motion-language.md "Motion Budget" subtle defaults (±2-3 px / ±1-2% scale, 2.5-4s cycle). Drop it entirely on the closing beat and on any scene where the idle phase would exceed 50% of duration; that scene settles and holds instead. Across the film, ≤ 2 consecutive scenes carry sustained drift.
• Then add by emotional beat: transition glue scale-swap-transition / card-morph-anchor, SVG life svg-icon-enrichment / svg-path-draw, data beats counting-dynamic-scale / asr-keyword-glow, depth reinforcement 3d-text-depth-layers / split-tilt-cards.
• Effect order = timeline layering: background -> primary entry -> continuous -> emphasis -> transition.

---

4. Writing the Plan - Film Direction Once, Scene Deltas After

Step 0 (before writing, mandatory): first restate this run's direction to yourself (Voice register for each scene) - full instructions live in the agent prompt "Restate the contract before writing" section (that persistent prompt is the single source of truth, not repeated here). Key constraint: restatement only sets direction in your head - what belongs on disk is ## Film Direction (film-level invariants, §4.1) and the scene blocks; any other preface = validator fatal.

The litmus test that governs this whole section: "Could this sentence appear verbatim in another scene's prose?" Yes -> it belongs in ## Film Direction, not in the scene. The archived failure mode this kills: an 11-scene plan of 4,000 words where every scene restated the caption band, the 60-30-10 split, the ambient layers, multiplicative breathing, and a stillness-before-climax - ~80% invariants repeated 11×, burying each scene's 2-3 genuinely unique ideas where the worker had to dig for them.

4.1 ## Film Direction (write once, before Scene 1; hard cap 700 words, aim for ~250-400)

The film-level invariant layer. prep.mjs copies it into group_spec.film_direction; the orchestrator prepends it verbatim to every scene worker's packet and the finalize dispatch - so anything written here reaches every downstream agent exactly once. Cover, as compact labeled lines / short lists:

1. Palette system - the film's 60-30-10 by role with accent binding ("60% canvas / 30% hairline + repeated canvas (no surface token) / 10% accent: brand-primary carries hero words and the active diagram element, deco-3 cyan as particle accents only").
2. Type roles - what display / body / mono are for across the film.
3. Motion defaults + budget - default ease intent per element class ("entries EASE.entry; heroes heavy; idle EASE.drift; exits none - scenes hold the final frame"), and the film's motion budget: every scene gets ONE root-level macro motion (camera drift / dolly / parallax) + at most 1-2 secondary live elements; everything else rests; ambient amplitudes stay at the subtle floor (±2-3 px / ±1-2% scale; see motion-language.md "Motion Budget"). Reference only canonical role keys EASE.entry/emphasis/exit/drift, DUR.snap/med/slow - worker uses this key set directly; invented aliases fall through.
4. Ambient system - the recurring background / atmosphere layers and any alternation scheme ("low-opacity grid + paper grain, full-bleed every scene; dark↔light ground alternation by scene parity").
5. Film negative list - what NO scene may do ("no mesh gradients, no neon-on-black, no glow bloom, no purple-blue AI gradient, no bokeh").
6. Transition vocabulary - the 2-3 Tier-B registry types this film repeats at break seams (must agree with the per-scene **Transition:** anchors).
7. Visual register mix (+ asset coverage when any) - the per-scene register allocation across the film (which scenes are kinetic typography / abstract graphics, which are diagram / data-viz - vary registers the way you vary composition templates, §5 Variety). On the rare film where assetCandidates[] is non-empty, also a coverage table: every candidate path -> the scene that uses it + its role, or DROP + a one-line reason. This is the single place coverage is decided; scene prose never defends keeping or dropping an asset.
8. Stillness-before-climax allocation - name the 2-3 scenes (max) that get the beat, where the narration lands a payoff. Repeated in every scene it stops being a comma and becomes a tic.
9. Captions (only when top-level dispatch says Captions: enabled) - one line: the bottom ~17% band is reserved film-wide, foreground anchors around 0.42×height; per-scene prose mentions captions only for genuinely risky placements.

Same role/intent discipline as everywhere: no hex / font names / ease curves / GSAP code (the subtle ambient amplitude bands from motion-language.md - "±2-3 px / ±1-2%" - are plan vocabulary and fine).

4.2 Scene prose (after anchors; target ≤150 words, validator-fatal above 320)

One free-prose paragraph of scene-specific deltas only, passed verbatim to the build agent - write as if briefing a senior animator who has already read Film Direction. In order:

1. Emotion and rhythm footnote - one sentence naming the beat's feeling and rhythm ("frustrated, slightly-off comma", "luminous launch-film slow build"). This is the dividing line between real plan and generic AI output.
2. Composition + register + subject - composition template (centered / thirds / split / layered / asymmetric / triptych / strip), this scene's faceless visual register (kinetic typography / abstract graphics / diagram / data-viz - see "Faceless visual register" below) and the key text/data it carries, the primary visual's canvas share (>=40%), supporting elements by role, whitespace intent. Mention the caption band only when this scene's concept pushes content low ("stat stamp bottom edge sits just above the caption band"). On the rare scene with non-empty assetCandidates, the Film Direction coverage table already decided placement - just stage what it assigned.
3. Scene-unique choreography - for every id in **Effects:**: the text label, graphic, diagram element, or data-viz series it drives, and when it fires (scene-local relative seconds / ratios - never restate total duration; worker timing is pinned from group_spec, prose approximations only conflict). Name this scene's macro motion (which camera-style move from the budget) and which element holds the live ambient slot when it departs from the Film Direction default (long-idle scenes: settle and hold the final 25-40%, see motion-language.md). Name spring intent / EASE.* keys only where the scene departs from the Film Direction defaults.
4. Style deltas (only if any) - where this scene deviates from Film Direction ("accent flips to the warm secondary as the hot focal this scene"; "text one weight lighter on the dark ground"). Nothing deviates -> write nothing.
5. One negative sentence (only if scene-specific) - "no glow on the edges - this is a clean schematic". Film-level negatives live in the header; do not repeat them.
6. Eye destination - one short sentence on where the eye travels into the next scene. At a break, the machine instruction is the **Transition:** anchor; do not elaborate veil/dissolve/curtain mechanics (the worker writes no exit tween - the harness injects Tier-B transitions on clip wrappers). At a continue seam (same worker) this sentence does real work: specify which element carries across and roughly how it should look at the handoff so the worker can author the continuous flow inside one group timeline.

Faceless visual register

Faceless explainers have no captured assets; the scene's primary visual is invented. Two registers are equally first-class, and the worker picks per scene by what the script is explaining:

• (a) Typography / abstract graphics - kinetic type, hero words, framed quotes, shapes, gradients, icon fields, brand-derived geometry. Reach for this when the script states a thesis, claim, quote, or term ("a process / a number / a comparison" has no obvious figure).
• (b) Diagram / data-viz - step flows, node graphs, timelines, charts, comparison tables, counters. Reach for this when the script describes a process (-> diagram / numbered steps), a number or comparison (-> data-viz / chart / counter), or structure / relationships (-> node or flow diagram).

Neither register is a fallback for the other - a typographic scene is a full, deliberate composition (composition.md "Frame Density"), and a diagram scene is not "more real" for having boxes. Vary the register across the film the way you vary composition templates (§5 Variety): an all-typography film reads flat, an all-chart film reads like a dashboard. Allocate the mix once in Film Direction item 7; name each scene's register in prose item 2.

Do not write pixel values (the sanctioned ambient amplitude bands aside), GSAP timeline code, composition HTML, concrete hex / font names / ease curves - that is build-agent work. But give enough constraints that the result clearly belongs to this scene, not a generic interpretation. Do not re-promise what already travels via Film Direction or dedicated channels: caption-band geometry, palette ratios, ambient layers, breathing / idle defaults, EASE/DUR labels that match the declared defaults, voice recipe mechanics (worker has the full voice_file; mention voice only for a special application - "hero resolves as one-line UPPERCASE stacked words"), or asset/register-coverage defenses (the header owns coverage). Every surviving word should be a decision unique to this scene.

Anchor order (PST/Handoff before prose) is in §2 and unchanged - risky scenes still carry **PrimarySubjectTimeline:** + **Handoff:** lines.

Complete File Example (header + one scene)

# How Compound Interest Works — Chalk Ledger

## Film Direction

**Palette:** 60% slate canvas / 30% hairline rules + repeated canvas (no surface token) / 10% accent — chalk-gold carries every hero number and the live diagram element; settled elements fall to ink.
**Type:** display = thesis words and hero numbers only; mono uppercase = eyebrows and axis labels; body = step labels.
**Motion:** entries EASE.entry; heroes heavy; idle EASE.drift at the subtle floor (±2-3 px / ±1-2%); exits none — scenes hold the final frame. Budget: one root-level camera move per scene (slow drift or push) + at most one breathing hero; everything else rests.
**Ambient:** low-opacity grid + paper grain, full-bleed, every scene. Nothing else.
**Never (film-wide):** no mesh gradients, no neon-on-black, no glow bloom, no bokeh.
**Transitions:** crossfade + push-slide only (break seams).
**Stillness-before-climax:** scenes 3 and 6 only.
**Register mix:** scenes 1/4/7 kinetic typography; 2/3 diagram; 5/6 data-viz (counter, area chart). No captured assets this film (`assetCandidates` all empty).

## Scene 5: the-snowball

**Effects:** [`counting-dynamic-scale`, `svg-path-draw`, `sine-wave-loop`]
**Duration:** 6.20s
**Continuity:** break
**Transition:** push-slide LEFT

Beat 3a — the snowball (quiet awe, accelerating rhythm). Data-viz register: a hero counter above a growing area chart fills ~55% of canvas, centered, generous air. `counting-dynamic-scale` runs the balance across ~4s while `svg-path-draw` traces the curve beneath it; `sine-wave-loop` keeps only the landed chart breathing. Macro motion: slow push-in on the scene root across the whole beat. Multi-phase: setup hold ~0.5s -> count-and-draw ~4.2s -> landed hold ~1.5s. Accent binds to the live curve tip only this scene. No gridline shimmer — the chart is chalk, not a terminal. Eye exits left with the curve's endpoint into the comparison split.

That scene block is ~100 words of prose, and every sentence is unique to the scene - that is the target shape. The palette system, ambient grid, breathing defaults, and caption band are all upstairs in Film Direction, written once.

---

5. Soft Guidance (taste-level, affects plan quality but not validator)

Scene Quality Floor - Motion Budget

Declared once in Film Direction item 3 ("Motion defaults + budget"); full rationale + the subtle amplitude floor in motion-language.md "Motion Budget". Do not re-spec it per scene - scene prose only names which macro move this scene uses (§4.2 item 3).

Every scene gets:

1. ONE macro motion (required) - a root-level camera-style move: slow drift, dolly in/out, push, parallax. It moves every layer coherently (background counter-scale is an archive signature; concrete values are build work) - this global correlation is what makes a frame read as filmed rather than animated UI.
2. At most 1-2 secondary live elements - hero multiplicative breathing (on final scale, not yoyo, subtle ±1-2%), CTA glow pulse, a single ambient deformation. Pick from motion-language.md's pattern menu.
3. Everything else rests. Stillness is not dead air - it is what makes the moving element read (composition.md hierarchy: "one element moving vs all else static" is a strong contrast). A scene where everything floats at its own phase reads as noise, not life.

An element that springs in and then sits still while the camera holds = slide. An element that rests while the camera drifts = cinema.

Scene Quality Floor - Ambient Layer

The ambient system (background swell / grid / scanline / particles / halftone) is declared once in Film Direction item 4 and mounted by every scene - scene prose does not re-list it. Per scene, what remains a floor:

1. No bare solid background - the film's declared ambient layers must actually be present
2. Emphasis moment - at least one impact beat (ripple / glow burst / impact lines / screen-shatter)

Multi-Phase Choreography

entry -> ambient drift -> major transition (morph / pivot / collapse) -> [stillness-before-climax (~0.3-0.75s), only in the 2-3 scenes Film Direction allocates] -> result / emphasis -> idle hold

Phases vary by the beat's role (motion-language.md "Beat Structure"): a fast-montage scene may be two phases; a process-reveal scene may be one continuous take. Do not stamp the same skeleton on all scenes.

Forbidden Patterns (most common failures)

• no macro motion: camera holds AND every element settles after entry (the scene reads as a slide)
• treating ambient micro-float as the scene's only "motion" — the macro move is the required motion; subtle drift (±2-3 px / ±1-2% scale) only fills a secondary live slot, it never substitutes for the camera move
• the opposite failure: everything moves - more than the budgeted 1-2 live elements floating / breathing / orbiting at once (uncorrelated ubiquitous motion = noise; it also erases motion as a hierarchy signal)
• using word-by-word text popping as the primary visual (unless carefully choreographed as visual lead)
• all elements enter simultaneously (must stagger; total <=500ms)
• only ambient layer, no primary content (particles + captions)
• same composition every scene (at least 3 different templates per film)
• primary visual element <40% of canvas
• when captions enabled, key content (CTA / hero / stat stamp / headline) enters bottom ~17% (y>900) caption band = covered by captions (background/ambient layers may extend down; key foreground may not)
• generic AI clichés: saturated neon on pure #000, purple-blue AI gradient background, decorative floating bokeh balls
• solid background without swell / grid / scanline / particle
• in a scene Film Direction allocated a stillness-before-climax: jumping directly from action to payoff with no comma; in every other scene: stamping the comma anyway (a signature repeated everywhere is a tic)
• multiple primary subjects fighting for center safe zone; any product / proof / logo / stat / headline / card cluster on screen together must have primary/supporting and handoff
• treating camera pan / zoom / push as old-content exit; camera moves the viewpoint but does not automatically reduce old primary visual weight
• copying concrete hex / font names / ease curves from chunks/tokens.css / chunks/easings.js into prose - that is build-agent work

Variety

Across all scenes, use at least 3 different composition arrangements. The strongest archive plan (playground-launch) used 5+ visual universes across 8 beats, glued with one shared transition vocabulary (cut-the-curve) + one shared palette grammar. Visual worlds varied, seam treatment consistent - that is the principle.