Animation Performance: diagnostique animações lentas com evidência

ANÁLISE EDITORIAL

Uma animação pode parecer fluida no notebook de quem a criou e engasgar no telefone do usuário. A Skill Animation Performance, mantida por Emil Kowalski, orienta um agente de programação a localizar a causa antes de trocar propriedades CSS ou adicionar otimizações. Ela não mede o seu site sozinha: o resultado depende do código disponível, de uma gravação de desempenho e da revisão de quem mantém a interface.

O que esta Skill faz

O arquivo SKILL.md organiza o diagnóstico em três fases: inventariar cada animação, investigar propriedades e trabalho por quadro, e registrar a causa com uma proposta verificável. O escopo é desempenho de movimento na web. A Skill distingue alterações que exigem layout, pintura ou composição e chama atenção para tarefas concorrentes no thread principal, re-renderizações frequentes em React, variáveis CSS herdadas e uso indiscriminado de will-change. Ela não escolhe a estética, a curva ou a duração ideal; essas decisões pertencem a outras Skills do mesmo mantenedor.

Há uma distinção importante: transform e opacity costumam evitar trabalho de layout, mas isso não é garantia de aceleração em todo navegador, elemento ou dispositivo. A documentação da MDN sobre desempenho de animações descreve as etapas de estilo, layout, pintura e composição. A Skill usa esse modelo para formular hipóteses, não para declarar que qualquer mudança isolada ficou mais rápida.

Para quem serve e quando não serve

É útil para desenvolvedores front-end, designers que implementam interfaces, equipes de produto com animações em React e responsáveis por um site que apresenta movimento irregular durante navegação, carregamento, arraste ou abertura de painéis. O uso mais produtivo começa com um caso concreto: um elemento, uma rota, um dispositivo e o momento em que a falha aparece. Se o problema é apenas escolher uma linguagem visual, a Skill não substitui uma revisão de design. Se a página está lenta sem animação, o diagnóstico deve abranger rede, scripts, imagens e renderização geral antes de atribuir a culpa ao movimento.

Compatibilidade e pré-requisitos

A Skill é um documento Markdown em formato de Agent Skills. Pode ser lida por agentes capazes de carregar SKILL.md, mas a pasta e a forma de invocação variam conforme o cliente. Não há binário nem biblioteca obrigatória dentro do ZIP do Bastidores. Para fazer uma auditoria real, forneça ao agente acesso ao código-fonte pertinente, às folhas de estilo e, se houver, ao componente que controla a animação. Para confirmar o diagnóstico, abra as ferramentas de desempenho do navegador e teste também em um dispositivo representativo dos usuários.

O README do mantenedor documenta npx skills@latest add emilkowalski/skills. Esse comando obtém Skills do repositório e pode executar código do instalador; revise a origem, o conjunto selecionado e o ambiente antes de usá-lo. Quem prefere começar sem instalador pode baixar nosso pacote documental, conferir o SHA-256, ler os três arquivos e só então copiar a pasta para o diretório de Skills que seu agente documenta. O ZIP não instala nada por si só.

Instalação controlada com o pacote local

Baixe o ZIP pelo card de download desta página e compare seu SHA-256 com o valor publicado no catálogo. Extraia em uma pasta de teste. Abra ORIGEM.md para confirmar o commit e os hashes individuais; depois leia LICENSE e o SKILL.md inteiro. A licença MIT do repositório permite redistribuir estes textos, mas não transforma exemplos de código em uma correção pronta para produção. Coloque a pasta animation-performance somente no caminho de Skills indicado pelo seu cliente e reinicie ou recarregue o agente se ele não detectar a nova instrução.

Há um botão separado para abrir o repositório oficial. Use-o para comparar o conteúdo empacotado ao commit fixado e consultar atualizações posteriores. O pacote local não recebe atualizações automáticas; isso favorece auditoria e repetibilidade, mas exige nova revisão quando você quiser adotar um commit mais recente. Não misture arquivos de commits diferentes dentro da mesma instalação.

Configuração antes do primeiro uso

Não configure credenciais. Esta Skill não precisa de conta, token ou acesso a serviço externo para orientar uma revisão do código. Defina o escopo de leitura: componente, CSS, rota e momento da interação. Diga se o agente pode apenas diagnosticar ou também propor um diff. Para uma primeira execução, mantenha somente leitura. O acesso de escrita é necessário apenas se você autorizar uma correção após avaliar a hipótese. Não conceda acesso a produção, dados pessoais ou segredos para investigar uma animação.

Registre uma linha de base: navegador e versão efetivamente usados, dispositivo, frequência de atualização quando conhecida e reprodução da falha. A gravação de desempenho importa mais do que a impressão visual em uma máquina rápida. O guia oficial do painel Performance do Chrome mostra como analisar quadros e tarefas. A aba Rendering também oferece indicadores visuais de repintura e estatísticas, conforme a documentação do Chrome DevTools.

Primeiro uso: um caso delimitado

Escolha, por exemplo, a abertura de um painel lateral que engasga durante a mudança de rota. Peça ao agente: “Use Animation Performance para analisar este componente e suas regras CSS. Liste as propriedades animadas, o mecanismo usado, as hipóteses de custo e o que precisa de medição. Não altere arquivos.” Forneça o caminho dos arquivos e uma descrição da reprodução. Se houver captura de perfil, compartilhe apenas um registro sem dados sensíveis.

A resposta esperada não é “use GPU”. Ela deve apontar o elemento e a linha de código, dizer se há transição de width, margin, sombra, transform ou opacity, observar se a animação coincide com navegação ou hidratação e marcar o que foi inferido do código versus o que foi confirmado por medição. A documentação da Web Animations API na MDN ajuda a entender uma opção de controle pelo navegador, mas a escolha entre CSS, WAAPI e JavaScript depende do caso.

Como ler o resultado sem prometer desempenho

Uma conclusão útil separa três coisas. Primeiro, a evidência: gravação que mostra quadros perdidos, tarefa longa ou custo de layout. Segundo, a hipótese causal: por exemplo, o painel muda sua largura e desloca o conteúdo vizinho a cada quadro. Terceiro, a proposta: testar uma transformação visual que preserve a interação, comparar gravações e conferir responsividade. O próprio arquivo da Skill pede um relatório com causa, antes, depois e estado da verificação. Se não houver gravação, a conclusão deve permanecer provisória.

Também não trate números gerais de quadros por segundo como benchmark do seu site. O tempo disponível por quadro muda com a tela e o navegador. Uma animação de transform pode continuar ruim por causa de imagens grandes, camadas caras, scripts concorrentes ou excesso de elementos. A mudança precisa ser testada no fluxo real, especialmente em aparelhos menos potentes e com preferência por movimento reduzido.

Permissões e riscos

O ZIP tem apenas documentação, porém um agente conectado ao repositório pode ler código e, se autorizado, alterá-lo. A Skill inclui sugestões como substituir propriedades e mexer em componentes React; uma aplicação automática pode mudar o layout, o foco, a acessibilidade ou a posição final de elementos. Revise o diff, teste teclado e toque, e preserve uma forma simples de reverter. will-change pode aumentar o uso de memória de camadas, portanto não é uma correção genérica.

Não copie uma regra da Skill sem entender as condições. Algumas afirmações dependem de browser, biblioteca e versão, e os exemplos servem como ponto de partida. Verifique suporte e comportamento no ambiente do projeto. Se uma gravação contém URL interna, nome de usuário ou dados de sessão, retire esses dados antes de compartilhá-la com um agente externo.

Erros comuns e solução

O agente não encontra a Skill: confirme o caminho aceito pelo cliente, a existência de SKILL.md na pasta e recarregue a sessão. O instalador trouxe o repositório inteiro: use o ZIP documental desta página ou selecione somente a Skill desejada no fluxo do instalador, após revisar o que será instalado. A animação melhorou no desktop, mas não no celular: repita a gravação no dispositivo-alvo e compare as mesmas interações. A alteração visual quebrou o layout: volte ao diff e confirme se scale ou translate mantêm área de clique, fluxo, foco e estado final.

O relatório diz “parece fluido” sem evidência: peça a localização do componente, a propriedade alterada, a hipótese específica e a medição que falta. Uma biblioteca foi culpada sem rastreio: capture a linha do tempo e descubra se o trabalho acontece no thread principal antes de trocar dependências. O resultado esperado é um diagnóstico delimitado e testável, não uma garantia de 60 quadros por segundo.

Versão, licença e fonte

Esta edição fixa o commit 2d228630ba1446365f614a108cb8252f1feda202 de emilkowalski/skills, pasta Animation Performance. O repositório registrava 45.702 estrelas em 12/10/2026, contagem de consulta e não selo de qualidade. O mantenedor é Emil Kowalski e a licença do repositório é MIT. O pacote local contém SKILL.md, LICENSE e ORIGEM.md, sem executáveis ou dependências. A arte de capa é uma ilustração editorial exclusiva do Bastidores da IA, não uma captura real nem uma medição de desempenho.