Arquitetura de movimento GSAP
Linha de base verificada (2026-11-15)
[email protected]é a versão mais recente no npm. Seu campo de licença é "Standard 'no charge' license" (gsap.com/standard-license): gratuita para sites comerciais, incluindo trabalho para clientes. O único uso proibido é criar ferramentas visuais de construtor de animação sem código que concorram com o Webflow. Todos os plugins são enviados no pacote público: ScrollTrigger, ScrollSmoother, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, CustomBounce, CustomWiggle, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin, ScrambleTextPlugin, ScrollToPlugin, Physics2D, PhysicsProps, GSDevTools, e mais.@gsap/[email protected]forneceuseGSAP.- Verifique novamente antes de um novo projeto:
npm view gsap version licenseels node_modules/gsap/*.js. - Use ScrollSmoother ou Lenis, nunca ambos. Este estúdio padroniza o Lenis (skill
lenis-scroll).
Arquitetura (copie assets/ para src/motion/)
| Arquivo | Função |
|---|---|
assets/registry.ts | Registra plugins uma vez, cria os CustomEases do projeto, define padrões, ScrollTrigger.config({ ignoreMobileResize: true }). Tudo importa gsap daqui. |
assets/tokens.ts | Tokens de movimento (durações, eases, staggers) espelhados de ANIMATION_SPECIFICATION.md + prefersReducedMotion() |
assets/lit.ts | Exemplo de primitiva de texto reutilizável: SplitText com aria:'auto', autoSplit, e onSplit retornando o tween. Adapte a revelação à marca (lit, mascarada, deslizada…). |
assets/useReducedMotion.ts | Hook prefers-reduced-motion ao vivo para alternâncias no nível do DOM (ex.: renderizar etapas estáticas em vez de um pin) |
assets/examples/*.tsx | Padrões testados da demo de referência: sequência fixa com scroll (Method), filtro Flip (ScheduleIndex), interativo com quickTo (TheHour), revelações ao aparecer (Rooms), véu de transição de rota (Router) |
Esses arquivos são a implementação verificada de demo/ neste repositório, exercitada por sua suíte Playwright (limpeza entre rotas, movimento reduzido, sincronização de scroll).
Regras que previnem 90% dos bugs de GSAP no React
- Toda animação vive dentro de
useGSAP(() => {...}, { scope: ref }). O contexto reverte todos os tweens, ScrollTriggers, SplitTexts e ramos matchMedia ao desmontar. Animações em manipuladores de evento usamcontextSafe. - Nunca crie ScrollTriggers no escopo do módulo ou em
useEffectsimples sem revertê-los. Nunca chameScrollTrigger.killAll()como estratégia de limpeza. - Um
gsap.matchMedia()por seção com condiçõesmotion/reduce(e desktop/mobile). Estados ocultos iniciais são definidos dentro do ramo motion, para que usuários sem JS e com movimento reduzido vejam o conteúdo final. - Seguro no modo estrito:
useGSAPlida com a dupla invocação do React 18/19. Verifique com uma checagem de vazamento:ScrollTrigger.getAll().lengthretorna ao valor inicial após navegar para longe e voltar. - Atualize após mudanças de layout: após o carregamento de fontes (
document.fonts.ready.then(() => ScrollTrigger.refresh())), após filtrar listas, e após o conteúdo da rota montar. UseinvalidateOnRefresh: trueem qualquer trigger cujos valores sejam calculados a partir do layout. - Fixação correta: fixe um wrapper interno, mantenha
pinSpacing, dê a ele ummin-height: 100svhque não dependa de webfonts, e useanticipatePin: 1com Lenis. Use um pin por experiência; pins empilhados confundem os usuários. - Anime propriedades baratas: transform, opacity, clip-path; variáveis CSS apenas em pequenas subárvores. Evite width/height/top/left em timelines com scroll, e leia o layout antes de escrever (GSAP agrupa suas próprias escritas).
will-changeapenas enquanto anima, e apenas em poucas camadas.
Receitas
references/recipes.md tem padrões testados ou documentados para: sequência hero cinematográfica, revelações de SplitText (chars/words/lines, mascarados), transições de clip-path e máscara, narrativa com pin e scroll, seção de scroll horizontal (containerAnimation), camadas de parallax, morphs de estado Flip, seções de gestos orientadas por Observer, carrosséis Draggable + Inertia, botões magnéticos, seguidores de cursor, morph/draw SVG, distorção de imagem com passagem para WebGL, transições de página, e scroll 3D com câmera WebGL.
references/react-lifecycle.md cobre mudanças de rota, redimensionamento, mudanças de conteúdo e depuração de vazamentos.
Lista de verificação de movimento intencional (antes de animar)
- O que esta animação comunica (hierarquia, causalidade, estado, material da marca)? Se nada, delete-a.
- É o momento de destaque, ou deve permanecer sutil?
- O que o movimento reduzido mostra em vez disso? (Deve permanecer totalmente compreensível.)
- Qual é a expressão para mobile? (Efeitos de hover precisam de uma alternativa de toque; pins ficam mais curtos.)
- Quantos ScrollTriggers a página cria? Escreva o inventário na especificação para que o QA possa verificá-lo.