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:
| Assunto | O 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:
- Fornecido pelo usuário — sempre vence. Peça-os no assistente, nunca depois.
- Gerado —
mcp__image-gen-mcp__generate_image(gpt-image-2,background: "transparent"para produtos, até3840x2160), ouedit_imagepara transformar uma foto real do produto em um render estilizado. - 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ão | Use para |
|---|---|
reveal-on-enter | Entradas de seção padrão, grades de cards |
text-reveal | Títulos, citações em destaque (SplitText, mascarado) |
pin-scrub | O momento "uau" central — palco fixo, timeline com scrub |
parallax-layers | Profundidade: backgrounds, objetos em primeiro plano |
media-scrub-sequence | Revelação de produto estilo Apple (canvas + frames) |
media-scrub-video | Mesmo efeito a partir de um arquivo de vídeo (currentTime) |
horizontal-scroll | Portfólios, galerias, timelines |
mask-reveal | Uma imagem se abrindo para engolir o viewport |
sticky-stack | Listas de funcionalidades, cards empilhados |
scroll-progress | Barras de progresso, contadores, indicadores de seção |
theme-morph | Mudança de fundo/cor entre seções |
snap-sections | Pá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:
- Um ScrollTrigger por timeline, na timeline — nunca em um tween filho, nunca aninhado dentro de uma timeline pai.
- 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 looprequestAnimationFrameseparado para o Lenis. ease: "none"em qualquer tween que controlacontainerAnimationou um media scrub.scruboutoggleActions, nunca ambos no mesmo trigger.ScrollTrigger.refresh()após fontes e imagens carregarem — não apenas no resize.- Antes de qualquer pin, percorra os ancestrais em busca de
transform/filter/contain. Qualquer um deles quebra silenciosamenteposition: fixed, então o pin é criado, reportapin: true, e não faz nada. Remova a propriedade ou definapinType: 'transform'. Veja08-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: truesobrevivendo 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| < 10dentro 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.jsoncorresponde ao que foi realmente construído - Cada batida verificada no desktop e mobile
- Zero erros no console, zero 404s
-
prefers-reduced-motiondegrada 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.logou umTODOno código entregue - ❌ Use
gsap-trialou 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