Communitygithub.com

Construtor de Sites com Animação Scroll

Crie sites completos com animações de scroll premiadas, do início ao fim. Executa um assistente de descoberta, compila um blueprint Scroll Score, estrutura o projeto, implementa animações GSAP ScrollTrigger e verifica tudo em um navegador real com Playwright MCP.

O que é Construtor de Sites com Animação Scroll?

Esta skill permite construir sites completos com animações de scroll (scroll-driven animations), como landing pages no estilo Apple, sites awwwards, scrollytelling, efeitos de parallax e seções fixas (pinned). O processo é dividido em seis fases: Discovery (questionário interativo para entender o assunto, objetivo e seções), Score (criação de um blueprint `scroll-score.json` com todos os beats de animação), Assets (geração ou coleta de imagens, vídeos e frames), Scaffold (geração do esqueleto do projeto com Vite + TypeScript + GSAP), Build (implementação de cada beat usando padrões prontos como `pin-scrub`, `text-reveal`, `media-scrub-sequence`) e Verify (testes automatizados em navegador real com Playwright MCP para garantir que tudo funciona corretamente). A skill é autônoma após a fase de descoberta, não devendo fazer perguntas ao usuário durante a construção. Ela suporta os principais frameworks (Vite vanilla, React/Next.js com `useGSAP()`) e inclui verificações rigorosas de qualidade, como ausência de erros no console, fallback para `prefers-reduced-motion`, orçamento de assets e funcionamento correto de fixação (pin) e scrub.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hemangjoshi37a/scroll_animated_webpages_skill/tree/HEAD/skills/scroll-animated-site

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Construtor de Sites com Animação Scroll faz?

Receba um tópico e um assunto do usuário e entregue um site completo, verificado e orientado por scroll (scroll-driven) — sem devolver o trabalho no meio do caminho.

Antes de começar: é um site novo ou uma adaptação (retrofit)?

Adicionar movimento a uma página que já tem tráfego é um trabalho diferente com riscos diferentes — o orçamento de scroll precisa incluir a altura existente da página, e um pin é distância de scroll morta em uma página que alguém está escaneando para tomar uma decisão. O padrão é construir em uma URL de showcase separada e linkar para ela; faça a conversão no local somente quando a página não tem tráfego a perder e seu trabalho é causar impressão, não servir como referência. Sempre faça um backup byte a byte primeiro e entregue ao usuário o comando para restaurar. Leia references/08-failure-modes.md §3 antes de concordar em fazer uma adaptação.

O pipeline

Seis fases. Execute-as em ordem. Somente a Fase 1 conversa com o usuário.

1 DISCOVER  → assistente, 2–3 rodadas de perguntas       [interativo]
2 SCORE     → compilar blueprint scroll-score.json       [autônomo]
3 ASSETS    → gerar/coletar imagens, frames, vídeo       [autônomo]
4 SCAFFOLD  → esqueleto do projeto + runtime de movimento [autônomo]
5 BUILD     → implementar cada batida do Score           [autônomo]
6 VERIFY    → dirigir um navegador real, corrigir, repetir [autônomo]

Após o assistente fechar na Fase 1, pare de fazer perguntas. As Fases 2–6 executam até a conclusão por seu próprio julgamento. Registre as premissas em DECISIONS.md e reporte-as no final, em vez de travar por causa delas. O usuário pediu uma construção completa; uma página pela metade mais uma pergunta é uma execução fracassada.


Fase 1 — DISCOVER (o assistente)

Pergunte com a ferramenta AskUserQuestion, nunca como um bloco de prosa. Duas rodadas são o normal, três é o máximo. Banco de perguntas completo, ramo por ramo:

→ Leia references/01-discovery-wizard.md

A Rodada 1 é sempre as mesmas duas perguntas — tipo de assunto e objetivo principal:

AssuntoO que o scroll realmente está fazendo
Pessoa (portfólio, currículo, marca pessoal)Gerando confiança: trabalho → prova → contato
Produto (físico ou digital)Revelando o objeto: herói → funcionalidades → comprar
Empresa (agência, startup, estúdio)Estabelecendo escala: manifesto → trabalho → equipe
Evento / Lançamento (conferência, drop, release)Criando antecipação: data → line-up → registrar
Causa / História (ONG, editorial, relatório)Conduzindo um argumento: gancho → evidência → ação

O ramo em que você parar determina o esqueleto de seções e o padrão de movimento dominante. A Rodada 2 faz perguntas específicas do ramo (qual trabalho, qual produto, qual prova). Rodada 3, somente se ainda ambíguo, define direção estética, intensidade do movimento e estratégia de assets.

Pare o assistente assim que você conseguir nomear: o assunto, o objetivo, 4–7 seções, uma direção estética e de onde vêm os assets. Infira o resto.


Fase 2 — SCORE (o blueprint)

Compile tudo em scroll-score.json na raiz do projeto. Este é o contrato que tanto a construção quanto o verificador leem — escreva-o antes de escrever qualquer componente.

→ Leia references/02-scroll-score.md para o schema completo.

Um Score é uma lista de batidas (beats). Uma batida = um momento impulsionado pelo scroll: o que fixa (pin), o que faz scrub, por qual distância e o que se move.

{
  "meta":  { "subject": "…", "type": "product", "goal": "…", "stack": "vite-vanilla" },
  "theme": { "bg": "#0a0a0a", "fg": "#fafafa", "accent": "#ff4d17", "font": { … } },
  "motion":{ "intensity": "cinematic", "smoothScroll": false, "reducedMotion": "degrade" },
  "beats": [
    { "id": "hero", "pattern": "media-scrub-sequence", "pin": true,
      "scrub": 1, "start": "top top", "end": "+=200%", "frames": 48, … },
    { "id": "features", "pattern": "sticky-stack", … }
  ]
}

Faça o orçamento do scroll. A altura total da página deve ficar próxima de 100vh × (1 + Σ custo de scroll das batidas). Uma batida de scrub com pin custa 1,5–2,5 alturas de viewport; uma batida de revelação custa ~1. Menos de 3 no total faz o site parecer abrupto; mais de 12 parece uma tarefa chata. Mire em 5–9.


Fase 3 — ASSETS

Nunca envie caixas cinzas. Cada batida nomeada no Score precisa de seu asset real antes da Fase 5 — uma construção com placeholders sempre tem que ser refeita.

→ Leia references/05-asset-pipeline.md para o pipeline completo, incluindo a cadeia de AI-render → vídeo interpolado → sequência de frames, todas as invocações ffmpeg e os orçamentos de peso.

Três fontes, em ordem de preferência:

  1. Fornecido pelo usuário — sempre vence. Peça-os no assistente, nunca depois.
  2. Gerado — mcp__image-gen-mcp__generate_image (gpt-image-2, background: "transparent" para produtos, até 3840x2160), ou edit_image para transformar uma foto real do produto em um render estilizado.
  3. Placeholder — somente para uma batida que o usuário explicitamente adiou, e deve ser uma composição de gradiente/tipografia bem pensada, nunca uma caixa cinza.

Para um herói com sequência de imagens (o estilo Apple de "produto explode enquanto você rola"), a cadeia é: primeiro frame + último frame → vídeo interpolado → frames extraídos → sequência WebP → scrub em canvas. Mantenha a sequência abaixo de 4 MB no total, 36–60 frames, 1600px de largura. Esse orçamento é a razão principal pela qual o efeito permanece utilizável; estourá-lo é a falha mais comum deste padrão.


Fase 4 — SCAFFOLD

Stack padrão, a menos que o usuário tenha nomeado uma: Vite + vanilla TS + GSAP. Não tem ciclo de vida de framework para lutar, e bugs do ScrollTrigger no React são quase sempre bugs de limpeza. Use Next.js/React somente quando o usuário pedir ou o projeto precisar de roteamento, e então use useGSAP() para a limpeza — nunca useEffect puro.

Scroll suave (Lenis) é OPCIONAL — não faz mais parte da stack padrão. Adicione-o somente quando o usuário pedir explícitamente por scroll suave ou inercial. Ele substitui a rolagem nativa por sua própria posição animada, e quando parece ligeiramente errado, a página inteira parece quebrada — esta é a razão mais comum pela qual uma construção tecnicamente correta é rejeitada. O scrub do ScrollTrigger já te dá o sensação suave e cinematográfica que as pessoas geralmente querem dizer com "suave". Veja references/08-failure-modes.md §1.

→ Leia references/07-stack-setup.md para scaffolds e comandos exatos.

GSAP é 100% gratuito desde v3.13 (aquisição pela Webflow), incluindo SplitText, ScrollSmoother e MorphSVG. npm install gsap instala tudo — sem chave de licença, sem gsap-trial, sem soluções alternativas de plugins via CDN. Não diga ao usuário que um plugin é pago.

O conteúdo fica em src/content.ts, nunca inline no markup. O usuário deve poder alterar o texto sem tocar no código de movimento.


Fase 5 — BUILD

Implemente cada batida do Score usando as implementações de padrão canônicas:

→ Leia references/03-pattern-library.md — 12 padrões, prontos para copiar.

PadrãoUse para
reveal-on-enterEntradas de seção padrão, grades de cards
text-revealTítulos, citações em destaque (SplitText, mascarado)
pin-scrubO momento "uau" central — palco fixo, timeline com scrub
parallax-layersProfundidade: backgrounds, objetos em primeiro plano
media-scrub-sequenceRevelação de produto estilo Apple (canvas + frames)
media-scrub-videoMesmo efeito a partir de um arquivo de vídeo (currentTime)
horizontal-scrollPortfólios, galerias, timelines
mask-revealUma imagem se abrindo para engolir o viewport
sticky-stackListas de funcionalidades, cards empilhados
scroll-progressBarras de progresso, contadores, indicadores de seção
theme-morphMudança de fundo/cor entre seções
snap-sectionsPáginas estilo deck, uma seção por scroll

E as regras GSAP não negociáveis:

→ Leia references/04-gsap-rules.md antes de escrever código ScrollTrigger.

As cinco que quebram builds com mais frequência:

  1. Um ScrollTrigger por timeline, na timeline — nunca em um tween filho, nunca aninhado dentro de uma timeline pai.
  2. Se — e somente se — você adicionou Lenis, ele compartilha o loop do GSAP. lenis.on('scroll', ScrollTrigger.update) + gsap.ticker.add(t => lenis.raf(t * 1000)) + gsap.ticker.lagSmoothing(0). Nunca adicione um loop requestAnimationFrame separado para o Lenis.
  3. ease: "none" em qualquer tween que controla containerAnimation ou um media scrub.
  4. scrub ou toggleActions, nunca ambos no mesmo trigger.
  5. ScrollTrigger.refresh() após fontes e imagens carregarem — não apenas no resize.
  6. Antes de qualquer pin, percorra os ancestrais em busca de transform / filter / contain. Qualquer um deles quebra silenciosamente position: fixed, então o pin é criado, reporta pin: true, e não faz nada. Remova a propriedade ou defina pinType: 'transform'. Veja 08-failure-modes.md §2.

Anime apenas transform e opacity. Qualquer coisa que toque top, left, width, height ou margin no scroll vai derrubar frames.


Fase 6 — VERIFY

Esta fase não é opcional e é o que diferencia esta skill de escrever GSAP à mão. Animações de scroll não podem ser verificadas lendo código — pins colapsam, triggers disparam na profundidade errada e frames desaparecem apenas em um navegador real com um viewport real.

→ Leia references/06-verification.md para o loop completo e a lista de verificação. → Leia references/08-failure-modes.md — falhas que passam em todas as verificações automatizadas. Leia antes da Fase 4, não depois de algo quebrar.

Inicie o servidor de desenvolvimento, então dirija-o com Playwright MCP:

mcp__playwright__browser_navigate      → a URL do servidor dev
mcp__playwright__browser_resize        → 1440×900, depois 390×844
mcp__playwright__browser_evaluate      → scroll até a profundidade, leia o estado
mcp__playwright__browser_take_screenshot → em cada profundidade
mcp__playwright__browser_console_messages → erros e avisos do GSAP
mcp__playwright__browser_network_requests → 404s, peso dos assets

Percorra 0%, 15%, 30%, 50%, 70%, 85%, 100% da altura da página no desktop e no mobile. Em cada parada, tire um screenshot e olhe para ele. Você está verificando se a página parece correta, não apenas se não lançou erros.

Dirija a página com entrada REAL — mouse.wheel() ou teclas, nunca window.scrollTo. Scroll sintético é engolido por bibliotecas de hijacking de scroll, que é exatamente a falha que você precisa pegar. Se três notches da roda não moverem a página, está quebrada, não importa o que as asserções digam.

Falhe na execução e corrija se qualquer uma destas condições for verdadeira:

  • Um erro no console, ou qualquer aviso do ScrollTrigger
  • Qualquer 404, ou peso total dos assets acima do orçamento
  • Um screenshot em branco/sem estilo em qualquer profundidade
  • Uma seção fixa que sobrepõe a próxima seção, ou colapsa o layout
  • Conteúdo que nunca se torna visível (uma revelação que nunca dispara)
  • Transbordamento horizontal a 390px de largura
  • markers: true sobrevivendo em qualquer lugar do código fonte
  • Nenhum fallback para prefers-reduced-motion
  • Três notches reais da roda não movem visivelmente a página
  • Um pin cujo palco ainda rastreia o scroll (afirme que |rect.top| < 10 dentro do intervalo)
  • Mídia com scrub atingindo seu fim antes de ~90% do seu pin
  • Mais de ~40 notches da roda para alcançar o CTA principal

Loop de correção → re-verifique até ficar limpo, até 5 rodadas. Se algo ainda falhar após 5, entregue o resto, desabilite aquela batida atrás de uma flag e diga isso claramente no relatório final. Nunca reporte sucesso em uma página não verificada.


Definição de concluído

  • scroll-score.json corresponde ao que foi realmente construído
  • Cada batida verificada no desktop e mobile
  • Zero erros no console, zero 404s
  • prefers-reduced-motion degrada para estados instantâneos, sem movimento
  • Sanidade estilo Lighthouse: nenhuma mudança de layout devido a pins, imagens dimensionadas
  • README.md — como executar, onde o conteúdo vive, como trocar assets
  • DECISIONS.md — premissas assumidas após o assistente fechar
  • Mensagem final: o que foi construído, o que foi assumido, o que rever

Não faça

  • ❌ Faça perguntas após o assistente fechar — assuma, registre e reporte
  • ❌ Reporte concluído sem executar a Fase 6 em um navegador real
  • ❌ Envie markers: true, console.log ou um TODO no código entregue
  • ❌ Use gsap-trial ou afirme que SplitText/ScrollSmoother precisam de uma licença Club
  • ❌ Anime propriedades de layout no scroll
  • ❌ Fixe (pin) no mobile sem verificar — prefira fade in abaixo de 768px
  • ❌ Exceda o orçamento de assets para uma sequência de herói

Habilidades Relacionadas