Motion Patterns
Padrões copie-e-cole para as necessidades mais comuns de animação de UI.
Cada padrão aqui é construído sobre tokens e molas do motion-foundations.
Não defina novos valores de duração ou easing aqui — importe-os.
Quando Ativar
- Ao animar um botão, cartão, modal ou notificação toast
- Ao construir entradas de lista com escalonamento (stagger)
- Ao configurar transições de página no App Router do Next.js
- Ao adicionar animações de entrada ou saída a conteúdo condicional
- Ao implementar revelação por scroll, progresso vinculado ao scroll ou seções de história fixas
- Ao construir cartões expansíveis, acordeões ou transições de elemento compartilhado
Resultados
Este skill produz:
- Animações acessíveis e seguras para SSR de todos os componentes de UI padrão
- Renderizações condicionais envolvidas em
AnimatePresencecom comportamento de saída correto - Componente wrapper para transição de página no App Router do Next.js
- Padrões de revelação por scroll e vinculados ao scroll usando
useScroll+useTransform - Padrões de animação de layout (
layout,layoutId) para elementos que se expandem e se sobrepõem
Princípios
- Cada padrão importa do
motion-foundations. Sem números brutos. - Toda renderização condicional é envolvida em
AnimatePresencecom umakey. - Animações de saída são sempre definidas junto com as de entrada — nunca como um pensamento posterior.
layouté usado apenas para pequenos deslocamentos isolados. Subárvores grandes recebem transformações explícitas.
Regras
- Sempre envolva renderizações condicionais em
AnimatePresencecom umakeyno filho direto. Sem umakey, as animações de saída nunca são executadas. - Sempre defina
exitao definirinitial+animate. Uma animação sem saída está incompleta. - Use
mode="wait"em transições de página. A entrada não deve começar até que a saída termine. - Nunca use
layoutem subárvores com mais de ~5 filhos ou DOM profundamente aninhado. Use transformações explícitas dex/y. - O intervalo de escalonamento (stagger) deve ficar entre
0.05se0.10s. Abaixo disso parece mecânico; acima parece lento. - Modais devem sempre incluir: foco armadilhado (focus trap), fechamento com tecla Escape, bloqueio de scroll,
role="dialog",aria-modal="true". - Revelações por scroll usam
viewport={{ once: true }}. Repetir ao sair da tela é distrativo, não informativo. - Todos os valores de tokens são importados do
motion-foundations. Sem números inline.
Orientação de Decisão
Escolhendo o padrão certo
| Situação | Padrão |
|---|---|
| Elemento aparece / desaparece | AnimatePresence |
| Lista de itens carregando em sequência | Variantes de escalonamento (stagger) |
| Navegando entre rotas | Wrapper de transição de página |
| Elemento muda de tamanho no lugar | Propriedade layout |
| Mesmo elemento se move entre contextos de página | layoutId |
| Elemento entra quando visível no scroll | whileInView |
| Valor vinculado à posição do scroll | useScroll + useTransform |
Quando usar mode="wait" vs mode="sync"
| Modo | Use quando |
|---|---|
wait | Transições de página, troca de conteúdo (um de cada vez) |
sync | Notificações empilhadas, itens de lista (sobreposição é aceitável) |
popLayout | Itens removidos de uma lista com refluxo |
Conceitos Principais
Contrato do AnimatePresence
Três coisas devem ser sempre verdadeiras:
AnimatePresenceenvolve o condicional- O filho direto tem uma
key - O filho tem uma propriedade
exit
Faltar qualquer uma delas e a animação de saída falha silenciosamente.
layout vs layoutId
layout— anima a própria mudança de tamanho/posição do elemento no lugarlayoutId— conecta dois elementos separados, fazendo uma transição suave entre eles durante as renderizações
Use layout="position" no texto dentro de um contêiner em expansão para evitar que o refluxo de texto seja animado.
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 escalonada
"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 },
}
<motion.ul variants={container} initial="hidden" animate="visible">
{items.map((i) => (
<motion.li key={i.id} variants={item} />
))}
</motion.ul>
Modal
"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
// Envolver no local de chamada:
// <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>
export function Modal({ onClose }: { onClose: () => void }) {
return (
<>
{/* Overlay */}
<motion.div
className="fixed inset-0 bg-black/50"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
onClick={onClose}
/>
{/* Painel — requisitos de acessibilidade: foco armadilhado, fechamento com Escape,
bloqueio de scroll, role="dialog", aria-modal="true" */}
<motion.div
role="dialog"
aria-modal="true"
className="fixed inset-x-4 top-1/2 -translate-y-1/2 rounded-xl bg-white p-6"
initial={{
opacity: 0,
scale: motionTokens.scale.press,
y: motionTokens.distance.sm,
}}
animate={{ opacity: 1, scale: 1, y: 0 }}
exit={{
opacity: 0,
scale: motionTokens.scale.press,
y: motionTokens.distance.sm,
}}
transition={springs.gentle}
/>
</>
)
}
Pilha de toasts
"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
<AnimatePresence mode="sync">
{toasts.map((t) => (
<motion.div
key={t.id}
layout
initial={{
opacity: 0,
x: motionTokens.distance.xl,
scale: motionTokens.scale.subtle,
}}
animate={{ opacity: 1, x: 0, scale: 1 }}
exit={{
opacity: 0,
x: motionTokens.distance.xl,
scale: motionTokens.scale.subtle,
}}
transition={springs.snappy}
/>
))}
</AnimatePresence>
Transição de página (Next.js App Router)
// components/page-transition.tsx
"use client"
import { motion, AnimatePresence } from "motion/react"
import { usePathname } from "next/navigation"
import { motionTokens } from "@/lib/motion-tokens"
const variants = {
initial: { opacity: 0, y: motionTokens.distance.sm },
enter: { opacity: 1, y: 0 },
exit: { opacity: 0, y: -motionTokens.distance.sm },
}
export function PageTransition({ children }: { children: React.ReactNode }) {
const pathname = usePathname()
return (
<AnimatePresence mode="wait">
<motion.div
key={pathname}
variants={variants}
initial="initial"
animate="enter"
exit="exit"
transition={{
duration: motionTokens.duration.normal,
ease: motionTokens.easing.smooth,
}}
>
{children}
</motion.div>
</AnimatePresence>
)
}
Revelação por scroll
"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
<motion.div
initial={{ opacity: 0, y: motionTokens.distance.lg }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true, margin: "-80px" }} // once: true — regra 7
transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>
Barra de progresso do scroll
"use client"
import { motion, useScroll } from "motion/react"
export function ScrollProgress() {
const { scrollYProgress } = useScroll()
return (
<motion.div
className="fixed top-0 left-0 h-1 bg-indigo-500 origin-left w-full"
style={{ scaleX: scrollYProgress }}
/>
)
}
Cartão expansível
"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"
export function ExpandingCard({ title, body }: { title: string; body: string }) {
const [expanded, setExpanded] = useState(false)
return (
<motion.div layout onClick={() => setExpanded(!expanded)} className="cursor-pointer">
{/* layout="position" impede que o refluxo de texto seja animado */}
<motion.h2 layout="position" className="font-semibold">
{title}
</motion.h2>
<AnimatePresence>
{expanded && (
<motion.p
key="body"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
transition={{ duration: motionTokens.duration.fast }}
>
{body}
</motion.p>
)}
</AnimatePresence>
</motion.div>
)
}
Transição de elemento compartilhado (crossfade)
// Contexto de origem
<motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />
// Contexto de destino (mesmo layoutId — o motion gerencia a transição)
<motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" />
Acordeão
<motion.div
initial={false}
animate={{ opacity: open ? 1 : 0, scaleY: open ? 1 : 0 }}
style={{ transformOrigin: "top", overflow: "hidden" }}
transition={{
duration: motionTokens.duration.normal,
ease: motionTokens.easing.smooth,
}}
> {children}
</motion.div>
Exemplo Completo (Ponta a Ponta)
Uma lista escalonada que entra ao montar, lida com presença condicional e respeita movimento reduzido — combinando tokens, molas, AnimatePresence e o hook de acessibilidade do motion-foundations:
"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"
const containerVariants = {
hidden: {},
visible: {
transition: { staggerChildren: 0.08, delayChildren: 0.1 },
},
}
function ListItem({ label, onRemove }: { label: string; onRemove: () => void }) {
const safe = useSafeMotion(motionTokens.distance.sm)
return (
<motion.li
variants={{
hidden: safe.initial,
visible: safe.animate,
}}
exit={safe.exit}
transition={springs.gentle}
className="flex items-center justify-between p-3 rounded-lg bg-white shadow-sm"
>
<span>{label}</span>
<button onClick={onRemove}>Remove</button>
</motion.li>
)
}
export function AnimatedList({ items, onRemove }: {
items: { id: string; label: string }[]
onRemove: (id: string) => void
}) {
return (
<motion.ul
variants={containerVariants}
initial="hidden"
animate="visible"
className="space-y-2"
>
<AnimatePresence mode="popLayout">
{items.map((item) => (
<ListItem
key={item.id}
label={item.label}
onRemove={() => onRemove(item.id)}
/>
))}
</AnimatePresence>
</motion.ul>
)
}
Restrições / Não Objetivos
Este skill não cobre:
- Definições de tokens e molas → veja
motion-foundations - Interações de arraste, gestos de swipe, listas reordenáveis → veja
motion-advanced - Animações de texto (revelação de palavras/caracteres, contadores) → veja
motion-advanced - Desenho de caminhos SVG ou morphing → veja
motion-advanced - Hooks de animação personalizados → veja
motion-advanced - Transições CSS-only que não usam
motion/react
Anti-Padrões
| Anti-padrão | Regra violada | Correção |
|---|---|---|
Filho de AnimatePresence sem key | Regra 1 | Adicionar key estável ao filho direto |
initial + animate sem exit | Regra 2 | Sempre definir todos os três juntos |
Transição de página sem mode="wait" | Regra 3 | Adicionar mode="wait" ao AnimatePresence |
layout em uma lista de 50 itens | Regra 4 | Usar mode="popLayout" ou transformações explícitas |
staggerChildren: 0.2 em uma lista de 10 itens | Regra 5 | Limitar a 0.08–0.10 |
| Modal sem foco armadilhado | Regra 6 | Adicionar focus-trap-react ou Radix Dialog |
whileInView sem viewport={{ once: true }} | Regra 7 | Entradas repetidas distraem, não informam |
transition={{ duration: 0.3 }} inline | Regra 8 | Usar motionTokens.duration.normal |
Skills Relacionados
motion-foundations— define todos os tokens, molas, o hookuseSafeMotione guardas SSR que cada padrão aqui importa. Deve ser configurado primeiro.motion-advanced— estende estes padrões com arraste, gestos, SVG, texto, hooks personalizados e sequenciamento imperativo. Não redefine nenhum padrão deste skill.