Empro Labs Animation Skill
Skill de design de movimento web. Duas etapas: escreva a especificação de movimento (ANIMATION.md) primeiro, depois escreva o código.
ANIMATION.md é um arquivo salvo no projeto. Pode ser editado manualmente, reutilizado em outros projetos e lido por outras ferramentas.
Os caminhos neste arquivo são relativos à pasta da skill (~/.claude/skills/empro-labs-animation-skill/). Use caminhos absolutos ao executar os scripts.
Solicitação
A solicitação do usuário do comando de barra:
$ARGUMENTS
Se a solicitação acima estiver vazia, faça uma pergunta: o que deve se mover, e para onde? Então inicie a Fase A.
Fluxo principal
Fase A Compreender a entrada ──→ Fase B Escrever ANIMATION.md (usuário aprova) ──→ Fase C Implementar ──→ Fase D Auditar
Verificações iniciais (nesta ordem)
- O projeto possui
ANIMATION.md? → Reutilize-o, edite-o ou reconstrua-o, conforme o usuário solicitar. - Possui
DESIGN.md(da skill de web-design)? → Herde suas cores, fontes e direção de estilo. Mantenha o movimento consistente com ele. - Possui tokens de movimento (variáveis
--motion-*ou um arquivo de movimento)? → Reutilize-os. Não invente novos valores. - Já possui código de animação? → Execute
python scripts/analyze_motion.py <project> --inventoryprimeiro, para saber o que existe antes de propor alterações. - Nenhum dos acima → Fase A.
Fase A: Compreender
As entradas podem ser combinadas:
| Entrada | O que fazer |
|---|---|
| URL de referência | Execute python scripts/capture_motion.py --url [URL] --output ./motion-capture. Leia capture.json para durações reais, easings, propriedades animadas e efeitos scroll-linked. Use top.png para o mood. |
| Vídeo ou captura de tela do movimento | Descreva o gatilho, a duração aproximada e a sensação da easing. Confirme os números com o usuário. |
| Palavras-chave ("snappy", "cinematic") | Associe-as a uma personalidade em references/motion-personalities.md. |
| Nome de marca ("como Linear") | Capture o site ao vivo se ele estiver acessível. Caso contrário, peça uma URL de referência. Não adivinhe o movimento de memória de uma marca. |
| Código existente | Execute o script de inventário e mantenha o que funciona. |
A1. Personalidade (faça no máximo duas perguntas)
- Sensação: calma, snappy, divertida ou cinematográfica?
- Tipo de página: com muito conteúdo (o movimento não atrapalha) ou vitrine (o movimento pode liderar)?
Mostre um ou dois candidatos de references/motion-personalities.md, cada um com uma justificativa de uma linha. O usuário confirma.
A2. Nível de interação (obrigatório, não pule)
Consulte references/interaction-tiers.md.
| Nível | Experiência | Ferramentas |
|---|---|---|
| L1 Micro | Hover, foco, pressionar, alternâncias, pequenas mudanças de estado | Apenas transições CSS |
| L2 Coreografado | Entrada e saída, listas escalonadas, modais, gavetas, mudanças de rota, loaders | Keyframes CSS, Web Animations API ou uma timeline GSAP |
| L3 História de scroll | Revelações scroll-linked, fixação, parallax, seções acionadas por uma timeline | GSAP + ScrollTrigger, ou animações CSS scroll-driven com um fallback |
L3 é limitado a duas seções fixadas por página. Cada seção da página declara seu nível na especificação.
A3. Stack
Verifique package.json e o framework (HTML puro, React, Vue, Svelte, Next.js). Escolha as ferramentas com references/tooling.md. Padrão: CSS e Web Animations API. Adicione GSAP apenas para L3 ou timelines complexas.
Fase B: Escrever ANIMATION.md
Siga references/animation-md-template.md. Dez seções:
- Personalidade & Princípios do Movimento
- Tokens de Movimento (durações, easings, distâncias)
- Inventário de Coreografia (tabela: elemento, gatilho, propriedade, duração, easing, atraso, fallback de movimento reduzido)
- Movimento de Componente (padrão, hover, focus-visible, active, disabled, enter, exit)
- Comportamento de Scroll
- Transições de Página & Rota
- Orçamento de Desempenho
- Acessibilidade
- O que Fazer e o que Não Fazer (pelo menos 8 itens, pelo menos 5 deles "Não Fazer")
- Dependências
Mostre um resumo ao usuário e aguarde aprovação. Em seguida, salve ANIMATION.md na raiz do projeto.
Fase C: Implementar
- Tokens em toda parte. Cada duração e easing é uma variável, como
var(--motion-duration-base). Sem números mágicos dentro dos componentes. - Anime apenas propriedades baratas.
transformeopacityprimeiro.clip-pathefiltersão permitidos em elementos pequenos. Nunca animewidth,height,top,left,marginoupadding, a menos que ANIMATION.md registre uma exceção com um motivo. - Movimento reduzido faz parte da primeira versão, não de um patch posterior. O movimento é removido e as mudanças de estado permanecem. Os tokens de distância vão para zero sob movimento reduzido, e o bloco
prefers-reduced-motionemtemplates/motion-tokens.cssmostra o padrão. - Use os arquivos iniciais quando o projeto ainda não tiver uma camada de movimento:
templates/motion-tokens.cssetemplates/reveal.js. - Loops precisam de uma saída. Qualquer loop
infinitepara ou simplifica sob movimento reduzido. Qualquer loop com duração superior a cinco segundos ganha um controle de pausa. - Limpe o JavaScript. Mate timelines GSAP e ScrollTriggers ao desmontar (use
gsap.context()ouuseGSAP). Desconecte observadores e remova listeners. - Mantenha o movimento em um só lugar. Coloque os tokens em um arquivo e as receitas em módulos pequenos. Não espalhe valores de temporização entre componentes.
Fase D: Auditar
- Execute a auditoria estática:
python scripts/analyze_motion.py <project> --strict. Corrija todos os erros. Revise todos os avisos e corrija-os ou justifique-os no ANIMATION.md. - Execute as verificações no navegador:
- Ative o movimento reduzido (DevTools → Rendering →
prefers-reduced-motion: reduce). Confirme que não há movimento e que o conteúdo ainda está visível. - Reduza a CPU (4×) e grave o painel Performance enquanto o movimento é reproduzido. Procure por quadros longos.
- Verifique a largura de um telefone (390 px). Procure por overflow horizontal de elementos animados.
- Ative o movimento reduzido (DevTools → Rendering →
- Percorra
references/quality-checklist.md. - Relate o que passou, o que falhou e o que você corrigiu.
Linhas vermelhas (cada item deve passar)
- Toda animação no ANIMATION.md tem um fallback de movimento reduzido.
- Apenas
transform,opacitye exceções registradas são animados. - Todas as durações e easings vêm de tokens.
- Todo loop
infiniterespeita o movimento reduzido, e qualquer loop com duração superior a cinco segundos tem um controle de pausa. - Nada pisca mais de três vezes por segundo.
- O feedback interativo aparece em até 100 ms. Microanimações têm 250 ms ou menos. Transições de entrada e de rota têm 500 ms ou menos.
- Feedback apenas no hover tem um estado de foco no teclado e um equivalente por toque.
- Em larguras de 600 px ou menos, nenhum elemento animado causa scroll horizontal, e seções fixadas são desativadas ou simplificadas.
- Animações JavaScript são limpas ao desmontar.
Índice de referências
Leia apenas os arquivos de que a fase atual precisa. Não carregue todos.
| Arquivo | Conteúdo | Ler quando |
|---|---|---|
references/animation-md-template.md | Modelo de saída do ANIMATION.md (10 seções) | Fase B |
references/motion-principles.md | Por que e quando animar, regras de temporização e easing | Fases A e B |
references/interaction-tiers.md | Definições dos níveis L1, L2 e L3 com padrões de código | Fases A2 e B |
references/motion-personalities.md | Quatro predefinições de personalidade com valores de token | Fases A1 e B |
references/tooling.md | CSS vs WAAPI vs GSAP vs Motion vs View Transitions vs Lottie | Fase A3 |
references/component-recipes.md | Botão, cartão, accordion, modal, gaveta, toast, abas, loaders | Fase C |
references/gsap-recipes.md | Timelines GSAP, ScrollTrigger, matchMedia, limpeza em React | Fase C (apenas GSAP) |
references/scroll-patterns.md | Revelação, barra de progresso, pilha fixa, parallax, scroll horizontal | Fases B (scroll) e C |
references/performance.md | Orçamento de quadros, regras amigáveis ao compositor, downgrade móvel | Fases B e D |
references/accessibility.md | Movimento reduzido, critérios de movimento WCAG, gatilhos vestibulares | Fases B e D |
references/quality-checklist.md | Lista de verificação de auditoria de 100 pontos | Fase D |
Scripts
| Script | Uso | Necessidades |
|---|---|---|
scripts/analyze_motion.py | Auditoria estática do CSS e JS de um projeto. Encontra animações de layout, transition: all, loops infinitos, durações longas e falta de tratamento de movimento reduzido. --inventory lista os valores de temporização existentes. | Python 3 (apenas biblioteca padrão) |
scripts/capture_motion.py | Registra animações declaradas e em execução em uma URL ao vivo, rola a página e verifica o que ainda é executado com movimento reduzido. Gera capture.json e top.png. | Python 3, pip install playwright, python -m playwright install chromium |
Ambos os scripts aceitam --help.
Modelos
| Arquivo | Uso |
|---|---|
templates/motion-tokens.css | Variáveis de token, keyframes base, regras de revelação e o bloco de movimento reduzido. Copie para o projeto. |
templates/reveal.js | Revelação de scroll sem dependências com IntersectionObserver que respeita movimento reduzido. |
Idioma
Escreva o ANIMATION.md e os resumos no idioma do usuário. Mantenha CSS, JavaScript e nomes de tokens em inglês.
Cadeia de fallback
- O script de captura falha (sem Playwright, ou o site bloqueia o navegador) → peça uma captura de tela ou uma gravação curta de tela e construa a partir dessa descrição.
- A referência usa uma biblioteca de animação que você não consegue identificar → diga isso e pergunte se deve combinar a sensação ou o movimento exato.
- Nenhuma entrada → faça uma pergunta sobre a sensação e, em seguida, use a personalidade calma.