¿Qué hace Sistema de Movimiento v4.2?
Sistema de animación listo para producción para React / Next.js.
Centrado en rendimiento, accesibilidad y usabilidad — no en decoración.
Cuándo Usarlo
Usa este sistema de movimiento cuando el movimiento:
- Guíe la atención (por ejemplo, tutoriales, acciones clave)
- Comunique estado (carga, éxito, error, transiciones)
- Preserve la continuidad espacial (cambios de diseño, navegación)
Escenarios Apropiados
- Componentes interactivos (botones, modales, menús)
- Transiciones de estado (cargando → cargado, abierto → cerrado)
- Continuidad en navegación y diseño (elementos compartidos, fundido cruzado)
Consideraciones
- Accesibilidad: Siempre soportar movimiento reducido
- Adaptación a dispositivos: Ajustar para dispositivos de gama baja
- Compensaciones de rendimiento: Preferir capacidad de respuesta sobre suavidad visual
Evitar Usar Movimiento Cuando
- Es puramente decorativo
- Reduce la usabilidad o claridad
- Impacta negativamente el rendimiento
Cómo Funciona
Principio Central
El movimiento debe:
- Guiar la atención
- Comunicar estado
- Preservar la continuidad espacial
Si no hace nada de esto → elimínalo.
Instalación
npm install motion
Versión
motion/react- predeterminado para proyectos Motion for React actuales (paquete:motion)framer-motion- ruta de importación heredada para proyectos que aún dependen de Framer Motion
No mezclar. Mezclar causa planificadores internos conflictivos y contextos AnimatePresence rotos: los componentes de un paquete no coordinarán animaciones de salida con componentes del otro.
Para verificar qué versión usa tu proyecto:
cat package.json | grep -E '"motion"|"framer-motion"'
Importa siempre de una sola fuente de manera consistente:
// Correcto (moderno)
import { motion, AnimatePresence } from "motion/react"
// Correcto (heredado)
import { motion, AnimatePresence } from "framer-motion"
// Nunca mezcles ambos en el mismo proyecto
Tokens de Movimiento
// motionTokens.ts
export const motionTokens = {
duration: {
fast: 0.18,
normal: 0.35,
slow: 0.6
},
// Úsalos como valor `ease` dentro de un 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
}
}
Ejemplo 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
}}
/>
Reglas de Rendimiento
Seguro
- transform
- opacity
Evitar
- width / height
- top / left
Regla: capacidad de respuesta > suavidad
Adaptación a Dispositivos
La heurística combina el número de núcleos de CPU y la memoria disponible para una señal más fiable. deviceMemory está disponible en Chrome/Android; la alternativa cubre Safari y Firefox.
const isLowEnd =
typeof navigator !== "undefined" && (
// Poca memoria (solo Chrome/Android; undefined en otros → tratar como capaz)
(navigator.deviceMemory !== undefined && navigator.deviceMemory <= 2) ||
// Pocos núcleos Y sin API de memoria (cubre Safari/Firefox en hardware débil)
(navigator.deviceMemory === undefined && navigator.hardwareConcurrency <= 4)
)
const duration = isLowEnd ? 0.2 : 0.4
Accesibilidad
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>
Arquitectura y Patrones
Patrones Principales
| Escenario | Patrón |
|---|---|
| Retroalimentación al pasar el ratón | whileHover |
| Retroalimentación al tocar / presionar | whileTap |
| Revelar al hacer scroll | whileInView |
| Valor vinculado al scroll | useScroll + useTransform |
| Montaje/desmontaje condicional | AnimatePresence |
| Pequeños cambios de diseño (un solo elemento, < ~300px de cambio) | Propiedad layout |
| Grandes cambios de diseño o reflujo de página completa | Evitar layout; usar transiciones CSS o enrutamiento a nivel de página |
| Secuencias complejas e imperativas | useAnimate |
¿Por qué evitar
layouten contenedores grandes? La animación de layout de Framer usatransformpara reconciliar posiciones, pero en elementos que abarcan todo el viewport o provocan un reflujo profundo, el costo de medición causa jank visible y CLS. Prefiere transiciones CSS Grid/Flexbox o coordina conlayoutIdsolo en elementos hijos específicos.
Diseño y Transiciones
- Transiciones de elementos compartidos →
layoutId(debe ser único por instancia montada) - Transiciones de entrada / salida →
AnimatePresence(ver guía demodea continuación)
Modo de AnimatePresence
Especifica siempre mode explícitamente — el valor por defecto ("sync") ejecuta entrada y salida simultáneamente, lo que causa superposición visual en la mayoría de los patrones de interfaz.
mode | Cuándo usarlo |
|---|---|
"wait" | La salida se completa antes de que comience la entrada. Úsalo para modales, notificaciones, transiciones de página. |
"sync" (por defecto) | Entrada y salida se superponen. Úsalo solo cuando la superposición sea intencional (por ejemplo, carruseles con fundido cruzado). |
"popLayout" | El elemento que sale se elimina del flujo inmediatamente; los elementos restantes se animan para llenar el espacio. Úsalo para listas, pestañas, tarjetas descartables. |
// Modal — siempre usar "wait"
<AnimatePresence mode="wait">
{open && <Modal key="modal" />}
</AnimatePresence>
// Elemento de lista descartable — usar "popLayout"
<AnimatePresence mode="popLayout">
{items.map(item => <Card key={item.id} />)}
</AnimatePresence>
Patrones Avanzados (Conceptos)
- Parallax (transformaciones vinculadas al scroll)
- Narrativa con scroll (secciones fijas)
- Inclinación 3D (transformaciones basadas en el puntero)
- Fundido cruzado (
layoutIdcompartido) - Revelado progresivo (clip-path)
- Carga con skeleton (opacidad en bucle)
- Micro-interacciones (retroalimentación hover/tap)
- Sistema de resorte (movimiento basado en física)
Esenciales de un Modal
- Trampa de foco
- Cierre con Escape
- Bloqueo de scroll
- Roles ARIA
- Usar
AnimatePresence mode="wait"para que la animación de salida se complete antes de que entre el siguiente modal
Ejemplo 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" asegura que la animación de salida termine antes de que entre cualquier nuevo modal
<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 del Diálogo</h2>
<button onClick={closeModal}>Cerrar</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)} />
</>
)
}
Seguridad SSR
- Coincidir estados iniciales entre el renderizado del servidor y el cliente
- Evitar orígenes de animación implícitos (siempre establecer
initialexplícitamente) - Envolver componentes motion en
"use client"en Next.js App Router
Depuración
Verificar:
- Importación incorrecta (mezclar
motion/reactyframer-motion) - Directiva
"use client"faltante en Next.js App Router - Propiedad
keyfaltante en hijos deAnimatePresence - Desajuste de hidratación (el estado inicial difiere entre SSR y cliente)
- Mal uso de la propiedad
layouten contenedores grandes que causa jank por reflujo - Animación impulsada por estado que no se activa (verificar arrays de dependencias)
QA
- Sin CLS
- El teclado funciona
- Foco atrapado en modales
- Roles ARIA correctos (
role="dialog",aria-modal="true") - Movimiento reducido respetado (
useReducedMotion+ media query CSS) - Sin advertencias de hidratación en Next.js
- Las animaciones se detienen limpiamente al desmontar (sin fugas de memoria)
modedeAnimatePresenceestablecido explícitamente en todos los puntos de uso
Anti-Patrones
- Animar propiedades de diseño (
width,height,top,left) - Animaciones infinitas sin propósito (preguntar siempre: ¿qué estado comunica esto?)
- Escalonamiento excesivo de listas (mantener
staggerChildren≤ 0.1s; más allá se siente lento) - Ignorar preferencias de movimiento reducido
- Usar
layouten contenedores grandes o de viewport completo - Omitir
modeenAnimatePresence(el valor por defecto"sync"causa superposición visual) - Usar movimiento puramente para decoración
Filosofía
El movimiento es diseño de interacción.
Regla Final
Si el movimiento no mejora la UX → elimínalo.
Ejemplos
Interacción de Botón
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] }}
>
Haz clic
</motion.button>
)
}
Ejemplo de Movimiento Reducido
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 Escalonada
import { motion } from "motion/react"
const container = {
hidden: {},
visible: {
transition: { staggerChildren: 0.08 } // mantener ≤ 0.1s para evitar lentitud
}
}
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}>Elemento {i}</motion.li>
))}
</motion.ul>
)
}
Modal con 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 con 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 }} />
}
Carga con 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, // pulso cómodo — faltaba, causaba un destello rápido
repeat: Infinity,
ease: "easeInOut"
}}
/>
)
}
Diseño Compartido (Fundido Cruzado)
import { motion } from "motion/react"
// layoutId debe ser único por instancia montada.
// Si pueden existir múltiples instancias simultáneamente, agrega un id único:
// layoutId={`shared-${item.id}`}
export function Shared() {
return <motion.div layoutId="shared" />
}