BerlinKing/craft-frontend-motion

Craft Frontend Motion (Criando Movimento Frontend)

Construa movimento como parte da interação do produto, não como decoração colada nele. Identifique o verdadeiro proprietário da renderização, selecione a menor técnica adequada, preserve a semântica de estado e verifique o resultado em um navegador ativo.

Fluxo de Trabalho

1. Inspecione o alvo antes de propor uma implementação.
   • Localize a rota real, componente, estilos, proprietário do estado, proprietário do evento e a pilha de animação existente.
   • Leia as instruções do projeto e preserve alterações não relacionadas.
   • Se o usuário pedir para discutir primeiro, pare em uma especificação concreta de movimento até a aprovação.
2. Defina o contrato de movimento.
   • Declare o gatilho, estados inicial e final, duração, easing ou spring, comportamento de interrupção, comportamento de repetição, camadas e resultado para movimento reduzido.
   • Separe o estado de negócios do feedback visual. Uma ação de exclusão, navegação ou envio de formulário não deve depender da conclusão de uma linha do tempo ornamental, a menos que o produto exija explicitamente.
3. Selecione o material de origem.
   • Execute python3 scripts/query_catalog.py --need "<descrição do efeito>" --top 4.
   • Leia references/motion-routing.md para seleção de técnica.
   • Inspecione o README oficial atual do repositório selecionado, o código-fonte relevante, a versão da dependência/API e a licença antes de copiar código ou adicionar uma dependência. Trate os metadados do catálogo como um instantâneo de roteamento datado, não como verdade permanente.
4. Escolha um modo de adoção.
   • Prefira a pilha de animação instalada do projeto alvo quando ela puder satisfazer o contrato de forma limpa.
   • Copie e adapte um componente pequeno apenas quando seu código e licença permitirem; remova suposições de shell de demonstração e dependências não utilizadas.
   • Adicione uma biblioteca quando seu modelo de execução reduzir materialmente a complexidade ou o risco.
   • Extraia a técnica em vez do pacote quando um repositório for antigo, com framework incompatível ou muito pesado.
5. Implemente o menor sistema de movimento coerente.
   • Mantenha temporização e easing centralizados.
   • Limpe loops RAF, observadores, manipuladores de eventos, canvases, linhas do tempo, texturas e recursos GPU.
   • Lidere remontagens, entrada repetida rápida, interrupção, mudanças de rota, redimensionamento, abas ocultas e React Strict Mode.
   • Bloqueie corretamente o código apenas para navegador em aplicações SSR e carregue motores visuais pesados de forma preguiçosa quando prático.
6. Verifique com references/quality-gates.md.
   • Execute verificações estáticas e testes focados.
   • Exercite o runtime real em desktop largo, tamanho intermediário/tablet e mobile.
   • Verifique continuidade da transição, geometria final, erros no console, estouro horizontal, comportamento de entrada, movimento reduzido e desempenho realista.
7. Relate o resultado.
   • Lidere com o que agora funciona.
   • Nomeie a técnica selecionada ou repositório de origem e por que se encaixou.
   • Declare o que foi verificado e qualquer limitação restante honestamente.

Regras de Seleção

• Use transições/keyframes CSS para um pequeno número de propriedades compostas e estados determinísticos simples.
• Use Motion para presença em React, layout compartilhado, gestos, valores e transições coordenadas de componentes.
• Use React Spring para física interrompível onde continuidade de velocidade e resposta natural importam mais do que uma linha do tempo fixa.
• Use GSAP para linhas do tempo multiestágio explícitas, orquestração densa, trabalho com SVG/path, coreografia de scroll ou integração imperativa.
• Use Anime.js para interpolação compacta de DOM/SVG/objeto/canvas e efeitos gerativos escalonados fora de uma abstração React específica.
• Use Disintegrate apenas como técnica/referência para particionamento de snapshot DOM; espere limites de fidelidade do html2canvas e modernize seu ciclo de vida.
• Use tsParticles para partículas ambiente configuráveis, confete, fogos de artifício e fundos; não o rotule como decomposição precisa de DOM.
• Use PixiJS para grandes contagens de partículas 2D, filtros, campos de sprites, efeitos 2D orientados por shader e controle explícito de recursos GPU.
• Use React Bits, Magic UI ou Motion Primitives como coleções de origem. Inspecione o componente individual, pois dependências, custo de renderização e qualidade variam.

Proteções do Produto

• Preserve causalidade espacial: o movimento deve explicar de onde um objeto veio, para onde foi ou o que mudou.
• Prefira transform e opacity; anime propriedades de layout apenas com evidência de que o custo é aceitável.
• Nunca esconda layout quebrado atrás de movimento.
• Evite animações ambiente, de scroll, hover e de entrada simultâneas competindo por atenção.
• Forneça comportamento equivalente ao teclado e retenha a semântica de foco.
• Respeite prefers-reduced-motion; substitua movimento por uma mudança de estado imediata ou crossfade contido.
• Não afirme suavidade apenas por inspeção de código. Verifique no caminho renderizado e relate o escopo testado.
• Não altere regras de proxy/roteamento ou configuração de ambiente local não relacionada, a menos que o usuário autorize explicitamente na rodada atual.

Recursos

• references/repositories.json: catálogo datado dos dez repositórios de origem, licenças, pontos fortes, riscos e pontos de entrada de origem.
• references/motion-routing.md: guia de decisão e padrões de arquitetura prontos para produção.
• references/quality-gates.md: lista de verificação de implementação e verificação visual ao vivo.
• scripts/query_catalog.py: valide e pesquise o catálogo de repositórios por necessidades em linguagem natural ou tags.