GSAP Animation Skill - Architecture Design

GSAP Animation Skill - Architecture Design

GSAP + Remotion integration for professional motion graphics video production

1. Overview

The gsap-animation skill provides a curated catalog of GSAP-powered motion graphics patterns, integrated with Remotion for deterministic video rendering. It complements the existing react-animation skill by offering GSAP's superior timeline orchestration, text splitting, SVG morphing, and advanced easing capabilities.

Why GSAP + Remotion?

GSAP Licensing

All GSAP plugins are 100% free since Webflow's acquisition in 2024, including former Club plugins (SplitText, MorphSVG, DrawSVG, MotionPath, etc.).

2. Core Integration: useGSAPTimeline Hook

The central bridge between GSAP and Remotion. GSAP timelines are created, paused, and seeked to match Remotion's frame-based rendering.

import { useCurrentFrame, useVideoConfig } from 'remotion';
import gsap from 'gsap';
import { useEffect, useRef, useCallback } from 'react';

/**
 * Sync a GSAP timeline with Remotion's frame-based rendering.
 *
 * - Creates the timeline once (paused)
 * - Seeks to the correct position on every frame
 * - Cleans up on unmount
 */
function useGSAPTimeline(
  factory: (tl: gsap.core.Timeline) => void,
  deps: any[] = []
) {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const tlRef = useRef<gsap.core.Timeline | null>(null);
  const containerRef = useRef<HTMLDivElement>(null);

  // Create timeline once
  useEffect(() => {
    if (!containerRef.current) return;

    const ctx = gsap.context(() => {
      const tl = gsap.timeline({ paused: true });
      factory(tl);
      tlRef.current = tl;
    }, containerRef);

    return () => {
      ctx.revert(); // Clean up all GSAP animations
      tlRef.current = null;
    };
  }, deps);

  // Seek to current frame position
  useEffect(() => {
    if (tlRef.current) {
      tlRef.current.seek(frame / fps);
    }
  }, [frame, fps]);

  return containerRef;
}

Key Design Decisions:

• gsap.context() scopes all animations to a container, enabling clean teardown
• tl.pause() prevents auto-play; tl.seek() gives Remotion full time control
• Timeline is created once; only seek() runs per frame (performance)
• deps array allows timeline recreation when dynamic props change

3. Plugin Integration Matrix

Compatible Plugins (Remotion-safe)

Incompatible Plugins (No video use case)

4. Animation Categories & Patterns

Category 1: Text Animations

SplitText Reveal - Char/word/line animations with mask clipping

const GSAPTextReveal: React.FC<{
  text: string;
  splitType?: 'chars' | 'words' | 'lines';
  stagger?: number;
  duration?: number;
  startAt?: number; // seconds
}> = ({ text, splitType = 'chars', stagger = 0.03, duration = 0.6, startAt = 0 }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const containerRef = useRef<HTMLDivElement>(null);

  const ref = useGSAPTimeline((tl) => {
    const split = SplitText.create(containerRef.current!, {
      type: splitType,
      mask: splitType,
    });
    tl.from(split[splitType === 'chars' ? 'chars' : splitType === 'words' ? 'words' : 'lines'], {
      y: '100%',
      duration,
      stagger,
      ease: 'power3.out',
    }, startAt);
  });

  return <div ref={ref}><div ref={containerRef}>{text}</div></div>;
};

ScrambleText - Decode/encrypt character effect TextPlugin Typewriter - Character-by-character typing Kinetic Typography - Multi-word dramatic entrances with scale, rotation

Category 2: SVG Animations

MorphSVG - Shape-to-shape morphing DrawSVG - Logo reveals, signature drawing, line art MotionPath - Elements following SVG paths with autoRotate

Category 3: Transition Effects

Clip-Path Transitions - Circle reveal, diagonal wipe, iris, blinds Slide/Push - Directional scene transitions Zoom/Scale - Scale-based transitions Crossfade - Opacity crossfade between scenes

Category 4: Motion Graphics Templates

Lower Thirds - Name/title overlay with bar + text reveal Title Cards - Intro sequences with split text + decorative elements Logo Reveals - DrawSVG stroke → fill, scale + rotation, morph from abstract Data Visualization - Counter animation, bar charts, donut charts CTA Overlays - Call-to-action with pulse attention End Screens - Outro with social icons + subscribe

Category 5: Advanced Effects

Particle Systems - Physics2D-driven particle bursts (seeded for determinism) 3D Transforms - Perspective-based card flips, text rotations Color/Gradient Transitions - Animated gradients via custom property tweening

5. Skill Structure

skills/gsap-animation/
├── SKILL.md                          # Main skill doc (pattern catalog + usage guide)
├── rules/
│   ├── remotion-integration.md       # useGSAPTimeline hook + Remotion patterns
│   ├── plugin-guide.md               # GSAP plugin compatibility + usage in Remotion
│   └── timing-conventions.md         # Standard timing/easing for motion graphics

6. SKILL.md Design

The SKILL.md should be organized as:

1. When to Use - GSAP vs Remotion native interpolate()
2. Setup - Install GSAP + register plugins in Remotion project
3. Core Hook - useGSAPTimeline pattern
4. Animation Catalog by category:
   • Text Animations (SplitText, ScrambleText, TextPlugin, Kinetic)
   • SVG Animations (MorphSVG, DrawSVG, MotionPath)
   • Transitions (clip-path, slide, zoom, crossfade)
   • Templates (lower third, title card, logo reveal, counter, CTA, end screen)
5. Easing Reference - GSAP ease → motion graphics use case mapping
6. Registered Effects - Pre-built gsap.registerEffect() library
7. Style Consistency - Do/Don't guidelines
8. Project Setup - Remotion + GSAP project scaffolding

7. When to Use GSAP vs Remotion Native

8. Relationship to react-animation Skill

Complementary Usage:

// Combine both skills in one Remotion composition
const Scene: React.FC = () => (
  <AbsoluteFill>
    {/* react-animation: background atmosphere */}
    <Aurora colorStops={['#3A29FF', '#FF94B4']} />

    {/* gsap-animation: text + SVG motion graphics */}
    <GSAPTextReveal text="Beautiful Motion" splitType="chars" />
    <GSAPLogoReveal svgPath={logoSVG} />

    {/* react-animation: film grain overlay */}
    <NoiseOverlay opacity={0.05} />
  </AbsoluteFill>
);

9. Project Setup Template

# New Remotion + GSAP project
npx create-video@latest my-motion-graphics
cd my-motion-graphics

# Install GSAP (all plugins now free)
npm install gsap

# Register plugins in src/Root.tsx

// src/gsap-setup.ts
import gsap from 'gsap';
import { SplitText } from 'gsap/SplitText';
import { MorphSVGPlugin } from 'gsap/MorphSVGPlugin';
import { DrawSVGPlugin } from 'gsap/DrawSVGPlugin';
import { MotionPathPlugin } from 'gsap/MotionPathPlugin';
import { ScrambleTextPlugin } from 'gsap/ScrambleTextPlugin';
import { TextPlugin } from 'gsap/TextPlugin';
import { CustomEase } from 'gsap/CustomEase';
import { CustomBounce } from 'gsap/CustomBounce';
import { CustomWiggle } from 'gsap/CustomWiggle';

gsap.registerPlugin(
  SplitText,
  MorphSVGPlugin,
  DrawSVGPlugin,
  MotionPathPlugin,
  ScrambleTextPlugin,
  TextPlugin,
  CustomEase,
  CustomBounce,
  CustomWiggle,
);

export { gsap };

10. Registered Effects Library

Pre-built effects that extend the timeline API:

// effects/text.ts
gsap.registerEffect({
  name: 'textReveal',
  effect: (targets, config) => {
    const split = SplitText.create(targets, { type: config.type, mask: config.type });
    return gsap.from(split[config.type], {
      y: '100%', duration: config.duration, stagger: config.stagger, ease: config.ease,
    });
  },
  defaults: { type: 'lines', duration: 0.6, stagger: 0.15, ease: 'power3.out' },
  extendTimeline: true,
});

gsap.registerEffect({
  name: 'charCascade',
  effect: (targets, config) => {
    const split = SplitText.create(targets, { type: 'chars' });
    return gsap.from(split.chars, {
      y: 50, opacity: 0, rotationX: -90, duration: config.duration,
      stagger: config.stagger, ease: config.ease,
    });
  },
  defaults: { duration: 0.5, stagger: 0.02, ease: 'back.out(1.7)' },
  extendTimeline: true,
});

// effects/transitions.ts
gsap.registerEffect({
  name: 'circleReveal',
  effect: (targets, config) => gsap.fromTo(targets,
    { clipPath: 'circle(0% at 50% 50%)' },
    { clipPath: `circle(${config.radius} at ${config.cx} ${config.cy})`, duration: config.duration, ease: config.ease },
  ),
  defaults: { radius: '75%', cx: '50%', cy: '50%', duration: 1, ease: 'power2.out' },
  extendTimeline: true,
});

gsap.registerEffect({
  name: 'wipeIn',
  effect: (targets, config) => gsap.fromTo(targets,
    { clipPath: 'inset(0 100% 0 0)' },
    { clipPath: 'inset(0 0% 0 0)', duration: config.duration, ease: config.ease },
  ),
  defaults: { duration: 0.8, ease: 'power2.inOut' },
  extendTimeline: true,
});

// effects/svg.ts
gsap.registerEffect({
  name: 'drawIn',
  effect: (targets, config) => gsap.from(targets, {
    drawSVG: 0, duration: config.duration, ease: config.ease, stagger: config.stagger,
  }),
  defaults: { duration: 1.5, ease: 'power2.inOut', stagger: 0.1 },
  extendTimeline: true,
});

gsap.registerEffect({
  name: 'morphTo',
  effect: (targets, config) => gsap.to(targets, {
    morphSVG: config.shape, duration: config.duration, ease: config.ease,
  }),
  defaults: { duration: 1.5, ease: 'power2.inOut' },
  extendTimeline: true,
});

Usage in timeline:

const ref = useGSAPTimeline((tl) => {
  tl.textReveal('.title')
    .charCascade('.subtitle', {}, '-=0.3')
    .circleReveal('.scene-2', {}, '+=0.5')
    .drawIn('.logo-path')
    .morphTo('.icon', { shape: '#target-shape' });
});

11. Timing Conventions

12. Easing Quick Reference