motion-system

# Motion System Scattered motion is the loudest AI tell there is. Every element gets its own hover transition, every duration is a different number, half the page animates on scroll and the other half does not. The fix is not less motion -- it is fewer decisions, reused everywhere. Do this before writing any animation code. It takes ten minutes and every later animation becomes a lookup instead of a judgment call. ## Workflow 1. **Pick the temperature.** One choice that governs everything after: is this app *calm* (slower, softer easing, motion recedes -- dashboards, tools, finance), *crisp* (fast, tight, near-instant feedback -- productivity, developer tools), or *expressive* (larger movement, overshoot, motion is part of the brand -- marketing, portfolio, launch pages). Write the choice down. Mixing temperatures is what makes an app feel like three people built it. 2. **Define the tokens.** Three durations and three easings, no more. Put them where the rest of the design tokens live -- CSS custom properties or the Tailwind theme -- so no component ever writes a raw `300ms` again. Defaults per temperature are in `references/motion-tokens.md`; adjust, do not expand. 3. **Name the moves.** A short vocabulary the whole app reuses: - **enter** -- how new content arrives (one treatment, applied consistently: usually a small rise plus fade, 8-16px, never more) - **exit** -- how it leaves (faster than enter; nobody wants to wait for a goodbye) - **emphasis** -- how something says "look here" (scale or color shift, never both plus a rotate) - **feedback** -- press, hover, focus (fastest tier, under 150ms; this one must feel instant) - **transition** -- moving between views or states 4. **Set the reduced-motion policy now.** Decide per move what happens under `prefers-reduced-motion: reduce` -- usually: opacity survives, movement and scale do not, scrub-driven scroll effects become static. Write it as one global rule, not a per-component afterthought. 5. **Build one reference component.** Implement the moves once on a real component and use it as the pattern for everything after. Then delete any existing animation that does not draw from the system. ## Rules - Three durations, three easings. A fourth means the system failed, not that the case is special. - Never animate `top`, `left`, `width`, `height`, or `margin`. `transform` and `opacity` only -- everything else costs layout on the main thread. See `motion-perf`. - Motion communicates hierarchy and causality: *why* something moved, and *where it came from*. Motion applied because a library is installed is decoration, and decoration ages badly. - Fast in, slow out for entrances; the reverse reads as sluggish. Nothing on the interaction path exceeds 300ms. - Stagger lists, do not animate every item independently -- 40-60ms between items, capped so a long list does not take two seconds to appear. - The system is per-app, not universal. A trading dashboard and a launch page should not share durations.