Motion design

Use this skill when motion carries meaning. It covers the story, the timing, the craft rules, a deterministic web engine and how to verify the result. It does not replace live tuning: when the lab skill exists, use it to let the user dial in values by eye. When wow-loop exists, use it for repeated review-and-repair rounds on one piece.

Motion inside a product (buttons, popovers, tooltips, toasts, drawers, drag gestures) or an animation that drops frames skips the story workflow below: read ui-components.md and follow it.

Workflow

1. Name the feeling and the job. Write one sentence saying what the viewer should feel and understand when the piece ends. Choose techniques after that, never before (Jay Grandin).
2. Write the story before any pixels. For an explainer, open on a concrete moment instead of a definition, chain the beats with "but" and "therefore", and give each beat one idea. Write a beat sheet with timestamps. See story.md.
3. Build an animatic with final timing and rough visuals. It needs a scrubber, pause and chapter ticks. Get the pacing approved before any polish.
4. Block the key poses, then polish the in-betweens: easing, stagger, overlap and secondary motion.
5. Verify in a real browser on the GPU. Judge motion by watching it play. Stills only prove layout. See verify-export.md.
6. Export to video when the piece has to travel to feeds that do not run JavaScript. Encode in the page with WebCodecs, never a PNG or screenshot per frame (user instruction, 2026-10-19); see verify-export.md.

Decision rules

These are defaults. Tune them by eye.

Pitfalls

• Opening on a definition or an architecture diagram before a concrete example.
• Motion that competes with the words: text sliding around while it is being read.
• Everything moving at once with even timing, which reads as mechanical.
• Ease-in on arrivals, scaling up from 0, or preset curves nobody looked at.
• Hard cuts that break an object's identity between states.
• Listing features instead of showing one real task.
• Mock copy where real product data exists, or real data that contradicts a claim on screen (a demo record where one of "all six" models failed).
• Layout checked only at key poses. Collisions show up mid-transition, when an orbiting element crosses a label.
• Static holds that look dead, or constant motion that never lets the eye rest.
• A UI loop that only loads in and then sits there with a few pulses. Every visual needs a story of what it does.
• A loop that stutters at the wrap: a story not back at rest, a field the reset missed, or an export that repeats the first frame at the end.
• A game-system shot that copies the game faithfully but explains nothing to a stranger, or a caption in game jargon (OVERHEAL) instead of the rule (KILLS HEAL).
• Per-frame state that one scene sets and the frame reset never clears, so seeking back renders differently from a fresh load. The same goes for stateful camera springs, Math.random() shake and live audio analysis.
• Juice on everything. In a 3,018-player study, both no juice and extreme juice lowered play time and motivation compared with medium and high amounts. Save the biggest shake and flash for one or two moments.
• Decorative motion inside a teaching beat, or narration printed word for word on screen.
• Saturated red text or 1 px coloured lines, which 4:2:0 video blurs.

Resources

• principles.md: who teaches what, with sources, perception and learning research, UI motion tokens, plus the claims that could not be verified.
• ui-components.md: product UI motion (whether to animate, easing and duration by component, press, popover, tooltip, toast and drawer rules, clip-path patterns, drag gestures), the frame budget and the traps that cause jank. Adapted from Emil Kowalski's MIT-licensed skills.
• story.md: explainer structure, a beat-sheet template, caption rules and game trailer structure.
• ui-loops.md: one story per visual for UI cards, dashboards and mockups, accents, intro choreography, the loop cycle, and live-page rules.
• web-engine.md: a deterministic frame(t) engine with keyframed particle tracks, staggered morphs, phosphor trails, bloom, captions and a transport, plus gotchas measured in practice.
• web-effects.md: landing-page recipes with cost ratings, reduced-motion and touch fallbacks: background video, fade and boomerang loops, framing and scrims, cursor- and scroll-scrubbed video, glass and grain, fail-safe entrances, scroll reveals, a sticky cinematic stage, stacking cards and a text crawl. Adapted from the MIT-licensed MotionSites technique library.
• verify-export.md: headed offscreen Chrome, stills, an fps probe, seek and colour checks, loop checks, delivery specs, encoding checks, WebCodecs export (from a canvas, or by tab capture for DOM pieces) and a last-resort frame-stepped export.
• generated-film.md: AI video films: the cost gate, one camera move, chained keyframes, the clip adapter contract, the continuity gate and its measured limits, living-still loops.
• page-runtime.md: the 3D iframe shield with its pointer-forwarding receiver, Spline notes, and the Off / On / X-ray motion switch.
• accessibility.md: flash limits, photosensitivity testing, and reduced-motion replacements for when the owner asks for one.
• camera-cut.md: cutting rules, shot-length data, lenses, camera damping, handheld noise and gameplay capture.
• impact-fx.md: shake, hitstop and squash numbers from shipped code, effect timing and readability, enemy telegraphs.
• color-light.md: colour scripts, tone mappers and hue, bloom and dither.
• sound.md: music prep, impact layering, sync tolerance, beat maps and loudness.
• assets/engine-skeleton.html: a working single-file starting point for the engine.
• scripts/stills.mjs: captures stills at given times and reports console errors and frame cost.
• scripts/film-chain.mjs and scripts/film-gate.mjs: build a film from chained generated clips, and check any video for hidden cuts and stalls.
• assets/iframe-shield.js and assets/motion-switch.js: drop-in page scripts from page-runtime.md.