Scroll cinematográfico com GSAP + Lenis no Claude Code: pin, scrub e parallax (com cases Oryzo AI e Studio K95)

Scroll cinematográfico quebra quando três controles disputam a página ao mesmo tempo: o smooth que dá inércia, o pin que segura a seção e o trigger que dispara a timeline. Sem uma ponte entre eles, a animação dispara fora de hora e o pin calcula a posição errada.

Este tutorial resolve isso em ordem: conceitos com tabela de decisão, base com GSAP 3.15 e Lenis 1.3.x, hero com pin e scrub, critério ScrollSmoother contra Lenis, prompts para o Claude Code, leitura dos cases e fechamento com fluidez e movimento reduzido. Para o mapa geral das bibliotecas, volte ao guia completo de motion.

Cada efeito responde a uma pergunta de leitura. Pin responde qual contexto continua valendo enquanto o resto avança. Scrub responde quanto da cena já avançou, porque amarra o progresso da timeline à posição do scroll. Parallax responde qual camada se move mais rápido, o que cria profundidade sem trocar de seção.

O ScrollTrigger cobre os três, com dois recursos extras que valem menção. Snap encaixa o scroll em pontos definidos, útil em apresentações por telas. Markers mostra linhas de início e fim dos triggers durante o desenvolvimento, o que acelera o acerto de posições.

A tabela abaixo resume efeito, plugin responsável e quando usar cada um. Ela funciona como triagem antes de qualquer prompt.

regra de triagem em três perguntas (há pin, há scrub, há parallax com velocidades distintas) decide CSS contra GSAP antes do prompt; se as três respostas forem não, CSS scroll-driven resolve e o artigo sai mais leve.

A triagem que decide CSS contra GSAP

Três perguntas definem a arquitetura. Há pin que segura conteúdo. Há scrub que amarra timeline ao scroll. Há parallax com velocidades distintas que exige sincronia por pixel. Três respostas negativas indicam CSS scroll-driven, que cobre reveal e parallax simples. Uma resposta positiva já justifica planejar GSAP com ScrollTrigger, com nomes de containers e comportamento mobile definidos antes de gerar código.

A base tem duas partes: registro de plugins e ponte de sincronia. O GSAP segue como referência de scroll com narrativa, e o contexto comercial mudou a conta: após a compra da GreenSock pela Webflow em out/2024, a distribuição passou a 100% gratuita desde 30/abr/2025, na versão v3.15.0, segundo gsap.com, noqode.fr de 13/mai/2026 e artofstyleframe de 25/mai/2026. Sem atrito de licença, o critério volta a ser técnico.

O Lenis entra como smooth scroll leve. A linha 1.3.x tem cerca de 3KB, licença MIT e manutenção da Darkroom, com o padrão de sincronia documentado na comunidade, segundo youngju.dev de 16/mai/2026, adamarant de 28/mai/2026 e snigdha de 18/jun/2026. A instalação usa npm com os dois pacotes, e o registro do plugin vem antes de qualquer trigger.

import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import Lenis from "lenis";

gsap.registerPlugin(ScrollTrigger);

const lenis = new Lenis({ lerp: 0.1 });
lenis.on("scroll", ScrollTrigger.update);

gsap.ticker.add((time) => lenis.raf(time * 1000));
gsap.ticker.lagSmoothing(0);

Esse bloco curto carrega três decisões. O evento de scroll do Lenis atualiza o ScrollTrigger, o raf roda dentro do ticker do GSAP em vez de um requestAnimationFrame separado, e o lagSmoothing zerado evita saltos após troca de aba. Sem essa ponte, pins calculam posição errada e timelines disparam cedo.

Pin segura contexto enquanto a timeline avança, e scrub transforma scroll em controle de progresso. O erro comum é fixar a seção sem reservar espaço nem definir fim, o que desloca o conteúdo seguinte e gera salto visível.

O bloco abaixo monta um hero fixo com timeline ligada ao scroll. O trigger define início no topo da viewport e fim após 150% de rolagem, o pin segura a seção e o scrub com valor 1 dá leve suavização ao vínculo entre scroll e timeline.

gsap.timeline({
  scrollTrigger: {
    trigger: ".pinned-hero",
    start: "top top",
    end: "+=150%",
    pin: true,
    scrub: 1,
    markers: false
  }
})
  .to(".pinned-hero h1", { yPercent: -30, opacity: 0, ease: "none" })
  .to(".pinned-hero .scene", { scale: 1.15, ease: "none" }, "<");

Parallax por camada segue a mesma lógica com triggers independentes. Cada camada recebe um deslocamento proporcional, com ease none para manter vínculo direto com o scroll. Velocidades distintas entre fundo e frente criam profundidade, e valores moderados preservam a leitura do texto.

gsap.to(".layer-back", {
  yPercent: 15,
  ease: "none",
  scrollTrigger: {
    trigger: ".story-section",
    start: "top bottom",
    end: "bottom top",
    scrub: true
  }
});

Durante o desenvolvimento, markers true mostra as linhas de start e end e revela triggers sobrepostos. Antes de publicar, desligue os markers e confira o espaço reservado do pin em telas estreitas, onde o conteúdo fixo costuma estourar primeiro.

Os dois resolvem a sensação do scroll, por caminhos distintos. O ScrollSmoother é nativo do ecossistema GSAP e trabalha com wrapper e content declarados, parallax por atributos e normalização de scroll, segundo docs do GSAP e annnimate. O Lenis atua no nível de window, sem exigir wrapper, com cerca de 3KB e integração pontual ao ScrollTrigger.

gsap.registerPlugin(ScrollTrigger, ScrollSmoother);

ScrollSmoother.create({
  wrapper: "#smooth-wrapper",
  content: "#smooth-content",
  smooth: 1.2,
  effects: true,
  normalizeScroll: true
});

Com effects ativo, atributos como data-speed e data-lag aplicam parallax declarativo direto no HTML, sem timeline por camada. Isso simplifica páginas com muitas seções e parallax uniforme.

O critério de escolha passa por stack e controle. Para páginas com GSAP dominante e parallax declarativo por seção, o ScrollSmoother simplifica porque vive no mesmo ecossistema dos triggers. Para smooth scroll agnóstico, com integração pontual e bundle mínimo, o Lenis cumpre o trabalho com cerca de 3KB. Evite combinar os dois controles de scroll na mesma página, pois disputam a mesma posição e geram cálculo duplicado.

Geração boa separa três funções: skill define padrão, prompt define estrutura, MCP confere API. O ponto de partida é o repositório iart-ai/web-animation-skills no GitHub, com 9 skills que incluem gsap-web, 60fps-animation e accessible-animation, instalado via npx skills add ou marketplace, segundo repo iart-ai. A skill de GSAP puxa timeline e ScrollTrigger, a de 60fps puxa transform e opacity, a acessível puxa preferência de movimento reduzido.

O prompt exemplo do repositório para hero com GSAP é direto: "Build a pinned hero section that scrubs a timeline to scroll with GSAP." Esse prompt funciona melhor com complemento de estrutura: nomes de seções, qual camada recebe pin, duração do scrub, comportamento em mobile e onde o Lenis entra. Quanto mais o prompt descreve estrutura, menos o modelo improvisa arquitetura.

Para conferir API antes de gerar timeline complexa, há MCPs dedicados. O pacote @vinhnguyen/gsap-mcp no npm faz ponte com a documentação, e a implementação bl00dclot no GitHub expõe 18 tools estáticas sem runtime. Em React, some a skill gsap-react com o padrão useGSAP citada no skillsplayground, que orienta montagem e limpeza de timelines no ciclo do componente e evita vazamento de listeners no scroll.

O toolkit associado a wilwaldon organiza o restante do fluxo, com frontend-design oficial da Anthropic, coleção freshtechbro com 23 skills, skill jezweb para Motion, Playwright MCP e Chrome DevTools MCP para auditoria, além de Context7 para docs e Figma MCP para handoff de layout. Peça arquivos separados por responsabilidade, com tokens de easing e duração centralizados, e rode auditoria no navegador antes de publicar.

micro-interações com Motion

Os sites premiados do período usam scroll com motivo legível, não com volume de efeitos. Oryzo AI, SOTD de 13/abr/2026 pelo estúdio Lusion, combina GSAP com Three.js para transformar produto de IA em narrativa por camadas, segundo a seleção de animação do Awwwards. Studio K95 segue a mesma lógica em portifólio, com GSAP, Three e Nuxt em entrada por camadas e tipografia que responde ao scroll.

Made With GSAP, também SOTD, funciona como catálogo vivo da biblioteca: cards com hover, hero com drag e explosão de texto mostram física e resposta ao cursor sem depender de vídeo. Codrops Telescope, de out/2025, usa ScrollSmoother com ScrollTrigger para zoom em camadas, segundo o artigo do Codrops, e serve de referência direta quando a dúvida for entre Lenis e ScrollSmoother.

O padrão que se repete é contenção com motivo. Uma ideia por viewport, reveal que respeita a ordem de leitura e resposta imediata ao gesto. Nenhum case exige stack exótica. Todos exigem decisão sobre o que anima, quando anima e por que anima.

Fluidez tem regra estável: animar transform e opacity, manter timelines curtas, reservar espaço para pins e auditar no navegador. Pin sem espaço reserva desloca layout, scroll sem sincronia dispara cedo e transição sem saída confunde. Auditoria com Playwright MCP e Chrome DevTools MCP pega esses erros antes do visitante.

Acessibilidade segue o mesmo rigor com gsap.matchMedia. Um ramo atende quem não declarou preferência por menos movimento, com pin, scrub e parallax completos. Outro ramo atende prefers-reduced-motion reduce, com versão estática legível e sem perda de conteúdo.

const mm = gsap.matchMedia();

mm.add("(prefers-reduced-motion: no-preference)", () => {
  // pin, scrub e parallax completos aqui
});

mm.add("(prefers-reduced-motion: reduce)", () => {
  // versão estática: conteúdo visível, sem pin nem scrub
});

Algumas animações merecem remoção em vez de otimização: intro longa que atrasa leitura, parallax que compete com texto e loop que distrai de formulário. Se o motion atrasa tarefa ou consome atenção sem explicar nada, retire e meça a leitura de novo.

motion performático 60fps e acessibilidade

Pin e scrub são a mesma coisa?

Não. Pin fixa a seção na viewport enquanto o scroll avança, e scrub amarra o progresso de uma timeline à posição do scroll. O padrão do artigo combina os dois: pin segura o hero e scrub controla a cena. Use pin sem scrub para pausas de leitura e scrub sem pin para parallax contínuo.

Posso usar ScrollSmoother e Lenis na mesma página?

Não é recomendado. Os dois controlam a posição do scroll e o cálculo duplica, o que gera conflito com pins e triggers. Escolha ScrollSmoother quando a página for dominada por GSAP com parallax declarativo por data-speed e data-lag, e escolha Lenis quando precisar de smooth leve de cerca de 3KB com integração pontual via lenis.on(scroll, ScrollTrigger.update).

Qual prompt envio ao Claude Code para um hero com pin?

Comece pelo prompt exemplo do repositório iart-ai: "Build a pinned hero section that scrubs a timeline to scroll with GSAP." Depois complete com estrutura: nomes das seções, qual camada recebe pin, duração do scrub, comportamento em mobile e onde o Lenis entra. Confira a API com os MCPs de docs antes de gerar timelines longas.

Como desligo pin e scrub para quem prefere menos movimento?

Use gsap.matchMedia com dois ramos: o ramo no-preference carrega pin, scrub e parallax, e o ramo reduce entrega conteúdo estático e legível, sem pin nem scrub. Essa divisão segue a mesma lógica da skill acessível do conjunto iart-ai, segundo repo iart-ai.

Scroll cinematográfico pede três acertos em sequência. Base com GSAP 3.15, gratuito desde 30/abr/2025, e Lenis 1.3.x sincronizado pela ponte com o ticker. Decisão entre ScrollSmoother e Lenis pelo critério de wrapper e stack. Geração com Claude Code apoiada em skill, prompt com estrutura e MCPs de docs. Os cases Oryzo AI, Studio K95, Made With GSAP e Telescope mostram onde cada escolha se paga.

O próximo passo depende do gargalo do seu projeto. Para micro-interações em componentes React, aprofunde o satélite de Motion. Para auditoria de fluidez e checklist de acessibilidade antes de publicar, aprofunde o satélite de performance a 60fps.

• GSAP, site oficial
• Noqode sobre GSAP gratuito
• Artofstyleframe sobre scroll e motion
• YoungJu Dev sobre animação web
• Adamarant sobre Lenis e GSAP
• Snigdha sobre libs de animação
• Awwwards, seleção de animação
• Codrops, zoom em camadas com ScrollSmoother
• Annnimate sobre ScrollSmoother
• iart-ai web-animation-skills no GitHub
• Toolkit frontend para Claude Code
• GSAP MCP de vinhnguyen no npm
• GSAP MCP bl00dclot no GitHub
• Skillsplayground sobre gsap-react