hyperframes/skills/pr-to-video/references/visual-design.md

Visual design — PR-to-video per-frame enrichment method

The method behind Step 4 (Frame visual design). You (the orchestrator) read it to enrich STORYBOARD.md frames in place — story-design wrote the skeleton (each frame's scene, voiceover, transition_in, and the narrative fields); you add how each frame looks and moves. Each frame is a directed shot, not a static slide — you choreograph it across its whole duration. Because a PR video is mostly faceless, most visuals are invented — typography, number-lockups, diagrams — so you describe visual elements rather than place captured assets; the exceptions are code beats (a ready-made code-* block) and the credits close (real contributor avatars), both covered below. You write no HTML (that's the frame workers). frame.md is your palette/type truth. Composition / motion detail lives in composition.md + motion-language.md; effect & blueprint bodies live in hyperframes-animation. Adding palette theory or a generic font rule here? Wrong home — frame.md + hyperframes-creative.

Every frame is a directed shot

A frame's visual layer is choreographed across its full duration, not front-loaded into an entrance. The failure that reads as PowerPoint: content animates in over the first ~0.8s, then freezes while a slow drift plays under it. So every frame's metadata + note describe a shot with phases — entrance → development → settle — where development (a reveal, a rearrange, a morph, an emphasis hit, a count-up) is the mid-shot motion that separates video from slides. The shot model and the choreography-vs-idle budget live in motion-language.md; here you encode it into the frame: the effects / blueprint ids are the motion vocabulary, and the composition note sequences them into phases.

In explainers, development is often the teaching itself — the formula assembling term by term, the diagram gaining a layer, the count-up landing the statistic. Let the build be the message.

Deliberate stillness is the marked exception — the 2-3 climax/breather frames you allocate in ## Video direction. Every other frame develops; a held frame outside that allocation is just a slide.

What you add to each frame

Story-design's ## Frame N block already carries the narrative. You append the visual layer as frame metadata + one composition note (story's role/message prose stays):

## Frame 3 — How interest compounds
- scene: a snowball rolls downhill, gaining a labeled ring each turn   ← refine only if it could read sharper
- voiceover: "…"            ← story's; leave it
- transition_in: crossfade  ← story's; leave it
- type: feature_showcase    ← story's
- persuasion: Concretization + progressive disclosure
- beat: comprehension
- effects: scale-in, layer-reveal, count-up   ← you add: cite effect ids (≥3, sequenced into the phases below)
- blueprint: messaging-multi-phase           ← you add (optional): one multi-phase blueprint id
- focal: the snowball                          ← you add: which INVENTED element is the hero
- roles: snowball = foreground subject; hill = background gradient; ring labels = supporting   ← you add: each invented element's role
- sfx: whoosh-soft, tick                       ← you add: the sound the beat wants (fetched + mounted at root; never yours to embed)

Entrance: the snowball seats upper-left on a dim hill gradient. Development: it rolls down across the beat, gaining one labeled ring per turn (layer-reveal) while a small total ticks up (count-up). Settle: the final ring emphasis holds; only the slow camera drift continues. A dense, left-anchored frame.

• effects — name atomic effect ids from hyperframes-animation's rules index. Cite ≥3 when you name no blueprint (the worker composes them into the beat; fewer than 3 reads as generic motion); 1+ as accents when a blueprint already carries the choreography. With no blueprint, those ≥3 effects are the shot's phases — your note must sequence them (one enters, one develops, one emphasizes), not list them as a flat set that all fires at entry. You cite; the worker reads the recipe body and reproduces it (not a name-guess).

• blueprint — name one multi-phase blueprint id from hyperframes-animation/blueprints-index.md when a frame's beat wants a proven multi-phase shape. Two postures — both require the worker to read the recipe body first:

  • Reproduce — the blueprint fits the beat cleanly and the frame's content maps onto its slots; write the composition note shot-by-shot to match.
  • Adapt — the blueprint is the right structure but the content / beat doesn't fit its exact form (or you want a fresher surface). Lead the note with a Base / Keep / Depart line — Base: the blueprint id · Keep: its signature move (never drop this) · Depart: what you change and why. Adapt may extend or vary, never reduce below the shot model — never flatten a multi-phase blueprint into a single entrance.

  Choose Reproduce when the shape fits as-is, Adapt when the structure fits but the form doesn't; omit blueprint entirely when none fits — then the cited effects (≥3) carry the phases (Compose).

• focal / roles — name the invented visual elements and their roles. focal is the hero element (a hero word, a diagram node, a chart series, a coined-term card). roles assigns each element a role: foreground subject (the thing the eye lands on, text laid around it), background (full-bleed field/gradient/grid, dim 30-50%), supporting (labels, secondary shapes, ambient layers). Since there are no captured assets, you are designing these elements, not selecting them — keep them few and load-bearing. A user-supplied public/<basename> image, if any, is named in story's asset_candidates; treat it as the focal cutout or a background.

• sfx — name the sound the beat wants (an impact for a slam, a whoosh for a push, a tick for a count). The audio script's fetch-sfx pass retrieves it and the assembler mounts it at the root — you only name it, never embed an <audio> element.

• composition note — the frame's visual brief: layout, hero, depth layers, the macro move, and the shot's phases. Default to a phased note — entrance: … → development: … → settle: … (mandatory when you named a blueprint). A single still line is correct only for a deliberately held climax or an allocated stillness frame. Full method → composition.md (layout) + motion-language.md (phases).

PR code beats — name a code-* block (the one place you don't invent)

(Frame type values are PR-native — diff / before_after / mechanism / impact / credits / … from story-design; the enrichment method below is the same regardless of type.)

For a diff / before_after / code beat, the frame's centerpiece is a ready-made code-* registry block, not an invented HTML visual — the one exception to "invent every visual." In that frame:

• Name the block in scene + focal. Pick the one that fits the beat (before→after = code-diff; refactor/rename = code-morph; new code written on = code-typing; spotlight a line = code-highlight; walk a long file = code-scroll; a hero reveal = code-3d-extrude / code-particle-assemble). Full map → code-vocabulary.md. Name the hunk too ("the request() retry block, ~6 lines"). The block is the focal; the Step-5 worker installs + fills it with the real diff.
• effects choreograph the surrounding chrome, not the code motion. The block owns the diff/typewriter/morph animation (it is the development beat). Your effects / blueprint move the claude Code Surface around it — the navy window seating in, a +N/−M count-up, a coral underline drawing on. Cite 1–3 for that chrome; do not re-specify the code animation itself — the worker only fits the block's cadence to the frame's data-duration (a long snippet overruns a short frame otherwise).

Numbers (+1,204 / −318, files touched, perf delta) go on an impact / evidence frame as a number-lockup (claude's Number/Impact treatment) — name it the focal, with a count-up. The credits close uses the real assets/<login>.png avatars (named in story's asset_candidates) as the focal — an avatar row; the visual phase features non-empty asset_candidates like real assets. A mechanism frame is also invented — but an animated diagram of the behavior, not typography (see the next section). Every other frame (hook / change / cta) is invented typography/graphics per the method above.

PR mechanism beats — invent an animated diagram of the behavior

A mechanism frame is the show-the-behavior beat — the antidote to a video that only shows code + text. Its focal is an invented animated diagram that plays out what the change does at runtime (the request retrying, the cache filling, serial→parallel, the race resolved), not a code-* block and not a headline.

• Name the behavior + the diagram in scene + focal. e.g. scene: "animate the request lifecycle — fire → 500 → backoff (delay growing) → retry → 200, invented SVG flow"; focal: the request-lifecycle flow. story-design's "what to animate, by what the change touches" table is the menu. Reach for the flowchart / flowchart-vertical / data-chart registry blocks where they fit (name them in scene like a code-* block so Step 5 pre-installs them); otherwise the worker builds it in SVG / HTML / GSAP from claude's atoms.
• The build is the development beat. Unlike a code block (which owns its own animation), the diagram is yours to choreograph: cite ≥3 effects (or a blueprint) and sequence them into the phases — the lanes / nodes draw on (entrance), the flow runs / the lane splits / the front advances (development), the resolved state + one coral emphasis lands (settle). This is exactly composition.md's "diagram / data-viz where the build is the teaching" register — here the mechanism is the teaching, so never let it enter then freeze.
• Stay on claude's cream ground, hairline-ink. Nodes / edges / lanes in hairline ink on cream; one coral marker on the active or changed element (the retry hop, the cache hit, the new lane); mono labels. Not the navy code surface (that's for code), not heavy shapes / bokeh. Plan it into the top ~83% (caption keep-out).

focal / roles name the invented diagram and its parts (the lanes = foreground subject; a timeline axis = supporting; a dim grid = background). A mechanism frame carries no asset_candidates (it's invented, like every non-credits frame).

Video direction — write the invariants ONCE

The whole video shares one look and one motion grammar. State it once, at the top of STORYBOARD.md (a ## Video direction block), so every frame inherits it and per-frame metadata carries only the delta:

• palette system — from frame.md: which roles map to which hues. Never invent.
• motion defaults + shot model — default eases + the choreography baseline (every frame a directed shot: entrance → development → settle) + the idle-life budget (what may keep moving during the hold) (→ motion-language.md).
• negative list — what never appears: off-brand textures the pack forbids, plus both motion failure modes — slideshow (enter-then-freeze) and screensaver (everything floating independently) (→ motion-language.md).
• stillness allocation — name the 2-3 frames that hold still before a climax; every other frame develops.

Do not repeat these in every frame — each frame's metadata is the delta on top of Video direction.

Palette & type — from frame.md, never invented

• Palette — frame.md (the adopted pack) is the color truth; apply its roles per frame. Generic basics (one accent, tint neutrals, avoid pure #000/#fff) → hyperframes-creative/references/house-style.md.
• Type — fonts resolve via frame.md's type tokens; reference them by role (display / body / mono / the pack's ramp), never by raw family or px. Typography craft (embedded fonts, dark-bg optical compensation, tabular-nums) → hyperframes-creative/references/typography.md. In a faceless explainer, type is often the primary visual — the hero word, the coined term, the kinetic enumeration — so lean on the type ramp hard.

Caption-band keep-out (plan side)

The bottom ~17% of the canvas is reserved for the caption pill. Plan every frame's content into the top ~83% so nothing important lands in the band (the worker enforces the pixel cutoff; you plan the layout). Holds even when captions are disabled — bottom-edge consistency. Geometry detail → composition.md.

Where the detail lives

For…	Read
composition — zones, density, templates, invented-visual prominence, caption geometry	composition.md (local)
motion — the shot model, phases, idle budget, beat structure, stillness	motion-language.md (local)
effect ids + blueprint ids (vocabulary + recipes)	../hyperframes-animation/blueprints-index.md + ../hyperframes-animation/rules-index.md
palette + type tokens	the project's frame.md; basics → hyperframes-creative house-style.md / typography.md
transitions	story-design owns transition_in; you don't touch it

Before you finish — checklist

• Every frame has effects (≥1 cited id; ≥3 when no blueprint is named); a blueprint where the frame matches one, with a shot-by-shot composition note.
• Every frame's composition note is phased (entrance → development → settle) — not a single entry that then freezes; the ≥3 effects are sequenced across phases, not all fired at t=0.
• Stillness is only the 2-3 frames allocated in Video direction; every other frame develops mid-shot.
• Each frame names its invented focal + per-element roles (foreground / background / supporting), kept few and load-bearing.
• A mechanism frame's focal is an invented animated diagram of the behavior (or a flowchart / data-chart), choreographed across its phases — not a code block, not typography; the body is not an unbroken run of code surfaces.
• Video direction stated once at the top (palette · shot model + idle budget · negative list incl. both failure modes · stillness allocation); per-frame entries are deltas.
• Content planned into the top ~83% (caption band clear).
• Palette / type pulled from frame.md by role — nothing invented.
• You wrote no HTML.