mathruffian-dot/claude-motion-explainer

Motion design (versión HyperFrames)

Los documentos de HyperFrames te enseñan la API; este archivo gestiona el buen gusto. Los números provienen de una producción real publicada; úsalos como valores predeterminados: puedes desviarte, pero debe ser intencional, no por descuido.

Adaptado del skill motion-design de whaleyxbt/claude-motion (MIT, ver archivo LICENSE en la misma carpeta). La versión original era para Remotion; esta versión está adaptada a HyperFrames (HTML + GSAP) e incluye reglas de tipografía para chino tradicional. Los párrafos marcados con "(nuevo en esta versión)" no pertenecen al contenido original.

División de trabajo con las skills oficiales de HyperFrames (nuevo en esta versión)

Esta máquina también tiene instaladas las skills oficiales de HyperFrames de HeyGen (hyperframes, hyperframes-core, hyperframes-animation, etc.). La división es la siguiente:

• Las skills oficiales gestionan el "cómo hacerlo": estructura del proyecto, atributos data-*, sintaxis de API, enrutamiento de flujo, componentes listos del registry. Si la sintaxis de la API entra en conflicto con este archivo, la oficial tiene prioridad.
• Este archivo gestiona el "buen gusto": easing, ritmo, tiempos de pausa, tipografía, paleta de colores, composición en chino. Cuando uses las reglas/blueprints de hyperframes-animation, los valores de tiempo y easing de este archivo son los predeterminados.
• Revisión: siempre usa review-loop, que ya incluye la verificación oficial hyperframes check.

0. Reglas estrictas de HyperFrames (nuevo en esta versión)

Si no se cumplen, la imagen parpadeará, se desplazará o dará resultados diferentes en cada salida:

• El tiempo lo determina HTML: cada escena es un elemento con class="clip", usando data-start y data-duration para la línea de tiempo. El elemento raíz debe tener data-composition-id y un data-duration explícito.

• Las animaciones son responsabilidad de GSAP: gsap.timeline({ paused: true }), registrada en window.__timelines["<composition-id>"], y la clave debe ser igual a data-composition-id.

• Cada tween importante debe tener una posición explícita (tercer parámetro); cuando ambos extremos son importantes, usa fromTo(), porque la salida se buscará saltando.

• Solo mueve transform y opacity; no manipules repetidamente top/left/width/height.

• Prohibido: CSS transition / @keyframes, Date.now(), requestAnimationFrame, setTimeout, Math.random() sin semilla, recursos que se obtengan durante la salida.

• No uses scripts para reproducir, pausar o buscar en audio/video, ni para mostrar u ocultar clips basados en el tiempo. Todo eso se hace con atributos data. Para mover un video, mueve el elemento contenedor externo.

• Para aleatoriedad, usa siempre una función con semilla:

  function rand(seed) { let t = (seed += 0x6D2B79F5); t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; }
  

1. Tiempo centralizado

• Cada compás es un punto de tiempo con nombre (en segundos), agrupado por escena (s1, s2...), escrito en timeline.js en la raíz del proyecto:

  window.TL = {
    s1: { start: 0, title: 0.3, items: [1.2, 1.45, 1.7], exit: 3.6 },
    s2: { start: 3.4, drawOn: 3.5, hook: 5.2, end: 8 },
  };
  

  En index.html, antes de todos los scripts de composición, carga primero <script src="timeline.js"></script>.

• Los parámetros de posición de GSAP siempre se toman de TL (se permite notación relativa como TL.s1.title, TL.s1.exit + 0.05). No escribas segundos fijos dentro de las escenas.

• Los atributos data-start / data-duration del contenedor de la escena deben coincidir con los límites de la escena en TL. Al re-temporizar, primero modifica timeline.js y luego sincroniza estos dos atributos.

• Los efectos de sonido y la narración se colocan con <audio data-start="…"> en los mismos compases. Los tiempos de captura de review-loop también se toman de TL, por lo que imagen, sonido y revisión se mueven juntos.

• Todas las imágenes están determinadas únicamente por el tiempo; consulta la sección 0.

2. Easing

Las cuatro curvas originales se reconstruyen exactamente en GSAP usando CustomEase. Asegúrate de cargar gsap@3/dist/CustomEase.min.js y registrarlo con gsap.registerPlugin(CustomEase):

CustomEase.create("enter", "0.16,1,0.3,1");   // easeOut
CustomEase.create("exit",  "0.6,0,0.9,0.35"); // easeIn
CustomEase.create("move",  "0.65,0,0.35,1");  // easeInOut
CustomEase.create("land",  "0.55,0,0.2,1.12"); // overshoot

Curva	Uso	Nombre integrado más cercano
enter = bezier(0.16, 1, 0.3, 1)	Entrada, revelación, cualquier "llegada"	expo.out (casi idéntica)
exit = bezier(0.6, 0, 0.9, 0.35)	Salida: rápida, sin titubeos	Aprox. power3.in
move = bezier(0.65, 0, 0.35, 1)	Movimiento entre dos estados (giro, aterrizaje, transformación)	power2.inOut (idéntica)
land = bezier(0.55, 0, 0.2, 1.12)	Valores que "se asientan" (un deslizador que encaja en una posición)	No hay un buen sustituto integrado; usa CustomEase

ease: "none" (lineal) se usa solo para movimiento continuo: rotación, deriva, partículas, segundero.

Para que una animación siga el valor de otra (por ejemplo, subtítulos que siguen la posición de un deslizador), usa el mismo tween para manejar un objeto proxy y deriva en onUpdate; no le des otro reloj independiente.

3. Elasticidad

El original usaba muelles físicos de Remotion; GSAP no tiene física de muelles. La siguiente tabla muestra los valores aproximados elegidos para esta versión (nuevo en esta versión, no son números originales); después de la exportación, usa review-loop para verificar la sensación:

Sensación	Configuración GSAP	Uso
Aterrizaje predeterminado	back.out(1.2), 0.6 s	Entrada de UI general
Pesado, sólido	power3.out, 0.8–1.0 s	Paneles grandes, reversa
Muesca de perilla	back.out(1.7), 0.35 s	Control que salta a una muesca
Pop-up	back.out(2.2), 0.45 s	Etiquetas, insignias, puntos de éxito
Acento elástico	elastic.out(1, 0.4), 0.9 s	Momento culminante, usado solo una vez por video

Los elementos con sensación física (UI, objetos) usan elasticidad; el texto y los movimientos de cámara usan curvas Bezier.

4. Ritmo

• Escalonamiento: palabras en inglés aprox. 0.09 s; caracteres chinos aprox. 0.04–0.05 s, palabras chinas aprox. 0.09 s (la parte del chino es nueva en esta versión); elementos de lista y etiquetas aprox. 0.2–0.25 s; anillos y puntos aprox. 0.06 s.
• Revelación de texto aprox. 0.8 s, usando máscara: contenedor externo con overflow: hidden, contenido interno con yPercent: 100 → 0 más una pequeña rotación (rotation: 3 → 0).
• La salida es aproximadamente la mitad de la entrada (0.35–0.55 s frente a 0.7–1.25 s), usando la curva exit.
• Las escenas deben superponerse: la siguiente escena comienza a dibujarse antes de que la anterior haya salido por completo (por ejemplo, s2.drawOn a los 4.02 s antes de s1.flipEnd a los 4.4 s). Un corte abrupto a espacio en blanco parece que está "cargando".
• Escritura mecánica aprox. 0.035 s por carácter; cuando está inactiva, el cursor parpadea a aprox. 2.4 Hz (usa steps o set en la línea de tiempo, no un temporizador).
• Pausa de lectura: cada estado que deba leerse debe detenerse después de asentarse. Frases cortas al menos 1 s; más de tres palabras, añade aprox. 0.25 s por palabra adicional; en chino, añade aprox. 0.25 s por cada 4 caracteres adicionales (nuevo en esta versión). La oración final debe durar al menos 2 s. La versión original de 22 segundos existe porque la versión de 15 segundos mostraba el texto demasiado rápido: cuando tengas dudas, detente más tiempo y mueve menos.

5. Tipografía

• Máximo tres familias tipográficas: serifa para display, sans-serif para interfaz, monoespaciada (para etiquetas, prompts, números).
  • Inglés (original): Instrument Serif / Inter / JetBrains Mono.
  • Chino tradicional (nuevo en esta versión): Noto Serif TC / Noto Sans TC, con JetBrains Mono para números y etiquetas. Los archivos de fuente se colocan en assets/fonts/ del proyecto y se cargan con @font-face; no dependas de las fuentes del sistema (diferentes en cada computadora).
• El texto display en inglés debe ser grande (aprox. 138 px en un lienzo de 1080 de ancho), con interletraje ajustado (-0.02em) y line-height: 1.
• Texto display en chino (nuevo en esta versión): en un lienzo de 1080 de ancho, aprox. 96–120 px, no más de aprox. 12 caracteres por línea, interletraje 0 a 0.02em (sin interletraje negativo para chino), line-height: 1.15–1.25.
• Por línea, un punto de énfasis: en inglés, una palabra en cursiva con color de acento; en chino, sin cursiva real, usa color de acento y peso negrita para el énfasis (nuevo en esta versión).
• Etiquetas monoespaciadas: mayúsculas, letter-spacing: 0.2–0.24em, color atenuado. Son solo decorativas; la información crucial que el público debe leer debe ser grande.
• Prueba en móvil: a 360 px de ancho (el tamaño real en feeds de redes sociales), el mensaje clave aún debe ser legible. Verifica con una hoja de contactos.

6. Paleta de colores

• (Nuevo en esta versión) Toda la pieza se define con tres colores, como una plantilla de presentación decidida por el usuario: color de fondo bg, color principal fg (texto y líneas), color de acento accent, escritos en theme.json del proyecto y aplicados con el script theme.py del skill motion-explainer (o la versión mejorada con imágenes motion-explainer-images). El color de acento se usa solo para "respuestas, conclusiones, números clave, tarjetas de sección".
• La paleta de colores se define como variables CSS en :root (--bg, --ink, --muted, --accent...); no aparezcan nuevos códigos de color dentro de las escenas.
• Solo hay un color de acento, y tiene significado: el objeto que cambia, la respuesta, el ganador. Si todo es acento, nada lo es.
• Los brillos están impulsados por el estado y no por el tiempo (glow = effort): la luz debe contar la historia.

7. Textura: nada está completamente estático

• Grano de película: superposición de filtro SVG feTurbulence, opacidad aprox. 0.09, cambia la semilla cada dos fotogramas (programado en la línea de tiempo con set, la semilla se calcula a partir del número de fotograma).
• Viñeta + cuadrícula de puntos, que se desplaza unos pocos píxeles por segundo: viñeta con radial-gradient, cuadrícula con un tween lineal que abarca toda la pieza.
• "Temblor de línea" dibujado a mano (feTurbulence + feDisplacementMap, también cambia la semilla cada dos fotogramas): se usa en estados de boceto y baja finalización, se desvanece al mejorar la calidad.
• Los elementos inactivos deben respirar: un reloj en movimiento, un cursor parpadeante, una rotación lenta.

8. Coherencia y transiciones

• Prefiere que los objetos continúen en lugar de cortes bruscos. La barra de prompts, las chispas y el deslizador del original atraviesan las escenas y cambian de función; esa es la diferencia entre "diseñado" y "ensamblado". En HyperFrames, los objetos que cruzan escenas se colocan en la composición raíz, no dentro de una escena.
• Cada transición debe ser provocada por un objeto en pantalla (cinco puntos de resultado se fusionan en uno y luego se convierten en un anillo de luz). No uses transiciones de barrido estándar.
• Usa la velocidad: los rastros de movimiento y las compresiones se derivan de "la diferencia de valores entre este fotograma y el anterior", no los fabriques artificialmente.
• Cada video tiene un momento culminante (anillo de luz + impacto). Construye hasta él, no lo uses demasiado pronto.

9. Anti-patrones

• Todo se desvanece al mismo tiempo, o todo usa la misma duración.
• Usar easing lineal para elementos que arrancan y se detienen.
• Texto que aún se está moviendo cuando debería estar siendo leído.
• Más de un punto focal en un solo fotograma.
• Contenido a menos de aprox. 60 px del borde del lienzo (zona segura), a menos que sea un recorte intencional.
• El primer fotograma está en blanco o negro: en la reproducción automática silenciada de redes sociales, el primer fotograma es la miniatura.
• (Nuevo en esta versión) Controlar la reproducción de audio/video o la visualización de clips en scripts, usar animaciones CSS, usar aleatoriedad sin semilla; ver sección 0.

Flujo de trabajo

1. Primero escribe los compases en timeline.js (un storyboard con números), confirma el ritmo con el usuario antes de comenzar.
2. Usa hyperframes_init de kinocut para crear el proyecto; cada escena es una composición en compositions/, los componentes compartidos y los objetos entre escenas van en index.html.
3. Después de cada modificación significativa, ejecuta el skill review-loop.
4. Maneja el audio solo después de que los tiempos visuales estén bloqueados: efectos de sonido y música con <audio data-start> sincronizados con los compases de TL. El acento y la emoción de la narración en chino deben ser evaluados por el usuario con el oído; no uses ASR ni puntuaciones de similitud como sustituto (nuevo en esta versión).