Communitygithub.com

s2530786-cell/ION-DEX

Crea composiciones de video, animaciones, tarjetas de título, superposiciones, subtítulos, voces en off, visuales reactivas al audio y transiciones de escena en HyperFrames HTML.

¿Qué es ION-DEX?

Este skill empodera a agentes de IA (como Claude Code, Cursor y Codex) para construir flujos completos de producción de video directamente en HTML utilizando el marco HyperFrames. Permite generar composiciones con temporización sincronizada, animaciones con GSAP, contenido visual reactivo al audio (como pulsos o brillos sincronizados con el ritmo), texto a voz y subtítulos automáticos. También soporta anotaciones animadas (resaltados, círculos dibujados a mano, líneas de ráfaga) y transiciones entre escenas (crossfades, wipes, reveals). El skill sigue un proceso paso a paso: primero establece un sistema de diseño basado en un archivo `design.md` o estilos predefinidos, luego expande la solicitud del usuario contra guías de estilo, y finalmente planifica y construye la composición usando un enfoque de "layout antes de animación" para evitar superposiciones accidentales. Está diseñado para cualquier solicitud que involucre contenido de video en HTML, desde simples tarjetas de título hasta piezas complejas de múltiples escenas, y se integra con otros skills de HyperFrames para comandos CLI y preprocesamiento de activos.

Compatible con~Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/s2530786-cell/ION-DEX/tree/HEAD/.cursor/skills/hyperframes

Preguntar en tu IA favorita

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

Documentación

HyperFrames

HTML es la fuente de verdad para el video. Una composición es un archivo HTML con atributos data-* para la temporización, una línea de tiempo de GSAP para la animación y CSS para la apariencia. El marco maneja la visibilidad de los clips, la reproducción de medios y la sincronización de la línea de tiempo.

Enfoque

Descubrimiento (solo solicitudes exploratorias)

Para solicitudes abiertas ("haz un video de lanzamiento de producto", "crea algo para nuestra marca") donde el usuario no se ha comprometido con una dirección, comprende la intención antes de elegir colores:

  • Audiencia — ¿quién ve esto? ¿Desarrolladores? ¿Ejecutivos? ¿Consumidores en general?
  • Plataforma — ¿dónde se reproduce? ¿Redes sociales (15s), héroe del sitio web, demo de producto, interno?
  • Prioridad — ¿qué importa más? ¿Calidad del movimiento? ¿Precisión del contenido? ¿Fidelidad de la marca? ¿Velocidad?
  • Variaciones — ¿el usuario quiere opciones o una sola mejor toma?

Para solicitudes específicas ("agrega una tarjeta de título", "arregla la temporización de la escena 3"), omite el descubrimiento.

Para solicitudes exploratorias, considera ofrecer 2-3 variaciones que difieran significativamente — no solo cambios de color, sino diferentes ritmos, niveles de energía o enfoques estructurales. Una segura/esperada, una ambiciosa. No lo hagas obligatorio — es una herramienta disponible cuando sea apropiado.

Paso 1: Sistema de diseño

Si design.md o DESIGN.md existe en el proyecto, léelo primero (verifica ambas mayúsculas/minúsculas — son archivos diferentes en Linux). Es la fuente de verdad para los colores de la marca, fuentes y restricciones. Usa sus valores exactos — no inventes colores ni sustituyas fuentes. Cualquier formato funciona (frontmatter YAML, prosa, tablas — solo extrae los valores).

Si nombra fuentes que no puedes encontrar localmente (sin un directorio fonts/ con archivos .woff2, no es una fuente incorporada), advierte al usuario antes de escribir HTML: "design.md especifica [nombre de fuente] pero no se encontraron archivos de fuente. Agrega archivos .woff2 a fonts/ o recurriré a [la alternativa incorporada más cercana]".

Si no existe design.md, ofrécele al usuario una opción:

  1. ¿El usuario nombró un estilo o ambiente? → Lee visual-styles.md para los 8 ajustes preestablecidos con nombre. Elige la coincidencia más cercana.
  2. ¿Quieres explorar opciones visualmente? → Ejecuta el selector de diseño: lee references/design-picker.md para el flujo de trabajo completo. Esto muestra una página de selector visual. El usuario configura el ambiente, la paleta, la tipografía y el movimiento en el navegador, luego copia el design.md generado y lo pega de nuevo en la conversación.
  3. ¿Quieres saltar esto e ir rápido? → Pregunta: ambiente, claro u oscuro, ¿colores/fuentes de marca? Luego elige una paleta de house-style.md.

design.md define la marca. No define las reglas de composición de video. Esas provienen de references/video-composition.md y house-style.md. Usa los colores de la marca a una escala apropiada para video — no a la opacidad de una interfaz web.

Paso 2: Expansión de la solicitud

Siempre ejecútalo en cada composición (excepto en piezas de una sola escena y ediciones triviales). Este paso fundamenta la intención del usuario contra design.md y house-style.md y produce un intermedio consistente que todos los agentes posteriores leen de la misma manera.

Lee references/prompt-expansion.md para el proceso completo y el formato de salida.

Paso 3: Planificar

Antes de escribir HTML, piensa a alto nivel:

  1. Qué — ¿qué debería experimentar el espectador? Identifica el arco narrativo, los momentos clave y los latidos emocionales.
  2. Estructura — cuántas composiciones, cuáles son subcomposiciones vs. en línea, qué pistas llevan qué (video, audio, superposiciones, subtítulos).
  3. Ritmo — declara tu ritmo de escena antes de implementar. Qué escenas son golpes rápidos, cuáles son pausas, dónde caen los shaders, dónde alcanza su punto máximo la energía. Nombra el patrón: rápido-rápido-LENTO-rápido-SHADER-pausa. Lee references/beat-direction.md para plantillas de ritmo.
  4. Temporización — qué clips determinan la duración, dónde caen las transiciones, cuál es el ritmo.
  5. Diseño — construye primero el estado final. Consulta "Diseño antes de animación" a continuación.
  6. Animar — luego agrega movimiento usando las reglas a continuación.

Construye lo que se pidió. Una solicitud de "una tarjeta de título" no es una solicitud de "una tarjeta de título + 3 escenas de apoyo + música ambiental + subtítulos". Cada escena, cada elemento, cada interpolación debe ganarse su lugar. Si las escenas o elementos adicionales mejoraran genuinamente la pieza, propónlos — no los agregues.

Para ediciones pequeñas (corregir un color, ajustar la temporización, agregar un elemento), ve directamente a las reglas.

Diseño antes de animación

Posiciona cada elemento donde debería estar en su momento más visible — el fotograma en el que ha entrado completamente, está colocado correctamente y aún no está saliendo. Escribe esto primero como HTML+CSS estático. Sin GSAP todavía.

Por qué esto es importante: Si posicionas elementos en su estado inicial animado (fuera de la pantalla, escalados a 0, opacidad 0) y los interpolas hacia donde crees que deberían aterrizar, estás adivinando el diseño final. Las superposiciones son invisibles hasta que el video se renderiza. Al construir el estado final primero, puedes ver y corregir problemas de diseño antes de agregar cualquier movimiento.

El proceso

  1. Identifica el fotograma principal para cada escena — el momento en que la mayoría de los elementos son visibles simultáneamente. Este es el diseño que construyes.
  2. Escribe CSS estático para ese fotograma. El contenedor .scene-content DEBE llenar la escena completa usando width: 100%; height: 100%; padding: Npx; con display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Usa padding para empujar el contenido hacia adentro — NUNCA uses position: absolute; top: Npx en un contenedor de contenido. Los contenedores de contenido posicionados de forma absoluta se desbordan cuando el contenido es más alto que el espacio restante. Reserva position: absolute solo para elementos decorativos.
  3. Agrega entradas con gsap.from() — anima DESDE fuera de la pantalla/invisible HASTA la posición CSS. La posición CSS es la verdad fundamental; la interpolación describe el viaje para llegar allí. (En subcomposiciones cargadas a través de data-composition-src, prefiere gsap.fromTo() — consulta las reglas de GSAP de carga en references/motion-principles.md.)
  4. Agrega salidas con gsap.to() — anima HASTA fuera de la pantalla/invisible DESDE la posición CSS.

Ejemplo

/* scene-content llena la escena, el padding posiciona el contenido */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* El contenedor llena cualquier tamaño de escena (1920x1080, 1080x1920, etc.).
   El padding posiciona el contenido. Flex + gap maneja el espaciado. */

INCORRECTO — dimensiones codificadas y posicionamiento absoluto:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}
// Paso 3: Animar HACIA esas posiciones
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// Paso 4: Animar SALIENDO de esas posiciones
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

Cuando los elementos comparten espacio a lo largo del tiempo

Si el elemento A sale antes de que el elemento B entre en la misma área, ambos deben tener posiciones CSS correctas para sus respectivos fotogramas principales. El orden de la línea de tiempo garantiza que nunca coexistan visualmente — pero si te saltas el paso de diseño, no detectarás el caso en que se superponen accidentalmente debido a un error de temporización.

Qué cuenta como superposición intencional

Los efectos en capas (brillo detrás del texto, elementos de sombra, patrones de fondo) y los diseños apilados en z (pilas de tarjetas, capas de profundidad) son intencionales. El paso de diseño se trata de detectar superposiciones no intencionales — dos titulares cayendo uno encima del otro, una estadística cubriendo una etiqueta, contenido saliéndose del marco.

Atributos de datos

Todos los clips

AtributoRequeridoValores
idSíIdentificador único
data-startSíSegundos o referencia de ID de clip ("el-1", "intro + 2")
data-durationRequerido para img/div/composicionesSegundos. Video/audio por defecto usa la duración del medio.
data-track-indexSíEntero. Los clips de la misma pista no pueden superponerse.
data-media-startNoDesplazamiento de recorte en la fuente (segundos)
data-volumeNo0-1 (por defecto 1)

data-track-index no afecta la superposición visual — usa CSS z-index.

Clips de composición

AtributoRequeridoValores
data-composition-idSíID de composición único
data-startSíTiempo de inicio (composición raíz: usa "0")
data-durationSíTiene prioridad sobre la duración de la línea de tiempo de GSAP
data-width / data-heightSíDimensiones en píxeles (1920x1080 o 1080x1920)
data-composition-srcNoRuta al archivo HTML externo
data-variable-valuesNoObjeto JSON de anulaciones de variables por instancia en un host de subcomp

En el elemento raíz <html>:

AtributoRequeridoValores
data-composition-variablesNoArreglo JSON de variables declaradas (id/type/label/default) — impulsa la UI de edición de Studio y proporciona valores predeterminados para getVariables()

Estructura de la composición

Las subcomposiciones cargadas a través de data-composition-src usan un contenedor <template>. Las composiciones independientes (el index.html principal) NO usan <template> — colocan el div data-composition-id directamente en <body>. Usar <template> en un archivo independiente oculta todo el contenido del navegador y rompe la representación.

Estructura de subcomposición:

<template id="mi-comp-template">
  <div data-composition-id="mi-comp" data-width="1920" data-height="1080">
    <!-- contenido -->
    <style>
      [data-composition-id="mi-comp"] {
        /* estilos con ámbito */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // interpolaciones...
      window.__timelines["mi-comp"] = tl;
    </script>
  </div>
</template>

Cargar en raíz: <div id="el-1" data-composition-id="mi-comp" data-composition-src="compositions/mi-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

Variables (Composiciones parametrizadas)

Renderiza la misma composición con contenido diferente — título, color del tema, precios, subtítulos — sin editar el HTML fuente.

Patrón de tres pasos:

  1. Declara variables en la raíz <html> de la composición con data-composition-variables. Cada entrada necesita id, type (uno de string, number, color, boolean, enum), label y default. Las entradas de enumeración también necesitan options: [{value, label}, ...].
  2. Lee los valores resueltos dentro del script de la composición con window.__hyperframes.getVariables(). Devuelve el resultado combinado de los valores predeterminados declarados + anulaciones por instancia + anulaciones de CLI.
  3. Anula en el momento de la representación con npx hyperframes render --variables '{...}' (nivel superior) o con data-variable-values='{...}' en el elemento host (por instancia para subcomps).
<!doctype html>
<html
  data-composition-variables='[
  {"id":"titulo","type":"string","label":"Título","default":"Hola"},
  {"id":"tema","type":"enum","label":"Tema","default":"claro","options":[
    {"value":"claro","label":"Claro"},
    {"value":"oscuro","label":"Oscuro"}
  ]}
]'
>
  <body>
    <div data-composition-id="raiz" data-width="1920" data-height="1080">
      <h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { titulo, tema } = window.__hyperframes.getVariables();
        document.getElementById("hero").textContent = titulo;
        document.body.dataset.tema = tema;
      </script>
    </div>
  </body>
</html>
# La vista previa de desarrollo usa los valores predeterminados declarados
npx hyperframes preview

# Renderiza con anulaciones
npx hyperframes render --variables '{"titulo":"Informe Q4","tema":"oscuro"}' --output q4.mp4

# O desde un archivo JSON
npx hyperframes render --variables-file ./vars.json

Valores por instancia de subcomposición: el mismo getVariables() funciona dentro de subcomps cargadas a través de data-composition-src. Cada elemento host pasa sus propios valores:

<div
  data-composition-id="tarjeta-pro"
  data-composition-src="compositions/tarjeta.html"
  data-variable-values='{"titulo":"Pro","precio":"$29"}'
></div>
<div
  data-composition-id="tarjeta-empresa"
  data-composition-src="compositions/tarjeta.html"
  data-variable-values='{"titulo":"Empresa","precio":"$99"}'
></div>

Comportamiento de reproducción de audio

Configura los clips de audio en data-track-index 10 (capa base). La duración por defecto es la duración del archivo. No uses data-duration a menos que quieras truncarlo. El audio se reproduce en el contexto de la composición — un clip de audio en una composición se reproduce cuando esa composición está activa, se detiene cuando no lo está.

AtributoRequeridoValores
data-track-indexSí10 (capa base de audio)
data-volumeNo0-1 (por defecto 1)
data-startSíSegundos
data-durationNoPor defecto: duración del archivo

Reproducción de video

Los clips <video> se reproducen cuando su composición contenedora está activa. Usa las APIs de medios de HyperFrames para una sincronización precisa con la línea de tiempo (lee references/media-apis.md).

Animación de texto

Para solicitudes que involucran resaltar texto (barridos de marcador, círculos dibujados a mano, líneas de ráfaga, garabatos, esbozos), consulta references/text-animation.md para implementaciones.

Flujo de trabajo de edición de Studio

Cuando ajustas piezas existentes en respuesta a la retroalimentación del usuario, sigue el proceso de "Modo Edición" descrito en references/studio-edit-workflow.md.

Transiciones

Usa references/transitions.md para transiciones entre composiciones (crossfades, wipes, reveals, transiciones de shader).

Referencias

Skills relacionados