Animating Scroll Reveals

Animation Decision Tree

Is this a single element fading/sliding into view?
├── YES → Use CSS .reveal classes (Tier 1)
│
└── NO → Are multiple elements animating in a coordinated group?
    ├── YES → Is the stagger simple (same animation, sequential timing)?
    │   ├── YES → Use GSAP ScrollTrigger with stagger (Tier 2)
    │   └── NO → Use GSAP timeline with ScrollTrigger (Tier 3)
    │
    └── NO → Is it triggered by user interaction (click, hover)?
        ├── YES → Use GSAP timeline without ScrollTrigger (Tier 3)
        └── NO → Use CSS .reveal (Tier 1)

Rule of thumb: Start with the simplest tier that works. CSS .reveal covers 60% of marketing animation needs.

Tier 1: CSS .reveal Classes

Defined in app.css. No JavaScript required. Animation triggers by adding .reveal-visible class via IntersectionObserver or GSAP ScrollTrigger.

Available Classes

Triggering with .reveal-visible

Add .reveal-visible when the element enters the viewport. Two approaches:

Approach A: Svelte use: action (lightweight):

<script lang="ts">
  function revealOnScroll(node: HTMLElement) {
    const observer = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          if (entry.isIntersecting) {
            entry.target.classList.add('reveal-visible');
          }
        });
      },
      { threshold: 0.1 }
    );

    observer.observe(node);

    return {
      destroy() {
        observer.disconnect();
      },
    };
  }
</script>

<div class="reveal" use:revealOnScroll>
  <h2>Section headline</h2>
</div>

Approach B: GSAP ScrollTrigger toggleClass (when GSAP is already imported):

<script lang="ts">
  import { onMount } from 'svelte';
  import { ScrollTrigger, cleanupScrollTriggers } from '$lib/gsap-config';

  let el: HTMLElement;

  onMount(() => {
    ScrollTrigger.create({
      trigger: el,
      start: 'top 80%',
      onEnter: () => el.classList.add('reveal-visible'),
      onLeaveBack: () => el.classList.remove('reveal-visible'),
    });

    return cleanupScrollTriggers;
  });
</script>

<div bind:this={el} class="reveal">
  <h2>Section headline</h2>
</div>

Reduced Motion

CSS .reveal classes already have a @media (prefers-reduced-motion: reduce) block in app.css that sets opacity: 1; transform: none; transition: none. No additional handling needed.

Tier 2: GSAP ScrollTrigger with Stagger

For groups of elements that animate in sequence (e.g., bento grid items, feature cards).

Pattern (from BentoGrid.svelte)

<script lang="ts">
  import { onMount } from 'svelte';
  import {
    gsap,
    prefersReducedMotion as checkReducedMotion,
    cleanupScrollTriggers,
  } from '$lib/gsap-config';

  let containerRef: HTMLElement;

  onMount(() => {
    // ALWAYS check reduced motion first
    if (checkReducedMotion()) {
      return;
    }

    const items = containerRef.querySelectorAll('.bento-item');

    // Set initial state (hidden)
    gsap.set(items, { opacity: 0, y: 30 });

    // Animate on scroll
    gsap.to(items, {
      scrollTrigger: {
        trigger: containerRef,
        start: 'top 80%',
        toggleActions: 'play none none reverse',
      },
      opacity: 1,
      y: 0,
      stagger: 0.1,
      duration: 0.6,
      ease: 'power2.out',
    });

    // ALWAYS return cleanup function
    return cleanupScrollTriggers;
  });
</script>

<div bind:this={containerRef} class="bento-grid">
  <!-- items with .bento-item class -->
</div>

Key Settings

Stagger Variations

Tier 3: GSAP Timeline with ScrollTrigger

For complex multi-step animations where elements animate with different properties or timing.

Pattern (from FlowDiagram.svelte)

<script lang="ts">
  import { onMount } from 'svelte';
  import {
    gsap,
    prefersReducedMotion as checkReducedMotion,
    cleanupScrollTriggers,
  } from '$lib/gsap-config';

  let sectionRef: HTMLElement;

  onMount(() => {
    if (checkReducedMotion()) {
      return;
    }

    const nodes = sectionRef.querySelectorAll('.flow-node');
    const connectors = sectionRef.querySelectorAll('.flow-connector');

    // Set initial states
    gsap.set(nodes, { opacity: 0, y: 20, scale: 0.9 });
    gsap.set(connectors, { scaleX: 0, transformOrigin: 'left center' });

    // Create timeline
    const tl = gsap.timeline({
      scrollTrigger: {
        trigger: sectionRef,
        start: 'top 70%',
        toggleActions: 'play none none reverse',
      },
    });

    // Step 1: Nodes appear
    tl.to(nodes, {
      opacity: 1,
      y: 0,
      scale: 1,
      stagger: 0.12,
      duration: 0.5,
      ease: 'back.out(1.4)',
    });

    // Step 2: Connectors draw (overlapping with step 1)
    tl.to(connectors, {
      scaleX: 1,
      stagger: 0.08,
      duration: 0.4,
      ease: 'power2.out',
    }, '-=0.3'); // Start 0.3s before previous step ends

    return cleanupScrollTriggers;
  });
</script>

GSAP Import Rules

ALWAYS import from $lib/gsap-config.ts, never directly from 'gsap' or 'gsap/ScrollTrigger':

// CORRECT
import { gsap, ScrollTrigger, prefersReducedMotion, cleanupScrollTriggers } from '$lib/gsap-config';

// WRONG -- bypasses singleton registration
import { gsap } from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

The config file (gsap-config.ts) handles:

• Plugin registration (once, in browser only)
• prefersReducedMotion() utility
• cleanupScrollTriggers() utility

Reduced Motion: Mandatory Pattern

Every component using GSAP MUST check reduced motion and bail early:

<script lang="ts">
  import { onMount } from 'svelte';
  import { gsap, prefersReducedMotion as checkReducedMotion, cleanupScrollTriggers } from '$lib/gsap-config';

  onMount(() => {
    // MUST be the first check
    if (checkReducedMotion()) {
      return; // No animations, no cleanup needed
    }

    // ... animation code ...

    return cleanupScrollTriggers;
  });
</script>

When reduced motion is active:

• CSS .reveal classes automatically show content (handled by app.css media query)
• GSAP animations are skipped entirely
• Content is immediately visible at its final state

ScrollTrigger Cleanup: Mandatory Pattern

Every onMount that creates ScrollTrigger instances MUST return the cleanup function:

onMount(() => {
  if (checkReducedMotion()) return;

  // ... create ScrollTrigger instances ...

  // MUST return cleanup to prevent memory leaks on navigation
  return cleanupScrollTriggers;
});

cleanupScrollTriggers() calls ScrollTrigger.getAll().forEach(st => st.kill()). This is safe to call even if no triggers were created.

Performance Guardrails

Only Animate Compositor Properties

ALLOWED (GPU-accelerated, no layout recalculation):

• opacity
• transform (translate, scale, rotate)

FORBIDDEN (triggers layout/paint, janky on scroll):

• width, height
• top, left, right, bottom
• margin, padding
• border-width
• font-size
• box-shadow (except for hover states via CSS transitions)

Duration Guidelines

Easing

Section Animation Recommendations

Based on the IA section archetypes:

Anti-Patterns

Related Skills

• scaffolding-sections -- build the static section first, then add animation
• assembling-pages -- page-level animation considerations (no competing animations)
• auditing-design-compliance -- verify reduced motion handling