Motion design

Remotion teaches you the API. This file is the taste. Every number below comes from a shipped piece (src/EffortVideo.tsx); treat them as defaults you deviate from on purpose, not by accident.

1. Time lives in timeline.json

• Every beat is a named timestamp in seconds in timeline.json, grouped by scene (s1, s2, …). Components read it through TL from src/lib.ts; the video's cue sheet in sfx/cues/ reads the same file. That is what keeps picture and sound locked.
• Never hardcode a start time inside a component. Offsets relative to a beat (s1.exit + 0.05) are fine.
• Retiming = editing timeline.json, then npm run sfx so audio follows.
• Everything is a pure function of frame. No CSS transitions or keyframes, no Math.random() (use rand(n)), no Date. Anything else flickers or drifts at render time.

2. Easing

Linear is only for continuous motion: rotation, drift, grain, ticking hands.

Use prog(t, t0, t1, ease) for tweens and band(x, a, b) to derive one animation from another value (e.g. captions from the slider position) instead of giving it its own clock.

3. Springs (via sp(frame, startSec, config))

Springs for things that feel physical (UI, objects). Bezier tweens for type and camera-like moves.

4. Timing

• Stagger words by ~0.09 s, list items/chips by ~0.2–0.25 s, rings/dots by ~0.06 s.
• Word reveal ≈ 0.8 s with Mask (slide up out of a clip + slight tilt).
• Exits are ~half an entrance (0.35–0.55 s vs 0.7–1.25 s). Exits use easeIn.
• Overlap scenes. The next scene starts drawing on before the previous one has fully left (s2.drawOn 4.02 s < s1.flipEnd 4.4 s). Hard gaps read as "loading".
• Typing ≈ 0.035 s per character, caret blinks at ~2.4 Hz when idle.
• Reading holds. Every readable state needs a hold after it settles: ≥ 1 s for a short phrase, add ~0.25 s per word beyond three, ≥ 2 s for the final hook. The 22 s cut of the effort video exists because the 15 s one flashed text too fast — when in doubt, hold longer and animate less.

5. Typography

• Max three families: display serif (Instrument Serif), UI sans (Inter), mono (JetBrains Mono) for labels, prompts, numbers.
• Display type is big (≈ 138 px on a 1080 canvas) with tight tracking (-0.02em), lineHeight: 1.
• One accent per line: a single italic word in the accent color carries the point (Same *prompt.*).
• Mono labels: uppercase, letterSpacing: 0.2–0.24em, muted color. They're decoration; anything the viewer must read goes big.
• Phone test: at 360 px wide (how X shows it in the feed) the key message must still read. Check it on the contact sheet.

6. Color

• Palette tokens live in C (lib.ts). Don't introduce new hex values in components.
• One accent color (coral) and it means something: the thing that changed, the answer, the winner. If everything is coral, nothing is.
• Drive glow from state, not time (glow = effort): light should explain the story.

7. Texture — nothing is dead-still

• Film grain overlay (Grain, opacity ≈ 0.09, reseeded on twos).
• Vignette plus a dot grid drifting a few px/s (Background).
• Hand-drawn "line boil" (WobbleFilter) for sketchy/low-fidelity states, faded out as quality rises.
• Idle elements breathe: a ticking clock, a blinking caret, a slow rotation.

8. Continuity and transitions

• Prefer persistent objects over cuts. The prompt bar, the spark and the slider travel through scenes and change role; that's what makes it feel designed rather than assembled.
• Every transition is motivated by an object on screen (the five result dots merge into one, which becomes the iris). No generic wipes.
• Use velocity: derive motion trails / squash from value(frame) - value(frame - 1) instead of faking it.
• One hero moment per video (the iris + impact). Build to it; don't spend it early.

9. Anti-patterns

• Everything fading in at once, or everything using the same duration.
• Linear easing on anything that starts or stops.
• Text that moves while it's supposed to be read.
• More than one focal point per frame.
• Content within ~60 px of the frame edge (safe area) unless it's intentionally cropped.
• An empty or black frame 0 — X autoplays muted and the first frame is the thumbnail.

Workflow

1. Write the beats into timeline.json first (a storyboard in numbers).
2. Build scenes as components in src/scenes/, shared bits in src/components/.
3. Run the review-loop skill after every meaningful change.
4. Run the sound-design skill once picture timing is locked.