Motion Craft

Motion Craft

Animation is not decoration you sprinkle at the end. It is how an interface explains itself: where things come from, where they go, and whether the software heard you. This skill makes two decisions well — which tool to reach for, and how to ship the motion with restraint, 60fps, and accessibility baked in.

Two Modes

Detect intent from the request and pick a mode. If unclear, ask which one.

• BUILD — "add an animation", "animate this", "make this feel premium", "transition between X and Y". Use the Tool Decision Gate, then the craft rules.
• REVIEW — "review my animations", "why does this feel janky/cheap/slow", "audit this motion". Skip straight to the Review Mode section and return the audit table.

When invoked with no specific task, respond only with one line: "Motion Craft ready — tell me what to animate, or point me at code to review." Do not dump the whole skill.

The First Question: should it move at all?

Most motion problems are solved by deleting the motion. Before anything else, weigh how often the user sees it against what the motion earns:

• Seen constantly (keyboard shortcuts, command palette, a toggle hit 100× a day) → no animation. Repetition turns delight into drag. Instant is the premium experience here.
• Seen often (hovers, list navigation, tab switches) → minimal and fast, or none.
• Occasional (modals, drawers, toasts, dropdowns) → standard, purposeful motion. This is the sweet spot.
• Rare / first-run (onboarding, success states, empty states) → you can afford delight.

Then demand a reason. Every animation must answer "what does this communicate?" Valid answers: orientation (where did this come from / go to), feedback (the click registered), continuity (don't pop things in and out — bridge the change), explanation (show how a feature works). "It looks cool" is only a valid reason for rare, first-run moments. Everywhere else, cool-for-its-own-sake is friction wearing a nice coat.

Tool Decision Gate

Climb this ladder only when the rung below genuinely can't express what you need. Reaching for a JS library when a CSS transition would do is the most common over-engineering in motion.

Default ladder: CSS → View Transitions → Motion → GSAP. Lottie is sideways — only for AE exports. The code for each lives in references/recipes.md; load it when you actually write.

Easing — the single biggest lever on "feel"

Easing decides whether motion feels intentional or accidental. The browser defaults (ease, ease-in, ease-out) are weak — they lack the punch that reads as crafted. Define custom curves and reuse them as tokens.

:root {
  --ease-out-expo:  cubic-bezier(0.16, 1, 0.30, 1);   /* entrances: snaps in, settles soft */
  --ease-in-out:    cubic-bezier(0.65, 0, 0.35, 1);   /* on-screen movement / morph */
  --ease-drawer:    cubic-bezier(0.32, 0.72, 0, 1);   /* iOS-ish sheets & drawers */
}

Pick the curve by what the element is doing:

The hard rule: never ease-in on anything the user is waiting to see or interact with. ease-in delays the visible start, so a dropdown opening with ease-in feels slower than the same duration with ease-out, even though the clock says otherwise. ease-in is allowed in exactly one place: an element accelerating completely off-screen.

Duration — fast, with intent

Keep interactive UI under ~300 ms. Two craft details that punch above their cost: exits are quicker than entrances (the user already decided — get out of the way), and perceived speed beats real speed — a snappier spinner makes a load feel faster even when the millisecond count is identical.

Springs — for motion that can be interrupted

Springs simulate physics, so they have no fixed duration — they settle. Their superpower is interruptibility: a spring keeps its velocity when you reverse it mid-flight, while a CSS keyframe restarts from zero. Use them for drag/gesture, anything "alive", and interactions a user can change halfway.

// Motion (motion/react)
transition={{ type: "spring", duration: 0.5, bounce: 0.2 }}   // Apple-style — easier to reason about
transition={{ type: "spring", stiffness: 300, damping: 30 }}  // classic physics — more control

Keep bounce subtle (0.1–0.3) and reserve it for playful or drag-to-dismiss moments. Bounce on a professional dashboard reads as toy-like. Match the motion to the product's mood.

Non-negotiable rules

1. Animate only transform and opacity for anything that moves or fades. They are GPU-composited — they skip layout and paint. Animating width, height, top, left, margin, or padding triggers reflow and drops frames. Move with translate()/scale().
2. Honor prefers-reduced-motion: reduce — always. Reduced does NOT mean none: keep opacity/colour transitions that aid comprehension, drop the movement (translation, scale, parallax, spin). This is accessibility, not a nice-to-have.
3. Restraint. One orchestrated hero moment beats ten scattered micro-animations. Motion directs attention; if everything moves, nothing is signal.
4. Never animate from scale(0). Nothing in the real world appears from a literal point. Start at scale(0.95) paired with opacity so the entrance has a shape.

Micro-interactions & components

• Pressables feel responsive when they react to touch: :active { transform: scale(0.97) } with a ~120 ms ease-out. Subtle (0.95–0.98), but the UI now "listens".
• Popovers scale from their trigger, not their center. Default transform-origin: center is wrong for anything anchored. With Radix/Base UI, bind it to the provided CSS variable (e.g. var(--radix-popover-content-transform-origin)). Modals are the exception — they aren't anchored, so they stay centered.
• Stagger grouped entrances by 40–80 ms per item for a cascade that feels alive without feeling slow. Stagger is decorative — never block interaction while it plays.
• Mask imperfect crossfades with a touch of blur (≤ 8 px) during the transition so the eye reads one morph instead of two overlapping states. Heavy blur is expensive, especially in Safari.

Performance

• CSS / WAAPI run off the main thread; JS requestAnimationFrame does not. When the page is busy (loading, hydrating, painting), JS-driven motion drops frames while CSS stays smooth. Use CSS or the Web Animations API for predetermined motion, JS libs for dynamic/interruptible.
• will-change is a loan, not a gift. It promotes an element to its own layer; leave it on everything and you blow the memory budget. Apply right before the animation, remove after.
• In Motion, the shorthand x/y/scale props are convenient but go through the main thread. For motion that must survive jank, animate the full transform string.

Accessibility

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
  }
}
/* Then re-enable gentle, comprehension-aiding fades deliberately where needed. */

Gate hover-driven transforms so touch devices don't fire them on tap:

@media (hover: hover) and (pointer: fine) {
  .card:hover { transform: translateY(-2px); }
}

Review Mode

When auditing existing motion, scan for the smells below and return a markdown table with exactly these columns: Smell · Fix · Why. One row per issue. Be specific — quote the offending value and give the replacement.

For a fast first pass over a codebase, run the bundled scanner — pure, dependency-free, and read-only (it never writes or phones home):

node skills/motion-craft/scripts/audit-motion.mjs [path]   # exits non-zero if issues found → CI-friendly

It prints file:line findings; then deepen the audit by hand using the full catalog in references/anti-patterns.md.

Reference Map (load on demand)

Pull these in only when the task needs them — keep the base skill lean.

Output Contract

Every BUILD answer states: the tool chosen and why (which rung of the ladder), the properties animated (must be transform/opacity for anything moving), the easing + duration, and the prefers-reduced-motion fallback. Every REVIEW answer is the Smell · Fix · Why table — nothing animated is signed off without a reduced-motion story.