patrones-de-movimiento

Patrones de Movimiento

Patrones de copiar y pegar para las necesidades de animación de UI más comunes. Cada patrón aquí está construido sobre los tokens y springs de motion-foundations. No definas nuevos valores de duración o easing aquí — impórtalos.

Cuándo activarlo

• Al animar un botón, tarjeta, modal o notificación toast
• Al construir entradas de lista con efecto escalonado
• Al configurar transiciones de página en el App Router de Next.js
• Al añadir animaciones de entrada o salida a contenido condicional
• Al implementar revelaciones al hacer scroll, progreso vinculado al scroll o secciones adhesivas
• Al construir tarjetas expandibles, acordeones o transiciones de elementos compartidos

Resultados

Este skill produce:

• Animación accesible y segura para SSR para todos los componentes de UI estándar
• Renderizado condicional envuelto en AnimatePresence con comportamiento de salida correcto
• Componente envoltorio de transición de página para el App Router de Next.js
• Patrones de revelación al scroll y vinculados al scroll usando useScroll + useTransform
• Patrones de animación de layout (layout, layoutId) para elementos que se expanden y se desvanecen

Principios

• Cada patrón importa desde motion-foundations. Sin números fijos.
• Cada render condicional está envuelto en AnimatePresence con una key.
• Las animaciones de salida siempre se definen junto con las de entrada — nunca como una idea posterior.
• layout se usa solo para cambios pequeños y aislados. Los subárboles grandes reciben transformaciones explícitas.

Reglas

1. Siempre envuelve los renders condicionales en AnimatePresence con una key en el hijo directo. Sin una key, las animaciones de salida nunca se disparan.
2. Siempre define exit cuando definas initial + animate. Una animación sin salida está incompleta.
3. Usa mode="wait" en las transiciones de página. La entrada no debe comenzar hasta que la salida se complete.
4. Nunca uses layout en subárboles con más de ~5 hijos o DOM profundamente anidado. Usa transformaciones explícitas con x/y en su lugar.
5. El intervalo de escalonamiento debe mantenerse entre 0.05s y 0.10s. Por debajo se siente mecánico; por encima se siente lento.
6. Los modales deben incluir siempre: trampa de enfoque, cierre con tecla Escape, bloqueo de scroll, role="dialog", aria-modal="true".
7. Las revelaciones al scroll usan viewport={{ once: true }}. Repetir al salir del viewport distrae, no informa.
8. Todos los valores de token se importan desde motion-foundations. Sin números inline.

Guía de decisión

Elegir el patrón correcto

Situación	Patrón
Un elemento aparece / desaparece	AnimatePresence
Lista de elementos cargando en secuencia	Variantes escalonadas
Navegando entre rutas	Envoltorio de transición de página
Un elemento cambia de tamaño en su lugar	Prop layout
Mismo elemento se mueve entre contextos de página	layoutId
Elemento entra cuando se desplaza a la vista	whileInView
Valor vinculado a la posición de scroll	useScroll + useTransform

Cuándo usar mode="wait" vs mode="sync"

Modo	Úsalo cuando
wait	Transiciones de página, intercambio de contenido (uno a la vez)
sync	Notificaciones apiladas, elementos de lista (la superposición está bien)
popLayout	Elementos eliminados de una lista que se refluye

Conceptos clave

Contrato de AnimatePresence

Tres cosas deben ser siempre ciertas:

1. AnimatePresence envuelve el condicional
2. El hijo directo tiene una key
3. El hijo tiene una prop exit

Si falta alguna de estas, la animación de salida falla silenciosamente.

layout vs layoutId

• layout — anima el cambio de tamaño/posición del propio elemento en su lugar
• layoutId — vincula dos elementos separados, haciendo una transición de fundido entre ellos a través de renders

Usa layout="position" en el texto dentro de un contenedor expandible para evitar que el reflujo del texto se anime.

Ejemplos de código

Retroalimentación de botón

"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 de la regla 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 en el lugar de uso:
// <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>

export function Modal({ onClose }: { onClose: () => void }) {
  return (
    <>
      {/* Superposición */}
      <motion.div
        className="fixed inset-0 bg-black/50"
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        exit={{ opacity: 0 }}
        onClick={onClose}
      />

      {/* Panel — requisitos de accesibilidad: trampa de enfoque, cierre con Escape,
          bloqueo 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}
      />
    </>
  )
}

Pila de notificaciones

"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>

Transición de página (App Router de Next.js)

// 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>
  )
}

Revelación al 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 — regla 7
  transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>

Barra de progreso de 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 }}
    />
  )
}

Tarjeta expandible

"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" evita que el reflujo de texto se anime */}
      <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>
  )
}

Fundido de elemento compartido

// Contexto de origen
<motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />

// Contexto de destino (mismo layoutId — motion maneja la transición)
<motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" />

Acordeón

<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>

Ejemplo completo

Una lista escalonada que aparece al montar, maneja presencia condicional y respeta el movimiento reducido — combinando tokens, springs, AnimatePresence y el hook de accesibilidad de 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}>Eliminar</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>
  )
}

Restricciones / No cubre

Este skill no cubre:

• Definiciones de tokens y springs → ver motion-foundations
• Interacciones de arrastre, gestos de deslizamiento, listas reordenables → ver motion-advanced
• Animaciones de texto (revelación de palabras/caracteres, contadores) → ver motion-advanced
• Dibujo o morphing de rutas SVG → ver motion-advanced
• Hooks de animación personalizados → ver motion-advanced
• Transiciones solo CSS que no usan motion/react

Antipatrones

Antipatrón	Regla violada	Solución
Hijo de AnimatePresence sin key	Regla 1	Añadir key estable al hijo directo
initial + animate sin exit	Regla 2	Definir siempre los tres juntos
Transición de página sin mode="wait"	Regla 3	Añadir mode="wait" a AnimatePresence
layout en una lista de 50 elementos	Regla 4	Usar mode="popLayout" o transformaciones explícitas
staggerChildren: 0.2 en una lista de 10 elementos	Regla 5	Limitar a 0.08–0.10
Modal sin trampa de enfoque	Regla 6	Añadir focus-trap-react o Radix Dialog
whileInView sin viewport={{ once: true }}	Regla 7	Las entradas repetitivas distraen, no informan
transition={{ duration: 0.3 }} inline	Regla 8	Usa motionTokens.duration.normal

Skills relacionados

• motion-foundations — define todos los tokens, springs, el hook useSafeMotion y las protecciones SSR que cada patrón aquí importa. Debe configurarse primero.
• motion-advanced — extiende estos patrones con arrastre, gestos, SVG, texto, hooks personalizados y secuenciación imperativa. No redefine ningún patrón de este skill.