Motion

Condensed from: emilkowalski/skills (https://github.com/emilkowalski/skills): animate, review-animations, improve-animations, find-animation-opportunities, animation-performance, animation-vocabulary, emil-design-eng

1. Gate: should it animate at all?

• Keyboard-initiated actions never animate (Raycast has no open/close animation; correct).
• Name the purpose in one word: feedback, spatial consistency, state indication, preventing a jarring change, explanation (marketing only), delight (rare tier only). Can't name it: don't build it.
• Data the user reads or acts on (dashboard charts, tables) does not move for style.
• Cheapest tool that works: CSS transition → @starting-style → CSS keyframes (predetermined, stays smooth while page is busy) → WAAPI el.animate() → Motion (springs, layout, exit, gestures). No library for a fade.
• Reuse the codebase's easing/duration tokens; never fork a parallel set.

2. Duration

UI stays under 300ms unless it is a drawer or marketing. A 180ms dropdown feels faster than a 400ms one.

3. Easing

:root {
  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);     /* enter, exit, default */
  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1); /* moving/morphing on screen */
  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);  /* iOS-like sheet */
}

• Enter/exit: ease-out. On-screen move: ease-in-out. Hover/color: ease. Progress, marquee, hold-fill: linear.
• Never ease-in on UI: it stalls the first frames, the exact moment the user watches.
• Built-in keywords are too weak for deliberate motion. Need another curve: take one from easing.dev or easings.co; don't invent or default to cubic-bezier(0.4,0,0.2,1).

4. Springs

Use when a pointer/finger drives it, it can be interrupted or reversed, it should feel alive, or it is decorative pointer-tracking.

Bounce 0.1-0.3 max and only when the gesture carried momentum. A menu that faded in never overshoots. Pointer-follow: useSpring(v, { stiffness: 100, damping: 10 }), not raw mapping.

5. Properties and physicality

• Animate transform + opacity. clip-path is the sanctioned fourth. height only for short accordions. Never width/height/margin/padding/top/left. Animated box-shadow → filter: drop-shadow().
• Never transition: all; list properties.
• Never scale(0). Enter from scale(0.95-0.97) + opacity: 0.
• Popovers, dropdowns, tooltips, menus scale from the trigger: transform-origin: var(--transform-origin) (Base UI) or var(--radix-popover-content-transform-origin) (Radix). Modals stay center.
• translateY(100%) is relative to the element itself; prefer over px for sheets/toasts.
• Motion x/y/scale shorthands run on the main thread. If the animation plays during route changes or hydration, use animate={{ transform: "translateX(100px)" }}.
• Never drive child transforms through a CSS variable on a parent (style recalc on every descendant). Set transform on the element.
• React: no setState per frame. Write ref.current.style.transform or a motion value.
• Animated blur under 20px (2-5px is enough). will-change: transform only after you see a 1px shift or measured drops.
• Frame budget: 16.7ms at 60Hz, 8ms at 120Hz. Judge on a mid-range phone.

6. Enter/exit, interruption, stagger

• Transitions retarget from the current value; keyframes restart from zero. Anything fired rapidly (toasts, toggles, expand) uses transitions or springs.
• Exit the way it entered (in from bottom, out through bottom).
• Asymmetry: slow where the user decides, snappy where the system answers. Hold-to-delete: 2s linear press, 200ms ease-out release. Exits faster than enters.
• Never lock input mid-transition; start new motion from the on-screen value.
• Stagger is decorative: 30-80ms, never blocks interaction, never on lists seen all day.
• Tooltips: delay the first; once one is open, neighbours open with transition-duration: 0ms.
• Crossfade shows two objects? Add filter: blur(2px) during the swap.
• Scroll reveal: marketing only, fire once (useInView(ref, { once: true, margin: "-100px" })).

7. Reduced motion and hover gating (ship with the animation)

@media (prefers-reduced-motion: reduce) {
  .panel { transition: opacity 200ms ease; transform: none; }
}
@media (hover: hover) and (pointer: fine) {
  .card:hover { transform: translateY(-2px); }
}

Reduced means fewer and gentler, not zero: keep opacity/color, drop translate, scale, parallax, overshoot. React: const reduce = useReducedMotion().

8. Perceived performance

• Feedback on :active / pointerdown, never only on click.
• ease-out at 200ms feels faster than ease-in at 200ms.
• A faster-spinning spinner makes the same load feel shorter.
• Skeletons must match the final layout exactly.

9. Vocabulary (prompt with the exact word)

Origin-aware animation · Scale in vs Pop in (overshoot) · Reveal (clip-path/mask) · Crossfade vs Morph vs Shared element transition vs Layout animation · Direction-aware transition · Stagger · Orchestration · Rubber-banding · Momentum · Velocity handoff · Interruptible animation · Swipe to dismiss · Hold to confirm · Text morph · Number ticker + tabular numbers · Skeleton/shimmer · Perceptual duration · Asymmetric easing · Anticipation · Follow-through.

10. Review checklist

Block on: animation on a keyboard/100+/day action · ease-in on UI · scale(0) · transition: all · UI >300ms without reason · centered origin on a trigger-anchored popover · keyframes on toasts/toggles · layout-property animation · Motion shorthands on busy pages · parent CSS var driving child transforms · ungated :hover motion · no reduced-motion · symmetric press/release timing · everything entering at once. Fix order: delete → reduce → easing → origin → interruptible → GPU → asymmetry → polish → a11y. Feel-check at 2-5× duration, frame by frame, on a real device, again next day.

11. Recipes

Button press

.btn { transition: transform 160ms var(--ease-out); }
.btn:active { transform: scale(0.97); }

Tailwind: transition-transform duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] active:scale-[0.97]

Dropdown from its trigger (Base UI)

.menu {
  transform-origin: var(--transform-origin);
  transition: opacity 200ms var(--ease-out), transform 200ms var(--ease-out);
}
.menu[data-starting-style], .menu[data-ending-style] { opacity: 0; transform: scale(0.95); }

Tailwind v4: origin-(--transform-origin) transition duration-200 data-[starting-style]:scale-95 data-[starting-style]:opacity-0 data-[ending-style]:scale-95 data-[ending-style]:opacity-0

Toast enter (prefer Sonner over hand-rolling)

.toast {
  transition: transform 400ms ease, opacity 400ms ease;
  @starting-style { opacity: 0; transform: translateY(100%); }
}

Transitions, not keyframes, so a new toast retargets the stack mid-flight. Exit through the same edge.

Drawer with flick-to-dismiss

.drawer { transition: transform 500ms var(--ease-drawer); }
.drawer[data-closed] { transform: translateY(100%); }

el.style.transform = `translateY(${dy}px)`;           // during drag, on the element itself
const v = Math.abs(dy) / (Date.now() - startTime);   // px/ms
if (dy > THRESHOLD || v > 0.11) close(); else snapBack();

Pointer capture on start, ignore extra touches, rubber-band past the top edge.

Skeleton shimmer done right

.skel { position: relative; overflow: hidden; background: var(--gray-3); border-radius: inherit; }
.skel::after {
  content: ""; position: absolute; inset: 0;
  background: linear-gradient(90deg, transparent, rgb(255 255 255 / .35), transparent);
  transform: translateX(-100%);
  animation: shimmer 1.4s linear infinite;
}
@keyframes shimmer { to { transform: translateX(100%); } }
@media (prefers-reduced-motion: reduce) { .skel::after { animation: none; } }

Shimmer moves via transform (composite only), not background-position (repaints). Same box sizes as the loaded content so nothing shifts.

Number ticker

import NumberFlow from "@number-flow/react";
<NumberFlow value={total} format={{ style: "currency", currency: "USD" }} />

Always font-variant-numeric: tabular-nums (Tailwind tabular-nums). Never re-render text per frame through state.

Height auto (accordion)

<AnimatePresence initial={false}>
  {open && (
    <motion.div
      initial={{ height: 0, opacity: 0 }}
      animate={{ height: "auto", opacity: 1 }}
      exit={{ height: 0, opacity: 0 }}
      transition={{ duration: 0.2, ease: [0.23, 1, 0.32, 1] }}
      style={{ overflow: "hidden" }}
    />
  )}
</AnimatePresence>

CSS-only: display: grid; grid-template-rows: 0fr → 1fr with transition: grid-template-rows 200ms var(--ease-out) and min-height: 0 on the child, or use the primitive's measured var (--radix-accordion-content-height). Keep it short: height costs layout every frame.

Hold to confirm

.fill { clip-path: inset(0 100% 0 0); transition: clip-path 200ms var(--ease-out); }
.hold:active .fill { clip-path: inset(0 0 0 0); transition: clip-path 2s linear; }

Read by your agent through get_guide("motion") in the taste MCP.