Objetivo
Metodologia de animações do site pessoal do Erlin: introduzir a biblioteca de animações motion em sites Next.js/React, migrar importações de framer-motion, e configurar animações de revelação ao scroll / grade com stagger / transições de página / efeitos de navegação, sem nunca deixar que as animações escondam o conteúdo. Lição principal: whileInView já fez com que cards da página inicial ficassem travados em opacity:0 ("os cards do projeto desapareceram"). Portanto, é necessário um fallback de visibilidade; implementações existentes e confiáveis podem ser mantidas; Reveal é uma referência opcional, não uma proibição geral de whileInView.
Etapas de Execução
-
Primeiro, avalie o ambiente do projeto (gaste 30 segundos antes de agir para evitar usar o template errado):
- Gerenciador de pacotes: Reconheça apenas um lockfile:
pnpm-lock.yaml→ pnpm,package-lock.json→ npm,yarn.lock→ yarn,bun.lockoubun.lockb→ bun. Se houver múltiplos lockfiles, pare e pergunte ao usuário; se não houver lockfile, leia opackage.jsone o campopackageManager; se ainda assim não for possível determinar, pare e não adivinhe o gerenciador. Comandos posteriores de instalação, migração, lint e build devem seguir o gerenciador confirmado. - Versões Next/React: Verifique as versões reais do Next.js, React e da biblioteca de animação instalada, peer dependencies e notas oficiais de compatibilidade; não hardcode versões nem declare compatibilidade total entre versões sem verificar.
- Estrutura de rotas (antes de escolher um template, detecte, não assuma App Router): Se existe diretório
app/→ App Router, siga as regras abaixo para escolher o template; se só existepages/→ Pages Router, não há mecanismo detemplate.tsx; nesse caso, modifique empages/_app.tsxou no nível do componente de página alvo para fazer a transição e explique a diferença ao usuário; se nenhum dos dois existir → não é um projeto Next, implemente de forma equivalente no ponto de montagem do framework. App Router: Se houver rotas com prefixo de locale (diretórioapp/[locale]/), coloque o template emapp/[locale]/template.tsx; se não houver rota com locale (como em sites que alternam idioma pelo client), coloque emapp/template.tsx; o Next também remonta o template a cada navegação, e a transição de fade-in funciona normalmente. - Verifique se o componente atual é server component: Componentes que precisam de interação (motion) devem ser isolados no menor componente client possível; não transforme todo um componente que contém lógica de servidor em client.
- Gerenciador de pacotes: Reconheça apenas um lockfile:
-
Reutilize dependências existentes: Se o projeto já usa
framer-motione atende aos requisitos, continue usando-o; não migre por padrão ao adicionar novas animações. Migre apenas quando o usuário solicitar ou quando a capacidade/compatibilidade atual realmente exigir. Nesse caso, verifique as diferenças de versão, instalemotioncom o gerenciador de pacotes do projeto, verifique uma a uma as importações e APIs demotion/react; após confirmar que não há dependências residuais, remova o pacote antigo. Não altere comentários ou documentação não relacionados. -
Adicione animações: consulte Reveal conforme necessário: O template está em
assets/reveal.tsx. Copie paracomponents/motion/reveal.tsxe adapte os aliases de caminho. Pontos de design (adaptáveis ao projeto):- Fallback de visibilidade: O template usa IntersectionObserver + timeout de 2.5s; 2.5s é apenas um parâmetro de referência, ajuste conforme a página e o comportamento de carregamento. Você pode usar
whileInViewjá validado ou outros mecanismos, garantindo que o conteúdo permaneça acessível mesmo se o observer, JavaScript ou a hidratação falharem. - Trate
reduced-motione ausência de observer de acordo com as regras de SSR/hidratação e lint do projeto; evite inconsistências de hidratação e atualizações síncronas de effect desnecessárias; não transforme uma experiência de lint em uma proibição geral de todas as APIs. - Com
reduced motion, renderize diretamente o estado final. - Use transição CSS pura (
cubic-bezier(0.22,1,0.36,1)), semmotion.div, zero overhead de runtime de animação. Revealjá possui a propclassName: se um card originalmente é umadiv(como um cardglass), passe a classe diretamente paraReveal, economizando um aninhamento; para elementos semânticos comoarticle/section, envolva-os comRevealpara preservar a semântica.
- Fallback de visibilidade: O template usa IntersectionObserver + timeout de 2.5s; 2.5s é apenas um parâmetro de referência, ajuste conforme a página e o comportamento de carregamento. Você pode usar
-
Locais de aplicação e fórmula de stagger:
Localização Como fazer delay Grade de cards (vários blocos na home) Cada item envolto em RevealMath.min(i * 0.08, 0.4), com teto para evitar lentidão em grades longasLista de artigos (writing, latest-writing) Cada linha envolta em Reveali * 0.05~0.07, com tetoMath.min(i*0.05, 0.3)para evitar lentidão em listas longasLinha de texto ao lado de imagem grande de projeto RevealFixo 0.15, para escalonar com o efeito de parallax da imagemCard de texto/contato (about) Bloco grande RevealSegundo bloco: 0.1Barra de navegação motion.headercom inicialy:"-100%"deslizando para baixo; ocultação ao scroll reutiliza a mesma transform— Menu mobile AnimatePresence+ transição deopacity/y, substituindo alternânciablock/hidden— Transição de rota Criar app/template.tsx(sem rota locale) ouapp/[locale]/template.tsx(com locale-prefixed; o Next remonta o template a cada navegação) com fade-in deopacity+y, 0.35s— -
Validação e entrega: Execute com o gerenciador de pacotes confirmado no passo 1:
pnpm lint && pnpm build # projetos pnpm; build deve ser bem-sucedido (projetos SSG completos com exportação SSG) npm run lint && npm run build # projetos npmApenas quando o usuário autorizar o commit, siga a convenção de commits do projeto, exemplo:
feat(motion): migrar biblioteca motion e adicionar animações em todo o site. Adicione apenas os arquivos relacionados a esta tarefa — se houver alterações não relacionadas no repositório, não as inclua neste commit.
Regras de Decisão
- Quando usar: Adicionar animações/efeitos a sites Next.js; migrar de
framer-motionpara o pacotemotion(verifique a compatibilidade da API da versão atual antes); quando o usuário solicitar "revelação ao scroll", "stagger", "transição de página", "mais animações". - Não cobre: SwiftUI, animações CSS-only ou animações em vídeo com Remotion.
- Regras de design de animações (lições aprendidas) :
- Elementos LCP (H1, hero) não devem ter animação de entrada:
SkewRevealtem propinstant, ou o estado inicial já deve ser o estado final; caso contrário, o texto SSR pode piscar. - Todas as animações respeitam
prefers-reduced-motion: UseuseReducedMotion(), e quando reduzido, renderize o estado final / não registre listeners. - Easing uniforme
[0.22, 1, 0.36, 1](estilo easeOutQuint), duração 0.3–0.8s, priorizando moderação. - Animações de hover usam transição CSS (ex.:
hover:-translate-y-1,group-hover:scale-105), não é necessário usarmotion. - Quando há filtragem no client (ex.: filtro por tag), itens com a mesma key não repetem a animação — isso é comportamento esperado; itens novos são animados automaticamente.
- Elementos LCP (H1, hero) não devem ter animação de entrada:
- Componentes existentes: Mantenha
SkewReveal(entrada),Parallax(parallax),Magnetic(magnético),MouseParallax(parallax do mouse); novas animações coexistirão no mesmo diretório. Se o projeto já tem um diretório.zcode/.agentspara componentes de animação (ex.:components/motion/), coloque novos componentes lá. - Limite server/client: Server components podem renderizar
Revealdiretamente (ele é um componente client, mas pode ser usado como filho sem problemas).
Antes de finalizar as animações, verifique visualmente a acessibilidade e visibilidade do conteúdo; este skill cobre a implementação técnica de animações com motion em Next.js/React; animações em RN/Expo ou outras pilhas devem ser implementadas diretamente seguindo os mesmos princípios, sem depender deste script.
Formato de Saída
- Componente
Reveal: Copiado deassets/reveal.tsxparacomponents/motion/reveal.tsx, com aliases de caminho adaptados. - Transição de rota:
app/template.tsx(sem rota locale) ouapp/[locale]/template.tsx(com locale-prefixed), fade-in comopacity+yem 0.35s. - Mensagem de commit: conventional commits + descrição em português, exemplo:
feat(motion): migrar biblioteca motion e adicionar animações em todo o site.
Exemplo
Pergunta do Usuário
"Adicionar revelação ao scroll no site e trocar framer-motion por motion."
Resposta da Ferramenta
pnpm
pnpm add motion && pnpm remove framer-motion bem-sucedido; package.json contém a versão de motion compatível com o projeto; pnpm lint && pnpm build mantém o SSG completo do site.
sed
sed -i '' 's/from "framer-motion"/from "motion\/react"/g' <arquivos> executado, todas as importações agora apontam para motion/react; apenas comentários relacionados à migração e que estejam realmente desatualizados foram atualizados.
Saída Final
components/motion/reveal.tsx (IntersectionObserver manual + timeout de 2.5s) + stagger de cards/lista + app/template.tsx com fade-in de rota; lint e build aprovados; relatório de verificação real; apenas arquivos relacionados à tarefa foram commitados, com autorização do usuário.
Requisitos de Qualidade
- Linha vermelha de conteúdo: Nunca deixe as animações esconderem o conteúdo — verifique se o conteúdo permanece acessível em SSR,
reduced-motion, falha de observer/script;Reveale o parâmetro de timeout são implementações de referência, não proíbam APIs mecanicamente. - Linha vermelha de acessibilidade: Todas as animações respeitam
prefers-reduced-motion; elementos LCP (H1, hero) não têm animação de entrada. - Validação: Execute
lint && buildcom o gerenciador de pacotes confirmado; obuilddeve permanecer bem-sucedido (se o projeto é SSG completo, a exportação SSG também não deve ser quebrada; projetos SSR/ISR consideram o build aprovado, sem inventar requisitos de SSG). - Disciplina de commit: Adicione apenas arquivos relacionados a esta tarefa; alterações não relacionadas no repositório não devem ser incluídas.
- Aprimoramento progressivo: Não modifique componentes de animação que já funcionam para "uniformizar o estilo"; baseie-se em requisitos e evidências de acessibilidade.