ui-motion-reel

UI motion reel

Un reel es una escena HTML renderizada fotograma a fotograma. Cada valor animado (tamaño de forma, radio, color, zoom de cámara, cursor, controles) es un muelle amortiguado simulado una vez al inicio a 8x la velocidad de fotogramas, de modo que cualquier fotograma se puede renderizar de forma independiente y en paralelo. La banda sonora se sintetiza a partir de la misma línea de tiempo, por lo que cada beat, clic y whoosh coincide con la imagen.

Los componentes incluidos:

• assets/engine/reel.js: el motor (muelles, medición, script del cursor, cámara, intercambios de contenido con desenfoque, hover y presión, bucle continuo, contadores de odómetro, el conjunto de iconos).
• assets/engine/score.js: una pista original bucleable (pads, arpegio punteado, bajo, batería, ascensores, campanas) más diseño de sonido de UI (clics, whooshes, escritura, topes, deslizamientos), renderizada con OfflineAudioContext.
• assets/template/index.html: una escena inicial de 24 s con cada tipo de interacción: lista con hover en filas, arrastre de deslizador, alternancia, odómetro, anillo de mantener presionado para confirmar, píldora de éxito, tarjeta de resumen, regreso al bucle.
• scripts/setup.sh: crea la estructura de una carpeta de reel (motor + plantilla + scripts + dependencias de node).
• scripts/render.mjs: imágenes fijas, audio y una renderización paralela en MP4 con la banda sonora multiplexada y normalizada en sonoridad.
• scripts/qa.mjs: hoja de contacto, verificación de empalme de bucle, tiras de transición, sonoridad y espectrograma.
• references/api.md: la referencia completa de configuración Reel.define. Léela antes de escribir una escena.
• references/craft.md: las reglas de movimiento y diseño, y los errores que ya se cometieron y solucionaron. Léelo antes de diseñar estados.
• references/score.md: cómo dar forma a la música y al diseño de sonido, y cómo verificar una mezcla que no puedes escuchar.
• references/examples/stockback.html: el reel original de 60 s y 14 estados del que se extrajo este skill (una app fintech de recibos a acciones). Léelo para obtener ideas de contenido y coreografía más densa. Es anterior a la API del motor, así que copia patrones, no código.

Flujo de trabajo

1. Aprende el producto primero. Lee el sitio o código del producto para conocer su paleta, fuentes, logotipo y los 5-8 momentos que cuentan su historia (la entrada, la "magia", la prueba, el beneficio). Utiliza texto y datos reales cuando sea posible: los números y logotipos reales hacen que el reel sea creíble. Si el usuario solicitó un aspecto específico, eso prevalece sobre el aspecto propio del producto.

2. Guioniza los estados antes de escribir el marcado. Para cada estado, decide su tamaño (ancho, alto, radio), relleno (uno de 3-4 colores de la paleta), zoom de cámara (para que ocupe aproximadamente el 80% de la altura o anchura del fotograma), duración y qué hace el cursor. Apunta a 45-60 s y 10-14 estados para un reel completo, o 20-30 s y 5-7 estados para un teaser. A 120 BPM, un beat dura 0.5 s y un compás 2 s. Haz que la duración de cada estado sea múltiplo de 0.5 s y coloca los momentos importantes en las líneas de compás (múltiplos de 2 s) para que la música pueda acentuarlos. Las duraciones deben sumar exactamente el total.

3. Prepara la estructura. bash ~/.claude/skills/ui-motion-reel/scripts/setup.sh <proyecto>/video, luego edita <proyecto>/video/index.html. Mantén los archivos del motor sin modificar, a menos que el reel necesite una funcionalidad del motor; si es así, cambia la copia en el proyecto y menciónalo.

4. Construye la escena siguiendo references/api.md: un bloque .content por estado (id="c-<id>", data-w/data-h igual al ancho/alto del estado), ids en todo lo que el cursor selecciona o animas, luego Reel.define({...}) con estados, eventos del cursor, canales personalizados (deslizadores, alternancias, pulsaciones, desplazamientos) y funciones update por estado para animaciones internas.

5. Revisa las imágenes fijas con frecuencia y al principio. node render.mjs --stills 0,1.5,4,... luego míralas (genera una hoja de contacto con node qa.mjs --every 2). Verifica cada estado en reposo y algunos fotogramas intermedios de la morph. Renderizar imágenes fijas lleva segundos; una renderización completa lleva aproximadamente un minuto y medio para 60 s con 6 workers.

6. Crea la banda sonora. Establece score (progresión, hits en los estados clave, pausas) y un hook sfx para sonidos específicos de la escena (escritura, topes, contadores, deslizamientos). node render.mjs --audio, luego node qa.mjs y lee la línea de sonoridad y out/qa/spectrum.png (consulta references/score.md: no puedes escuchar, así que juzgas la mezcla por números e imágenes).

7. Renderiza y verifica la calidad. node render.mjs --mp4 --with-audio --out <nombre>.mp4, luego node qa.mjs --transitions --video out/<nombre>.mp4. Confirma que el empalme del bucle es 1.000000, mira transitions.png en busca de morphs grises intermedios o contenido que se salga del marco, y revisa la hoja de contacto una vez más.

8. Entrega el MP4 (y una copia en 720p si la transferencia de archivos pudiera tener problemas con el tamaño), más una breve lista de lo que contiene: estados, interacciones, qué hace la música. Informa al usuario honestamente que verificaste el audio mediante análisis, no con el oído. Ofrece cambiar el tiempo o la temática: una re-renderización es económica.

No negociables (el aspecto)

Estos son los elementos que hacen que se lea como un reel de diseñador en lugar de una plantilla. references/craft.md explica cada uno.

• Una sola forma, nunca cortada. Cada estado es el mismo elemento que cambia de tamaño, radio y relleno; el contenido se intercambia en su interior con un breve desenfoque (el motor lo hace).
• Un cursor provoca cada cambio: un clic, un arrastre o una pulsación prolongada. Ningún estado cambia por sí solo, a menos que sea una respuesta genuina del sistema (una pulsación que se completa).
• Muelles en todas partes; como máximo un pequeño rebasamiento (zeta alrededor de 0.86 para el tamaño, 1.0 para el color y la cámara). Sin easing rebotante.
• La cámara se adapta a cada estado; el último fotograma es igual al primero para que el reel haga bucle.
• Sin tiempo muerto: algo significativo se mueve en cada momento, y el cursor nunca espera más de aproximadamente un segundo.
• Sin explosiones de partículas, resplandores, destellos de lente, degradados en el cromo de la UI o trazos de iconos no coincidentes (usa el conjunto de iconos del motor: una cuadrícula de 24, un trazo de 1.75).
• Una tipografía de UI, opcionalmente con un acento de exhibición (la plantilla combina Geist con Instrument Serif en cursiva). Usa las fuentes del producto cuando las tenga.

Notas de rendimiento

• Un reel de 60 s a 1080p60 son 3600 fotogramas. Con 6 workers se renderiza en aproximadamente 80-90 s en una Mac con chip Apple Silicon.
• Los scripts llaman a process.exit al final porque puppeteer puede mantener Node activo después de terminar el trabajo. Si escribes tus propios scripts, haz lo mismo, o los comandos largos parecerán colgados.
• En redes donde las subidas grandes se agotan, exporta también una copia en 720p: ffmpeg -i reel.mp4 -vf scale=1280:720 -c:v libx264 -crf 25 -c:a aac -b:a 160k reel-720p.mp4 (ffmpeg está en node_modules/@ffmpeg-installer/*/ffmpeg).