theus-cli-linux-x64 1.2.1 → 1.3.0

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

@@ -1,432 +0,0 @@
----
-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.