motion-designer: films from code

You direct and build short videos: most often a film of an app in use, and any other short motion video on the same engine (types). The app's own interface, rebuilt from its code and screenshots or captured from its web frontend, lives inside a device that one camera films, and every move lands on the music's beat. The film is a page whose every frame is a pure function of time, seek(t), so it renders frame-exactly, loops without a seam, and can be checked frame by frame.

• Blank: full-frame shots on a canvas of any size, for titles, kinetic type, explainers, data, music videos and montages (templates/blank). Overlay: a clear background drawn over the user's footage, for lower thirds, captions and callouts (templates/overlay). Both lean on effects.
• Mobile: an iPhone (templates/mobile). Desktop: the app's window on a laptop display with menu bar, dock, pointer and a lid that closes (templates/desktop); web apps in the same window with browserBar(url). Story: a hook, the product's arrival, features as panels, the brand's character, and an end card (templates/story, types).
• SKILL_DIR in every command is ${CLAUDE_SKILL_DIR}, the folder holding this file, with scripts/, templates/ and reference/. Write it out as that absolute path in each command.
• Any agent can run this skill. Where a step says Plan, Ask, Look, Delegate, Background or Send, harness maps it to your tools (Claude Code, Codex, others).

1. Start from the project's state

Take the first row that matches and do only what it says; the rows below it do not apply.

2. Workflow

Stop for the user's go-ahead after step 0 and again after step 2 unless they asked you to go straight through; after that, work without asking except where rights says to. At the end of every step, rewrite the ## Status section at the bottom of brief.md: the step reached, what is done, what is next, what is open. With it and the files on disk, a fresh session continues where this one stopped.

0. Brief, as a plan (Plan: in Claude Code EnterPlanMode, then ExitPlanMode with the brief; unless the user asked to go straight to building or gave you a complete brief). Find the product's name, read what it does and which flows are worth filming, write a brief for this product alone (brief), with the film's type (types).
1. Materials. Find what you can: the app's code (screens, tokens, fonts, icons, copy), a Simulator or desktop build, brand assets, screenshots or recordings. Ask only for what you can't find: the music (the user's track; without one, make an original with music or, with their go-ahead, search music sources), format and length, features that must appear, claims to avoid. Confirm every feature you plan to show exists and works that way: read its code and try it.
2. Concept. Offer two or three styles that suit the app. Write the story in beats (one visual change per beat, a hold after each result, the biggest reveal on the drop), a beat-map table (beat, time, what happens), the screens and assets needed, and four stills from the template in the chosen style: the opening, the key product moment, the drop, the final frame. List your assumptions. A social cut (15 to 25 s) shows the app's strongest action in the first two seconds. For an App Store app preview, explain guideline 2.3.4 first (rights).
3. Build.
   • bash SKILL_DIR/scripts/new_film.sh <film-dir> mobile|desktop|story|blank|overlay; open src/index.html in Chrome to preview and scrub.
   • Set the clock on the first line of scenes.js: film({ BPM, BEATS, holds }).
   • Pack the app's look: swift SKILL_DIR/scripts/symbols.swift <film-dir>/assets/sym plus@semibold … for SF Symbols, then python3 SKILL_DIR/scripts/assets.py <film-dir>/src/assets.js --font "Family=font.ttf" --img icon=AppIcon.png --sym <film-dir>/assets/sym. The app's family goes first in film.css, the style's tokens in its :root.
   • Rebuild each screen in scenes.js from the real app, in app or window points; write every time as a story beat B(n). For web-tech desktop apps, capture the real UI instead (capture). Read motion and phone or desktop first.
4. Sound (music): follow the sound brief. Make the track if there is none, listen with beats.py, pick bars so its lifts and breaks land on the film's, cut it to <film-dir>/audio/edit.m4a, put its BPM and BEATS in film({...}). In a story, feature cards or type-led film, give the actions their sounds (cues(), sfx.py).
5. QA loop (qa):
   • node SKILL_DIR/scripts/check.mjs <film-dir>/src/index.html: no clocks, timers, randomness or CSS animation, no page errors, the loop closes, frames identical in any seek order.
   • Delegate the looking to reviewers, one per stretch of about 12 s and per kind (overview, transitions, text), plus one at phone size for the whole film, all at once. Each scores its stretch from 1 to 10. Fix what they report, then send them back to what changed. Repeat until every report reads clean with every score at 8 or more.
6. Render (Background, about 0.4 s a frame): node SKILL_DIR/scripts/render.mjs video <page> <film-dir>/out/<name>.mp4 --audio <film-dir>/audio/edit.m4a --scale 2 (add --blur 8 for motion blur when the film has fast moves; it renders 8 times slower), then the loop, poster and any smaller copy (qa). node SKILL_DIR/scripts/render.mjs verify <page> <film-dir>/out/<name>.mp4 checks frames, size, duration and a frame against a still.
7. Voiceover, if asked (voiceover): let the user pick the voice engine, then mux the mix over the rendered picture.
8. Single file. python3 SKILL_DIR/scripts/build_single.py <film-dir>/src/index.html <film-dir>/dist/<name>.html, then check.mjs <page> --dist <film-dir>/dist/<name>.html proves it shows the same pixels.
9. Report in the user's language: the film beat by beat, what you checked and how, the files and the post text, and what is still open (music licence, logos, voices, unverified claims). Send the video.

3. Deliverables

In a film folder in the project (default docs/launch-film/, or tmp/launch-film/ when it must stay out of git):

4. Keep the context small

A session pays for everything in its context again on every turn, so what stays in it matters more than what is read once.

• Pictures go to reviewers. Look at images yourself only for the four concept stills, frame 0 and the poster.
• Read code by place. grep -n for the scene or function, then read that range. Read a file whole once at most; don't read back a file you just wrote, the templates (the copy in src/ is the same) or the scripts (run one without arguments for its usage).
• Read a reference when its step starts, once, and only the ones the step names.
• Keep output short. The scripts print summaries; give any ffmpeg you run -v error and ffprobe -v error; send long logs to a file and read its tail.
• Fewer turns. Make independent calls together. Run renders in the Background and check the file once, instead of polling.
• Restart at the seams. After the brief is approved and after the film passes QA, everything needed is on disk. If the session is long by then, tell the user they can start a fresh one there with "continue the launch film".

5. Hard rules

Every video:

• Deterministic. Every property is computed from t with easings, closed-form springs and track(). No CSS transitions or animations, timers, Math.random, Date, or state carried between frames. Spinners, waveforms, carets and typing are functions of t.
• Readable on a phone. Each result holds 1 to 2 s before the next action. Text that matters is at least about 20 px on the stage: move the camera in rather than shrinking the film. No truncated labels, text cut by a mask or the frame edge, text crossed by motion, one-frame flashes, or layers popping.
• Local only. No external libraries, fonts, images or CDNs in the film unless the user agrees; everything is packed into assets.js and inlined in the single file.
• Never overwrite the user's source assets, footage or app code; derived files go in the film folder.

An app film also:

• The device is always there. Mobile: once the screen opens, the app lives inside the iPhone; close-ups crop top and bottom but keep its sides, island or status bar. Desktop: the app is in its window, with the traffic lights or caption buttons in frame, first on the canvas, then on the desktop, then on the laptop. Never app UI full-bleed.
• Real features, fictional data. Only what the app does, the way it does it; opt-in features shown being used, not as defaults; nothing implied about on-device processing that isn't true. Every name, amount, file and person is invented.
• Motion from the app itself. Transitions come from shapes and actions: a row opens into the window, a button grows into a sheet, a card lifts into a preview, the palette closes into what it opened. No crossfades between scenes, blur-ins, brightness reveals, glass or glow, 3D flips, particles, random pointer paths, stock imagery. What viewers asked for: to see it is a phone or a desktop app at every moment; slow enough to follow, one action per beat with a hold after each result; nothing that looks broken ("Savi" or "Uncategori…" gets reframed until it fits, badges sized from DOM-measured text); a voice clearly on top of the music, with the music still present between lines.

6. References: read when