ElvinEga/skills

Animação de Rolagem

Um roteiro para dez padrões de animação de rolagem. Todos os padrões, exceto JOS, são construídos sobre as mesmas primitivas React + Framer Motion — useScroll + useTransform (+ useSpring para suavização) — portanto, leia este arquivo primeiro para entender o modelo mental compartilhado e, em seguida, carregue apenas o(s) arquivo(s) de referência que correspondem ao que o usuário deseja.

Modelo Mental Compartilhado (padrões Framer Motion)

Quase todos os efeitos neste skill seguem o mesmo esqueleto:

import { motion, useScroll, useSpring, useTransform } from "framer-motion";
import { useRef } from "react";

const containerRef = useRef<HTMLDivElement>(null);

const { scrollYProgress } = useScroll({
  target: containerRef,
  offset: ["start start", "end end"],
});

const smoothProgress = useSpring(scrollYProgress, {
  damping: 25,     // 20–30: maior = menos oscilação
  stiffness: 200,  // 150–300: maior = mais rápido
  mass: 0.5,       // 0.5–0.8: menor = mais leve/rápido
});

const someValue = useTransform(smoothProgress, [0, 1], [valorInicial, valorFinal]);

• A altura do contêiner controla a velocidade/dramaticidade. Mais vh = rolagem mais lenta e cinematográfica. Faixa típica: 150vh (rápida) a 400vh (meditativa).
• position: sticky; top: 0 prende o conteúdo à viewport enquanto o contêiner alto fornece espaço para animar durante a rolagem.
• Sempre envolva o scrollYProgress bruto em useSpring — sem isso, o movimento parece robótico/linear em vez de físico.
• Efeitos com múltiplos elementos (pilhas, grades, orbitadores) dão a cada item uma janela: start = índice / total, end = start + 1 / total, e então mapeiam [start, end] (ou uma curva de sino de 5 pontos para efeitos de pico no meio) para as transformações desse item.
• Respeite prefers-reduced-motion: recorra a um layout estático ou a um simples fade para usuários que o solicitarem.

Escolhendo um Padrão — Guia de Seleção

Leia o arquivo de referência correspondente em references/ para obter o código completo do componente, variantes, regras críticas e tabela de solução de problemas. Não adivinhe os valores de transformação de memória — os arquivos de referência possuem números calibrados e funcionais.

O usuário pede...	Leia esta referência
Cartões empilhando/prendendo conforme a rolagem, "cartões empilhados" genérico, pilha 3D inclinada, pilha multicamada, pilha horizontal de cartões	references/scroll-stack.md
Especificamente estilo "Chronos" de empilhamento, recessão cinematográfica agressiva com crescimento de sombra/raio	references/chronos-scroll-stack.md
Camadas de profundidade com múltiplas velocidades, fundo/primeiro plano em velocidades diferentes, paralaxe "insana"/dramática, formas de acento flutuantes	references/insane-parallax.md
Zoom de herói estilo Apple em uma imagem, desfoque com puxão de foco, revelações de texto em camadas sobre imagem com zoom, zoom de lançamento de produto cinematográfico	references/immersive-scroll-zoom.md
Imagens da galeria com zoom ao entrar na viewport, zoom com foco em ponto do produto, grade de imagens com escala conduzida por rolagem	references/image-zoom-scrolling.md
Divisão de imagem em metades/quadrantes e separação, fragmentação diagonal, revelação estilo portfólio de agência com inclinação 3D	references/image-split-3d.md
Elementos orbitando, anéis de progresso circular, galerias radiais/espirais, texto seguindo um caminho circular	references/circular-scroll.md
Cartões/azulejos que crescem/escalam conforme se tornam ativos, expansão de grade em curva de sino, alvenaria clicável para expandir	references/expanding-cards-scroll.md
Avanço quadro a quadro, "livro animado" por rolagem, sequências de imagem com canvas, revelação de vídeo de produto vinculada à posição de rolagem	references/scroll-image-sequences.md
Revelações simples de fade/slide/zoom-in, revelações escalonadas, SEM usar React/Framer Motion, ou explicitamente "JOS"	references/jos-animation.md

Se a solicitação for ambígua ou puder se encaixar em vários padrões (por exemplo, "torne o herói mais dinâmico na rolagem"), prefira insane-parallax.md ou immersive-scroll-zoom.md para seções de herói, e pergunte apenas se realmente não estiver claro — caso contrário, escolha a correspondência mais próxima e anote a suposição.

Regras Transversais (aplicam-se independentemente do padrão)

• Apenas Framer Motion para todos os padrões, exceto JOS — sem GSAP, sem código vanilla de escuta de rolagem, a menos que o usuário peça explicitamente uma implementação sem Framer Motion.
• Padrões de Spring que funcionam bem em quase todos os lugares: damping: 20–30, stiffness: 150–300, mass: 0.5–0.8. Cada arquivo de referência fornece os valores calibrados exatos para aquele padrão — use esses em vez dos padrões gerais quando diferirem.
• willChange: "transform, opacity" em elementos animados para manter as coisas no thread do compositor.
• Matemática de z-index para qualquer coisa empilhada: geralmente total - index para que os elementos anteriores fiquem no topo enquanto recuam.
• Não anime demais. 3–8 cartões/quadros/camadas geralmente é o ponto ideal; mais se torna cansativo ou prejudica o desempenho mobile.
• Mobile: suavize as faixas de escala, reduza a contagem de camadas/quadros e prefira whileInView em vez de longas sequências conduzidas por rolagem onde o drama não é essencial.

Combinando Padrões

Esses padrões se combinam. Uma landing page pode usar insane-parallax para o herói, scroll-stack para uma seção de recursos e jos-animation para simples fades escalonados em outras partes da mesma página. Leia cada arquivo de referência relevante de forma independente — eles não dependem uns dos outros, exceto onde indicado (por exemplo, scroll-stack.md aponta para chronos-scroll-stack.md para a variante cinematográfica completa).