theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-animacion/SKILL.md

@@ -0,0 +1,432 @@
+---
+name: patrones-animacion
+description: Patrones de animación listos para producción en React / Next.js — botones, modales, toasts, stagger, transiciones de página, animaciones de salida, scroll y layout — construidos sobre los tokens y springs de fundamentos-animacion.
+version: 1.0
+tags: [motion, animacion, patrones-ui]
+category: frontend
+---
+
+# Patrones de animación
+
+Patrones listos para copiar y pegar que cubren las necesidades de animación de UI más comunes.
+Cada patrón de esta skill está construido sobre los tokens y springs de `fundamentos-animacion`.
+No definas aquí nuevos valores de duración o easing — impórtalos.
+
+## Cuándo activarla
+
+- Al animar un botón, una tarjeta, un modal o una notificación toast
+- Al construir entradas de listas con stagger
+- 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 scroll-reveal, progreso ligado al scroll o secciones narrativas sticky
+- Al construir tarjetas expandibles, acordeones o transiciones de elemento compartido
+
+## Resultados
+
+Esta skill produce:
+
+- Animación accesible y segura para SSR en todos los componentes de UI estándar
+- Renders condicionales envueltos en `AnimatePresence` con el comportamiento de salida correcto
+- Componente envolvente de transición de página para el App Router de Next.js
+- Patrones de scroll-reveal y de valores ligados al scroll usando `useScroll` + `useTransform`
+- Patrones de animación de layout (`layout`, `layoutId`) para elementos que se expanden o hacen crossfade
+
+## Principios
+
+- Cada patrón importa desde `fundamentos-animacion`. Nada de números crudos.
+- Cada render condicional se envuelve en `AnimatePresence` con una `key`.
+- Las animaciones de salida se definen siempre junto a las de entrada — nunca como una ocurrencia tardía.
+- `layout` se usa solo para desplazamientos pequeños y aislados. Los subárboles grandes reciben transforms explícitos.
+
+## Reglas
+
+1. **Envuelve siempre los renders condicionales en `AnimatePresence` con una `key`** en el hijo directo. Sin key, las animaciones de salida nunca se disparan.
+2. **Define siempre `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 empezar hasta que la salida termine.
+4. **Nunca uses `layout` en subárboles con más de ~5 hijos o DOM profundamente anidado.** Usa transforms explícitos de `x`/`y` en su lugar.
+5. **El intervalo de stagger debe mantenerse entre `0.05s` y `0.10s`.** Por debajo se siente mecánico; por encima, lento.
+6. **Los modales deben incluir siempre:** trampa de foco, cierre con la tecla Escape, bloqueo de scroll, `role="dialog"`, `aria-modal="true"`.
+7. **Los scroll-reveals usan `viewport={{ once: true }}`.** Repetir la animación al salir del viewport distrae, no informa.
+8. **Todos los valores de tokens se importan de `fundamentos-animacion`.** Nada de números inline.
+
+## Guía de decisión
+
+### Elegir el patrón correcto
+
+| Situación | Patrón |
+| ---------------------------------------------- | ---------------------- |
+| Un elemento aparece / desaparece                | `AnimatePresence`      |
+| Lista de ítems que cargan en secuencia          | Variants con stagger   |
+| Navegación entre rutas                          | Envoltorio de transición de página |
+| Un elemento cambia de tamaño en su sitio        | Prop `layout`          |
+| El mismo elemento se mueve entre contextos de la página | `layoutId`     |
+| Un elemento entra al hacerse visible por scroll | `whileInView`          |
+| Un valor ligado a la posición del scroll        | `useScroll` + `useTransform` |
+
+### Cuándo usar `mode="wait"` vs `mode="sync"`
+
+| Modo | Úsalo cuando |
+| ------- | --------------------------------------- |
+| `wait` | Transiciones de página, intercambios de contenido (de uno en uno) |
+| `sync` | Notificaciones apiladas, ítems de lista (el solapamiento está bien) |
+| `popLayout` | Ítems eliminados de una lista que se reacomoda |
+
+## Conceptos clave
+
+### El contrato de AnimatePresence
+
+Tres cosas deben cumplirse siempre:
+
+1. `AnimatePresence` envuelve el condicional
+2. El hijo directo tiene una `key`
+3. El hijo tiene una prop `exit`
+
+Si falta cualquiera de las tres, la animación de salida falla en silencio.
+
+### layout vs layoutId
+
+- `layout` — anima el cambio de tamaño/posición del propio elemento en su sitio
+- `layoutId` — enlaza dos elementos separados, haciendo crossfade entre ellos a través de renders
+
+Usa `layout="position"` en el texto dentro de un contenedor que se expande para evitar que el reflujo del texto se anime.
+
+## Ejemplos de código
+
+### Feedback de botón
+
+```tsx
+"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 con stagger
+
+```tsx
+"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 de 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
+
+```tsx
+"use client"
+import { motion, AnimatePresence } from "motion/react"
+import { motionTokens, springs } from "@/lib/motion-tokens"
+
+// Envolver en el punto de uso:
+// <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}
+      />
+
+      {/* Panel — requisitos de accesibilidad: trampa de foco, 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 toasts
+
+```tsx
+"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)
+
+```tsx
+// 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>
+  )
+}
+```
+
+### Scroll reveal
+
+```tsx
+"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
+
+```tsx
+"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
+
+```tsx
+"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 del 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>
+  )
+}
+```
+
+### Crossfade de elemento compartido
+
+```tsx
+// Contexto de origen
+<motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />
+
+// Contexto de destino (mismo layoutId — motion gestiona la transición)
+<motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" />
+```
+
+### Acordeón
+
+```tsx
+<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 de extremo a extremo
+
+Una lista con stagger que entra al montarse, gestiona presencia condicional y
+respeta la preferencia de movimiento reducido — combinando tokens, springs,
+`AnimatePresence` y el hook de accesibilidad de `fundamentos-animacion`:
+
+```tsx
+"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 / Fuera de alcance
+
+Esta skill **no** cubre:
+
+- Definiciones de tokens y springs → ver `fundamentos-animacion`
+- Interacciones de arrastre, gestos de swipe, listas reordenables
+- Animaciones de texto (revelado por palabra/carácter, contadores)
+- Dibujo o morphing de trazados SVG
+- Hooks de animación personalizados
+- Transiciones solo-CSS que no usan `motion/react`
+
+## Antipatrones
+
+| Antipatrón | Regla violada | Corrección |
+| -------------------------------------------- | ------- | ------------------------------------------ |
+| Hijo de `AnimatePresence` sin `key` | Regla 1 | Añade una `key` estable al hijo directo |
+| `initial` + `animate` sin `exit` | Regla 2 | Define siempre los tres juntos |
+| Transición de página sin `mode="wait"` | Regla 3 | Añade `mode="wait"` a `AnimatePresence` |
+| `layout` en una lista de 50 ítems | Regla 4 | Usa `mode="popLayout"` o transforms explícitos |
+| `staggerChildren: 0.2` en una lista de 10 ítems | Regla 5 | Limítalo a `0.08–0.10` |
+| Modal sin trampa de foco | Regla 6 | Añade `focus-trap-react` o Radix Dialog |
+| `whileInView` sin `viewport={{ once: true }}` | Regla 7 | Las entradas repetidas distraen, no informan |
+| `transition={{ duration: 0.3 }}` inline | Regla 8 | Usa `motionTokens.duration.normal` |
+
+## Skills relacionadas
+
+- **`fundamentos-animacion`** — define todos los tokens, springs, el hook `useSafeMotion` y las salvaguardas de SSR que importa cada patrón de esta skill. Debe configurarse primero.