O que Sistema de Movimento v4.2 faz?
Sistema de movimento de UI pronto para produção para React / Next.js.
Focado em desempenho, acessibilidade e usabilidade — não em decoração.
Quando Usar
Use este sistema de movimento quando o movimento:
- Guia a atenção (ex.: onboarding, ações principais)
- Comunica estado (carregamento, sucesso, erro, transições)
- Preserva a continuidade espacial (mudanças de layout, navegação)
Cenários Apropriados
- Componentes interativos (botões, modais, menus)
- Transições de estado (carregando → carregado, aberto → fechado)
- Navegação e continuidade de layout (elementos compartilhados, crossfade)
Considerações
- Acessibilidade: Sempre suportar movimento reduzido
- Adaptação de dispositivo: Ajustar para dispositivos de baixo desempenho
- Compensações de desempenho: Preferir responsividade em vez de suavidade visual
Evite Usar Movimento Quando
- É puramente decorativo
- Reduz a usabilidade ou clareza
- Impacta o desempenho negativamente
Como Funciona
Princípio Central
O movimento deve:
- Guiar a atenção
- Comunicar estado
- Preservar a continuidade espacial
Se não fizer nada disso → remova-o.
Instalação
npm install motion
Versão
motion/react- padrão para projetos Motion for React atuais (pacote:motion)framer-motion- caminho de importação legado para projetos que ainda dependem do Framer Motion
Não misture. Misturar causa conflitos internos de agendadores e contextos AnimatePresence quebrados — componentes de um pacote não coordenarão animações de saída com componentes do outro.
Para verificar qual versão seu projeto usa:
cat package.json | grep -E '"motion"|"framer-motion"'
Sempre importe de uma única fonte de forma consistente:
// Correto (moderno)
import { motion, AnimatePresence } from "motion/react"
// Correto (legado)
import { motion, AnimatePresence } from "framer-motion"
// Nunca misture ambos no mesmo projeto
Tokens de Movimento
// motionTokens.ts
export const motionTokens = {
duration: {
fast: 0.18,
normal: 0.35,
slow: 0.6
},
// Use estes como valor `ease` dentro de um objeto `transition`:
// transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}
easing: {
smooth: [0.22, 1, 0.36, 1] as [number, number, number, number],
sharp: [0.4, 0, 0.2, 1] as [number, number, number, number]
},
distance: {
sm: 8,
md: 16,
lg: 24
}
}
Exemplo de uso:
import { motionTokens } from "@/lib/motionTokens"
<motion.div
initial={{ opacity: 0, y: motionTokens.distance.md }}
animate={{ opacity: 1, y: 0 }}
transition={{
duration: motionTokens.duration.normal,
ease: motionTokens.easing.smooth
}}
/>
Regras de Desempenho
Seguro
- transform
- opacity
Evite
- width / height
- top / left
Regra: responsividade > suavidade
Adaptação de Dispositivo
A heurística combina a contagem de núcleos da CPU e a memória disponível para um sinal mais confiável. deviceMemory está disponível no Chrome/Android; o fallback cobre Safari e Firefox.
const isLowEnd =
typeof navigator !== "undefined" && (
// Pouca memória (Chrome/Android apenas; undefined em outros lugares → tratar como capaz)
(navigator.deviceMemory !== undefined && navigator.deviceMemory <= 2) ||
// Poucos núcleos E sem API de memória (cobre Safari/Firefox em hardware fraco)
(navigator.deviceMemory === undefined && navigator.hardwareConcurrency <= 4)
)
const duration = isLowEnd ? 0.2 : 0.4
Acessibilidade
JS (useReducedMotion)
import { motion, useReducedMotion } from "motion/react"
export function FadeIn() {
const reduce = useReducedMotion()
return (
<motion.div
initial={{ opacity: 0, y: reduce ? 0 : 24 }}
animate={{ opacity: 1, y: 0 }}
/>
)
}
CSS
@media (prefers-reduced-motion: reduce) {
.motion-safe-transition {
transition: opacity 0.2s;
}
.motion-reduce-transform {
transform: none !important;
}
}
Tailwind
<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>
Arquitetura e Padrões
Padrões Centrais
| Cenário | Padrão |
|---|---|
| Feedback de hover | whileHover |
| Feedback de toque/pressionar | whileTap |
| Revelar ao scroll | whileInView |
| Valor vinculado ao scroll | useScroll + useTransform |
| Montagem/desmontagem condicional | AnimatePresence |
| Pequenas mudanças de layout (elemento único, < ~300px de alteração) | Propriedade layout |
| Grandes mudanças de layout ou reflow de página inteira | Evite layout; use transições CSS ou roteamento a nível de página |
| Sequências imperativas complexas | useAnimate |
Por que evitar
layoutem contêineres grandes? A animação de layout do Framer usatransformpara reconciliar posições, mas em elementos que abrangem toda a viewport ou acionam reflow profundo, o custo de medição causa jank visível e CLS. Prefira transições CSS Grid/Flexbox ou coordene comlayoutIdapenas em elementos filhos específicos.
Layout e Transições
- Transições de elemento compartilhado →
layoutId(deve ser único por instância montada) - Transições de entrada/saída →
AnimatePresence(veja orientaçãomodeabaixo)
Modo mode do AnimatePresence
Sempre especifique mode explicitamente — o padrão ("sync") executa entrada e saída simultaneamente, o que causa sobreposição visual na maioria dos padrões de UI.
mode | Quando usar |
|---|---|
"wait" | A saída termina antes da entrada começar. Use para modais, toasts, transições de página. |
"sync" (padrão) | Entrada e saída se sobrepõem. Use apenas quando a sobreposição for intencional (ex.: carrosséis crossfade). |
"popLayout" | O elemento de saída é removido do fluxo imediatamente; os itens restantes animam para preencher o espaço. Use para listas, abas, cartões descartáveis. |
// Modal — sempre use "wait"
<AnimatePresence mode="wait">
{open && <Modal key="modal" />}
</AnimatePresence>
// Item de lista descartável — use "popLayout"
<AnimatePresence mode="popLayout">
{items.map(item => <Card key={item.id} />)}
</AnimatePresence>
Padrões Avançados (Conceitos)
- Parallax (transformações vinculadas ao scroll)
- Contação de histórias com scroll (seções fixas)
- Inclinação 3D (transformações baseadas no ponteiro)
- Crossfade (
layoutIdcompartilhado) - Revelação progressiva (clip-path)
- Carregamento skeleton (opacidade em loop)
- Micro-interações (feedback de hover/toque)
- Sistema de mola (movimento baseado em física)
Essenciais de Modal
- Foco armadilhado (focus trap)
- Fechar com Escape
- Bloqueio de rolagem
- Papéis ARIA
- Use
AnimatePresence mode="wait"para que a animação de saída termine antes da próxima modal entrar
Exemplo Completo
import React, { useEffect, useRef, useState } from "react"
import { motion, AnimatePresence } from "motion/react"
function useFocusTrap(ref: React.RefObject<HTMLDivElement | null>, active: boolean) {
useEffect(() => {
if (!active || !ref.current) return
const el = ref.current
const focusable = el.querySelectorAll<HTMLElement>(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
)
const first = focusable[0]
const last = focusable[focusable.length - 1]
function handleKey(e: KeyboardEvent) {
if (e.key !== "Tab") return
if (e.shiftKey && document.activeElement === first) {
e.preventDefault()
last?.focus()
} else if (!e.shiftKey && document.activeElement === last) {
e.preventDefault()
first?.focus()
}
}
el.addEventListener("keydown", handleKey)
first?.focus()
return () => el.removeEventListener("keydown", handleKey)
}, [active, ref])
}
function useScrollLock(active: boolean) {
useEffect(() => {
if (!active) return
const prev = document.body.style.overflow
document.body.style.overflow = "hidden"
return () => { document.body.style.overflow = prev }
}, [active])
}
function Modal({ open, closeModal }: { open: boolean; closeModal: () => void }) {
const ref = useRef<HTMLDivElement>(null)
useFocusTrap(ref, open)
useScrollLock(open)
useEffect(() => {
function onKey(e: KeyboardEvent) {
if (e.key === "Escape") closeModal()
}
if (open) window.addEventListener("keydown", onKey)
return () => window.removeEventListener("keydown", onKey)
}, [open, closeModal])
return (
// mode="wait" garante que a animação de saída termine antes de qualquer nova modal entrar
<AnimatePresence mode="wait">
{open && (
<motion.div
role="dialog"
aria-modal="true"
aria-labelledby="modal-title"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
transition={{ duration: 0.2 }}
className="fixed inset-0 flex items-center justify-center bg-black/40"
>
<motion.div
ref={ref}
initial={{ scale: 0.95, opacity: 0 }}
animate={{ scale: 1, opacity: 1 }}
exit={{ scale: 0.95, opacity: 0 }}
transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}
className="bg-white p-6 rounded"
>
<h2 id="modal-title">Título do Diálogo</h2>
<button onClick={closeModal}>Fechar</button>
</motion.div>
</motion.div>
)}
</AnimatePresence>
)
}
export function Example() {
const [open, setOpen] = useState(false)
return (
<>
<button onClick={() => setOpen(true)}>Abrir</button>
<Modal open={open} closeModal={() => setOpen(false)} />
</>
)
}
Segurança SSR
- Corresponder estados iniciais entre renderizações do servidor e do cliente
- Evitar origens de animação implícitas (sempre defina
initialexplicitamente) - Envolver componentes motion em
"use client"no Next.js App Router
Depuração
Verifique:
- Importação errada (misturando
motion/reacteframer-motion) - Diretiva
"use client"ausente no Next.js App Router - Propriedade
keyausente nos filhos deAnimatePresence - Incompatibilidade de hidratação (estado inicial difere entre SSR e cliente)
- Uso indevido da propriedade
layoutem contêineres grandes causando jank de reflow - Animação orientada por estado não acionando (verifique arrays de dependência)
QA
- Sem CLS
- Teclado funciona
- Foco preso em modais
- Papéis ARIA corretos (
role="dialog",aria-modal="true") - Movimento reduzido respeitado (
useReducedMotion+ media query CSS) - Sem avisos de hidratação no Next.js
- Animações param limpa e suavemente ao desmontar (sem vazamentos de memória)
modedoAnimatePresencedefinido explicitamente em todos os locais de uso
Anti-Padrões
- Animar propriedades de layout (
width,height,top,left) - Animações infinitas sem propósito (sempre pergunte: que estado isso comunica?)
- Escalonamento excessivo de listas (mantenha
staggerChildren≤ 0.1s; além disso parece lento) - Ignorar preferências de movimento reduzido
- Usar
layoutem contêineres grandes ou de viewport inteira - Omitir
modeemAnimatePresence(padrão"sync"causa sobreposição visual) - Usar movimento puramente para decoração
Filosofia
Movimento é design de interação.
Regra Final
Se o movimento não melhorar a UX → remova-o.
Exemplos
Interação de Botão
import { motion } from "motion/react"
export function Button() {
return (
<motion.button
whileHover={{ scale: 1.02 }}
whileTap={{ scale: 0.97 }}
transition={{ duration: 0.15, ease: [0.4, 0, 0.2, 1] }}
>
Clique aqui
</motion.button>
)
}
Exemplo com Movimento Reduzido
import { motion, useReducedMotion } from "motion/react"
export function FadeIn() {
const reduce = useReducedMotion()
return (
<motion.div
initial={{ opacity: 0, y: reduce ? 0 : 24 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: reduce ? 0.1 : 0.35, ease: [0.22, 1, 0.36, 1] }}
/>
)
}
Lista com Escalonamento
import { motion } from "motion/react"
const container = {
hidden: {},
visible: {
transition: { staggerChildren: 0.08 } // mantenha ≤ 0.1s para evitar lentidão
}
}
const item = {
hidden: { opacity: 0, y: 10 },
visible: { opacity: 1, y: 0, transition: { duration: 0.3, ease: [0.22, 1, 0.36, 1] } }
}
export function List() {
return (
<motion.ul variants={container} initial="hidden" animate="visible">
{[1, 2, 3].map(i => (
<motion.li key={i} variants={item}>Item {i}</motion.li>
))}
</motion.ul>
)
}
Modal com AnimatePresence
import { motion, AnimatePresence } from "motion/react"
export function Modal({ open }: { open: boolean }) {
return (
<AnimatePresence mode="wait">
{open && (
<motion.div
initial={{ opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.95 }}
transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}
/>
)}
</AnimatePresence>
)
}
Parallax com Scroll
import { useScroll, useTransform, motion } from "motion/react"
export function Parallax() {
const { scrollYProgress } = useScroll()
const y = useTransform(scrollYProgress, [0, 1], [0, -80])
return <motion.div style={{ y }} />
}
Carregamento Skeleton
import { motion } from "motion/react"
export function Skeleton() {
return (
<motion.div
className="bg-gray-200 h-6 w-full rounded"
animate={{ opacity: [0.5, 1, 0.5] }}
transition={{
duration: 1.5, // pulsação confortável — estava faltando, causava flash rápido
repeat: Infinity,
ease: "easeInOut"
}}
/>
)
}
Layout Compartilhado (Crossfade)
import { motion } from "motion/react"
// layoutId deve ser único por instância montada.
// Se várias instâncias podem existir simultaneamente, anexe um id único:
// layoutId={`shared-${item.id}`}
export function Shared() {
return <motion.div layoutId="shared" />
}