Imported from Hive-Academy/ptah-extension (.claude/skills/angular-gsap-animation-crafter/SKILL.md). Install upstream with npx skills add Hive-Academy/ptah-extension --skill angular-gsap-animation-crafter. Copyright stays with the author.

Angular GSAP Animation Crafter

Design stunning scroll-based animations using the @hive-academy/angular-gsap library through guided, conversational design.

Before generating any animation code, verify that @hive-academy/angular-gsap is listed in the project's package.json; if it is not, install it (or confirm the intended version with the user) first.

Overview

This skill supports two workflows:

• Workflow A: Image/Video-Based Reverse Engineering - Take a reference video or image from the user, analyze its motion, timing, and effects, and recreate similar scroll animations
• Workflow B: Text-Based Design - Take the user's description and recommend animation types, timing, and configurations

Workflow A: Image/Video-Based Reverse Engineering

Use when: User provides a reference video, GIF, or image showing scroll animations to recreate.

1. Request Image/Video

Ask the user to share:

• Video/GIF of scroll interaction
• Screenshot of animation state
• Link to reference website

2. Perform Motion Analysis

When media is provided, analyze these key aspects:

Animation Type Detection

• Entrance animations: Identify fadeIn, slideUp, scaleIn, etc.
• Scroll-linked: Determine if animations are tied to scroll progress (scrubbed)
• Parallax effects: Detect multi-layer depth with different scroll speeds
• Pinned sections: Identify sections that stay fixed while scrolling
• Hijacked scroll: Detect fullpage step-by-step presentations
• Staggered sequences: Notice cascading entrance patterns

Timing & Easing Analysis

• Duration: Estimate animation speed (fast: 0.3s, medium: 0.6-0.8s, slow: 1.2s+)
• Easing function: Identify easing type
  • Linear (constant speed) → ease: 'none'
  • Smooth acceleration → ease: 'power2.out'
  • Bounce/elastic → ease: 'back.out(1.7)'
  • Custom curve → ease: 'power3.inOut'
• Delay patterns: Notice sequential delays in lists or grids

Trigger Point Analysis

• Start point: Where animation begins (viewport position)
  • Early trigger: "top 90%" (element at bottom of viewport)
  • Mid trigger: "top 60%" (element mid-viewport)
  • Late trigger: "top 30%" (element near top)
• End point: Where animation completes or reverses
• Scrub detection: Does animation move 1:1 with scroll?

Scroll Behavior

• Parallax speed: Estimate layer speeds (0.3 = very slow, 1.0 = normal, 1.5+ = fast)
• Pin duration: How long sections stay fixed
• Direction: Left, right, up, down slide directions
• Fade: Opacity changes during animation

3. Map to Available Directives

Match detected patterns to angular-gsap directives:

4. Identify Closest Demo Pattern

Reference proven patterns from the demo sections:

• Hero Entrance Stagger (Pattern 1) - Sequential badge → title → subtitle → buttons
• Parallax Background (Pattern 2) - Layered depth with speed variations
• Content Fade-Out on Scroll (Pattern 3) - Hero disappearing as user scrolls
• Staggered Pills (Pattern 4) - Cascading list items with delays
• Metric Card Animation (Pattern 5) - Stats with bounce easing
• Fullpage Hijacked Scroll (Pattern 6) - One viewport per slide
• Ambient Glow Backgrounds (Pattern 7) - Atmospheric blur effects
• Split Panel Alternating (Pattern 8) - Content/image sides alternating
• Custom Scroll Animation (Pattern 9) - Complex multi-property changes
• Gradient Text Animation (Pattern 10) - Animated color gradients

See references/patterns.md for complete code examples.

5. Generate Reconstruction Code

Provide Angular component code:

import { Component, ChangeDetectionStrategy } from '@angular/core';
import { ScrollAnimationDirective, ViewportAnimationDirective } from '@hive-academy/angular-gsap';

@Component({
  selector: 'app-reconstructed-animation',
  standalone: true,
  imports: [ScrollAnimationDirective, ViewportAnimationDirective],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <!-- Based on your reference video -->

    <!-- Background parallax layer -->
    <div
      scrollAnimation
      [scrollConfig]="{
        animation: 'parallax',
        speed: 0.4,
        scrub: 1.5,
      }"
    >
      Background
    </div>

    <!-- Entrance animations -->
    <h1
      viewportAnimation
      [viewportConfig]="{
        animation: 'slideUp',
        duration: 0.8,
        threshold: 0.2,
      }"
    >
      Title
    </h1>

    <!-- More elements based on analysis -->
  `,
})
export class ReconstructedAnimationComponent {}

6. Provide Customization Notes

Document approximations and suggestions:

• Exact timing unknown: Estimated 0.8s based on visual speed
• Easing approximation: Used power2.out for smooth feel
• Trigger point guess: Set to "top 80%" for early entrance
• Alternative approaches: Consider using scrollSectionPin for pinning
• Performance tip: Use once: true if animation doesn't need to reverse

Workflow B: Text-Based Conversational Design

Use when: User describes desired scroll animations without visual reference.

Step 1: Understand Intent

Ask clarifying questions:

For Animation Goal:

• "What should happen as the user scrolls?"
  • Fade in elements?
  • Slide content from sides?
  • Pin sections in place?
  • Create parallax depth?
  • Hijack scroll for presentation?

For Trigger Behavior:

• "Should animation be tied to scroll progress or trigger once on entry?"
  • Scrubbed (1:1 with scroll) → Use scrollAnimation with scrub: true
  • One-time entrance → Use viewportAnimation

For Aesthetic:

• "What's the desired feel?"
  • Smooth and professional → ease: 'power2.out'
  • Bouncy and playful → ease: 'back.out(1.7)'
  • Dramatic and slow → duration: 1.5, ease: 'power3.inOut'

Step 2: Recommend Animation Type

Based on intent, suggest directive and animation type:

For Viewport Entrance (One-Time)

viewportAnimation with:
- 'fadeIn' - Simple opacity fade
- 'slideUp' - Upward slide with fade
- 'scaleIn' - Scale from small with fade
- 'rotateIn' - Rotation with opacity
- 'bounceIn' - Elastic bounce entrance

For Scroll-Linked Progress

scrollAnimation with:
- 'parallax' - Background depth effect
- 'fadeIn'/'fadeOut' - Opacity tied to scroll
- 'custom' - Multi-property animation
- pin: true - Keep element fixed while scrolling

For Fullpage Presentations

hijackedScroll + hijackedScrollItem with:
- slideDirection: 'left'|'right'|'up'|'down'
- Step-based navigation
- Progress indicators

Step 3: Configure Timing

Recommend duration and easing:

See references/best-practices.md for comprehensive timing guide.

Step 4: Set Trigger Points

Help choose ScrollTrigger start/end:

// Early trigger (element enters from bottom)
start: 'top 90%';

// Mid trigger (element center-ish)
start: 'top 60%';

// Late trigger (element near top)
start: 'top 30%';

// Pin at top of viewport
start: 'top top';

Step 5: Build Incrementally

Guide through scene construction:

Phase 1: Basic Animation

<div viewportAnimation
  [viewportConfig]="{
    animation: 'slideUp'
  }">
  Content
</div>

Phase 2: Customize Timing

<div viewportAnimation
  [viewportConfig]="{
    animation: 'slideUp',
    duration: 0.8,
    ease: 'power2.out'
  }">
  Content
</div>

Phase 3: Add Stagger (if needed)

<div viewportAnimation
  [viewportConfig]="{
    animation: 'slideUp',
    duration: 0.8,
    stagger: 0.1,
    staggerTarget: '.item'
  }">
  <div class="item">Item 1</div>
  <div class="item">Item 2</div>
  <div class="item">Item 3</div>
</div>

Phase 4: Combine with Scroll Directive

<!-- Background parallax -->
<div scrollAnimation
  [scrollConfig]="{
    animation: 'parallax',
    speed: 0.5,
    scrub: 1.5
  }">
  Background
</div>

<!-- Foreground content -->
<div viewportAnimation
  [viewportConfig]="{
    animation: 'slideUp',
    duration: 0.8
  }">
  Foreground content
</div>

Step 6: Generate Complete Component

Provide production-ready Angular component:

import { Component, ChangeDetectionStrategy } from '@angular/core';
import { ScrollAnimationDirective, ViewportAnimationDirective, HijackedScrollDirective, HijackedScrollItemDirective } from '@hive-academy/angular-gsap';

@Component({
  selector: 'app-custom-animation',
  standalone: true,
  imports: [
    ScrollAnimationDirective,
    ViewportAnimationDirective,
    // Import others as needed
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <!-- Parallax background -->
    <div
      scrollAnimation
      [scrollConfig]="{
        animation: 'parallax',
        speed: 0.4,
        scrub: 1.5,
      }"
    >
      <!-- Background image -->
    </div>

    <!-- Hero section entrance -->
    <section>
      <h1
        viewportAnimation
        [viewportConfig]="{
          animation: 'slideUp',
          duration: 0.8,
          threshold: 0.2,
        }"
      >
        Hero Title
      </h1>

      <p
        viewportAnimation
        [viewportConfig]="{
          animation: 'fadeIn',
          duration: 0.8,
          delay: 0.2,
          threshold: 0.2,
        }"
      >
        Subtitle
      </p>
    </section>

    <!-- Staggered feature list -->
    <div
      viewportAnimation
      [viewportConfig]="{
        animation: 'slideUp',
        stagger: 0.1,
        staggerTarget: '.feature',
      }"
    >
      <div class="feature">Feature 1</div>
      <div class="feature">Feature 2</div>
      <div class="feature">Feature 3</div>
    </div>
  `,
  styles: [
    `
      :host {
        display: block;
        position: relative;
      }
    `,
  ],
})
export class CustomAnimationComponent {}

Example Interaction (Workflow B)

User: "I want a hero section where the title slides up and a background image moves slower than the scroll."

You: Perfect! That's a classic parallax effect with a viewport entrance. Let me build this step by step:

Step 1: Background Parallax

<div
  scrollAnimation
  [scrollConfig]="{
    animation: 'parallax',
    speed: 0.5,
    scrub: 1.5
  }"
>
  <img src="background.jpg" />
</div>

This makes the background move at 50% scroll speed with a 1.5s smooth lag.

Step 2: Title Slide Up

<h1
  viewportAnimation
  [viewportConfig]="{
    animation: 'slideUp',
    duration: 0.8,
    threshold: 0.2
  }"
>
  Hero Title
</h1>

Title appears when 20% visible, slides up over 0.8s.

User: "Can I make the title fade out as I scroll down?"

You: Yes! Add a ScrollAnimation directive to the title:

<h1
  viewportAnimation
  [viewportConfig]="{
    animation: 'slideUp',
    duration: 0.8,
    threshold: 0.2
  }"
  scrollAnimation
  [scrollConfig]="{
    animation: 'custom',
    start: 'top 20%',
    end: 'bottom 60%',
    scrub: 1.2,
    from: { opacity: 1, y: 0 },
    to: { opacity: 0, y: -150 }
  }"
>
  Hero Title
</h1>

This combines entrance (viewport) with scroll-linked fade out.

Ready-to-Use Animation Templates

The assets/ folder contains complete, production-ready animation components organized by type. Each template is heavily documented with customization points and can be used as first drafts for user requirements.

Page Templates (assets/pages/)

Section Templates (assets/sections/)

Using Templates

1. Match user intent: When user describes an animation matching a template, offer it as starting point
2. Customize documented points: Each template has comments explaining what to change
3. Combine sections: Build complete pages by combining multiple section templates

Example workflow:

User: "I want a landing page with sections that snap into place"

You: "Perfect! I have a Fullpage Showcase template that matches this exactly:
     [fullpage-showcase.component.ts](assets/pages/fullpage-showcase.component.ts)

     It includes:
     - HijackedScrollContainer for smooth section snapping
     - Hero, features, stats, and CTA sections
     - Progress dots synced to scroll position
     - ViewportAnimations for content reveals

     Customization points:
     - Change `duration` for faster/slower transitions
     - Modify `ease` for different feel
     - Update section content and colors
     - Add/remove sections as needed"

Combining sections:

User: "I need a hero with parallax and then a timeline section"

You: "Great combination! Here's how to build it:

     1. Start with [parallax-hero.component.ts](assets/sections/parallax-hero.component.ts)
        - Multi-layer depth effect
        - Staggered title and CTA

     2. Follow with [split-panel-timeline.component.ts](assets/sections/split-panel-timeline.component.ts)
        - Pinned description panel
        - Scrolling timeline items

     I'll combine these into a single component for you..."

Reference Files

For detailed information, see:

• references/components.md - Complete catalog of all directives, components, services, and configurations
• references/patterns.md - 10 reusable animation patterns from demo sections with full code examples
• references/best-practices.md - Timing strategies, easing functions, trigger point guides, performance tips

Key Principles

1. SSR Compatibility - All directives work with server-side rendering
2. Performance First - Use once: true for non-reversible animations, optimize stagger counts
3. Accessibility - Support prefers-reduced-motion by reducing durations
4. Progressive Enhancement - Start simple, add complexity as needed
5. Composition - Combine multiple directives for rich effects

Quick Start Template

Use assets/animation-template.component.ts as a starting point. It includes:

• Parallax background setup
• Hero entrance stagger pattern
• Staggered list items
• Scroll-linked content fade
• All necessary imports and configuration

Let's create amazing scroll experiences together!