/design-engineering motion

---

title: cmd-motion summary: "/design-engineering motion [remove | opportunities | audit] [target]" — decide whether motion should exist, then judge or build timing, easing, springs, transitions, gestures and stagger with concrete values; subtract over-animation, find the few places that should move, or audit a codebase into executable plans. tags: [command, motion, judge, decide, build, audit]

Posture: decide first, then judge (code in hand) or build (greenfield). The modes below change the posture; bare motion is judge or build.

Steps

1. Read animation-decision-framework. If the motion should not exist, recommend removing it, name the frequency or purpose test it fails, and stop.
2. Classify the pattern and open only its nodes:
   • enter or exit → easing-curves, duration-table, never-scale-from-zero, compose-subtract-asymmetry
   • hover or press → hover-states-subtle, responsive-feedback
   • drag, swipe or momentum → gesture-momentum, spring-animations
   • lists → stagger-choreography
   • a state change in place → fly-not-teleport, cross-blur-transitions
   • jank → the jank branch below
   • React Native or Expo → react-native-motion
   • a canonical CSS transition → the transitions.dev catalog, values checked against duration-table
3. Apply prefers-reduced-motion, gotchas and pov.

Build sequence (greenfield)

Run in order; steps 1–2 can end the job with zero code, which is a valid result.

1. Frequency gate — 100+/day or keyboard-triggered: stop.
2. Purpose — name one word from animation-decision-framework, or stop.
3. Tool — the cheapest that works (CSS transition → @starting-style → CSS animation → WAAPI → Motion).
4. Properties — transform/opacity; origin at the trigger (modals exempt) (transform-opacity-only).
5. Curve and duration, or a spring — from easing-curves, duration-table, spring-animations; never invent a value.
6. Interruption and exit — transitions for anything fired twice a second; exit along the entry path, quieter.
7. Reduced motion and hover gating — ship with the animation, not after.

Output the code, then three lines: gate result, ingredients, and what to feel-check (2–5× slow motion, real device) (debugging-animations).

Jank branch

Name the cause before changing code. Walk the diagnosis order in performance-discipline: property tier → busy main thread → per-frame React state → content-growth (inherited CSS variable) → animated CSS variable → blur over 20px → only then will-change. Report each finding as file:line · Cause · Before · After · Verified (from code / needs a device recording), ordered layout before paint, busy before idle.

motion remove

Subtract only; never add or retune. Walk every animation through the gate (keyboard → 100+/day → functional data → purpose → tens/day → over budget), recording the deciding branch. Check animation-removal-hazards before each delete or reduce, edit, clean up orphans, grep removed names. Report: Removed and reduced (location · was · verdict · branch), Kept with the purpose that saved each, badly built survivors handed to audit, then a one-paragraph verdict. Propose, never perform, a dependency removal.

motion opportunities

Read-only. Hunt feedback gaps, teleporting state, missing spatial story, all-at-once groups, physics-less gestures and flat rare moments. Every candidate passes four questions — frequency, purpose, speed (fits the budget), function (data being read doesn't move). Return at most 5–7 rows (location · today · purpose · frequency · exact motion values), a required Rejected list naming the question that killed each, and the single highest-leverage pick. "Nothing survives" is a good result.

motion audit

Read-only on source; writes plans only, under plans/.

1. Recon — stack and motion libraries, existing easing and duration tokens, product personality, a frequency map.
2. Audit eight categories: purpose and frequency, easing and duration, origin and physicality, interruptibility, performance, accessibility, cohesion and tokens, missed opportunities. Fan out read-only subagents per category on large repos.
3. Vet every finding at its file:line; drop by-design and exempt cases. One table by leverage, severity HIGH (feel-breaking) / MEDIUM / LOW. Stop for the user to pick.
4. Plan one self-contained file per pick, NNN-slug.md, stamped with git rev-parse --short HEAD: problem with current code quoted, exact target values, repo conventions with an exemplar, ordered steps, boundaries (stop if the code drifted), mechanical checks and a feel-check. Update plans/README.md with order and status.

Output

• Code in hand: the review-format table. Every After names its numbers: the duration in ms, the easing token or curve, the properties animated.
• Greenfield: the build-sequence output above, each value citing a node.

Hand-offs

A launch film's motion → cmd-film; launch-film values do not transfer to UI (launch-video-motion). An SVG that moves → cmd-svg animate. Sonner setup or bugs → sonner-usage. You may delegate to the motion-auditor subagent where the host has it.