React Motion Engineering

Motion is a usability tool. It must not compromise accessibility, lifecycle correctness, responsiveness, or frame performance.

Apply react-production-engineering and react-component-engineering alongside this skill.

Tool hierarchy

Choose the simplest tool that communicates the state change:

1. no animation when it adds no meaning;
2. CSS transitions/keyframes for simple transitions;
3. Web Animations API when appropriate to the existing stack;
4. GSAP for complex sequencing, scroll linkage, SVG, drag, or high-frequency interactive animation.

Do not add GSAP for a basic hover/fade.

Workflow

1. Define the purpose of the motion and the no-animation fallback.
2. Determine reduced-motion behavior before implementation.
3. Choose CSS/platform/GSAP based on complexity.
4. Keep animation ownership aligned with component ownership and cleanup lifecycle.
5. Prefer transform/opacity for continuous animation and measure expensive effects.
6. Verify keyboard/touch behavior and multiple responsive layouts.
7. Test on realistic lower-powered/mobile hardware for important motion.

Non-negotiable rules

• Respect prefers-reduced-motion for non-essential motion.
• Content and controls must remain usable when animation is disabled or fails.
• Do not use scroll-jacking for ordinary content navigation.
• Do not create a new tween on every pointer event in a high-frequency path.
• Clean up timelines, observers, listeners, and ScrollTrigger instances when their owner unmounts.
• Do not make animation callbacks the only mechanism that completes business-critical state.
• Hover animation must not be the only interaction feedback; preserve focus/touch/selected states.

When to load references

• GSAP + React lifecycle: references/gsap-react.md
• Reduced motion: references/reduced-motion.md
• Scroll motion: references/scroll-animation.md
• Animation performance: references/performance.md