GSAP e Framer Motion — Habilidade de Animações de Scroll

Animações de scroll prontas para produção com prompts do GitHub Copilot, receitas de código prontas para usar e referências profundas da API.

Companheiro de Design: Esta habilidade fornece a implementação técnica para movimento impulsionado por scroll. Para a filosofia criativa, princípios de design e estética premium que devem guiar como e quando animar, sempre consulte a habilidade premium-frontend-ui. Juntas, elas formam uma abordagem completa: premium-frontend-ui decide o quê e o porquê; esta habilidade entrega o como.

Seletor Rápido de Biblioteca

Leia o arquivo de referência relevante para receitas completas e prompts do Copilot:

• GSAP → references/gsap.md — API ScrollTrigger, todas as receitas, integração React
• Framer Motion → references/framer.md — useScroll, useTransform, todas as receitas

Configuração (Sempre Faça Primeiro)

GSAP

npm install gsap

import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
gsap.registerPlugin(ScrollTrigger); // MUST call before any ScrollTrigger usage

Framer Motion (Motion v12, 2025)

npm install motion   # new package name since mid-2025
# or: npm install framer-motion  — still works, same API

import { motion, useScroll, useTransform, useSpring } from 'motion/react';
// legacy: import { motion } from 'framer-motion'  — also valid

Fluxo de Trabalho

1. Interprete a intenção do usuário para identificar se GSAP ou Framer Motion é o mais adequado.
2. Leia o documento de referência relevante em references/ para APIs e padrões detalhados.
3. Sugira a instalação do pacote necessário, se ainda não estiver presente.
4. Implemente o esqueleto para a estrutura da animação, aderindo ao formato solicitado (componentes React, requisitos de hook ou vanilla JS).
5. Aplique as ferramentas corretas (elementos de scroll vs. elementos visíveis), garantindo que as opções de acessibilidade estejam presentes e que os hooks não causem re-renderizações infinitas.

Os 5 Padrões de Scroll Mais Comuns

Referência rápida — receitas completas com prompts do Copilot estão nos arquivos de referência.

1. Fade-in ao entrar (GSAP)

gsap.from('.card', {
  opacity: 0, y: 50, stagger: 0.15, duration: 0.8,
  scrollTrigger: { trigger: '.card', start: 'top 85%' }
});

2. Fade-in ao entrar (Framer Motion)

<motion.div
  initial={{ opacity: 0, y: 40 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: '-80px' }}
  transition={{ duration: 0.6 }}
/>

3. Scrub / vinculado ao scroll (GSAP)

gsap.to('.hero-img', {
  scale: 1.3, opacity: 0, ease: 'none',
  scrollTrigger: { trigger: '.hero', start: 'top top', end: 'bottom top', scrub: true }
});

4. Vinculado ao scroll (Framer Motion)

const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'end start'] });
const y = useTransform(scrollYProgress, [0, 1], [0, -100]);
return <motion.div style={{ y }} />;

5. Timeline fixada (GSAP)

const tl = gsap.timeline({
  scrollTrigger: { trigger: '.section', pin: true, scrub: 1, start: 'top top', end: '+=200%' }
});
tl.from('.title', { opacity: 0, y: 60 }).from('.img', { scale: 0.85 });

Regras Críticas (Aplicar Sempre)

• GSAP: sempre chame gsap.registerPlugin(ScrollTrigger) antes de usá-lo
• GSAP scrub: sempre use ease: 'none' — o easing parece errado quando o scrub está ativo
• GSAP React: use useGSAP de @gsap/react, nunca o useEffect puro — ele limpa automaticamente os ScrollTriggers
• GSAP debug: adicione markers: true durante o desenvolvimento; remova antes da produção
• Framer: a saída de useTransform deve ir para a prop style de um elemento motion.*, não de um div simples
• Framer Next.js: sempre adicione 'use client' no topo de qualquer arquivo que use hooks de motion
• Ambos: anime apenas transform e opacity — evite width, height, box-shadow
• Acessibilidade: sempre verifique prefers-reduced-motion — veja cada arquivo de referência para padrões
• Polimento premium: siga os princípios da habilidade premium-frontend-ui para tempo de movimento, curvas de easing e moderação — a animação deve aprimorar, nunca sobrecarregar

Dicas de Prompt para Copilot

• Forneça ao Copilot o seletor completo, a imagem base e o intervalo de scroll antecipadamente — prompts vagos produzem código vago

…