Communitygithub.com

503496348-ops/mischief-production

Sistema de movimiento UI listo para producción para React/Next.js. Úsalo al implementar animaciones, transiciones o patrones de movimiento.

¿Qué es mischief-production?

Este skill define un sistema de movimiento UI completo y listo para producción para aplicaciones React/Next.js. Su propósito es guiar la implementación de animaciones y transiciones enfocándose en rendimiento, accesibilidad y usabilidad, no en la decoración. Proporciona principios claros (guiar la atención, comunicar estado, preservar continuidad espacial), tokens de movimiento predefinidos (duraciones, easing, distancias), reglas de rendimiento (usar transform y opacity, evitar layout properties), adaptación por dispositivo (detección de hardware limitado) y accesibilidad obligatoria (useReducedMotion, consultas CSS). Incluye patrones de arquitectura como hover, tap, scroll, AnimatePresence con modos explícitos (wait, popLayout), y anti-patrones a evitar. Es compatible con motion/react (moderno) y framer-motion (legado), pero advierte no mezclarlos. El skill se usa como guía de referencia para cualquier implementación de movimiento en UI, desde micro-interacciones hasta modales completos con foco, scroll lock y roles ARIA.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/503496348-ops/mischief-production/tree/HEAD/skills/ecc-motion-ui

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Sistema de Movimiento v4.2

Sistema de movimiento UI listo para producción para React / Next.js.

Enfocado 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 (ej., onboarding, 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 de navegación y diseño (elementos compartidos, encadenado)

Consideraciones

  • Accesibilidad: Siempre soportar movimiento reducido
  • Adaptación de dispositivo: 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 modernos (paquete: motion)
  • framer-motion - ruta de importación heredada para proyectos que aún dependen de Framer Motion

No mezcles. Mezclar causa conflictos entre schedulers internos 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 desde una sola fuente de forma 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
  },
  // Usa estos como el valor de `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 de Dispositivo

La heurística combina el recuento de núcleos de CPU y la memoria disponible para una señal más fiable. deviceMemory está disponible en Chrome/Android; el fallback cubre Safari y Firefox.

const isLowEnd =
  typeof navigator !== "undefined" && (
    // Poca memoria (solo Chrome/Android; undefined en otros se trata 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 Centrales

EscenarioPatrón
Feedback al pasar el ratónwhileHover
Feedback al presionar / tocarwhileTap
Revelar al hacer scrollwhileInView
Valor vinculado al scrolluseScroll + useTransform
Montaje/desmontaje condicionalAnimatePresence
Pequeños cambios de diseño (un solo elemento, < ~300px de cambio)Propiedad layout
Grandes cambios de diseño o reflujos de página completaEvitar layout; usar transiciones CSS o enrutamiento a nivel de página
Secuencias imperativas complejasuseAnimate

¿Por qué evitar layout en contenedores grandes? La animación de layout de Framer usa transform para 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 con layoutId solo 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 de mode a continuación)

Modo de AnimatePresence

Especifica siempre mode explícitamente — el valor predeterminado ("sync") ejecuta la entrada y la salida simultáneamente, lo que causa superposición visual en la mayoría de los patrones de UI.

modeCuándo usarlo
"wait"La salida se completa antes de que comience la entrada. Úsalo para modales, toasts, transiciones de página.
"sync" (predeterminado)La entrada y la salida se superponen. Úsalo solo cuando la superposición sea intencional (ej., carruseles con encadenado).
"popLayout"El elemento que sale se elimina inmediatamente del flujo; los elementos restantes se animan para llenar el espacio. Úsalo para listas, pestañas, tarjetas descartables.
// Modal — usa siempre "wait"
<AnimatePresence mode="wait">
  {open && <Modal key="modal" />}
</AnimatePresence>

// Elemento de lista descartable — usa "popLayout"
<AnimatePresence mode="popLayout">
  {items.map(item => <Card key={item.id} />)}
</AnimatePresence>

Patrones Avanzados (Conceptos)

  • Paralaje (transformaciones vinculadas al scroll)
  • Narrativa con scroll (secciones adhesivas)
  • Inclinación 3D (transformaciones basadas en el puntero)
  • Encadenado (layoutId compartido)
  • Revelado progresivo (clip-path)
  • Carga con esqueleto (opacidad en bucle)
  • Micro-interacciones (feedback al pasar el ratón / presionar)
  • Sistema de resorte (movimiento basado en física)

Elementos Esenciales del Modal

  • Trampa de foco
  • Cierre con Escape
  • Bloqueo de scroll
  • Roles ARIA
  • Usa 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 un 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

  • Coincide los estados iniciales entre las renderizaciones del servidor y del cliente
  • Evita orígenes de animación implícitos (siempre establece initial explícitamente)
  • Envuelve los componentes de movimiento en "use client" en Next.js App Router

Depuración

Verifica:

  • Importación incorrecta (mezclar motion/react y framer-motion)
  • Directiva "use client" faltante en Next.js App Router
  • Propiedad key faltante en hijos de AnimatePresence
  • Desajuste de hidratación (el estado inicial difiere entre SSR y cliente)
  • Mal uso de la propiedad layout en contenedores grandes que causa jank por reflujo
  • Animación impulsada por estado que no se activa (verifica los 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 + consulta de medios CSS)
  • Sin advertencias de hidratación en Next.js
  • Las animaciones se detienen limpiamente al desmontar (sin fugas de memoria)
  • mode de AnimatePresence establecido explícitamente en todos los sitios de uso

Anti-Patrones

  • Animar propiedades de layout (width, height, top, left)
  • Animaciones infinitas sin propósito (pregunta siempre: ¿qué estado comunica esto?)
  • Escalonamiento excesivo de listas (mantén staggerChildren ≤ 0.1s; más allá se siente lento)
  • Ignorar las preferencias de movimiento reducido
  • Usar layout en contenedores grandes o de viewport completo
  • Omitir mode en AnimatePresence (el valor predeterminado "sync" causa superposición visual)
  • Usar movimiento puramente por 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>
  )
}

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

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 destello rápido
        repeat: Infinity,
        ease: "easeInOut"
      }}
    />
  )
}

Diseño Compartido (Encadenado)

import { motion } from "motion/react"

// layoutId debe ser único por instancia montada.
// Si pueden existir varias instancias simultáneamente, agrega un id único:
// layoutId={`shared-${item.id}`}
export function Shared() {
  return <motion.div layoutId="shared" />
}

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

503496348-ops/mischief-production

Use this skill when inspecting Blender characters, rigs, poses, animation retargeting, ground contact, facing direction, or model-vs-motion alignment where screenshots alone are not enough.

503496348-ops/mischief-production

Build reusable Manim explainers for technical concepts, graphs, system diagrams, and product walkthroughs, then hand off to the wider HCP video stack if needed. Use when the user wants a clean animated explainer rather than a generic talking-head script.

503496348-ops/mischief-production

Advanced motion patterns for React / Next.js — drag & drop, gestures, text animations, SVG path drawing, custom hooks, imperative sequences (useAnimate), loaders, and the full API decision tree. Requires motion-foundations.

503496348-ops/mischief-production

Motion tokens, spring presets, performance rules, device adaptation, accessibility enforcement, and SSR safety for React / Next.js using motion/react. Foundation layer — all other motion skills depend on this.

503496348-ops/mischief-production

Production-ready animation patterns for React / Next.js — button, modal, toast, stagger, page transitions, exit animations, scroll, and layout — built on motion-foundations tokens and springs.

503496348-ops/mischief-production

Best practices for Remotion - Video creation in React. 29 domain-specific rules covering 3D, animations, audio, captions, charts, transitions, and more.

503496348-ops/mischief-production

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

Skills relacionados