Communitygithub.com

erlinerd/erlin-skills

Introduz a biblioteca de animações motion em projetos Next.js/React, migra de framer-motion e configura animações de revelação ao scroll, grade com stagger, transições de página e efeitos de navegação.

O que é erlin-skills?

Este skill é especializado em adicionar animações modernas e acessíveis a sites Next.js/React usando a biblioteca `motion`. Ele automatiza a migração de `framer-motion` para `motion`, gerencia a instalação correta com base no gerenciador de pacotes do projeto (pnpm, npm, yarn, bun) e cria componentes prontos para uso, como `Reveal`, que aplicam animações de entrada com visibilidade garantida. O skill segue princípios rigorosos de acessibilidade, como respeitar a preferência `prefers-reduced-motion`, evitar animações em elementos LCP (como H1 e hero) e garantir que o conteúdo nunca seja ocultado, mesmo em falhas de JavaScript ou hidratação. Ele também configura transições de rota usando o `template.tsx` do Next.js App Router, inclui um sistema de stagger para grades e listas, e orienta a criação de animações de navegação. É indicado para desenvolvedores que desejam adicionar animações de scroll, efeitos de página e migrações de bibliotecas de animação em projetos Next.js, mas não cobre SwiftUI, animações CSS-only ou Remotion.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

Perguntar na sua IA favorita

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

Documentação

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

  1. 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.lock ou bun.lockb → bun. Se houver múltiplos lockfiles, pare e pergunte ao usuário; se não houver lockfile, leia o package.json e o campo packageManager; 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ó existe pages/ → Pages Router, não há mecanismo de template.tsx; nesse caso, modifique em pages/_app.tsx ou 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ório app/[locale]/), coloque o template em app/[locale]/template.tsx; se não houver rota com locale (como em sites que alternam idioma pelo client), coloque em app/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.
  2. Reutilize dependências existentes: Se o projeto já usa framer-motion e 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, instale motion com o gerenciador de pacotes do projeto, verifique uma a uma as importações e APIs de motion/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.

  3. Adicione animações: consulte Reveal conforme necessário: O template está em assets/reveal.tsx. Copie para components/motion/reveal.tsx e 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 whileInView já 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-motion e 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)), sem motion.div, zero overhead de runtime de animação.
    • Reveal já possui a prop className: se um card originalmente é uma div (como um card glass), passe a classe diretamente para Reveal, economizando um aninhamento; para elementos semânticos como article/section, envolva-os com Reveal para preservar a semântica.
  4. Locais de aplicação e fórmula de stagger:

    LocalizaçãoComo fazerdelay
    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 longas
    Lista de artigos (writing, latest-writing)Cada linha envolta em Reveali * 0.05~0.07, com teto Math.min(i*0.05, 0.3) para evitar lentidão em listas longas
    Linha de texto ao lado de imagem grande de projetoRevealFixo 0.15, para escalonar com o efeito de parallax da imagem
    Card de texto/contato (about)Bloco grande RevealSegundo bloco: 0.1
    Barra de navegaçãomotion.header com inicial y:"-100%" deslizando para baixo; ocultação ao scroll reutiliza a mesma transform—
    Menu mobileAnimatePresence + transição de opacity/y, substituindo alternância block/hidden—
    Transição de rotaCriar app/template.tsx (sem rota locale) ou app/[locale]/template.tsx (com locale-prefixed; o Next remonta o template a cada navegação) com fade-in de opacity+y, 0.35s—
  5. 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 npm
    

    Apenas 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-motion para o pacote motion (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: SkewReveal tem prop instant, 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: Use useReducedMotion(), 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 usar motion.
    • 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.
  • 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/.agents para componentes de animação (ex.: components/motion/), coloque novos componentes lá.
  • Limite server/client: Server components podem renderizar Reveal diretamente (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 de assets/reveal.tsx para components/motion/reveal.tsx, com aliases de caminho adaptados.
  • Transição de rota: app/template.tsx (sem rota locale) ou app/[locale]/template.tsx (com locale-prefixed), fade-in com opacity+y em 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; Reveal e 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 && build com o gerenciador de pacotes confirmado; o build deve 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.

Habilidades Relacionadas