Motion Director

A motion design system distilled from five reference films plus a personal portfolio reel. It is not one template. Each presents differently, so the skill keeps eight layouts (different structures, pacing, camera, and audio) on top of one shared type-and-motion language, with interchangeable color flavors. Everything runs locally and free by default; API keys are only for optional voice providers.

Division of labor. This skill decides how it looks, moves, and sounds. HyperFrames (/hyperframes → /general-video, /motion-graphics, /product-launch-video …) builds, checks, and renders. The handoff is the project's frame.md (read first by HyperFrames, per hyperframes-creative/references/design-spec.md), the runtime in assets/, and assets/audio/mix.wav.

The shared language: ten laws

Every layout follows these. They're what all five references have in common.

1. Type is the lead actor. Lines build word by word (rise + de-blur) or type on behind an accent caret. Text arrives; it never just appears. That's what makes the viewer read.
2. One keyword per line. The payoff word gets the accent: a filled pill, marker sweep, selection brackets, or accent color with a heavier weight. Two highlights cancel each other out.
3. One accent, full stop. Base (dark or light-neutral) + ink + ONE saturated color. The accent is ~10% of the pixels, except for full-bleed accent panels used as punctuation.
4. Weight contrast inside a line. Regular body with a bold/black keyword; single-word hero hits go oversized, all-caps, tight. Serif narration lines are available where the layout calls for them.
5. Transitions carry continuity. Morphs, push/pull-throughs, whips, panel wipes, and camera moves. Hard cuts only on the beat; how many is a layout decision (see layouts.md).
6. Ride the beat grid. Music BPM (96–128) sets the grid: something changes every beat, a new idea every 1.5–3 s, one breathing hold before the end. Voice layouts follow word timestamps instead.
7. Show the real thing. UI cards in 3D, prompts typing, chips popping, real screenshots and dashboards. Proof beats show the work, not stock.
8. Atmosphere, never flat. Blurred orbs, grain, glow, vignette. Depth even behind one sentence.
9. Every visible landing has a sound. Impacts on slams, pops on chips, keyboard ticks on typing, risers into big moments, a music bed on the grid, voice where the layout is narrated.
10. Thread a motif, end on a question. A guide element (spark, dot, caret, mark) leads the eye; close with a brand lockup and a question or call to action.

Workflow

0. Setup (first video on a machine). If a script fails on a missing tool, run node ~/.claude/skills/motion-director/scripts/doctor.mjs and relay its fixes. Whose brand is this? For the user's own brand, use the skill-folder brand.json; if it doesn't exist, ask for the fields in brand.example.json once and write it there. For a client, write brand.json in the project folder instead, so the user's own brand never leaks into client work.

1. Intake. If /hyperframes already wrote BRIEF.md, read it and ask nothing it answers. Get the message, audience, length, aspect, brand, and real assets (screens, footage, numbers). Never invent stats or client names. Route every input with references/intake.md: a URL, a local app, screenshots, a Figma link, a PDF or deck, a screen recording, a logo only, or a text brief with no assets. Run scripts/prep-media.mjs on any images you're given. Before picking a layout, write the asset inventory (the block in intake.md) and show it to the user:

   Asset inventory
   Have:        <each real asset: file · shape · how big it can appear>
   Missing:     <what the story needs that nobody supplied>
   Build in HTML: <UI or diagrams recreated as code, labeled as concept>
   Numbers:     <every figure on screen and where it came from, or "none">

2. Pick the layout with references/layouts.md (the choosing table), then the flavor with references/flavors.md (layout default, a different flavor, or one derived from the brand; media-report.json suggests an accent from screenshots). State both picks in one line each.
3. Scaffold from the matching demo, which is the fastest way to a working piece: node ~/.claude/skills/motion-director/scripts/scaffold.mjs <project-dir> --demo <layout> [--aspect 9:16] [--brand <file>] [--dry-run] (--list shows every demo and its ready-made aspects; it never overwrites existing files). It fills the brand into the copy and seeds any image you haven't supplied with a SAMPLE placeholder: replace every one it lists before the final render. Then write frame.md from assets/frame-template.md.
4. Beat sheet. Use the layout's structure and references/story-structures.md for durations; assign moves from references/signature-moves.md. Motion numbers are in references/motion-grammar.md.
5. Voice. Narrated layouts, or a sparse line per scene when the user asks for voice. Write vo.json, run scripts/voice.mjs, get word times with scripts/transcribe.py --words, and land each key word on its visual. Kokoro is the default; if the user wants ElevenLabs or their own cloned voice, set "provider" and follow the consent, licence and cost checks in references/sound-design.md §5 (run --dry-run before any paid call).
6. Build the composition: replace the demo copy and media with the project's, keep the move structure, keep the helpers' determinism rules.
7. Sound. Write cues.json at the same timestamps as the tweens, run scripts/sound.mjs, and reference assets/audio/mix.wav with an <audio id>.
8. Audit and verify. Run references/audit.md, then npx hyperframes lint and check (0 errors), render a draft, look at every beat (scripts/beat-frames.mjs <render> --bpm N tiles one frame per beat), run scripts/transcribe.py <render>.mp4 to confirm every voice line is intelligible, and check loudness. Fix, then do the final render.

Runtime (assets/motion-director.js, global MotionDirector)

Every applier is fn(tl, target, at, opts): it adds tweens to your paused timeline at an absolute time and returns the time its move settles.

Determinism (HyperFrames): no clocks, seeded randomness only, finite repeats, set-based typing, tween transforms/opacity (not letter-spacing), never tween a .clip element's visibility, and register window.__timelines[id] after the build. Measure elements only in clips active at build time; otherwise pass coordinates.

Evolving the style

To add a reference, make contact sheets and a cut report (the HyperFrames student kit's motion-showreel/scripts/analyze-reference.mjs <video> <out-dir> --fps 4 does both; plain ffmpeg -i ref.mp4 -vf "fps=4,scale=480:270,tile=4x4" sheet_%02d.png covers the sheets), read every sheet, and run scripts/transcribe.py ref.mp4 to see whether it has voiceover. A new presentation becomes a new layout (plus a demo); a pattern shared by most references becomes a law.

Files

• references/intake.md: what to do with each kind of input (URL, screenshots, Figma, PDF, footage, brief only) + the asset inventory
• references/layouts.md: the eight layouts (structure, pacing, moves, audio), the HUD add-on, and how to choose
• references/website-case-study.md: recipe + capture rules + gotchas for films that present a website
• references/sound-design.md: cue sheets, SFX palette, music styles, voiceover, loudness
• references/flavors.md: palettes and deriving one from a client brand
• references/design-language.md · references/motion-grammar.md · references/signature-moves.md · references/story-structures.md · references/audit.md
• assets/motion-director.js · assets/motion-director.css · assets/fonts/ (Inter, Instrument Serif, Dancing Script; OFL) · assets/frame-template.md
• assets/demos/<layout>/ (index.html with {{brand.*}} tokens, cues.json, vo.json for voiced ones; <layout>-9x16/ and -1x1/ for other ready-made aspects) · assets/demos/MEDIA.md (what each demo image should show) · assets/demos/_placeholders/ (committed SAMPLE media) · assets/demos/_media/ (optional, never committed: your own images, used before the samples)
• brand.example.json → brand.json (who the video is for; scripts/brand.mjs validates and fills it)
• scripts/doctor.mjs (setup check) · scripts/scaffold.mjs · scripts/prep-media.mjs (any image in → WebP + shape, size and palette report) · scripts/sound.mjs · scripts/voice.mjs (+ scripts/voice/ providers, scripts/env.mjs for keys, .env.example) · scripts/capture-site.mjs · scripts/beat-frames.mjs (one frame per beat, tiled) · scripts/transcribe.py · scripts/make-placeholders.mjs (maintainers only)
• PROMPTS.md: copy-paste prompts for users
• Tests: node --test tests/*.test.mjs