Motion Engine

Rule: intent first, engine second

Read references/tool-router.md and references/capability-matrix-2026.md and choose the smallest engine that cleanly implements the interaction.

Native first

Use CSS transitions/keyframes, WAAPI, CSS Scroll-Driven Animations or View Transitions when they cover the behavior cleanly.

Motion

Prefer for React state/layout/shared-layout, presence, gestures, springs and common scroll-linked UI motion. Read references/motion.md.

Anime.js

Prefer for precise lightweight timelines, staggered choreography, SVG/text/value animation and deterministic sequencing. Read references/animejs.md.

GSAP

Prefer for advanced multi-part timelines, ScrollTrigger pin/scrub, Flip, SplitText, MotionPath and complex scroll/DOM/3D orchestration. Read references/gsap-lenis.md.

Lenis

Use only when smooth scrolling or a normalized scroll signal is an intentional part of the experience. Native scroll remains the default.

Cross-engine discipline

• Do not install two engines that solve the same job unless distinct capabilities are actively used.
• If multiple systems animate in the same frame, coordinate update loops rather than creating uncontrolled RAF competition.
• Preserve logical state when motion is disabled.
• Keep transform/opacity animation compositor-friendly where possible; avoid layout thrash in scroll handlers.
• Pause offscreen or nonessential animation.

Output

For notable motion, record: Intent → Engine → Why → Reduced-motion behavior → Performance risk.