gsap

GSAP Animation Skill

References (Official)

• GSAP Official
• GSAP Docs
• Easing Visualizer
• Common Mistakes
• React & GSAP
• ScrollTrigger

Basic Policy of This Skill

• Tool selection: Use CSS for simple animations that CSS can handle. Use GSAP when complex sequences/interactions/control are needed.
• Structure: Design in stages: Tween (single) → Timeline (sequence) → ScrollTrigger (scroll-linked).
• Performance: Assume requestAnimationFrame. Combining with CSS transition is strictly forbidden.
• License: All features became free (own license, commercial use OK) due to the 2024 Webflow partnership.
• React: useGSAP() Hook (@gsap/react) is officially recommended. A drop-in replacement for useEffect/useLayoutEffect.

Philosophy (Decision Rules)

1. Decide first whether to use CSS or GSAP — CSS is sufficient for simple effects like hover. Use GSAP when sequences/control/interactions are needed.
2. Manage sequences centrally with Timeline — Control using Timeline's relative timing rather than manually calculating delays.
3. Do not combine CSS transition and GSAP — Browser interruptions cause the worst performance.
4. Understand the default ease (power1.out) — Easing determines the "personality" of the animation.
5. ScrollTrigger is one-to-one — One animation per ScrollTrigger (combine multiple into a Timeline).
6. Cleanup is mandatory — Always remove scroll/resize listeners, timers, and event handlers.

Output Format (Always in This Order)

1. Recommended policy (1–3 lines)
2. Reason (expressive intent / performance / maintainability)
3. Design proposal (Tween/Timeline structure / Easing selection / ScrollTrigger design / React integration)
4. Checklist (confirm before implementation)
5. Pitfalls (to avoid)
6. Next actions (order of small experiments)

Checklist

• Have you first considered whether it can be achieved with CSS? (GSAP may be overkill)
• Is CSS transition applied to the animation target element? (conflict check)
• Is the Timeline created in advance? (better performance than creating it each time it's needed)
• Are you applying ScrollTrigger individually to Tweens inside a nested Timeline?
• will-change Are you providing pre-optimization hints via CSS properties?
• In a React environment, are you using useGSAP() + contextSafe() ?
• Is there cleanup on unmount (gsap.context().revert())?

Common Pitfalls

• Combining CSS transition and GSAP (worst performance, the browser always interrupts)
• Adding a Tween to a completed Timeline (it won't be called unless re-run)
• .from() Misconception (animation from specified value to current value; if incomplete, the intended endpoint is not reached)
• Applying ScrollTrigger to individual Tweens within a nested Timeline (the parent Timeline and scrollbar controls conflict)
• Excessive use of animation (impressive, but too much makes the UX chaotic)
• Import mistakes in a module environment (refer to the official installation guide)
• Event handlers in a React environment without contextSafe() (cleanup does not work)