gsap-tackl

Files (1)

• SKILL.md

SKILL.md (first lines)

# GSAP (Tackl)

## System overview

```
app/(site)/Providers.tsx
  └── AnimationPlugins     # registers ScrollTrigger + useGSAP globally
  └── Contexts
        └── PerformanceProvider   # isReducedMotion, devicePixelRatio

app/(site)/layout.tsx
  └── SmoothScroll (Lenis)
        └── {page children}
        └── LenisGsapBridge # ScrollTrigger.scrollerProxy + ticker sync
```

Animation is **client-side only**. Never run Lenis/GSAP in Server Components.

## Stack

- `gsap` + `@gsap/react` (`useGSAP`)
- `ScrollTrigger` — registered in `src/components/AnimationPlugins/index.tsx`
- Project hook: `useAnimation` in `src/utils/useAnimation.ts` (wraps `useGSAP` + `gsap.matchMedia`)

Do not re-register plugins in every file. `AnimationPlugins` is imported once in `app/(site)/Providers.tsx`.

## When to use what

| Need | Tool |
|------|------|
| Smooth scroll | Lenis via `SmoothScroll` — already mounted, do not duplicate |
| Scroll-linked reveal/scrub | GSAP ScrollTrigger via `useAnimation` |
| Responsive breakpoints | `useAnimation` matchMedia (`isDesktop`, `isMobile`, `isTablet`) |
| Simple mount tween (no breakpoints) | `useGSAP` |
| Route transitions | React `<ViewTransition>` via `@parts/PageTransition` + `transitionTypes` on `next/link` |
| Reduced motion fallback | `PerformanceContext.isReducedMotion` |

## Rules

1. GSAP code belongs in **client components** (`'use client'`).
2. Prefer `useAnimation` for responsive / scroll work; pass `{ scope: ref }` when using selectors.
3. Prefer refs over class selectors when possible.
4. Always scope cleanup — `useGSAP`/`useAnimation` handle this via `gsap.context()`.
5. Interaction-driven animations (click, delayed) are **not** context-safe — manage and revert manually.
6. Respect `PerformanceContext` — skip or simplify when `isReducedMotion` is true.
7. Animate `transform` and `opacity` first; avoid layout properties.

## Default breakpoints (`useAnimation`)

| Key | Query |
|-----|-------|
| `isDesktop` | `(min-width: 1024px)` |
| `isMobile` | `(max-width: 699px)` |
| `isTablet` | `(min-width: 700px) and (max-width: 1023px)` |

## Lenis + GSAP contract

`SmoothScroll` / `LenisGsapBridge` sets:

- `ScrollTrigger.scrollerProxy` on the Lenis root element
- `ScrollTrigger.defaults({ scroller: wrapper })`
- `lenis.on('scroll', ScrollTrigger.update)` + `gsap.ticker` RAF bridge (`autoRaf: false`)

**Do not** set ScrollTrigger `scroller: window`. **Do not** mount a second `ReactLenis`.

When creating ScrollTriggers that may run before the bridge is ready, pass `scroller: lenis.rootElement` explicitly and refresh after the proxy is live (one `requestAnimationFrame` after setup is enough).

## Pattern: responsive scroll animation

```tsx
'use client';

import { use, useRef } from 'react';
import gsap from 'gsap';
import { PerformanceContext } from '@parts/Contexts/Performance';
import { useAnimation } from '@utils/useAnimation';

const MySection = () => {
	const { isReducedMotion } = use(PerformanceContext);
	const ref = useRef<HTMLDivElement>(null);

	useAnimation(
		({ isDesktop }) => {
			if (isReducedMotion || !ref.current) return;

			gsap.from(ref.current, {
				y: isDesktop ? '2rem' : '1rem',
				scrollTrigger: {
					trigger: ref.current,
					start: 'top 100%',
					end: isDesktop ? 'bottom 50%' : 'bottom 80%',
					scrub: true,
				},
			});
		},
		{ scope: ref },
	);

	return <div ref={ref}>Content</div>;
};
```

## Pattern: simple `useGSAP`

Use when matchMedia breakpoints are not needed:

```tsx
import { useRef } from 'react';
import gsap from 'gsap';
import { useGSAP } from '@gsap/react';

const ref = useRef<HTMLDivElement>(null);

useGSAP(
	() => {
		gsap.to(ref.current, { opacity: 1, duration: 0.6 });
	},
	{ scope: ref },
);

From 12-Studio/Tackl, MIT.

More from 12-Studio/Tackl