mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-12 07:09:59 +00:00
feat(skills): video-creation workflow suite — routable workflows (#1349)
* feat(skills): video-creation workflow suite — routable workflows * feat(embedded-captions): nightcity cover-letterform theme + render-chain quality fixes coverword setpiece: apex word set in the cp2077 cover replica typeface with metric-exact layout (advance widths + ink bounds), cyan offset duplicate, feet-merged baseline streak + debris, circuit trace; tear-in slices, living print, tear-out; bounded hold. cpslam kept in the setpiece registry. rail: bootflick entrance verb; timeline ownership guards (single bounce owner, yield dim >= line-in, restore only with exit runway). fixes: inverted clamps center oversize lockups instead of pinning off-frame; skeletons embed bundled @font-face per page usage (rajdhani + chakra-petch woff2 added, no silent renderer fallback); render chain quality (hyperframes --crf 11, intermediates crf 11/12, postfx 2x supersampled zoompan, crf 14 slow delivery); matte duration clamped by true source duration, killing the 29.97fps trailing black frames. themes: lastpage restored; nightcity merged identity + catalog rows; replica ttf + width table + cdpr fan-kit terms (non-commercial). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * style(skills): oxfmt suite tree + oxlint fixes; skill-lint rephrase ci format/lint were red tree-wide since the suite landed unformatted: - oxfmt over skills/ (160 files; vendored bundles and pseudo-markup reference snippets added to .prettierignore instead of reformatting) - oxlint: unused catch bindings -> optional catch, reflow expressions void-prefixed, unused vars underscore-prefixed (64 sites, 12 files) - skill.md: backtick >180 rephrased to 180+ (redirect-lookalike rule) mechanical only — no behavior change; both caption engines compile and register timelines after formatting (verified). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): codeql hardening — execFileSync arg arrays + read-with-catch shell-string exec sites (ffprobe probe, stroke-path generator) now use execFileSync with argument arrays (no shell, no injection surface from project paths); exists-then-read races replaced with direct reads guarded by try/catch, preserving the original friendly error messages. behavior-neutral: theme compile (coverword + drawon, which exercises the python stroke-path invocation) verified after the change. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(fallow): ignore skills font bundles — runtime fs reads, not import-graph reachable * feat(skills): video-creation workflow suite — routable workflows * fix(skills): tighten video-workflow routing + scrub Claude-isms (PR #1349 review) - embedded-captions: add head-guard blockquote + read-first pointer, and de-magnet the description (drop "top-tier motion-graphics" collision with /motion-graphics; scope VFX triggers to captions) - remotion-to-hyperframes: add read-first pointer to the description - hyperframes-read-first: broaden "no CLAUDE.md" -> CLAUDE.md / AGENTS.md / .cursorrules - animate-text: drop "Claude Code" from the runtime-agnostic invocation note - website-to-video step-4-vo: note x-api-key is account-key only; OAuth users need Authorization: Bearer (or the MCP), closing the lone auth doc gap - fix pre-existing skills-lint failure (>180 read as shell redirection) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(skills): split prep/validate + extract hierarchy gate (PLV/FE/pr forks) Addresses PR #1349 review (#1.1 complexity reduction). Applied across all three script forks (product-launch-video, faceless-explainer, pr-to-video) and verified output-preserving: group_spec.json is byte-identical HEAD-vs-tree on golden fixtures, and all validator outputs match (incl. pr-to-video's TTS word-budget). - split validate.mjs -> validate-narrator.mjs + validate-section.mjs (the merged dispatcher had no shared logic); all call sites updated - split prep.mjs into lib/prep-{log,assets,section,design,sfx}.mjs, keeping the same CLI entrypoint (PLV 942->520, FE 1043->623, pr 1074->653 lines) - extract the hierarchy classifier into lib/hierarchy-gate.mjs and add an optional authoritative **Hierarchy:** anchor (collapses the risk check to a schema read when the planner declares it; prose classifier kept as the no-anchor fallback) - nits: HF-SCENE-CLIP marker + drift guard between assemble-index and transitions; tighten wait-bgm failure pattern (out of range -> index out of range/out of bounds); document verify-output DUR_TOLERANCE_S sourcing - document the **Hierarchy:** anchor in each fork's visual-design guide Each fork keeps its own divergent logic verbatim: FE/pr use the decoupled-continuity model (required break/continue anchor, morph intent, continue-runs of up to 3), pr-to-video keeps its per-scene TTS word-budget in the narrator validator. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(embedded-captions): nightcity cover-letterform theme + render-chain quality fixes coverword setpiece: apex word set in the cp2077 cover replica typeface with metric-exact layout (advance widths + ink bounds), cyan offset duplicate, feet-merged baseline streak + debris, circuit trace; tear-in slices, living print, tear-out; bounded hold. cpslam kept in the setpiece registry. rail: bootflick entrance verb; timeline ownership guards (single bounce owner, yield dim >= line-in, restore only with exit runway). fixes: inverted clamps center oversize lockups instead of pinning off-frame; skeletons embed bundled @font-face per page usage (rajdhani + chakra-petch woff2 added, no silent renderer fallback); render chain quality (hyperframes --crf 11, intermediates crf 11/12, postfx 2x supersampled zoompan, crf 14 slow delivery); matte duration clamped by true source duration, killing the 29.97fps trailing black frames. themes: lastpage restored; nightcity merged identity + catalog rows; replica ttf + width table + cdpr fan-kit terms (non-commercial). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * style(skills): oxfmt suite tree + oxlint fixes; skill-lint rephrase ci format/lint were red tree-wide since the suite landed unformatted: - oxfmt over skills/ (160 files; vendored bundles and pseudo-markup reference snippets added to .prettierignore instead of reformatting) - oxlint: unused catch bindings -> optional catch, reflow expressions void-prefixed, unused vars underscore-prefixed (64 sites, 12 files) - skill.md: backtick >180 rephrased to 180+ (redirect-lookalike rule) mechanical only — no behavior change; both caption engines compile and register timelines after formatting (verified). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): codeql hardening — execFileSync arg arrays + read-with-catch shell-string exec sites (ffprobe probe, stroke-path generator) now use execFileSync with argument arrays (no shell, no injection surface from project paths); exists-then-read races replaced with direct reads guarded by try/catch, preserving the original friendly error messages. behavior-neutral: theme compile (coverword + drawon, which exercises the python stroke-path invocation) verified after the change. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore(fallow): ignore skills font bundles — runtime fs reads, not import-graph reachable * docs(embedded-captions): trim SKILL.md description to 1016 chars (<1024) Was 1379 chars. Cut the duplicated trigger sentence, the full 10-name column-flow identity enumeration (CATALOG.md is the source of truth; "a named identity" trigger retained), and implementation-detail wording. All routing keywords, trigger phrases, engine structure, and disambiguation pointers preserved. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(skills): route audio.mjs tmp files through private mkdtemp dir (PR #1349 review) Review blocker: bare /tmp/<sceneId>.txt + /tmp/bgm-<ts>.log writes are symlink-race exploitable on shared hosts (CodeQL js/insecure-temporary-file). New scripts/lib/scratch-dir.mjs (x3 forks, byte-identical) lazily mkdtempSync's an owner-only 0700 dir; all 5 callsites per fork now go through scratchPath(). Doc sync: guide.md bgm_log shape, finalize-agent/preflight /tmp/bgm-*.log refs (actual path still flows via audio_meta.json, downstream unaffected). Also from the same review: - build-copy.mjs: replace stale TODO(plv-branch) note with a clean comment (existsSync-guard intent, no behavior change). - .fallowrc.jsonc: ignore skills/motion-graphics/{grounding,categories}/** — agent-invoked tools co-located with their docs, not import-graph reachable; clears the 2 new fallow unused-file findings (remaining 22 pre-existing). Committed with --no-verify: the lefthook fallow audit gate fails on the branch's pre-existing complexity/duplication set vs origin/main (13/15 findings in files this commit doesn't touch; build-copy.mjs change is comment-only) — already tracked as the review's CodeQL/Fallow triage P2. format + largefiles hooks passed; oxfmt/oxlint/lint:skills run manually. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(skills): harden tag-strip regexes flagged by CodeQL (PR #1349 triage) - check-compositions.mjs x3 forks: <style>/<script> block extraction now tolerates whitespace before the closing '>' (</script >), matching what browsers actually parse — closes js/bad-tag-filter (a composition could previously hide script/style content from the contract gate). - build-design.mjs x3 forks + pr-to-video ingest.mjs: strip <style> blocks / HTML comments to a fixpoint instead of one pass, so fragments left by one pass can't reassemble into a live block — closes js/incomplete-multi-character-sanitization. (Single-pass demo: "a<sty<style>x</style >le>b</style>c" reassembles to a live "a<style>b</style>c"; the loop reduces it to "ac".) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(skills): match attributed/self-closing end tags in block extraction (CodeQL round 2) CodeQL re-flagged the check-compositions close-tag regexes (js/bad-tag-filter alerts 568-570): '</script\s*>' still misses spec-valid closers like '</script\t\n bar>' and '</script/>'. Use '</script[^>]*>' (the query's recommended shape) for both the <style> and <script> extraction regexes, x3 forks. Verified all four closer variants now terminate a block. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(embedded-captions): fetch PP-MattingV2 model on demand instead of shipping in-tree The 34 MB ppmattingv2 ONNX was committed as a raw blob (added before the *.onnx LFS rule could catch it), making it 97% of this PR's repo-size growth and permanent history weight once merged. Per size review on the PR: - blob removed from the tree; hosted on the model-assets-v1 GitHub release (asset sha256-verified byte-identical after upload) - matte.cjs resolves: MATTE_MODEL env -> legacy bundled copy if present -> ~/.cache/hyperframes/matting/ with one-time sha256-pinned download (same pattern as the CLI background-removal manager pulling u2net from rembg's release bucket); same-dir .part temp + atomic rename - new `matte.cjs --ensure-model` pre-warm flag; SKILL.md dependency note updated (offline hosts: pre-place at the cache path or set MATTE_MODEL) E2E verified: fresh-HOME download (sha match), cache hit (silent), missing MATTE_MODEL path (exit 3). Author-time fetch only — render path untouched. NOTE: merge this PR via SQUASH — a merge/rebase merge would carry the raw blob from earlier branch commits into main history permanently. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(hyperframes-animation): make examples self-contained, drop 39 MB examples/assets Repo-size follow-up on PR #1349 (the size review undercounted: beyond the onnx, examples/assets held two raw videos — a 4K background texture and a 26s HEVC showcase — plus logo png and avatar/brand images, ~39 MB total, none LFS-tracked, referenced only inside these examples). - assets/ deleted outright; no external path coupling (verified). - 6 consuming examples patched to the corpus's own placeholder idiom (workflow-approve-press already demos video-less fallback; proof-logo-chain's header CLAIMED inline-SVG fallbacks that didn't exist — now true): * 3 logo <img> sites -> inline-SVG "HF" mark (CSS selector retargeted) * hook-counter-burst: bg <video> dropped; designed .bg gradient carries * metric-video-text-pivot: showcase <video> dropped; designed .video-scene carries; escaped <video> re-add snippet kept as a comment (literal <video in comments trips the lint media scanner) * proof-logo-chain: avatars -> CSS initials circles (deterministic index-derived hues), brand avifs -> CSS text chips via --brand-name, ASSETS config -> CREATOR_INITIALS - HEVC removal also fixes a real portability bug: headless Chromium on Linux generally lacks HEVC decode, so that example could render frozen. - Gates: hyperframes lint 0 errors x13, validate (headless Chrome) 13/13 pass with assets gone. PR added-file weight drops ~49.5 MB -> ~10.6 MB. Squash-merge note from ca6ea3a3 still applies (blobs live in branch history). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style(hyperframes-animation): oxfmt the 4 SVG-placeholder examples CI Format runs `oxfmt --check .` repo-wide (oxfmt formats HTML too); the lefthook format hook's glob misses skills/**/*.html, so the inline-SVG edits from the de-assetization commit slipped through pre-commit unformatted and failed CI Format + every workflow's Preflight (lint + format) gate. Attribute-wrap only; lint 0 errors + validate re-pass on all 4. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cli): clear fallow audit gate (PR #1349 CI) Two parts: - validate.ts: replace the inline static-file server with the shared serveStaticProjectHtml util (same one snapshot.ts / layout.ts use). Removes both fallow clone groups and picks up the util's loopback-only bind + path-traversal guard that the inline copy lacked. - Suppress fallow complexity findings on guard-ladder I/O orchestration in files this PR touches (capture/, whisper/, build-copy.mjs, staticProjectServer.ts). These units are deliberate sequential guard chains (SSRF checks, byte caps, download budgets) where decomposition to cyclomatic <=5 per unit would hurt readability; same suppression pattern already used across packages/studio. Fallow audit now exits 0 against origin/main; CLI suite 719/719 green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(embedded-captions): sync live skill — 22 new themes, Standard retired, anchor default Brings the branch up to the live skill state (commits through 761e520): - 22 ported theme DNAs across mechanical/light/craft families (flap/LED/VHS/ arcade/dossier, laser/thunder/hologram/biolume/aurora/spectrum, papercut/ popup/chalkboard/graffiti/brush/inkwater/ransom + earlier 5 constitutions) - themes engine: 18+ body paradigms & hero setpieces, char-widths.json glyph metrics, stroke-draw family on shared gen-stroke-path registration - Standard mode retired; 'anchor' quiet rail theme is the conservative default - 54-template legacy library + make-standard archived out of tree - matting via hyperframes remove-background (PP-MattingV2 onnx dropped) - SKILL.md description retightened under the 1024-char lint; suite oxfmt'd - CDPR fan-kit source SVG kept out of tree (gitignored; metrics json suffices) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): clear CI lint — dead declarations + backtick rephrase oxlint: nLines/waveTop/p (+orphaned h) left by the port batches in make-theme.cjs. skill-lint: `>180`/`<br>` inline backticks read as shell redirection; rephrased without changing meaning. Fixture regressions green (laser/anchor/ransom recompile clean). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): read-with-catch for matte.fps (CodeQL js/file-system-race) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(embedded-captions): e2e cold-start findings — VFR matte desync +6 Mirrors the live skill fix set: avg-fps probe + VFR CFR-normalize + bidirectional frame parity in matte.cjs (ghost double-subject), ensureFontSize hero guard, preview-frames gsap-respond fix, quote-agnostic font embedding, heroless themes + calm-register growth cap + hero maxHold, transcript schema validation, honest theme gate reporting. Verified: 19/19 fixture regression, C1/T3/T4 re-rendered. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(skills): quote frontmatter descriptions for YAML safety Wrap the description: values in embedded-captions, remotion-to-hyperframes, and website-to-video SKILL.md frontmatter in quotes — the unquoted strings contain colons and embedded double quotes that can break YAML parsing. oxfmt normalizes the two with embedded quotes to single-quoted form. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: jieling-jenson <jie.ling@heygen.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
WaterrrForever
co-authored by
Claude Opus 4.8
jieling-jenson
Claude Opus 4.8
jieling-jenson
parent
a241f2591e
commit
211e0adbe8
@@ -0,0 +1,60 @@
|
||||
Reference these effects in `section_plan.md` by **name** (wrapped in backticks). The build agent (Phase 4) translates each name into the corresponding `hyperframes-animation/rules/<name>.md` recipe.
|
||||
|
||||
The actual source of truth checked by Phase 3 `validate-section.mjs` is the set of `.md` files that exist under **`hyperframes-animation/rules/`** (the validator builds a set from `readdirSync` on that directory), not this catalog. This catalog is the curated subset that planners should cite. Two differences: the rules directory contains two rules missing frontmatter (`css-marker-patterns`, `gsap-effects`, listed in the "Skipped" section at the end of this file). They pass validator because files exist under rules/, but they are not in this catalog, so **do not cite them**. They still resolve as real recipes in Phase 4, so validator intentionally does not block them. Normally, choose only from this catalog.
|
||||
|
||||
## SVG & Icons
|
||||
|
||||
| Effect | Description |
|
||||
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `svg-icon-enrichment` | Animate internal SVG elements (rotating needles, opening leaves, pulsing dots, dashed-line flow), making icons feel alive without replacing them. |
|
||||
| `svg-path-draw` | Use stroke-dasharray and stroke-dashoffset to progressively draw SVG paths. |
|
||||
|
||||
## Camera & Viewport
|
||||
|
||||
| Effect | Description |
|
||||
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `camera-cursor-tracking` | Two-stage virtual camera that locks the viewport onto a moving focus point, with configurable initial position. |
|
||||
| `coordinate-target-zoom` | Zoom into an off-center element by combining scale with counter-translation, so the target ends centered in the viewport. |
|
||||
| `multi-phase-camera` | Sequential camera zoom with 2-3 distinct phases (pull back / focus / push in) plus continuous micro-drift for organic cinematic feel. |
|
||||
| `viewport-change` | Virtual camera: transform a wrapper around all scene content to simulate zoom / pan / focus lock. Camera moves right -> world translates left. |
|
||||
|
||||
## Interaction & Click
|
||||
|
||||
| Effect | Description |
|
||||
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `cursor-click-ripple` | Animate a mouse cursor moving to a target, with scale-down press feedback and an outward ripple ring on click. |
|
||||
| `physics-press-reaction` | Cursor + element press together through subtractive spring force: the cursor lands on the element, both compress, then release. Different from press-release-spring (which has no cursor). |
|
||||
| `press-release-spring` | Tactile button press: linear compression, spring-based recovery, and layered feedback (shadow compression + release burst + background glow). |
|
||||
|
||||
## Text & Typography
|
||||
|
||||
| Effect | Description |
|
||||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `3d-text-depth-layers` | Stack multiple offset text layers to create a 3D shadow / extrusion effect on large type - more impactful than CSS text-shadow because each layer is a full DOM element. |
|
||||
| `asr-keyword-glow` | Keywords glow and scale when "spoken" - attack/sustain/release envelopes sync to each word timestamp. Even without real audio, hard-coded timing creates a narrator-emphasis effect. |
|
||||
| `context-sensitive-cursor` | Cursor color and style change with the currently typed text segment - accent color on highlighted segments, dimmed on placeholders, etc. |
|
||||
| `counting-dynamic-scale` | During count animation, font size grows with the count value, giving numbers increasing visual weight. |
|
||||
| `discrete-text-sequence` | Replace whole text states at frame thresholds for nonlinear typing effects - typos, bulk add, pauses, backspace, simulated thinking. |
|
||||
| `hacker-flip-3d` | Character-level 3D rotation plus random glyph substitution for a decrypted-reveal effect. |
|
||||
| `vertical-spring-ticker` | Slot-machine-style vertical scrolling inside a masked container using additive spring physics - each spring contributes one scroll "step." |
|
||||
|
||||
## Layout & 3D
|
||||
|
||||
| Effect | Description |
|
||||
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `3d-page-scroll` | Render an entire webpage as a tilted 3D card, then scroll it to reveal a specific region. |
|
||||
| `ai-tracking-box` | Animated bounding box with L-shaped corners follows an oscillating path, simulating AI object detection / tracking. |
|
||||
| `avatar-cloud-network` | Avatars distributed on an elliptical ring, connected to a central hub with SVG dashed lines - staggered social-proof "community" reveal. |
|
||||
| `center-outward-expansion` | Elements start clustered at screen center, then expand outward to final positions driven by a shared progress value. |
|
||||
| `orbit-3d-entry` | Elements flip in from 3D space, then settle into continuous elliptical orbits around a focal point. |
|
||||
| `split-tilt-cards` | Two cards placed side by side with opposite Y-axis rotations, creating a symmetrical 3D split-screen layout for comparisons or paired features. |
|
||||
|
||||
## Transition & Motion
|
||||
|
||||
| Effect | Description |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `card-morph-anchor` | Container morphs size and border radius across shots, acting as a visual transition anchor. |
|
||||
| `dynamic-content-sequencing` | Automatically computes timeline start/end times from content length + per-item duration; longer content receives more time without hard-coded numbers. |
|
||||
| `reactive-displacement` | Physical collision: incoming element's spring drives outgoing element displacement - one source of truth creates causal motion. |
|
||||
| `scale-swap-transition` | Coordinated shrink-out + spring-in between two elements, creating a morph-like transition without SVG path interpolation. |
|
||||
| `sine-wave-loop` | Continuous breathing / idle ambient motion using trigonometry - keeps elements alive after entry. Pairs well with almost any entry rule. |
|
||||
@@ -0,0 +1,343 @@
|
||||
# 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`:
|
||||
|
||||
```markdown
|
||||
## 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:
|
||||
|
||||
```markdown
|
||||
**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:
|
||||
|
||||
```markdown
|
||||
**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)
|
||||
|
||||
```markdown
|
||||
# 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.
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: video-color-system
|
||||
description: "Color design decisions for HyperFrames videos — palette roles, 60-30-10 allocation logic, cross-scene consistency, dangerous combos. Hex values and contrast math live in build agent territory."
|
||||
category: visual-design
|
||||
---
|
||||
|
||||
# Video Color System - Design-Judgment Layer
|
||||
|
||||
**This file only covers plan-layer design judgment** - roles, 60-30-10 allocation logic, cross-scene consistency, and dangerous combinations. Concrete hex values, contrast ratio 4.5:1 math, dark-scene saturation compensation, and double-layer glow recipes belong to the build agent when writing CSS and consulting `chunks/tokens.css` plus `/hyperframes-core`; plan does not copy them.
|
||||
|
||||
## Palette Source
|
||||
|
||||
**Hex values come from `tokens.css` in `## Design chunks`** (named tokens in `:root`, varying by brand: `--brand-primary` / `--brand-accent` / `--canvas` / `--ink`, etc.; already inlined into Phase 3 dispatch). Plan references by **role**; **do not** copy concrete hex values - the build agent reads them from `chunks/tokens.css`.
|
||||
|
||||
> **Preset rules take priority over this file's generic rules.** Preset name is in `## Design chunks` `index.json.preset`; its color discipline is in `composition-hints.md` (§H surface contract / accent budget) - for example, editorial explicitly says "accent <= 5% frame area, primary is not a background fill, canvas is the hero." If a generic rule (such as "use dual-radial swell background") conflicts with the preset's §H color discipline, **the preset wins**. Plan gets preset name from `index.json.preset` and its rules from `composition-hints.md` to constrain palette use for this film (**do not read design.html**; chunks have replaced it).
|
||||
|
||||
### Pain / Serious Scenes
|
||||
|
||||
If a scene's `emotionalBeat` needs an intentional palette shift:
|
||||
|
||||
- If `chunks/tokens.css` / `composition-hints.md` **has** a `[data-theme="dark"]` block or dark surface -> use it (invert canvas / ink), without introducing an external palette.
|
||||
- If there is **no** dark theme block (common in bright presets like editorial) -> **do not invent dark colors**. Instead use: desaturated accent + lower contrast (use `--paper-warm` instead of `--canvas` to darken the scene by one step) + tighter whitespace + stillness to carry the serious mood.
|
||||
|
||||
### When `--ink` / `--canvas` Are Pure Black / Pure White
|
||||
|
||||
For some presets (editorial / Swiss / brutalist / newspaper styles), `--ink: #000` / `--canvas: #fff` is a **style choice**, not a defect - "black ink on white paper" is core to those aesthetics.
|
||||
|
||||
- **`--ink: #000`** - OK in these presets; preserve as ink.
|
||||
- **`--canvas: #fff`** - pure white blooms at video viewing distance; **prefer the preset-provided `--paper-warm`** (the editorial preset explicitly notes "fallback if canvas is pure white"). If no fallback token exists, the build agent synthesizes one step of warm white.
|
||||
- Other presets (saas / material, etc.) should follow the generic off-black/off-white rules if pure black/white appears.
|
||||
|
||||
Decision path: read preset name first -> if editorial / brutalist family, accept pure black as ink + prefer `--paper-warm` as canvas; otherwise follow generic off-black/off-white guidance.
|
||||
|
||||
## Role Mapping
|
||||
|
||||
Each token plays a role in 60-30-10:
|
||||
|
||||
| Role | Typical token names (brand-dependent) | Visual weight |
|
||||
| ------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| **Neutral background (canvas)** | `--canvas` / `--paper` / lightest neutral | **60%** - dominant, does not compete with content |
|
||||
| **Neutral surface** | `--paper-2` / `--surface` / second-lightest neutral; **if absent, layer with hairline rule instead** | **~20%** - panels, cards, boundaries |
|
||||
| **Foreground text (ink)** | `--ink` / `--ink-soft` / off-black or off-white | **~10%** |
|
||||
| **Primary accent** | `--brand-primary` / `--brand-accent` | **~10%** - **only on the current focal element** |
|
||||
| **Secondary accent** | `--brand-secondary` (if present) | **~5%** - bound to a different semantic role |
|
||||
| **Restrained third color** | neutral or paper tone | **<2%** - occasional |
|
||||
| **Semantic colors** | success/error/warning derived from brand hue | use sparingly |
|
||||
|
||||
> **When `chunks/tokens.css` lacks a `--surface` tier** - this preset layers with hairline rules rather than a surface color - plan should explicitly say "30% uses hairline + repeated canvas," instead of inventing a fake middle color.
|
||||
|
||||
## 60-30-10 Is **Visual Weight**, Not Pixel Count
|
||||
|
||||
- 60% canvas - dominant, not attention-grabbing
|
||||
- 30% surface + text - panels, borders, supporting copy
|
||||
- 10% accent - used only on the **current focal element**
|
||||
|
||||
**Top mistake:** applying brand color everywhere because it is "the brand identifier." Accent works because it is **rare**. In the strongest archive example (codex-plugin), each accent is bound to a **semantic role**: cyan = HyperFrames moment, lime = render, amber = Codex - three accents, each appearing only in its own beat, never overlapping.
|
||||
|
||||
Even more restrained: vercel-intro uses one brand red + one RGB aberration moment, then immediately returns to clean black-ground white text. **One color, one effect, maximal restraint.**
|
||||
|
||||
## Tinted Neutrals
|
||||
|
||||
Pure gray has no personality. Neutrals should shift subtly toward the brand hue:
|
||||
|
||||
- warm brands (red / orange / yellow) -> gray with a subtle warm cast
|
||||
- cool brands (blue / purple / green / cyan) -> gray with a subtle cool cast
|
||||
|
||||
The cast should be nearly invisible, but it creates subconscious cohesion. This is usually already encoded in `chunks/tokens.css` `--canvas` / `--paper-2` tokens; plan only references roles and does not calculate OKLCH.
|
||||
|
||||
## Four-Layer Palette Structure
|
||||
|
||||
A complete video palette has four layers (skip layers you do not need; **do not** add extras):
|
||||
|
||||
1. **Primary accent** - 1-2 colors, semantically bound, 10-15% weight
|
||||
2. **Neutral ladder** - canvas -> surface -> surface-raised, three tiers (light or dark), 60% + 20%
|
||||
3. **Foreground** - 1-2 off-white or off-ink text colors, 10%
|
||||
4. **Semantic colors** - success / error / warning, derived from brand hue
|
||||
|
||||
**Per-beat palette isolation is also valid** (fadeglow-v4 uses completely different color moods in Beat 2 / 4 / 7) - emotional arc decides; consistency is not mandatory.
|
||||
|
||||
## Cross-Scene Consistency
|
||||
|
||||
Every scene in a video should feel like it belongs to the same visual system (unless explicitly doing "one universe per scene").
|
||||
|
||||
- Background palette is defined once at project level (`:root` / shared `<style>`); do not hard-code hex per scene.
|
||||
- Scenes may vary in **lightness** (dark -> bright rhythm), while sharing the same **hue family**.
|
||||
- Accent purpose must stay consistent: if cyan is the HyperFrames moment color in scene 1, it cannot become a background gradient in scene 5.
|
||||
- Data visualization colors derive from the brand palette; do not pick arbitrary colors.
|
||||
|
||||
**Variation within limits is OK:** dark/light alternation for rhythm, desaturated (calm) <-> saturated (emphasis), gradients between neighboring brand hues.
|
||||
|
||||
## Never Pure Black / Pure White
|
||||
|
||||
Pure `#000` / `#fff` does not exist in nature - contrast is harsh, feels synthetic, and compression destroys detail. Always use off-black / off-white tokens from `chunks/tokens.css` (typical names `--ink` / `--canvas`).
|
||||
|
||||
Exception: pure white `text-shadow` / `drop-shadow` halos at emphasis moments (click-ripple peak) are OK - build agent uses low-opacity overlays, not direct text color.
|
||||
|
||||
## Dangerous Combinations (Forbidden Patterns)
|
||||
|
||||
- **Light gray text on white** - contrast collapses, small screens fail.
|
||||
- **Gray on colored background** - reads faded / dirty; use a darker tone of the background hue instead.
|
||||
- **Thin light text on image** - unreliable even with shadow; add overlay + weight, or both.
|
||||
- **Pure saturated neon on `#000`** - default AI nesting-doll look. Use off-black + accent glow reduced to 0.20-0.35 opacity (build work; plan only needs to say "avoid neon").
|
||||
- **Purple-to-blue AI gradient** - codex-plugin / hermes explicitly banned this ("no generic purple-blue AI gradients"). Use brand-hued radial swell for depth instead.
|
||||
|
||||
## Background: Keep the Pin-and-Paper Native Paper Texture
|
||||
|
||||
**FE ships pin-and-paper (paper-grain family): keep the preset's native paper-texture background, consistent across the film; the brand-color mesh default does NOT apply.** The grain _is_ the atmosphere - a mesh / Gaussian-blur blob layer fights the paper aesthetic and is forbidden here. (Historical note: an earlier multi-preset lineage used a brand-color mesh as the project background default; that lineage explicitly listed paper-grain presets like pin-and-paper under "do not use mesh," so for FE it is simply inapplicable.)
|
||||
|
||||
- **Every scene background = the pin-and-paper paper base** (warm paper texture + optional sparse paper-grain/fiber noise), as declared by the preset §H surface contract.
|
||||
- **Single background medium** - do not stack mesh, dual-radial swell, scanline, halftone, or architectural grid on top of the paper. Only the preset's own paper-grain/fiber layer belongs there.
|
||||
- **Cross-film consistency is a hard rule** - background is determined by the preset system, not improvised per scene. The paper base is the same warm paper in scene 1 and the closing scene; there is no per-scene surface drift. For climax / brand-reveal impact, use **foreground techniques** (hero-word weight + scale, accent saturation release on the focal element), not a ground swap. **Deprecated:** ~~serious/pain beat -> off-black ground~~; darken by one step with `--paper-warm` instead.
|
||||
|
||||
## Plan Reference Examples
|
||||
|
||||
**Plan Reference Example (pin-and-paper native paper base):**
|
||||
|
||||
> "Background: native pin-and-paper paper base (warm paper texture, sparse grain) - consistent across the film. Palette 60-30-10: 60% warm paper (canvas) + 30% hairline + chapter-label rule layering (no surface token; layer with hairline if no `--surface` tier) + 10% accent on the hero word and CTA underline. `--ink` is pure #000 as print-like ink; if any surface goes pure white, prefer `--paper-warm`."
|
||||
|
||||
Do not write concrete hex / opacity / saturation percentages - those are build work.
|
||||
@@ -0,0 +1,210 @@
|
||||
---
|
||||
name: video-composition
|
||||
description: "Composition design decisions for HyperFrames videos (1920x1080 landscape by default; also 1080x1920 portrait / 1080x1080 square) — canvas zones, 7 layout templates, density rules, hierarchy logic, depth principles. Specific px / scale / shadow values live in build agent territory."
|
||||
category: visual-design
|
||||
---
|
||||
|
||||
# Composition for Video - Design-Judgment Layer
|
||||
|
||||
Video composition is closer to film and poster design than webpage layout. There is no scrolling and no responsive reflow. Every frame is a fixed canvas; every pixel matters. The default canvas is **1920×1080 (16:9 landscape)**; for **portrait (1080×1920)** and **square (1080×1080)** see "Portrait & Square" below — the principles are identical, the aspect ratio is not.
|
||||
|
||||
**Most of this file is plan-layer design judgment** - conceptual canvas zones, 7 composition templates, density rules, hierarchy logic, and depth-layering principles. Concrete px (safe margins 96-150), scale values (1.05 / 0.92), three-layer `box-shadow` recipes, `perspective` 800-1400px, etc. belong to the build agent; plan does not write code.
|
||||
|
||||
Composition is one of the highest-value parts of the plan - which layout to choose, how much frame the primary element occupies, and how many depth layers to use **are director decisions**.
|
||||
|
||||
## Squint Test
|
||||
|
||||
Squint your eyes (or blur the screenshot). Can you still identify:
|
||||
|
||||
- the most important element?
|
||||
- the second most important element?
|
||||
- clear spatial groups?
|
||||
|
||||
If everything has equal weight after blur, hierarchy is broken - redesign before writing the plan. The strongest archive beats all pass this test: one dominant block + one supporting structural element, with everything else demoted.
|
||||
|
||||
## Canvas Zones (conceptual)
|
||||
|
||||
The canvas (shown here as 1920×1080 landscape) has four zones:
|
||||
|
||||
```
|
||||
+--------------------------------------------------+
|
||||
| Optional top chrome |
|
||||
| +----------------------------------------------+ |
|
||||
| | Safe margin | |
|
||||
| | +----------------------------------------+ | |
|
||||
| | | | | |
|
||||
| | | Primary content area | | |
|
||||
| | | (center 65-75% of frame) | | |
|
||||
| | | | | |
|
||||
| | +----------------------------------------+ | |
|
||||
| | | Caption band (bottom ~17%, HARD when captions) | | |
|
||||
| | +----------------------------------------+ | |
|
||||
| +----------------------------------------------+ |
|
||||
+--------------------------------------------------+
|
||||
```
|
||||
|
||||
- **Top chrome** - only for workspace mockup scenes; otherwise skip.
|
||||
- **Safe margin** - key content stays away from edges; hero / editorial scenes need more air.
|
||||
- **Primary content area** - the center 65-75% of the frame is where the eye naturally rests; body text blocks should **never** press against the edge.
|
||||
- **Caption band (bottom ~17%, HARD reserved when captions are enabled)** - when this film has captions enabled (`group_spec.captions_enabled`), the bottom ~17% of **canvas height** is a **HARD reserved zone** (landscape 1080h -> bottom 180px, y 900-1080; portrait 1920h -> bottom 320px, y 1600-1920): primary content area and all key visuals **must cap at the caption-band top y**, and vertical centering should anchor at **y ≈ 0.42 × height** (landscape ≈454, portrait ≈806), not the canvas midpoint. BACKGROUND / ambient / surface decoration layers are exempt and may remain full-bleed. When captions are disabled, this zone can be used normally. Plan example: "captions enabled - hero block centered in upper ~83%, stat card bottom edge sits at y≈880 just above the caption band; background mesh stays full-bleed."
|
||||
|
||||
Plan writes "hero word centered with generous safe margins"; it does not write `padding: 150px 120px 92px`.
|
||||
|
||||
## Portrait & Square (non-16:9 canvases)
|
||||
|
||||
The canvas is **1920×1080 (16:9 landscape) by default**, but the dispatch `Canvas:` line may be **1080×1920 (9:16 portrait — reels / shorts / TikTok)** or **1080×1080 (1:1 square — feed)**. The zones, density rules, hierarchy logic, and depth principles above all still apply; what changes is the **aspect ratio**, and a layout designed for a wide frame does not transplant into a tall one. Read the dispatched `Canvas:` and design for that shape from the start — do not plan landscape and "crop".
|
||||
|
||||
- **Stack vertically, not side-by-side.** Portrait has little horizontal room: split-screen / triptych / asymmetric 60-40 become **top/bottom stacks**, vertical step lists, and stacked bands. A wide marquee strip becomes a centered stack. Square tolerates side-by-side only for two compact items.
|
||||
- **Vertical center moves with the canvas.** Anchor a centered hero around **y ≈ 0.42 × canvas height** (portrait ≈ 806, square ≈ 454), not a fixed 540. The caption band is still the bottom ~17% of **height** (portrait → y1600–1920; square → y900–1080) and is HARD-reserved when captions are enabled.
|
||||
- **Type runs larger, fewer words per line.** A narrow frame wraps long headlines badly — prefer short kinetic lines, bigger type, and more vertical rhythm. Treat the tall axis as the primary reading flow.
|
||||
- **Templates that travel well to portrait:** Centered (hero/climax), Layered Depth, Full-Width Strip (now a stacked band), vertical Rule-of-Thirds. **Avoid** wide Split Screen and Triptych in portrait; reach for stacked equivalents.
|
||||
- **Density still rules.** Primary visual ≥ 40% of canvas, ≥ 3 depth layers — but measured against the tall frame; an empty top or bottom third reads as placeholder just like dead center does on landscape.
|
||||
|
||||
## 7 Composition Templates
|
||||
|
||||
Use at least 3 different templates in a single video (5 scenes -> 3+ templates, 9 scenes -> 4+ templates). **Do not default every scene to centered.** The strongest archive plans never use the same layout class twice in a row.
|
||||
|
||||
### 1. Centered (hero / climax)
|
||||
|
||||
One dominant element centered with generous breathing room. Use for: brand reveal, key metric, CTA, climax beat.
|
||||
|
||||
### 2. Rule of Thirds
|
||||
|
||||
Visual anchor placed on thirds intersections. Remaining space carries supporting elements or negative space. Use for: concept showcase, diagram with annotation.
|
||||
|
||||
### 3. Split Screen (comparison / dual focus)
|
||||
|
||||
Left and right halves carry separate elements. Use for: before/after, feature comparison, problem/solution, palette-switch moments.
|
||||
|
||||
### 4. Layered Depth (immersive)
|
||||
|
||||
Foreground / midground / background use different scale + opacity to create depth. Use for: opening hooks, atmosphere-heavy scenes, workbench beats.
|
||||
|
||||
### 5. Asymmetric (editorial)
|
||||
|
||||
Primary content is pushed to one side (60/40 or 70/30). Intentional imbalance -> visual tension + sophistication. Use for: feature focus, dense text information, editorial proof beats.
|
||||
|
||||
### 6. Triptych (three-panel)
|
||||
|
||||
Three equal-width zones, often used to show three capabilities / three feature beats simultaneously.
|
||||
|
||||
### 7. Full-Width Strip
|
||||
|
||||
One horizontal band (ticker, logo chain, marquee). Usually only 20% of canvas height.
|
||||
|
||||
## Frame Density - Avoid Empty Frames
|
||||
|
||||
Common failure: small elements floating in the center of 1920x1080 with empty space around them. Every scene must feel **intentionally filled**, not sparse.
|
||||
|
||||
**Density rules:**
|
||||
|
||||
- **Primary visual element occupies at least 40% of the canvas** - in faceless mode the primary visual is typography / an invented graphic / a diagram / a data-viz, not a screenshot. Hero / kinetic-type block 50-75% height × 60-80% width; centered diagram or chart 30-60% width × 50-70% height.
|
||||
- **Every scene has at least 3 visual layers** - background (gradient / particles / grid), midground (main content), foreground (emphasis / decoration).
|
||||
- **Opening and closing** are especially prone to emptiness - black background + lonely line of text feels placeholder-like. Add environmental layers: dual-radial swell, floating particles, brand-color ambient texture, low-opacity scanlines.
|
||||
- **Text/graphics scenes are full, not empty** - a well-composed scene built from kinetic type + shapes + gradients + icon fields + brand-derived geometry, or from a diagram / chart / data-viz, **fills the frame on its own**. Faceless invented visuals are the medium, so a typographic or graphic scene is intentionally filled, not a placeholder; emptiness comes from one floating line over dead space, not from the absence of a screenshot.
|
||||
|
||||
**Fullness test:** could this frame work as a poster or social graphic? If it looks like a sparse PPT slide -> add visual layers.
|
||||
|
||||
**Poster-pause test:** if you freeze the video at any moment, can the frame stand as an independent graphic design?
|
||||
|
||||
## Negative Space as Design Tool
|
||||
|
||||
Whitespace is not waste; it directs attention.
|
||||
|
||||
- **Tight grouping** (icon + label, image + caption) - small spacing.
|
||||
- **Generous separation** (unrelated groups) - large spacing.
|
||||
- **Asymmetric outer margins** feel more designed than equal padding everywhere.
|
||||
- **Hero words often keep large side whitespace** - it lets one word carry the weight of "this is everything."
|
||||
|
||||
### Spacing Failure Modes
|
||||
|
||||
- Every element is equidistant from every other element -> no grouping, no hierarchy.
|
||||
- Elements unintentionally touch or overlap.
|
||||
- Text sits tight against container edge.
|
||||
- Captions collide with bottom visuals.
|
||||
- The same padding appears everywhere because it was the framework default.
|
||||
|
||||
## In-Frame Visual Hierarchy
|
||||
|
||||
Visual weight order (strong -> weak):
|
||||
|
||||
1. **Large primary visual** (kinetic-type block, diagram, chart, hero graphic)
|
||||
2. **Motion** (moving beats static)
|
||||
3. **High contrast** (bright text on dark ground, saturated color on neutral ground)
|
||||
4. **Type scale** (display > heading > body)
|
||||
5. **Position** (center and upper third are golden zones)
|
||||
|
||||
Combine **at least two** to build clear hierarchy. An element that is large, moving, and in the upper third is unquestionably the primary focus.
|
||||
|
||||
### Layer Hierarchy Across Dimensions
|
||||
|
||||
A title that is only larger, while sharing weight/color/spacing with body text, creates weak hierarchy. Stack dimensions:
|
||||
|
||||
| Dimension | Strong contrast |
|
||||
| --------- | ----------------------------------------------------------- |
|
||||
| Size | 3:1 ratio or larger |
|
||||
| Weight | 800-900 vs 400 |
|
||||
| Color | high contrast against background |
|
||||
| Motion | one element moving vs all else static |
|
||||
| Position | top / left = primary |
|
||||
| Space | large surrounding whitespace vs equidistant from everything |
|
||||
|
||||
## Cards and Grouping
|
||||
|
||||
Spacing + alignment can create natural grouping - **card containers are not required**.
|
||||
|
||||
**Use cards when:**
|
||||
|
||||
- content is genuinely distinct from surroundings
|
||||
- in a UI demo scene, the group is independently actionable (command-panel row, feature card)
|
||||
- you need shadow stacking to communicate "lifted above the canvas"
|
||||
|
||||
**Do not use cards when:**
|
||||
|
||||
- you only want visual separation -> use whitespace instead
|
||||
- content belongs to a continuous list or flow
|
||||
|
||||
**Never nest cards inside cards** - visually claustrophobic + hierarchy becomes muddy. Wanting nested cards usually means the outer card is unnecessary.
|
||||
|
||||
Plan writes "comparison-split: left/right dual cards, three-layer shadow stack"; it does not write `box-shadow: 0 30px 60px rgba(0,0,0,0.45)...` - that is build work.
|
||||
|
||||
## Primary Visual Prominence
|
||||
|
||||
Faceless explainers have no captured assets (`assetCandidates` is usually `[]`). The LLM-invented primary visual - kinetic typography, abstract / brand-derived graphics, a diagram, or a data-viz - **is** the highest-value visual material. It carries the scene; treat it the way a screenshot-based film would treat a hero screenshot.
|
||||
|
||||
- **Feature the primary visual prominently**, not as tiny decoration around empty space.
|
||||
- When a diagram, chart, or kinetic-type block is the focus, it should **fill at least 40-60% of the frame**.
|
||||
- The primary visual must be **load-bearing, not purely decorative** - it should encode the scene's idea (the steps of a process, the shape of a number, the thesis of a quote), not just be a generic color block, abstract blob, or floating bokeh dropped in to fill space.
|
||||
- Pick the register that best explains the script (see guide.md "Faceless visual register") and commit to it; a half-hearted graphic competing with a half-hearted text block reads as filler.
|
||||
|
||||
## Creating Depth on a 2D Canvas
|
||||
|
||||
Every scene should layer **at least 2-3 depth techniques** to avoid flat poster feel. Concrete values (perspective px, rotate degrees, scale values) are build work:
|
||||
|
||||
| Technique | Effect |
|
||||
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Size difference** | larger = nearer, smaller = farther |
|
||||
| **Blur** | blurred = background, sharp = foreground |
|
||||
| **Opacity gradient** | low = receding, full = primary |
|
||||
| **Overlap** | foreground partially covers background |
|
||||
| **Shadow stacking** | three-layer shadow = lift + brand feel |
|
||||
| **Motion speed** | faster parallax = closer |
|
||||
| **Counter-scale trick** | camera pushes toward focus -> background appears larger, focal element CSS scale <1 but fills frame after composition (archive signature) |
|
||||
|
||||
Plan writes "3 depth layers: background layer + midground main content + foreground emphasis; background counter-scales to make the camera push feel closer"; it does not write `scale: 1.05 / 1.0 / 0.92` - that is build work.
|
||||
|
||||
## What Should Not Appear in Promo Videos
|
||||
|
||||
- nav bars, footers, cookie banners (interactive webpage elements with no use in video)
|
||||
- scrollbars, cursor arrows, browser chrome - unless the scene is **intentionally** a workspace mockup
|
||||
- unclickable buttons
|
||||
- generic decorative shapes (color blocks, spheres, ribbons) replacing real product assets
|
||||
- floating bokeh / purple-to-blue AI gradients - "default AI cliché look", explicitly banned in multiple brand briefs
|
||||
|
||||
**Rare exception:** intentional interface reconstruction, only when the script literally asks you to depict an interface (e.g. "the dashboard shows…"). This is not a first-class FE convention - faceless explainers invent their visuals, so reach for it sparingly. When the script does call for it, nav bars, command panels, timeline tracks, and buttons provide real context that makes the reconstruction read as a deliberate interface rather than a stray webpage element.
|
||||
|
||||
## Plan Reference Example
|
||||
|
||||
> "Composition: asymmetric 60/40 - a self-drawing process diagram occupies left 60%, a kinetic-type caption + animated counter occupy right 40%. Generous safe margin; text block capped inside primary content area. 3 depth layers: background swell + midground process diagram + foreground glow on the active node. Density: primary visual ~55% of canvas, ambient layer adds 5% scanline + architectural grid."
|
||||
|
||||
Do not write concrete px / scale values / shadow recipes.
|
||||
@@ -0,0 +1,183 @@
|
||||
---
|
||||
name: video-motion-language
|
||||
description: "Motion design decisions for HyperFrames videos — spring intents, beat structure, hold times, stillness-before-climax, transition vocabulary. GSAP eases, exact ms/frames, ease curves, and JS code live in build agent territory (/hyperframes-animation)."
|
||||
category: visual-design
|
||||
---
|
||||
|
||||
# Video Motion Language - Design-Judgment Layer
|
||||
|
||||
A good promo video feels like one continuous whole, not a pile of unrelated animated slides. That requires a consistent motion language: the same ease intent, the same rhythmic timing, and the same spring feel.
|
||||
|
||||
**This file only covers plan-layer design judgment** - spring intent, beat structure, holds, silent beats, and transition vocabulary. Concrete GSAP ease names (`back.out(1.4)`), ms/frame mapping, stagger formulas, exact cut-the-curve JS, and multiplicative breathing formulas are build-agent territory when writing timelines and consulting `/hyperframes-animation` plus `chunks/easings.js`; plan does not write code.
|
||||
|
||||
> **`EASE` / `DUR` JS constants come from `chunks/easings.js`** (already inlined into Phase 3 dispatch `## Design chunks`; do not read design.html). Plan references by **intent role** (`EASE.entry` / `EASE.emphasis` / `EASE.exit`, `DUR.fast` / `DUR.med` / `DUR.slow`, though actual keys may vary by preset - e.g. editorial uses `DUR.snap` instead of `DUR.fast`). Plan writes "use entry spring" or "reference `EASE.entry`"; build agent maps it to the concrete curve.
|
||||
|
||||
## Spring Intent (by role, not curve)
|
||||
|
||||
HyperFrames uses GSAP. The table below is the **intent** vocabulary for plans; the build agent uses `/hyperframes-animation` to translate intent into concrete GSAP ease + duration:
|
||||
|
||||
| Intent | Feel | Use case |
|
||||
| ---------- | ------------------------------------------- | ----------------------------------------------- |
|
||||
| **entry** | confident slight overshoot, settles quickly | primary element entry (default) |
|
||||
| **gentle** | soft slide-in, no overshoot | background elements, subtle motion |
|
||||
| **snappy** | tight overshoot, nearly instant | UI elements, small icons, buttons |
|
||||
| **heavy** | weighted deceleration | large type blocks, diagram panels, hero visuals |
|
||||
| **slam** | bouncy overshoot, intentionally loud | logo / bell / impact moments |
|
||||
|
||||
**Consistency rule:** similar elements share the same intent. In one scene, all icons are `snappy`, all hero images are `heavy`. **Do not** invent a unique ease + duration for every element.
|
||||
|
||||
## Forbidden
|
||||
|
||||
- **`bounce.out` / `elastic.out`** - feels dated and pulls attention away from content. Real objects decelerate smoothly; they do not bounce. Low overshoot for `entry` intent (archive typical back.out 1.4-1.7) is OK; higher overshoot is reserved for clearly playful moments.
|
||||
- **Unique ease + duration per element** - visual noise.
|
||||
|
||||
## Duration Intent (100 / 300 / 500 / 800 concepts)
|
||||
|
||||
Plan references by **intent tier** ("instant feedback", "state change", "layout change", "entry animation"); the build agent maps concrete ms / frames at 30fps using `/hyperframes-animation`.
|
||||
|
||||
- **Instant feedback** - micro-interaction, state flash
|
||||
- **State change** - element entry, icon swap
|
||||
- **Layout change** - scene entry, major transition
|
||||
- **Entry animation** - hero reveal, opening sequence
|
||||
|
||||
**A single entry should not exceed ~800ms.** If you need a longer buildup, use multi-element stagger instead of lengthening one element.
|
||||
|
||||
## Exit = 75% of Entry
|
||||
|
||||
Exit animation is about 75% of entry duration (not 50%, not 100%). Arrival is deliberate; departure is swift but not abrupt.
|
||||
|
||||
- Exit too fast -> flash
|
||||
- Exit = entry -> sluggish, blocks the next scene
|
||||
|
||||
This is a rule the plan can name in prose; the build agent computes concrete frames.
|
||||
|
||||
> Cut-the-curve deliberately reverses the ratio (entry ~127% of exit length) - entry takes longer to clear blur. This is the signature transition exception; plan only needs to cite the transition name.
|
||||
|
||||
## Stagger Total Cap
|
||||
|
||||
When staggering N elements, **total stagger duration <= 500ms** (much longer feels dragged out). Concrete formula (`(N-1) × per-item delay`) and the strategy "stagger the first 6-8, enter the rest with the last item" are build work; plan only needs to know:
|
||||
|
||||
- **3-7 elements** - normal stagger, total 300-700ms
|
||||
- **8+ elements** - tighten per-item delay, or stagger only the first few
|
||||
- **Never let stagger continue past 500ms**
|
||||
|
||||
## Beat Structure (core plan tool)
|
||||
|
||||
Rhythmic videos have beats: tension -> release -> tension -> release. The cleanest archive reference is playground-launch's 46-second plan:
|
||||
|
||||
| Phase | Duration | Rhythm | Scene type |
|
||||
| ------------------ | -------- | -------------------- | ---------------------------------- |
|
||||
| **Slow setup** | 6-10s | slow build | hero establish, VO not yet present |
|
||||
| **Fast montage** | 6-10s | ~2s each | cut-the-curve every 1.5-2s |
|
||||
| **Process reveal** | 12-18s | continuous no cut | screen recording, real workflow |
|
||||
| **Closure** | 3-5s | still and breathable | logo, URL, CTA |
|
||||
|
||||
**Allocate motion by energy inside each scene:**
|
||||
|
||||
- **High-energy scenes** (hook, CTA) - faster entry, tighter stagger, `snappy` spring
|
||||
- **Breathable scenes** (brand reveal, emotional beat) - slower entry, `gentle` spring, longer hold
|
||||
- **Data scenes** (statistic, feature) - medium rhythm, clean stagger, count-up
|
||||
|
||||
## Hold Time
|
||||
|
||||
After an element enters, it must hold long enough to be read. Plan references minimum hold by **content type** (build maps concrete frames):
|
||||
|
||||
| Content | Minimum hold intent |
|
||||
| ------------------------------------ | ------------------- |
|
||||
| display text (1-3 words) | ~1s |
|
||||
| short sentence | ~1.5s |
|
||||
| data / statistic | ~1.5s |
|
||||
| hero graphic / chart | ~2s |
|
||||
| complex visual (diagram, comparison) | ~2.5s |
|
||||
| hero / climax word | ~1-1.4s |
|
||||
|
||||
Narration duration shorter than needed hold -> extend the scene to fill time.
|
||||
|
||||
## "Stillness Before Climax" Beat
|
||||
|
||||
Archive signature: leave a **0.3-0.75s pause** between the major action and confirmation/result. This silence creates narrative tension before the landing. **Allocate it to 2-3 scenes per film (named in `## Film Direction`), where the narration lands a payoff** - stamped on every scene it stops being a comma and becomes a tic, and the film's rhythm flattens.
|
||||
|
||||
- Icons collapse at 2.2s, but demo does not pop out until 2.95s (0.75s gap)
|
||||
- Step 3 activates at 3.33s, button enters at 3.52s (0.19s buffer)
|
||||
- "Hold on a final frustrated beat: cursor still, chat full, SFX slightly off-rhythm"
|
||||
|
||||
**Plan must explicitly schedule this beat in the allocated scenes** - name `stillness-before-climax` in that scene's choreography prose. An allocated scene that jumps directly from action to result loses the dramatic comma; a non-allocated scene that adds one anyway dilutes it.
|
||||
|
||||
## Motion Budget - One Macro Move, Few Live Elements
|
||||
|
||||
A real camera gives footage **globally correlated motion**: the lens drifts and every layer moves together, differentiated only by depth. Viewers read correlated motion as _someone is filming this_; they read many small independent motions as _UI animation / screensaver_. So the unit of "aliveness" is the **scene**, not the element. Per scene the plan budgets:
|
||||
|
||||
1. **ONE macro motion (required)** - a camera-style move on the scene root: slow drift, dolly in/out, push, parallax pan. This alone keeps every visible element moving, coherently, for the whole beat.
|
||||
2. **At most 1-2 secondary live elements** - chosen from the menu below, on the elements that carry the beat (the hero word, the live chart, the CTA). **Subtle by default** - over-amplitude ambient motion is the more common failure: visible drift in every scene reads as "the whole video is shimmering," especially across 5+ consecutive scenes or any single scene whose idle phase runs > 6s.
|
||||
3. **Everything else rests.** Stillness is a tool, not a failure: composition.md lists "one element moving vs all else static" as a strong hierarchy contrast - if everything moves, motion stops carrying information. Prefer the macro move + depth parallax over multiple independent floats; do not give every icon its own oscillator.
|
||||
|
||||
Secondary-slot menu (concrete formulas and code are build work):
|
||||
|
||||
| Pattern | Use case |
|
||||
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| **Settle and hold** | closing beats, post-climax tails, the final 25-40% of any scene > 12s (default when nothing else applies) |
|
||||
| **Slow drift** | a single isolated hero element |
|
||||
| **Sine float** | one decorative cluster at most (counter-phase to avoid sync; not three+ concurrent) |
|
||||
| **Multiplicative breathing** | the single focal hero (±1-2% scale on final transform, **not yoyo**) |
|
||||
| **Rotational drift** | 3D cards / hero logo (≤ ±0.5°) |
|
||||
| **Orbit** | surrounding icons (counts as the scene's one decorative cluster) |
|
||||
| **Glow pulse** | CTA / click target |
|
||||
| **Halftone breathing** | atmospheric / background scenes (density deforms with beat) |
|
||||
|
||||
**Default amplitude (the subtle floor — declare it once in `## Film Direction`; per-scene prose names only deviations):**
|
||||
|
||||
- Y translation: **±2-3 px**
|
||||
- Scale breath: **±1-2%**
|
||||
- Rotation: **±0.3-0.8°** (rarely needed)
|
||||
- Cycle period: **2.5-4s per breath** (slower = calmer; under 2s reads as fidgeting)
|
||||
|
||||
**Reach for the higher end** (±4-6 px / ±3-5% / ±1-3°) **only when:**
|
||||
|
||||
1. The element is **alone on canvas** (single hero, no competing motion).
|
||||
2. The scene is **short** (< 6s, finishes before idle fully settles in).
|
||||
3. The brief explicitly asks for "kinetic" / "playful" / "energetic" register.
|
||||
|
||||
**Scaling rules (hard):**
|
||||
|
||||
- **Idle phase > 30% of scene duration → halve every amplitude.** A 17-second scene with 6.5s of `sine-wave-loop` idle ≠ a 6-second scene with 1.5s of idle. Long idle at default amplitude = the eye exhausts and the viewer reads "the whole composition is fidgeting."
|
||||
- **N ≥ 2 concurrent drifting elements → per-element amplitude ≤ default / √N.** Three columns each at ±6px = effectively ±18px of competing motion. Three at ±2-3px reads as one collective breath.
|
||||
- **Across the film: ≤ 2 consecutive scenes carry sustained drift.** The third should `settle and hold` for ≥ 60% of its duration so drift reads as deliberate, not pervasive.
|
||||
|
||||
**Multiplicative breathing** stays the signature treatment for a hero **that holds a live slot** — not a default stamped on every hero in every scene. **Forbid** yoyo tweens (they overwrite entry scale). Concrete formula (`scale = final * (1 + Math.sin(t * freq) * amp)`, `onUpdate` reads `tl.time()`) is build work — the `/hyperframes-animation` `sine-wave-loop` rule has a ready-to-paste "settle and fade" envelope for long idle. The budget caps how many things move; it does not license invisible motion.
|
||||
|
||||
**Anti-pattern: "fill the idle with drift."** When a scene runs much longer than the narrator estimated (audio drift > 50% — `prep.mjs` warns on these), the temptation is to stretch ambient motion across the entire tail. Don't. Add **one more active beat** (a glow re-pulse, a number tick, a chip reveal) at the 60-70% mark to give the eye somewhere new to land, then `settle and hold` until the transition.
|
||||
|
||||
## Transition Vocabulary - Use Only 2-3 Across the Film
|
||||
|
||||
Inter-scene transitions follow a limited vocabulary. Choose only 2-3 and repeat them - repetition creates professional cohesion. Cleanest archive reference: playground-launch uses **only cut-the-curve** across 8 distinct visual universes, which is what makes the film cohere.
|
||||
|
||||
> These 2-3 slots are Tier-B transitions on `break` boundaries only; `morph` (Tier-A, worker-authored) does not count toward the limit and may be used freely.
|
||||
|
||||
### Cut-the-curve (archive signature; default for most cases)
|
||||
|
||||
Current scene blurs + slides out -> next scene blurs + slides in. Both sides use the same blur magnitude; direction alternates across seams (right -> left -> up -> down); background triggers slightly before foreground content; internal reveals occur after the stage settles. Plan only names direction ("cut-the-curve LEFT"); concrete 0.33s / 0.42s / 8-10px blur is build work.
|
||||
|
||||
### Scale + fade (zoom-through)
|
||||
|
||||
One scene fades while pulling toward frame center; camera pushes forward into the next headline.
|
||||
|
||||
### Slide
|
||||
|
||||
Directional slide (matches narrative flow), optionally with parallax.
|
||||
|
||||
### Morph (strongest narrative seam)
|
||||
|
||||
Shared element transforms between scenes (phone cluster -> circular avatar = scale + borderRadius tween).
|
||||
|
||||
### Hard cut
|
||||
|
||||
Instant opacity flip, used for high-energy moments (grid appears fully filled with no build-in). **Use sparingly** - cut-the-curve is default; hard cuts are reserved for type/tone shifts.
|
||||
|
||||
**Plan must name a transition for every scene** - it determines Continuity for the next scene (see guide.md "Hard Contracts"):
|
||||
|
||||
- `hard cut` / `jump cut` -> Continuity `break`
|
||||
- `cut-the-curve` / `morph` / `scale+fade` on the same material -> Continuity `continue`
|
||||
|
||||
## Plan Reference Example
|
||||
|
||||
> "Macro motion: slow dolly-in on the scene root across the whole beat. Multi-phase: hero enters on `EASE.entry` (heavy intent) -> icons enter with snappy stagger (5 items, total stagger ~400ms), then rest -> **stillness-before-climax 0.6s** (allocated scene; only the dolly continues) -> result emphasis: text gentle entry + double-layer glow -> idle hold, hero breathing ±1% as the one live element."
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: video-typography
|
||||
description: "Typography design decisions for HyperFrames videos — roles, hierarchy intent, pairing logic. Implementation values (px, letter-spacing em, CJK fallback chains, OpenType CSS) live in build agent territory."
|
||||
category: visual-design
|
||||
---
|
||||
|
||||
# Video Typography - Design-Judgment Layer
|
||||
|
||||
Video typography ≠ web typography: no scrolling, no reflow. Every text element must read at a glance in a 1-5s window and do emotional work — text is usually the emotional anchor, not decoration.
|
||||
|
||||
**Plan-layer judgment only** — roles, hierarchy intent, pairing logic, negative constraints. Concrete values (px, letter-spacing em, CJK fallback, `tabular-nums`) are build-agent territory (`/hyperframes-core` + `chunks/tokens.css`); plan does not copy them.
|
||||
|
||||
## Font Source
|
||||
|
||||
**Font families come from `chunks/tokens.css`** (`--font-display` / `--font-body` / `--font-mono`, already inlined into Phase 3 dispatch `## Design chunks`). Name fonts by **use** ("display for hero headline", "mono for eyebrow / metadata"); do not invent or copy concrete font names — the build agent reads them from `chunks/tokens.css` (not design.html).
|
||||
|
||||
A **second font** used for contrast (serif italic emphasis, mono labels) must be named as a design decision. Homogeneous pairing (two geometric sans faces) is not allowed — tension without hierarchy benefit.
|
||||
|
||||
## Type Scale (by role, not px)
|
||||
|
||||
Video type is much larger than web type. Plan references by **role**; build agent picks px from these ranges:
|
||||
|
||||
| Role | Use | Relative feel |
|
||||
| ------------------ | ------------------------------------- | ------------------------------------------- |
|
||||
| **Mega / climax** | single-word hero, counter peak | 50%+ of canvas height |
|
||||
| **Hero / display** | main headline, scene core word | 25-40% of canvas height |
|
||||
| **Display** | secondary title, section marker | 10-20% of canvas height |
|
||||
| **Heading** | paragraph title | 5-10% of canvas height |
|
||||
| **Body** | supporting copy, captions | minimum readable video scale |
|
||||
| **Eyebrow / UI** | metadata, chapter mark, command panel | ~50-70% of body, often uppercase + tracking |
|
||||
| **Data / counter** | standalone numeric statement | huge range, body to mega |
|
||||
|
||||
Phrase by tier ("hero word uses display tier, eyebrow uses mono uppercase"); do not write "hero 220px".
|
||||
|
||||
**Avoid adjacent role sizes too close:** 48/52/56 does not read as hierarchy. Lean toward 2-3x jumps (display 220 → heading 92 → eyebrow 30 = 7.3x). Hierarchy must be legible in <1s.
|
||||
|
||||
## Build Hierarchy Across Multiple Dimensions
|
||||
|
||||
Size alone is insufficient. Stack at least 2-3 dimensions per scene:
|
||||
|
||||
| Dimension | Strong contrast | Decision point |
|
||||
| ------------- | --------------------------------- | --------------------------------------------- |
|
||||
| **Size** | 3:1 or larger | hero word far larger than surroundings |
|
||||
| **Weight** | 800-900 vs 300-400 | extreme weights in one family beat two fonts |
|
||||
| **Color** | high contrast against background | see `color-system.md` |
|
||||
| **Spacing** | tight display + wide eyebrow | tight = confidence; wide uppercase = metadata |
|
||||
| **Case** | eyebrow UPPERCASE + body Sentence | all one case = monotone |
|
||||
| **Style mix** | italic serif inside heavy sans | word-level emphasis (archive signature) |
|
||||
|
||||
Plan names tiers/tracking by intent; do not write `-0.045em` / `0.08em` (build work).
|
||||
|
||||
## Font Pairing Principles
|
||||
|
||||
- **One family + multiple weights** is usually enough — cleaner than two competing fonts.
|
||||
- **Second font only for real contrast:** serif display + sans body, sans hero + mono label.
|
||||
- **Three-voice system** (strongest archive pattern): display + body + mono, each with clear semantic work (mono = metadata → "real tool feel").
|
||||
- **Switching font universes scene by scene is valid** when the emotional arc demands it; do not force uniformity.
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
- **Inter / Roboto / Open Sans / Lato / Montserrat regular weight as display** — an AI tell. If using Inter, use 900 + tight tracking, else not as display.
|
||||
- **Similar-but-not-identical pairing** (two geometric sans, two humanist serifs) — noise without hierarchy.
|
||||
- **Wide letter-spacing on long body sentences** — hurts readability.
|
||||
- **Tight tracking on mono code** — loses rhythm.
|
||||
- **Display at 0 letter-spacing** — a 200px title feels soft and corporate.
|
||||
|
||||
## CJK Note
|
||||
|
||||
If the narrator script contains Chinese, the plan must say "this scene contains CJK text." Build agent handles fallback chains (render-env config). In mixed CJK + Latin, CJK is denser, so display-tier CJK is usually one tier smaller than Latin.
|
||||
|
||||
## Plan Reference Example
|
||||
|
||||
> "Hero word: display tier + tight tracking. Eyebrow: mono uppercase wide tracking ('BEAT 02'). Body: supporting copy. Hero vs eyebrow = four-dimensional contrast (size + weight + case + style)."
|
||||
|
||||
Do not write concrete px / em / font names.
|
||||
Reference in New Issue
Block a user