Principles

• Physics-based motion (useSpring, springs.*) always feels more natural than duration-based for direct manipulation.
• useMotionValue + useTransform computes derived values without triggering re-renders.
• useAnimate sequences are imperative and interrupt-safe — calling animate() mid-flight cancels the previous animation automatically.
• Motion values (useMotionValue, useSpring) are SSR-safe and do not cause hydration errors.

Rules

1. Drag interactions must be tested on touch devices, not just mouse. drag prop works on both but feel and threshold differ.
2. Infinite animations must pause when document.visibilityState === "hidden". Background tabs must not consume GPU/CPU.
3. Swipe threshold must be explicit. Never infer intent from velocity alone; combine offset + velocity checks.
4. useAnimate scope ref must be attached to a mounted DOM element. Calling animate() before mount throws silently.
5. Motion values must not be recreated on render. useMotionValue(0) inside a component body is correct; new MotionValue(0) in a render is not.
6. All token values are imported from motion-foundations. No inline numbers.
7. Custom hooks must handle cleanup. Every window.addEventListener needs a matching removeEventListener in the useEffect return.
8. SVG morphing requires equal path command counts. Paths with different command structures snap instead of interpolating.

Decision Guidance

Choosing the right advanced API

When to use useSpring vs a spring transition

…

motion-foundations

为 React/Next.js 动效系统建立规范基座，统一令牌、弹簧预设、性能与无障碍规则。