design-motion

Motion is not decoration applied after the design. It is how the interface explains itself: where things came from, what is connected to what, and whether the product heard you.

Two rules sit above everything else here:

1. Motion answers a question or it does not ship. Where did this come from, where did it go, did my action register, what changed, what is connected. Animation that answers nothing is latency you added on purpose.
2. The user's time is not yours to spend. Every animation is a delay you chose. A transition seen twice is delightful. The same transition seen four hundred times is a tax.

Engine

DS=$(ls "${CLAUDE_PLUGIN_ROOT:-/nonexistent}/engine/dstack.py" "$HOME/.claude/dstack/engine/dstack.py" 2>/dev/null | head -1)
python3 "$DS" "<symptom>" --motion            # search 80 motion practices
python3 "$DS" --categories --motion           # list motion categories
python3 "$DS" --audit --motion                # full motion checklist by severity
python3 "$DS" --audit --motion -c performance # one area

Categories: timing, easing, choreography, interaction-feedback, scroll, page-transitions, gestures, performance, accessibility-motion, text-animation, layout-animation, video-pacing, remotion, audio-sound, export-delivery.

Query before you write a duration or a curve. The numbers in the base are the point of this skill.

The defaults, memorized

You should not have to look these up. Everything else, query.

Durations. instant 100ms, fast 150ms, base 250ms, slow 400ms. Anything over 400ms needs a reason you can say out loud. Scale to distance travelled, not to importance: under 100px is 150ms, a full screen sheet is 350 to 400ms.

Curves. Three per product, no more.

--ease-out:    cubic-bezier(0.16, 1, 0.3, 1);    /* enters, hovers, reveals. the workhorse */
--ease-in:     cubic-bezier(0.4, 0, 1, 1);       /* exits that leave the screen */
--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);   /* in place moves and size changes */

Linear is for loops only: spinners, marquees, progress. Never for anything travelling through space.

Springs. For anything dragged, thrown, or dismissed by hand. stiffness 300, damping 30, mass 1 for UI. Drop damping to 14 only when the moment should feel playful.

Exit is 75 percent of enter. Arriving earns time. Leaving is already decided.

First feedback within 100ms, always, even when the real work takes a second.

Step 1: Decide what should move

Before writing anything, list the moments. Most interfaces need fewer than you think.

Moment            What it answers                  Treatment
Button press      did it register                  scale 0.97, 100ms
Modal open        where did this come from         origin anchored, 250ms ease-out
List item added   what changed                     layout animation + 300ms fade
Route change      am I somewhere new               250ms overlapped, chrome held still
Drag to dismiss   am I in control                  1:1 track, spring release

Then name the ones you are deliberately not animating. An interface where everything moves has no emphasis left.

Step 2: Pick the signature

One motion characteristic that is recognizably this product's, applied consistently. A curve that overshoots slightly. Content that always enters from its origin. A stagger rhythm. A single spring used everywhere direct manipulation happens.

Without a signature you get correct motion that feels like nobody chose it, which is the motion equivalent of a stock template.

Step 3: Audit what exists

If there is already motion in the codebase, sweep it before adding more. Grep for the tells:

grep -rn "transition:\|animation:\|duration-\|ease-\|cubic-bezier\|@keyframes" src/ --include=*.css --include=*.tsx --include=*.jsx --include=*.vue --include=*.svelte | head -50

Flag on sight:

• linear on anything that moves through space
• transition: all which animates properties you never intended and costs frames
• Durations over 400ms outside a deliberate hero moment
• Animation on width, height, top, left, margin, or box-shadow
• No prefers-reduced-motion handling anywhere in the project
• Entrance animations that replay on every scroll pass
• Six different durations that should be four tokens

Step 4: Implement

Compositor only. Animate transform and opacity. Nothing else. Replace width and height with scale, replace top and left with translate, replace a shadow transition with a stacked layer whose opacity you fade.

Height to auto does not interpolate. Use grid-template-rows: 0fr to 1fr, or measure in JS, or use a layout animation.

Interruptible. Anything a user can grab must animate from its current position and velocity, never restart from a fixed origin.

Clean up. Kill every timeline, disconnect every observer, remove every listener on unmount. Orphaned tickers compound across route changes into a leak that only shows after a few minutes.

Reduced motion is not optional. Always ship the branch:

@media (prefers-reduced-motion: reduce) {
  /* keep the feedback, remove the travel */
  * { animation-duration: 0.01ms !important; transition-duration: 150ms !important; }
  .parallax, .reveal { transform: none !important; }
}

Reduced does not mean none. Keep opacity, color, and focus changes so state stays legible. Remove translation, parallax, scale, and rotation.

Step 5: Verify

Never approve motion from reading the code.

• Throttle CPU to 4x and watch it. Motion that is smooth on your machine is the least useful data point available.
• Hold the frame under 16ms at 60fps, under 8ms at 120fps.
• Turn on reduced motion at the OS level and use the interface. It must still be usable and still communicate state.
• Interrupt every animation mid flight. Click twice fast, grab the sheet while it settles, navigate before the transition ends.
• If browser tools are available, record the interaction and watch it back at quarter speed.

Choosing the tool

Do not add an animation library to move one modal 8 pixels.

The video lane

When the request is video rather than interface, this skill routes rather than improvises. Run them in order and do not skip the spec.

1. Script and structure. explainer-video-guide for script formulas, hooks, and pacing. Hook inside 3 seconds. 140 to 160 words per minute. One idea per scene, 3 to 6 seconds each.
2. Motion spec. motion-designer for the scene by scene plan: timing, audio, sound effects, and what animates when. Write the script first and cut the visuals to the narration, never the reverse.
3. Implementation. remotion-best-practices for building the composition. Think in frames derived from fps, clamp every interpolate, use spring rather than linear, keep it deterministic with no Math.random or Date.now.
4. Render. remotion-render to produce the MP4.
5. Encode and deliver. ffmpeg for aspect variants and compression. 16:9 for site and YouTube, 9:16 for Reels and Shorts, 4:5 for feed. Autoplaying background video stays under 2MB with no audio track and a matching poster frame.

Query --motion -c video-pacing, -c remotion, -c audio-sound, and -c export-delivery at the relevant stage.

Captions are not optional. Most feed video is watched muted. Two lines maximum, 32 to 40 characters per line, keep everything inside 10 percent of every edge and out of the bottom 15 percent on vertical.

Report format

## What moves, and why

<the moment table: moment, question it answers, treatment>

## Signature
<the one characteristic, one line>

## Tokens
<the durations and curves added, as code>

## Changes
<file>:<line>
Was: <old>
Now: <new>
Why: <practice, one line>

## Not animated, on purpose
<what you left still and why>

## Verify
<exactly what to click, throttled, and what should happen>