Communitygithub.com

503496348-ops/mischief-production

Tokens de movimiento, presets de resorte, reglas de rendimiento, adaptación a dispositivos, cumplimiento de accesibilidad y seguridad SSR para React / Next.js usando motion/react. Capa base: todas las demás habilidades de movimiento dependen de esta.

¿Qué es mischief-production?

Esta habilidad (skill) establece la capa base fundamental del sistema de animación para aplicaciones React/Next.js que utilizan la librería motion/react. Define todos los valores, restricciones y reglas que heredan las habilidades downstream como motion-patterns y motion-advanced. Proporciona un objeto compartido motionTokens con duraciones, easings, distancias y escalas; un mapa de presets de resortes (springs) con 5 configuraciones nombradas; una función shouldAnimate() que actúa como puerta de entrada para todos los componentes; soporte de accesibilidad mediante prefers-reduced-motion y el hook useReducedMotion; y estados iniciales seguros para SSR que evitan advertencias de hidratación. Es útil para cualquier desarrollador que comience a trabajar con animaciones, ya que garantiza consistencia, rendimiento y accesibilidad desde el inicio. Se activa al crear cualquier componente animado desde cero, configurar tokens o valores de easing, implementar soporte para movimientos reducidos, depurar problemas de hidratación en SSR o evaluar si una animación debería existir. Las reglas son innegociables: usar solo motion/react, mantener initial coherente con la salida del servidor, anteponer la reducción de movimiento, no animar propiedades de layout, usar siempre los tokens y springs definidos, requerir la directiva 'use client' y nunca leer window o navigator a nivel de módulo.

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

Preguntar en tu IA favorita

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

Documentación

Fundamentos de Movimiento

La capa base del sistema de movimiento. Define cada valor, restricción y regla que heredan las habilidades posteriores (motion-patterns, motion-advanced). Carga esta habilidad antes de comenzar cualquier trabajo de animación.

Cuándo activar

  • Al empezar cualquier componente animado desde cero
  • Al configurar tokens, presets de resorte o valores de easing
  • Al implementar soporte para prefers-reduced-motion
  • Al depurar incoherencias de hidratación causadas por estados iniciales de animación
  • Al evaluar si una animación debería existir en absoluto

Salidas

Esta habilidad produce:

  • Un objeto compartido motionTokens (duración, easing, distancia, escala)
  • Un mapa de presets springs (5 configuraciones nombradas)
  • Una puerta de entrada shouldAnimate() utilizada por todos los componentes
  • Valores predeterminados de animación conformes con accesibilidad mediante useReducedMotion
  • Estados iniciales seguros para SSR sin advertencias de hidratación

Principios

El movimiento debe cumplir al menos uno de los siguientes objetivos o debe eliminarse:

  • Guiar la atención
  • Comunicar estado
  • Preservar la continuidad espacial

La capacidad de respuesta siempre tiene prioridad sobre la fluidez. Una animación a 60 fps que causa retraso en la entrada es peor que ninguna animación.

Reglas

Estas son innegociables. Se aplican a todos los componentes del sistema.

  1. Usa solo motion/react. Nunca importes desde framer-motion. No mezcles ambos en el mismo árbol.
  2. initial debe coincidir con la salida del servidor. Si el servidor renderiza opacity: 1, la prop initial también debe ser opacity: 1. Sin excepciones.
  3. La reducción de movimiento anula todo. Cuando useReducedMotion() devuelve true o prefersReduced es true, todas las transformaciones se deshabilitan. Los desvanecimientos solo de opacidad en ≤ 0.2 s son la única alternativa permitida.
  4. Nunca animes propiedades de layout. width, height, top, left, margin, padding están prohibidas en animate. Usa solo transform y opacity.
  5. Todos los valores de tokens provienen de motionTokens. Las duraciones y easings hardcodeados en archivos de componentes están prohibidos.
  6. Todas las configuraciones de resorte provienen del mapa springs. Los valores inline de stiffness/damping están prohibidos.
  7. Se requiere "use client" en cada archivo que importe desde motion/react.
  8. Nunca leas window o navigator a nivel de módulo. Siempre protégete con typeof window !== "undefined".

Guía de decisión

Elegir una duración

TokenÚsalo cuando
instantMostrar/ocultar tooltip, anillo de enfoque, actualización de badge
fastFeedback de botón, cambio de icono, alternancia de chip
normalApertura de modal, expansión de tarjeta, entrada de elemento de página
slowEntrada de héroe, transición de página completa
crawlNarración deliberada; úsalo con moderación

Elegir un resorte

PresetÚsalo cuando
snappyUI predeterminado: botones, chips, elementos de navegación
gentleTarjetas, modales, paneles que aterrizan suavemente
bouncyMomentos lúdicos: estados vacíos, incorporación
instantTooltips, popovers, menús desplegables
releaseLiberación de arrastre: sensación física natural

Cuándo deshabilitar la animación por completo

Deshabilita (haz que shouldAnimate() devuelva false) cuando:

  • prefersReduced es true
  • isLowEnd es true y la animación no es esencial
  • El elemento está fuera de pantalla y nunca entrará en el viewport
  • La animación es puramente decorativa sin propósito UX

Conceptos centrales

Sistema de tokens

// lib/motion-tokens.ts
export const motionTokens = {
  duration: {
    instant: 0.08,
    fast:    0.18,
    normal:  0.35,
    slow:    0.6,
    crawl:   1.0,
  },
  easing: {
    smooth: [0.22, 1, 0.36, 1],
    sharp:  [0.4, 0, 0.2, 1],
    bounce: [0.34, 1.56, 0.64, 1],
    linear: [0, 0, 1, 1],
  },
  distance: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 48,
  },
  scale: {
    subtle: 0.98,
    press:  0.95,
    pop:    1.04,
  },
}

export const springs = {
  snappy:  { type: "spring", stiffness: 300, damping: 30 },
  gentle:  { type: "spring", stiffness: 120, damping: 14 },
  bouncy:  { type: "spring", stiffness: 400, damping: 10 },
  instant: { type: "spring", stiffness: 600, damping: 35 },
  release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 },
}

Banderas de tiempo de ejecución

// lib/motion-config.ts
export const motionConfig = {
  isLowEnd() {
    return (
      typeof navigator !== "undefined" &&
      navigator.hardwareConcurrency <= 4
    )
  },

  prefersReduced() {
    return (
      typeof window !== "undefined" &&
      window.matchMedia("(prefers-reduced-motion: reduce)").matches
    )
  },

  shouldAnimate({ essential = false } = {}) {
    if (this.prefersReduced()) return false
    if (!essential && this.isLowEnd()) return false
    return true
  },

  duration() {
    return this.isLowEnd() || this.prefersReduced()
      ? motionTokens.duration.instant
      : motionTokens.duration.normal
  },
}

Accesibilidad

Orden de prioridad (de mayor a menor):

  1. prefers-reduced-motion: reduce — deshabilita todas las transformaciones, limita las transiciones de opacidad a ≤ 0.2 s
  2. Detección de dispositivos de gama baja — reduce la duración, elimina animaciones no esenciales
  3. Preferencia de diseño — todo lo demás

El movimiento debe degradarse con elegancia. Nunca debe desaparecer abruptamente de una manera que provoque un cambio de layout o confunda la orientación.

// hooks/use-reduced-motion.tsx
"use client"
import { useReducedMotion } from "motion/react"

export function useSafeMotion(fullY: number = 16) {
  const reduce = useReducedMotion()
  return {
    initial: { opacity: 0, y: reduce ? 0 : fullY },
    animate: { opacity: 1, y: 0 },
    exit:    { opacity: 0, y: reduce ? 0 : -fullY },
  }
}
/* globals.css */
@media (prefers-reduced-motion: reduce) {
  .motion-safe-transition  { transition: opacity 0.15s; }
  .motion-reduce-transform { transform: none !important; }
}
<!-- Tailwind -->
<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>

Seguridad SSR / hidratación

Regla: initial siempre debe coincidir con lo que renderiza el servidor.

// INCORRECTO: el servidor renderiza opacity:1 pero initial dice 0 → incoherencia de hidratación
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />

// CORRECTO: usa AnimatePresence o difiere al montaje del cliente
"use client"
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])

<motion.div
  initial={{ opacity: mounted ? 0 : 1 }}
  animate={{ opacity: 1 }}
/>

Ejemplos de código

Integral: tokens + resortes + accesibilidad + protección SSR

// components/fade-in-card.tsx
"use client"

import { useState, useEffect } from "react"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"
import { motionConfig } from "@/lib/motion-config"

interface FadeInCardProps {
  children: React.ReactNode
  delay?: number
}

export function FadeInCard({ children, delay = 0 }: FadeInCardProps) {
  // Protección SSR — initial debe coincidir con la salida del servidor (opacity: 1)
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])

  // Accesibilidad — deshabilita transformación cuando se prefiere movimiento reducido
  const safeMotion = useSafeMotion(motionTokens.distance.md)

  // Puerta de dispositivo — salta la animación en hardware de gama baja
  if (!motionConfig.shouldAnimate() || !mounted) {
    return <div>{children}</div>
  }

  return (
    <motion.div
      initial={safeMotion.initial}
      animate={safeMotion.animate}
      exit={safeMotion.exit}
      transition={{
        ...springs.gentle,
        delay,
      }}
      whileHover={{ scale: motionTokens.scale.pop }}
      whileTap={{ scale: motionTokens.scale.press }}
    >
      {children}
    </motion.div>
  )
}

Restricciones / No objetivos

Esta habilidad no cubre:

  • Patrones de componentes de UI (botón, modal, escalonado) → consulta motion-patterns
  • Arrastre, gestos, SVG, animaciones de texto, hooks personalizados → consulta motion-advanced
  • Animaciones solo CSS o clases animate-* de Tailwind sin motion/react
  • Librerías de animación de terceros (GSAP, anime.js, etc.)
  • Decisiones de diseño de movimiento (cuándo animar, qué enfatizar) — eso es una preocupación de diseño, no una restricción de código

Anti-patrones

Anti-patrónRegla violadaSolución
import { motion } from "framer-motion"Regla 1Usa motion/react
initial={{ opacity: 0 }} en componente SSRRegla 2Agrega protección de montaje
Omitir verificación de useReducedMotionRegla 3Usa el hook useSafeMotion
animate={{ width: "100%" }}Regla 4Usa transformación scaleX en su lugar
transition={{ duration: 0.4 }} inlineRegla 5Usa motionTokens.duration.normal
{ stiffness: 300, damping: 30 } inlineRegla 6Usa springs.snappy
Falta la directiva "use client"Regla 7Agrégala al inicio del archivo
navigator.hardwareConcurrency a nivel de móduloRegla 8Envuélvelo en typeof navigator !== "undefined"

Habilidades relacionadas

  • motion-patterns — consume los tokens y resortes definidos aquí para construir patrones de botón, modal, escalonado, transición de página y desplazamiento. No redefine ningún valor.
  • motion-advanced — consume los tokens y resortes definidos aquí para patrones de arrastre, SVG, texto y gestos. Agrega secuencias useAnimate y hooks personalizados sobre esta base.

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

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

Production-ready UI motion system for React/Next.js. Use when implementing animations, transitions, or motion patterns.

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