Motion

Motion explains change: where something came from, what it relates to, what just happened. If it explains nothing, cut it.

1. Presets, not ad-hoc values

Keep one presets file ({{MOTION_DIR}}/presets) with named recipes, e.g. fadeUp, stagger, reveal, parallax, plus durations and easings. Each theme or product picks a feel:

Feel	Durations	Easing	Use for
Calm	200–400 ms	ease-out	studio, content sites
Playful	spring, slight overshoot	spring	games, consumer apps
Precise	120–200 ms	sharp ease-in-out	tools, dashboards

2. Thin wrappers

Pages assemble wrappers instead of calling libraries directly: <Reveal>, <Stagger>, <ScrollScene> (pin + scrub), <Marquee>, <Counter>. Swapping a library later touches only the wrappers.

3. Reduced motion is a first-class design

• Read prefers-reduced-motion (e.g. useReducedMotion, gsap.matchMedia).
• When set: no parallax, no smooth-scroll hijack, no auto-play, no large movement. Fades ≤ 150 ms or none.
• The reduced version must still look finished, not broken.

4. Performance

• Animate only transform and opacity. Never width/height/top/left/margin.
• Heavy libraries (scroll timelines, 3D, Lottie) load via dynamic import only on pages that use them.
• No layout thrash: read then write; avoid animating during scroll handlers without rAF/IntersectionObserver.
• Target 60 fps on a mid-range phone and Lighthouse mobile ≥ {{LIGHTHOUSE_TARGET}}.
• The LCP element is real HTML text/image, never behind an entrance animation.

5. Taste rules

• One hero moment per page; everything else is quiet.
• Enter: ease-out. Exit: ease-in and faster than enter.
• Stagger lists by 30–60 ms; cap the total under ~600 ms.
• Hover feedback ≤ 150 ms. Never delay a click response for an animation.
• Scroll-pinned sections only where they tell a story; never on every section.
• Nothing flashes more than 3 times per second.

Review checklist

• Uses presets and wrappers only
• transform/opacity only
• Reduced-motion path checked in the browser
• Heavy libs dynamically imported
• 60 fps in a performance trace; Lighthouse target met

Customize for your project

{{MOTION_DIR}}, {{MOTION_LIBRARY}} (e.g. Motion, GSAP), the feel per theme, {{LIGHTHOUSE_TARGET}} (e.g. 90).