Motion Avançado

Padrões de animação complexos, interativos e baseados em física. Requer que motion-foundations seja configurado primeiro. Use estes quando motion-patterns não for suficiente.

Quando Ativar

• Construindo folhas de arrastar para descartar, gestos de deslizar ou listas reordenáveis
• Animando texto palavra por palavra, caractere por caractere ou como um contador em tempo real
• Desenhando caminhos SVG, transformando ícones ou animando progresso circular
• Escrevendo um hook de animação personalizado (useScrollReveal, botão magnético, seguidor de cursor)
• Sequenciando animações de múltiplos passos imperativamente com useAnimate
• Construindo spinners, esqueletos de brilho, indicadores de pulso ou estados de botão de carregamento

Saídas

Esta habilidade produz:

• Interações de arrastar: cartões arrastáveis, folhas de arrastar para descartar, listas Reorder.Group
• Hooks de gestos: detecção de deslizar, pressionamento longo, contorno de pinça
• Componentes de animação de texto: revelação de palavras, máquina de escrever de caracteres, contador de números
• Animação SVG: desenho de caminho, transformação de ícone, anel de progresso de traço
• Hooks personalizados: useScrollReveal, useHoverScale, useNavigationDirection, useInViewOnce
• Sequências imperativas via useAnimate com async/await seguro contra interrupções
• Componentes de carregamento: spinner, brilho, ponto de pulso, barra de progresso, estado de carregamento do botão

Princípios

• Movimento baseado em física (useSpring, springs.*) sempre parece mais natural do que baseado em duração para manipulação direta.
• useMotionValue + useTransform computa valores derivados sem acionar novas renderizações.
• Sequências useAnimate são imperativas e seguras contra interrupções — chamar animate() no meio do voo cancela a animação anterior automaticamente.
• Valores de movimento (useMotionValue, useSpring) são seguros para SSR e não causam erros de hidratação.

Regras

1. Interações de arrastar devem ser testadas em dispositivos de toque, não apenas em mouse. A prop drag funciona em ambos, mas a sensação e o limite diferem.
2. Animações infinitas devem pausar quando document.visibilityState === "hidden". Abas em segundo plano não devem consumir GPU/CPU.
3. O limite de deslize deve ser explícito. Nunca infira intenção apenas pela velocidade; combine verificações de offset + velocity.
4. A ref de escopo useAnimate deve ser anexada a um elemento DOM montado. Chamar animate() antes da montagem falha silenciosamente.
5. Valores de movimento não devem ser recriados na renderização. useMotionValue(0) dentro do corpo de um componente está correto; new MotionValue(0) em uma renderização não está.
6. Todos os valores de token são importados de motion-foundations. Sem números inline.
7. Hooks personalizados devem lidar com a limpeza. Cada window.addEventListener precisa de um removeEventListener correspondente no retorno do useEffect.
8. A transformação de SVG requer contagens de comandos de caminho iguais. Caminhos com estruturas de comando diferentes se ajustam em vez de interpolar.

Orientação de Decisão

Escolhendo a API avançada correta

Quando usar useSpring vs uma transição de mola

Conceitos Principais

useMotionValue + useTransform

Computação reativa sem novas renderizações:

const x = useMotionValue(0)
const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])
// opacity updates every frame as x changes — no setState, no re-render

useAnimate

Retorna [scope, animate]. A ref de escopo deve ser anexada a um elemento DOM. Chamadas animate() são seguras contra interrupções — chamar no meio do voo cancela a execução anterior.

const [scope, animate] = useAnimate()


…