Padrões de Movimento

Copie e cole padrões para as necessidades mais comuns de animação de UI. Cada padrão aqui é construído sobre tokens motion-foundations e molas. Não defina novos valores de duração ou easing aqui — importe-os.

Quando Ativar

• Animando um botão, card, modal ou notificação toast
• Construindo entradas de lista com stagger
• Configurando transições de página no Next.js App Router
• Adicionando animações de entrada ou saída a conteúdo condicional
• Implementando scroll-reveal, progresso vinculado a scroll ou seções de história fixas
• Construindo cards expansíveis, accordions ou transições de elemento compartilhado

Saídas

Esta habilidade produz:

• Animação acessível e segura para SSR para todos os componentes de UI padrão
• Renderizações condicionais envolvidas por AnimatePresence com comportamento de saída correto
• Componente wrapper de transição de página para Next.js App Router
• Padrões de scroll-reveal e scroll-linked usando useScroll + useTransform
• Padrões de animação de layout (layout, layoutId) para elementos expansíveis e crossfading

Princípios

• Todo padrão importa de motion-foundations. Sem números brutos.
• Toda renderização condicional é envolvida por AnimatePresence com um key.
• Animações de saída são sempre definidas junto com animações de entrada — nunca como um pensamento posterior.
• layout é usado apenas para mudanças pequenas e isoladas. Subárvores grandes recebem transforms explícitos.

Regras

1. Sempre envolva renderizações condicionais em AnimatePresence com um key no filho direto. Sem uma chave, animações de saída nunca são acionadas.
2. Sempre defina exit ao definir initial + animate. Uma animação sem saída está incompleta.
3. Use mode="wait" em transições de página. A entrada não deve começar até que a saída termine.
4. Nunca use layout em subárvores com mais de ~5 filhos ou DOM profundamente aninhado. Use transforms explícitos de x/y em vez disso.
5. O intervalo de stagger deve permanecer entre 0.05s e 0.10s. Abaixo parece mecânico; acima parece lento.
6. Modais devem sempre incluir: armadilha de foco, fechamento com tecla Escape, bloqueio de scroll, role="dialog", aria-modal="true".
7. Scroll reveals usam viewport={{ once: true }}. Repetir no scroll-out é distrativo, não informativo.
8. Todos os valores de token são importados de motion-foundations. Sem números inline.

Orientação de Decisão

Escolhendo o padrão certo

Quando usar mode="wait" vs mode="sync"

Conceitos Principais

Contrato AnimatePresence

Três coisas devem ser sempre verdadeiras:

1. AnimatePresence envolve o condicional
2. O filho direto tem uma key
3. O filho tem uma prop exit

Falhe em qualquer um desses e a animação de saída falha silenciosamente.

layout vs layoutId

• layout — anima a mudança de tamanho/posição do próprio elemento no lugar
• layoutId — vincula dois elementos separados, fazendo crossfade entre eles em diferentes renders

Use layout="position" em texto dentro de um contêiner expansível para evitar que a animação de reflow do texto ocorra.

Exemplos de Código

Feedback de botão

"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"

<motion.button
  whileHover={{ scale: motionTokens.scale.pop }}
  whileTap={{ scale: motionTokens.scale.press }}
  transition={springs.snappy}
/>

Lista com Stagger

"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

const container = {
  hidden: {},
  visible: {
    transition: {
      staggerChildren: 0.08,   // dentro da regra 0.05–0.10
      delayChildren: 0.1,
    },
  },
}

const item = {
  hidden:  { opacity: 0, y: motionTokens.distance.md },
  visible: { opacity: 1, y: 0, transition: springs.gentle },
}


…