motion alive, fast, cheap

Motion exists to explain cause and effect, keep spatial continuity, or confirm an action. Rarely, it is delight. Most great sites animate far less than generated ones: Emil Kowalski's homepage animates nothing; Vercel had nothing moving 3.5s after load. Performance rules for animation live in speed. Library effects (marquee, spotlight, border beam, number ticker, aurora) and how to source them live in components. This skill decides what moves, how, and how much.

Principles below are paraphrased after Emil Kowalski (animations.dev, emilkowal.ski/ui); recipe portions adapted from emilkowalski/skills (MIT, see references/CREDITS.md).

The 12 rules

1. Frequency decides. 100+ times a day (⌘K, shortcuts, list arrow keys, tab switching by keyboard): no animation. Tens a day (hover, menus): near-instant. Occasional (dialog, toast, drawer): standard. Rare (first visit hero, success moment): delight allowed.
2. Name the purpose before writing it: feedback, spatial continuity, state change, explanation, or (rare) delight. "Looks cool" is not a purpose.
3. UI motion ≤ 300ms. Press 100–160ms, tooltip 125–200, dropdown 150–250, dialog/drawer 200–500. Marketing entrances may run 300–600ms (measured reveals: Supabase 400, Stripe 500, Granola 600, Mercury 670).
4. Enter with ease-out, exit ~25% faster. Never ease-in on UI (lint/ease-in-enter). Built-in ease-out is too weak; void's ease-out token is cubic-bezier(0.23, 1, 0.32, 1).
5. Nothing appears from scale(0). Start at scale(0.95–0.97) + opacity: 0 (lint/scale-zero-entry).
6. Origin-aware. Popovers, menus and tooltips grow from their trigger (transform-origin from the primitive). Dialogs are the exception: centered.
7. Transitions for state, keyframes for autonomous motion. Transitions retarget when interrupted; keyframes restart from zero. Toggles, toasts and tabs use transitions.
8. Compositor-only. Animate transform/translate/scale/rotate and opacity. Never width, height, top, left, margin, box-shadow (lint/animate-layout-prop, smooth/animate-layout-property). Never transition: all (lint/transition-all).
9. Stagger 30–60ms per item, ≤ 6 items, ≤ 300ms total. Never block input while it plays. Only on first reveal, never on re-render or filter.
10. Reduced motion = a finished static frame, never hidden content. Movement goes; short opacity may stay (lint/no-reduced-motion, smooth/reduced-motion-ignored).
11. Budget: one signature effect + at most one secondary per page; T0–T1 by default; ≤ 1 WebGL context; 0 decorative effects on app routes. 1–3 scroll reveals per page, not every section.
12. Never hide the LCP. The hero H1 and hero image render visible at first paint. Animate secondary elements, or move the H1 without fading it.

1. Tokens

Durations are plain CSS variables (set by the direction; reduced motion zeroes base, slow, slower). Use them with the v4 syntax duration-(--duration-fast), never duration-[--duration-fast].

Full decision flow, distance scaling and spring configs: references/timing.md.

2. Should it animate? (answer in order)

Is it triggered by keyboard or used 100+ times/day? ── yes → no animation (0ms)
Does it show cause→effect, continuity or state change? ── no → is it a rare, first-visit moment? ── no → don't animate
Can CSS do it (transition, @starting-style, keyframes, view()) ? ── yes → CSS (T1)
Is it gesture-driven, layout/shared-element, or exit orchestration? ── yes → motion library (T2, LazyMotion)
Is it a generative visual (particles, shader)? ── only as the page's one signature → T3/T4 with webgl-canvas rules

3. Effect tiers and budgets

Default to T0–T1. A page with a T3/T4 signature has no other T2+ effect. Every infinite animation pauses offscreen (speed → PauseOffscreen) and has a reduced-motion frame.

4. Interaction patterns (summary; code in references/recipes.md)

5. Load and scroll choreography (marketing)

• Load: animate hero text only, once, ≤ 600ms total: eyebrow/sub/CTA rise 8–12px with 40–60ms stagger; the H1 either static or translate only (no opacity from 0). Measured: Paco 600ms 7-step enter, Attio 500ms. Never a preloader (hellohello's ~8s intro is the anti-pattern).
• Scroll: 1–3 set pieces per page. Use the reveal utility (CSS scroll-driven view(), 12px rise + fade, runs off the main thread in Chromium and Safari 26; Firefox and reduced motion get the static, fully visible element). Not on body copy, not on every section, never on the hero.
• Scrubbed or pinned scenes: at most one per page (position: sticky track + CSS view-timeline, or one useScroll), transform-only, never pinning native scroll with JS.
• Ambient loops (marquee, pulse, shimmer): 2–6s pulses, 30–180s marquees, paused offscreen, pausable (WCAG 2.2.2 for > 5s movement), static under reduced motion.

6. Scroll-driven animations and View Transitions

Keyframes own the from-state. A browser without animation-timeline drops the entire @supports block, keyframes included — so any hidden value (opacity: 0, a collapsed scale, an off-screen translate) that lives outside that block is never undone, and the content is gone permanently for that audience. Firefox has no scroll-driven animation support at all, which is roughly 3% of the web and 100% of a Firefox user's experience. smooth/scroll-timeline-no-fallback and lint/scroll-timeline-no-fallback catch it; the rule, the two-render diff behind the check and the correct patterns are in references/fallbacks.md.

View Transitions: page-level ≤ 400ms (--duration-slower or less), ≤ 10 named elements, disabled under reduced motion (base's reduced-motion rule + speed snippet). React 19.2 + next/link transitionTypes in Next 16: references/recipes.md §11.

7. CSS or the motion library?

Use CSS unless you need one of: gesture with velocity (drag, swipe, throw), layout / shared-element animation (layout, layoutId), exit animations of React-unmounted trees with orchestration, or springs that must retarget mid-gesture.

"use client";
import { LazyMotion, MotionConfig } from "motion/react";
import * as m from "motion/react-m";
const features = () => import("@/lib/motion-features").then((mod) => mod.default); // export { domAnimation as default } from "motion/react";

export function Sheet({ children }: { children: React.ReactNode }) {
  return (
    <LazyMotion features={features} strict>
      <MotionConfig reducedMotion="user">
        <m.div initial={{ transform: "translateY(100%)" }} animate={{ transform: "translateY(0%)" }}
          transition={{ type: "spring", duration: 0.45, bounce: 0 }}>{children}</m.div>
      </MotionConfig>
    </LazyMotion>
  );
}

• LazyMotion + m (+32 KB measured on Next 16.3.5), never motion.div (+46 KB) or framer-motion. From motion/react import only LazyMotion, MotionConfig, domAnimation/domMax and hooks; elements come from motion/react-m (this is what speed means by banning motion imports on marketing routes). One animation runtime per app; no GSAP next to motion.
• Prefer a full transform string over x/y/scale shorthands for motion that runs while the page is busy.
• Springs: { type: "spring", duration: 0.35–0.5, bounce: 0 } for UI; bounce 0.1–0.25 only for playful moments. Near-critical damping, no multi-second settles.
• Never .on("change") or timers in render (lint/motionvalue-subscribe-in-render, lint/timer-in-render); per-frame values via MotionValues or element.style, never React state.
• Scope layoutId with useId().

8. Smooth scroll, scroll-jacking, parallax

Default: none. No Lenis, locomotive-scroll, GSAP ScrollSmoother or pinning. Why: smooth-scroll libraries move scrolling onto the main thread (any long task freezes scroll), add a permanent rAF loop (~10 KB + CPU), override OS scroll physics and accessibility settings, and break in iframes and nested scrollers. Only agency showreels use them (hellohello, Dia, Framer); zero measured SaaS sites do.

If the user explicitly insists (portfolio/agency showreel): one instance mounted in the root layout; lerp ≥ 0.08; disabled under prefers-reduced-motion and on touch; destroyed in cleanup; route passes TBT ≤ 100ms (perf/tbt-high); nested scroll areas marked data-lenis-prevent; document the exception in the design statement.

Parallax: ≤ 6% translate via CSS view() on one image per viewport; none under reduced motion.

9. Canvas and WebGL

Only as the page's single signature, and only if all of references/webgl-canvas.md holds: one context, never in .map(), DPR ≤ 1.5 (1 for backdrops), ≤ 30fps, cancel rAF offscreen and when hidden, static frame under reduced motion, context-loss handlers, next/dynamic with ssr: false, a CSS fallback matching the average color. The WebGL2 hook is in speed/references/rendering-smoothness.md §8; the 2D canvas hook and design rules are in references/webgl-canvas.md. Try the CSS downgrade first (inspire/references/effect-downgrades.md). For a 3D object that moves with the scroll, use OGL (~14 KB gzip) with procedural geometry, never three.js/r3f/Spline on marketing routes (131–520 KB+). Follow references/3d-scenes.md.

For section backgrounds specifically (a hero or section sitting on an alive surface rather than flat --bg) — decision table by evoked feeling and measured cost tier, the cheap CSS/SVG ladder to try first, the one-shared-context multi-section pattern, and paste-ready OGL implementations (fluid distortion, particle field, pixel/dither grid, displacement grid): references/backgrounds.md.

10. Verify

1. void lint: lint/transition-all, lint/animate-layout-prop, lint/scale-zero-entry, lint/ease-in-enter, lint/long-ui-duration, lint/no-reduced-motion, lint/raf-without-cancel, lint/webgl-in-map, lint/will-change-static, lint/tw-v3-arbitrary-var.
2. bun run build, then void smooth --start "bun run start -p 3100" --port 3100: smooth/long-frames-during-scroll, smooth/raf-loop-idle, smooth/multiple-webgl-contexts, smooth/reduced-motion-ignored.
3. Watch each animation at 0.25× speed (DevTools → Animations) and once with OS reduced motion on. Check it again the next day with fresh eyes.

References

• references/recipes.md — paste-ready CSS/TSX for every pattern above
• references/timing.md — durations, easing decision flow, distance, stagger, springs
• references/webgl-canvas.md — when a canvas is justified, 2D hook, token → uniform colors, fallbacks
• references/3d-scenes.md — scroll-linked 3D: measured library costs, lazy-loaded OGL SceneCanvas, render-on-demand, asset pipeline
• references/backgrounds.md — section backgrounds: decision table, cheap-first ladder, shared-context pattern, measured CSS + OGL implementations
• references/fallbacks.md — what a browser without scroll-driven animations renders; the keyframes-own-the-from-state rule and the checks that enforce it
• references/CREDITS.md — attribution and MIT notice for adapted material