Fundamentos de Movimento

A camada base do sistema de movimento. Define cada valor, restrição e regra que as habilidades downstream (motion-patterns, motion-advanced) herdam. Carregue esta habilidade antes que qualquer trabalho de animação comece.

Quando Ativar

• Iniciando qualquer componente animado do zero
• Configurando tokens, predefinições de mola ou valores de easing
• Implementando suporte a prefers-reduced-motion
• Depurando incompatibilidades de hidratação de estados iniciais de animação
• Avaliando se uma animação deve existir

Saídas

Esta habilidade produz:

• Um objeto motionTokens compartilhado (duração, easing, distância, escala)
• Um mapa de predefinições springs compartilhado (5 configurações nomeadas)
• Um portão shouldAnimate() usado por todos os componentes
• Padrões de animação compatíveis com acessibilidade via useReducedMotion
• Estados iniciais seguros para SSR com zero avisos de hidratação

Princípios

O movimento deve fazer pelo menos uma das seguintes coisas ou deve ser removido:

• Guiar a atenção
• Comunicar o estado
• Preservar a continuidade espacial

A responsividade sempre supera a suavidade. Uma animação de 60 fps que causa atraso na entrada é pior do que nenhuma animação.

Regras

Estas são inegociáveis. Elas se aplicam a cada componente do sistema.

1. Use apenas motion/react. Nunca importe de framer-motion. Nunca misture os dois na mesma árvore.
2. initial deve corresponder à saída do servidor. Se o servidor renderizar opacity: 1, a prop initial também deve ser opacity: 1. Sem exceções.
3. Movimento reduzido substitui tudo. Quando useReducedMotion() retorna true ou prefersReduced é true, todas as transformações são desabilitadas. Transições de opacidade de ≤ 0,2s são o único fallback permitido.
4. Nunca anime propriedades de layout. width, height, top, left, margin, padding são banidos de animate. Use apenas transform e opacity.
5. Todos os valores de token vêm de motionTokens. Durações e easings codificados em arquivos de componentes são proibidos.
6. Todas as configurações de mola vêm do mapa springs. Valores inline de stiffness/damping são proibidos.
7. "use client" é obrigatório em todos os arquivos que importam de motion/react.
8. Nunca leia window ou navigator no nível do módulo. Sempre proteja com typeof window !== "undefined".

Orientação para Decisão

Escolhendo uma duração

Escolhendo uma mola

Quando desabilitar a animação completamente

Desabilite (faça shouldAnimate() retornar false) quando:

• prefersReduced é true
• isLowEnd é true e a animação não é essencial
• O elemento está fora da tela e nunca entrará na viewport
• A animação é puramente decorativa, sem propósito de UX

Conceitos Principais

Sistema de tokens

// lib/motion-tokens.ts
export const motionTokens = {
  duration: {
    instant: 0.08,
    fast:    0.18,
    normal:  0.35,
    slow:    0.6,
    crawl:   1.0,
  },
  easing: {
    smooth: [0.22, 1, 0.36, 1],
    sharp:  [0.4, 0, 0.2, 1],
    bounce: [0.34, 1.56, 0.64, 1],
    linear: [0, 0, 1, 1],
  },
  distance: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 48,
  },
  scale: {
    subtle: 0.98,
    press:  0.95,
    pop:    1.04,
  },
}

export const springs = {
  snappy:  { type: "spring", stiffness: 300, damping: 30 },
  gentle:  { type: "spring", stiffness: 120, damping: 14 },
  bouncy:  { type: "spring", stiffness: 400, damping: 10 },
  instant: { type: "spring", stiffness: 600, damping: 35 },
  release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 },
}

Flags de tempo de execução

// lib/motion-config.ts
export const motionConfig = {
  isLowEnd() {
    return (
      typeof navigator !== "undefined" &&
      navigator.hardwareConcurrency <= 4
    )
  },

  prefersReduced() {
    return (
      typeof window !== "undefined" &&
      window.matchMedia("(prefers-reduced-motion: reduce)").matches
    )
  },


…