Construindo Animações
Este repositório (Asymmetric-al/core)
Use esta habilidade para implementar movimento web após os contratos de design-engineering e motion operativo do Core. Reconcilie esta sobreposição após atualizações upstream antes de executar bun run skills:sync.
Gatilhos
- Construir ou reescrever uma animação web, transição ou micro-interação.
- Não use para Expo/React Native (
animate-expo), uma auditoria de codebase (improve-animations) ou uma revisão estrita de movimento (review-animations).
Fluxo de Trabalho
- Carregue primeiro
docs/ai/skills/emil-design-engineering/SKILL.mdedocs/ai/skills/anim/SKILL.md. - Reutilize tokens de movimento do Core existentes e primitivas da Base UI. Não crie forks de durações, easings ou introduza APIs Radix.
- Mantenha o movimento reduzido na linha de base global em
packages/ui/styles/globals.css. - Se a tarefa precisar de um toast, drawer, menu ou dropdown, reutilize
@asym/ui/ Base UI. Não invoquepick-ui-librarya menos que o usuário tenha perguntado explicitamente qual biblioteca usar.
Lista de Verificação
- A animação tem um propósito e permanece em transform/opacity sempre que possível.
- Tokens do Core, Base UI e
animprevalecem sobre valores ilustrativos upstream. - Utilitários compartilhados e
@asym/lib/motion-presetssão preferidos a novos literais de temporização.
Uma habilidade de construção. Ela faz UMA coisa: transformar uma solicitação de movimento em uma implementação que sobreviveria a uma revisão rigorosa. Ela não audita um codebase (isso é improve-animations), critica um diff (isso é review-animations), procura lugares que poderiam animar (isso é find-animation-opportunities) ou constrói para React Native (isso é animate-expo).
Postura Operacional
Você é um engenheiro de design sênior construindo a animação você mesmo. O padrão é a filosofia de animação de Emil Kowalski — o mesmo padrão que review-animations impõe. Escreva de forma que passe na revisão na primeira vez.
Dois modos de falha, e o primeiro é pior:
- Animar algo que não deveria ser animado. O portão abaixo existe para produzir zero linhas de código às vezes. Isso é um sucesso, não uma fuga.
- Animar a coisa certa com os ingredientes errados —
ease-inem uma entrada,scale(0), keyframes em um toast, uma duração que faz um dropdown parecer lento.
Nunca apresente opções de movimento como um menu. Tome a decisão, declare o raciocínio em uma linha, escreva o código.
Regras Rígidas
- Execute a sequência em ordem. As etapas 1 e 2 controlam tudo. Não pegue uma curva antes de saber se a animação acontece.
- Sem valores aproximados. Cada curva, duração e configuração de mola vem das tabelas abaixo. Nunca invente
cubic-bezier(0.4, 0, 0.2, 1)porque parece familiar. - Estenda os tokens do codebase, não os bifurque. Se
--ease-out-softou um token de duração já existe empackages/ui/styles/globals.css, use-o. Adicionar um sistema paralelo é um defeito. - Movimento reduzido e bloqueio de hover acompanham a animação, não como uma atividade posterior.
- A ferramenta mais barata que funciona. Não instale uma biblioteca de movimento para um fade.
A Sequência de Construção
1. Isso deve animar?
| Frequência | Decisão |
|---|---|
| 100+ vezes/dia (atalhos de teclado, alternância de paleta de comandos) | Nunca anime. Pare aqui. |
| Dezenas de vezes/dia (efeitos de hover, navegação em listas) | Apenas quase imperceptível — rápido e sutil, ou nada |
| Ocasional (modais, drawers, toasts) | Animação padrão |
| Raro / primeira vez (onboarding, sucesso, celebração) | O orçamento de encanto mora aqui |
Ações iniciadas por teclado são um eliminador, não um julgamento. Raycast não tem animação de abrir/fechar — isso está correto para algo aberto centenas de vezes ao dia.
Se a solicitação falhar neste portão, diga claramente e não escreva a animação. Ofereça a alternativa sem movimento (mudança de estado instantânea, uma affordance estática).
2. Qual é o propósito?
Nomeie-o em uma destas palavras antes de continuar:
- Feedback — confirmando que a interface ouviu o usuário
- Consistência espacial — mostrando de onde algo veio ou para onde foi
- Indicação de estado — tornando uma mudança de estado legível
- Prevenção de uma mudança brusca — preenchendo conteúdo que, de outra forma, teletransportaria
- Explicação — demonstrando como algo funciona (apenas marketing/onboarding)
- Encanto — permitido apenas no nível raro/primeira vez
Não consegue nomear? Não construa. "Parece legal" em um elemento visto com frequência é um motivo para parar.
Verifique também a função: dados que o usuário está lendo ou interagindo não devem se mover por estilo. Um efeito decorativo de rastreamento de mouse pertence a uma página de marketing, não a um gráfico em um aplicativo bancário.
3. Escolha a ferramenta — a mais barata que funciona
Desça; pare na primeira que se encaixa.
| Necessidade | Ferramenta |
|---|---|
| Hover, pressionar, cor, uma alternância de estado que você controla com uma classe ou atributo | Transição CSS |
| Animação de entrada na montagem, sem estado JS | CSS @starting-style |
| Movimento predeterminado que deve permanecer suave enquanto a página está carregando | Animação CSS (roda fora da thread principal) |
| Controle programático com desempenho CSS, sem biblioteca | WAAPI (element.animate()) |
| Molas, animações de layout, animações de saída, valores orientados por gestos | Motion (motion.dev) |
Animações CSS vencem JS sob carga — elas rodam fora da thread principal, enquanto a animação baseada em requestAnimationFrame perde quadros enquanto o navegador carrega, scripts ou pinta. Use CSS para movimento predeterminado, JS para movimento dinâmico e interrompível.
Se a tarefa precisar de um componente em vez de uma animação — um toast, um drawer, um menu de comandos, um dropdown — reutilize @asym/ui e Base UI. Não invoque pick-ui-library a menos que o usuário tenha perguntado explicitamente qual biblioteca usar. Implementar manualmente é como você acaba com um dropdown <div> e sem gerenciamento de foco.
4. Escolha as propriedades
transformeopacityapenas. Eles pulam layout e paint e rodam na GPU.width/height/margin/padding/top/leftacionam todos os três. (clip-pathé o quarto sancionado — veja RECIPES.md.heighté tolerado apenas para acordeões, onde não há equivalente de transform.)- Nunca
scale(0). Comece descale(0.9–0.97)+opacity: 0. Nada no mundo real aparece do nada. transform-originno gatilho para popovers, dropdowns, menus, tooltips —var(--transform-origin)na Base UI. Modais estão isentos; eles não estão ancorados a um gatilho, então permanecem centralizados.- Porcentagens em
translate()são relativas ao tamanho do próprio elemento —translateY(100%)move pela sua própria altura, independentemente do conteúdo. Prefira em vez de pixels codificados. - No Motion,
x,yescalesão transformações independentes suportadas. Eles têm desempenho. Use uma stringtransformcompleta apenas quando a animação deve permanecer no compositor enquanto a thread principal está ocupada:
<motion.div animate={{ x: 100 }} />
<motion.div animate={{ transform: "translateX(100px)" }} />
- Nunca direcione a transformação de um filho a partir de uma variável CSS no pai — isso recalcula estilos para cada filho. Defina
transformno elemento diretamente.
5. Easing e duração — ou uma mola
Easing, em ordem de decisão:
| Situação | Easing |
|---|---|
| Entrando ou saindo | ease-out |
| Movendo / transformando na tela | ease-in-out |
| Hover / mudança de cor | ease |
| Movimento constante (marquee, progresso) | linear |
| Padrão | ease-out |
Nunca ease-in em UI. Ele começa devagar, atrasando o momento exato que o usuário está observando. ease-out em 200ms parece mais rápido que ease-in em 200ms.
Os easings CSS embutidos são muito fracos. Use estes:
--ease-out-soft: cubic-bezier(
0.22,
1,
0.36,
1
); /* Token do Core; ease-out forte para UI */
--ease-in-out-soft: cubic-bezier(
0.77,
0,
0.175,
1
); /* ease-in-out forte para movimento na tela */
--ease-drawer: cubic-bezier(
0.32,
0.72,
0,
1
); /* Curva de drawer estilo iOS (Ionic) */
Precisa de uma curva que não está aqui? Pegue de easing.dev ou easings.co. Não crie uma manualmente.
Duração:
| Elemento | Duração |
|---|---|
| Feedback de pressionar botão | var(--duration-press) (120ms) |
| Tooltips, popovers pequenos | var(--duration-micro) (150ms) |
| Dropdowns, selects | var(--duration-standard) (220ms) |
| Modais | var(--duration-modal) (220ms) |
| Drawers | var(--duration-drawer) (320ms) |
| Marketing / explicativo | Pode ser mais longo |
Animações de UI ficam abaixo de 300ms. Um dropdown de 180ms parece mais responsivo que um de 400ms.
Recorra a uma mola quando o movimento é arrastar com momentum, um elemento que deve parecer vivo, um gesto que o usuário pode interromper ou reverter, ou rastreamento de mouse decorativo:
{ type: "spring", duration: 0.5, bounce: 0.2 } // Estilo Apple — mais fácil de raciocinar
{ type: "spring", mass: 1, stiffness: 100, damping: 10 } // Física tradicional — mais controle
Mantenha bounce entre 0,1–0,3 e evite bounce na maioria das UI — reserve para arrastar para dispensar e interações lúdicas.
6. Interrupção e saída
- Transições, não keyframes, para qualquer coisa acionada rapidamente — toasts, alternâncias, qualquer coisa que um usuário pode disparar duas vezes em um segundo. Transições redirecionam do valor atual; keyframes reiniciam do zero.
- Molas para gestos, porque carregam velocidade através de uma interrupção.
- Saia da mesma forma que entrou. Um toast que desliza de baixo sai por baixo. Caminhos simétricos são o que tornam o deslizar para dispensar óbvio.
- Temporização assimétrica onde o usuário está decidindo. Lento na fase deliberada (um pressionar para confirmar: 2s linear), rápido na resposta do sistema (liberação: 200ms ease-out).
7. Movimento reduzido e bloqueio de pointer
Acompanha a animação, toda vez.
@media (prefers-reduced-motion: reduce) {
.element {
animation: fade 0.2s ease;
} /* mantenha opacity/color, remova movimento baseado em transform */
}
@media (hover: hover) and (pointer: fine) {
.element:hover {
transform: scale(1.05);
} /* toque dispara hovers falsos no toque */
}
const reduce = useReducedMotion();
const closedX = reduce ? 0 : "-100%";
Movimento reduzido significa menos e mais suaves animações, não zero — mantenha transições que auxiliam a compreensão, remova mudanças de movimento e posição.
Receitas
Para implementações prontas para construir dos casos comuns — pressionar botão, dropdown, tooltip, modal, drawer, toast, acordeão, escalonamento, pressionar para confirmar, indicador de aba, revelação ao rolar, arrastar para dispensar — veja RECIPES.md. Carregue sempre que a solicitação corresponder a um desses componentes; comece da receita em vez de um arquivo em branco.
Nunca Enviar
Auto-verifique antes de terminar. Cada um destes é um bloqueio automático em review-animations:
| Nunca | Em vez disso |
|---|---|
transition: all | Nomeie as propriedades exatas |
transform: scale(0) entrada | scale(0.95) + opacity: 0 |
ease-in em um elemento de UI | ease-out ou uma curva personalizada forte |
ease-out embutido em uma animação deliberada | cubic-bezier(0.23, 1, 0.32, 1) |
| Animação em um atalho de teclado ou ação 100+/dia | Sem animação |
| Duração de UI acima de 300ms sem motivo | 150–250ms |
transform-origin: center em um popover ancorado a gatilho | var(--transform-origin) (modais isentos) |
| Keyframes em toasts, alternâncias, elementos acionados rapidamente | Transições CSS |
Animando width/height/margin/padding/top/left | transform / opacity |
Props x/y/scale do Motion sob carga | String transform completa |
Movimento :hover sem bloqueio | @media (hover: hover) and (pointer: fine) |
prefers-reduced-motion ausente | Variante mais suave, não zero |
| Tudo entrando de uma vez | Escalonamento de 30–80ms |
Saída
Escreva o código. Em seguida, em no máximo algumas linhas:
- O resultado do portão — nível de frequência e o propósito nomeado. Se algo na solicitação foi rejeitado, diga o que e por quê.
- Os ingredientes — ferramenta, propriedades, curva, duração ou configuração de mola, em uma linha cada.
- O que verificar na sensação — se o resultado depende da sensação que você não pode julgar a partir do código (um crossfade, o bounce de uma mola, o equilíbrio opacity/altura em uma lista que entra), diga e aponte para a verificação: reproduza em 2–5× a duração ou no inspetor de animação das DevTools, avance quadro a quadro, teste gestos em um dispositivo real e olhe novamente.