GSAP Animations Skill

Create production-grade GSAP animation components that transform static interfaces into memorable, tactile experiences. Every animation should feel intentional, physically grounded, and choreographed — not decorative.

Quick Reference — Read Before Building

Before writing any animation code, read the relevant reference files based on the task:

Task	Reference File
Any GSAP component	references/core-patterns.md ← ALWAYS read this first
Page load / intro sequences	references/loading-animations.md
Scroll-driven effects	references/scroll-animations.md
Page transitions (between pages)	references/page-transitions.md
Navigation / menu animations	references/navigation-animations.md
Text reveals, splits, loops	references/text-animations.md
React / Next.js / Astro setup	references/framework-adapters.md
Responsive scaling system	references/scaling-system.md

Read references/core-patterns.md for EVERY task — it contains the universal rules that all components must follow.

Design Philosophy

These animations work because they follow three principles:

1. Choreography over decoration. Every element enters with purpose. Timelines orchestrate 5-15 elements into a single cohesive motion, not isolated bounces. The "<" position parameter is used extensively to run tweens in parallel with fine-grained offsets — this is what makes complex sequences feel like one fluid gesture.

2. Physical grounding. Motion feels real because it references physics — elastic overshoot on a word carousel, gravity on falling text, parallax depth on slideshows. Easing choices define personality: expo.inOut for dramatic power, expo.out for confident arrivals, elastic.out for playful mechanics, and custom eases for signature motion.

3. Invisible infrastructure. Users never see loading flicker, broken font metrics, or scroll jank. Class-based state gating (is--hidden → is--loading → final) prevents flash. document.fonts.ready protects SplitText measurements. Lenis syncs smooth scroll with ScrollTrigger via a shared ticker. The animation code that users DO see is built on defensive infrastructure they don’t.

Component Architecture

Every GSAP component follows this structure:

1. Register plugins at file top
2. Define custom eases
3. Wrap in an init function
4. Query DOM with defensive null-checks
5. Build timeline(s)
6. Gate initialization (DOMContentLoaded + fonts.ready if text)

gsap.registerPlugin(ScrollTrigger, SplitText, CustomEase);
CustomEase.create("smooth", "0.625, 0.05, 0, 1");

function initMyComponent() {
  const container = document.querySelector(".my-component");
  if (!container) return;

  const elements = container.querySelectorAll(".my-element");
  const heading = container.querySelector("h1");

  // Timeline with shared defaults
  const tl = gsap.timeline({
    defaults: { ease: "expo.inOut", duration: 1.2 },
    onStart: () => container.classList.remove("is--hidden"),
  });

  // Defensive checks before each animation block
  if (elements.length) {
    tl.fromTo(elements,
      { yPercent: 100, opacity: 0 },
      { yPercent: 0, opacity: 1, stagger: 0.05 }
    );
  }
}

document.addEventListener("DOMContentLoaded", () => {
  document.fonts.ready.then(() => initMyComponent());
});

Core Rules

These rules apply to every GSAP component. Violating them produces the jank, flicker, and breakage that separates amateur animations from production ones.

State Management

• Use class-based state gating: is--hidden (display:none initially) → remove on onStart → is--loading removed on complete
• Store interactive state on DOM with data-* attributes (e.g., data-nav-state="open")
• Use data-* attributes for component targeting — never rely on class names that may change

Timeline Construction

• Use gsap.timeline() with defaults for shared easing and duration
• Position tweens with "<" (start of previous) and "< 0.2" (offset from previous start) for parallel choreography
• Use fromTo for explicit start states — never assume DOM state
• Wrap every animation block in if (elements.length) guards

Performance

• Use xPercent / yPercent over pixel values — they’re resolution-independent
• Use autoAlpha instead of opacity — it toggles visibility: hidden at 0, removing elements from accessibility tree
• Keep will-change in CSS for known animated properties, never set it via JS
• Use em units in CSS for dimensions that should scale responsively

Easing Vocabulary

Feel	Ease	Use Case
Dramatic power	expo.inOut	Loading sequences, hero reveals
Confident arrival	expo.out	Content entering viewport
Snappy interface	CustomEase("0.65, 0.01, 0.05, 0.99")	Nav toggles, UI state changes
Playful mechanic	elastic.out(1, 0.85)	Carousels, slot-machine effects
Smooth wipe	CustomEase("0.625, 0.05, 0, 1")	Slideshow transitions, panel reveals
No ease (physics)	"none"	When Physics2D or real physics handles motion

Stagger Patterns

Pattern	Config	Effect
Cascade	{ each: 0.05 }	Sequential wave
Spread	{ amount: 0.75, from: "random" }	Pixelated / organic
Pinch	{ each: 0.05, from: "edges" }	Edges-first convergence
Reveal	{ each: 0.025 }	Fast letter-by-letter

Plugin Reference

Plugin	CDN	Purpose
gsap core	gsap@3.13.0/dist/gsap.min.js	Timeline, tweens, easing
ScrollTrigger	gsap@3.13.0/dist/ScrollTrigger.min.js	Scroll-driven animation
SplitText	gsap@3.13.0/dist/SplitText.min.js	Text splitting + masked reveals
CustomEase	gsap@3.13.0/dist/CustomEase.min.js	Custom easing curves
Physics2DPlugin	gsap@3.13.0/dist/Physics2DPlugin.min.js	Gravity, velocity, angle-based motion
Lenis	lenis@1.2.3 (separate)	Smooth scroll, syncs with GSAP ticker

CDN base: https://cdn.jsdelivr.net/npm/

CSS Foundation

Every GSAP component needs these CSS patterns:

/* State gating — prevent flash of unstyled content */
.component.is--hidden { display: none; }

/* Scroll lock during loading */
main:has(.component.is--loading) { height: 100dvh; }

/* Masked reveal containers */
.reveal-container { overflow: hidden; }

/* Animated elements */
.animated-element {
  will-change: transform;
}

Error Handling

• Missing DOM elements: Every querySelectorAll result must be guarded with .length check. Single querySelector results must be checked for truthiness. The timeline should still work when optional elements are absent.
• Font loading race condition: SplitText animations must gate on document.fonts.ready inside DOMContentLoaded. Without this, character measurements break when web fonts swap in after splitting.
• Rapid toggle (nav/modal): Use tl.clear() on a single reusable timeline instead of creating new timelines. This prevents half-open states when users click open/close rapidly.
• Back/forward cache: Page transitions must handle the pageshow event with event.persisted check. Without this, browsers restoring from bfcache show a frozen exit-animation state.
• Memory leaks: React components must return ctx.revert() from the cleanup function. Vanilla JS components using ScrollTrigger must kill triggers on teardown. SplitText with autoSplit must return gsap.context() from onSplit.

Output Quality Checklist

Before delivering any GSAP component, verify:

• No flash of unstyled content — is--hidden class prevents it
• Timeline has defaults with easing and duration
• Every querySelectorAll result is guarded with .length check
• Text animations wait for document.fonts.ready
• Uses xPercent/yPercent instead of pixel transforms
• Stagger values feel natural (0.025-0.1 for letters, 0.05-0.15 for elements)
• Custom eases are registered at file top, not inline
• data-* attributes used for JS targeting
• em units used for responsive dimensions in CSS
• Cleanup is handled (context return, kill methods, or event removal)