animation
Add scroll animations, micro-interactions, or page transitions to a component using GSAP. Use when a section needs motion design or interactive polish.
SKILL.mdclaude/design/animation/SKILL.md
GitHubAdd animation/interaction to a component or section.
Target: $ARGUMENTS
Before Starting
- Read the target component to understand its structure
- Check if GSAP is already imported/used in the file or nearby components
- Read
src/app/globals.cssfor any existing animation tokens or keyframes
Animation Recipes
Choose the appropriate pattern based on what's needed:
Scroll Reveal (most common)
// Staggered fade-up entrance
useGSAP(() => {
gsap.from('.reveal-item', {
y: 20,
opacity: 0,
duration: 0.6,
stagger: 0.1,
ease: 'power2.out',
scrollTrigger: {
trigger: containerRef.current,
start: 'top 80%',
},
});
}, { scope: containerRef });
Card Hover (use Tailwind when possible)
hover:-translate-y-0.5 hover:shadow-lg transition-all duration-200
Only use GSAP for complex hover effects (tilt, glow, border beam).
Page/Route Transitions
Coordinate with Next.js App Router. Use layout-level animation wrappers, not per-page.
Loading States
Use shadcn Skeleton component. Only add shimmer via CSS keyframes if the default isn't sufficient.
Hero Animations
- Text reveal: Split text, stagger character/word entrance
- Background: Subtle parallax or gradient shift (60s+ cycle for gradients)
- CTA: Delayed entrance (300-500ms after hero text)
Implementation Rules
- ALWAYS wrap in
prefers-reduced-motioncheck:const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches; if (prefersReducedMotion) return; // skip all animations - Use
useGSAPhook (not raw useEffect + gsap) for proper cleanup - Only animate
transformandopacity— never width, height, top, left - Durations: micro-interactions 150-300ms, scroll reveals 400-600ms, page transitions 200-300ms
- Easing:
power2.outfor entrances,power2.inOutfor transitions - Debounce/throttle any scroll-linked animations
- Test on low-end devices — if janky, simplify or remove
- If the component is a Server Component, it needs "use client" to use GSAP. Consider extracting the animated part into a client child component instead of converting the whole page.
- Maximum simultaneous animations: 3-4 elements. More causes jank.
Anti-Patterns
- No animations on page load that delay content visibility
- No infinite animations except subtle background effects
- No bounce/elastic easing on UI elements (feels cheap)
- No animation that moves content the user is trying to read
- No GSAP for things Tailwind
transition-*can handle