rbrown101010/codex-marketing-skills

HyperFrames

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

Enfoque

Antes de escribir HTML, piensa en un nivel alto:

1. Qué — ¿qué debería experimentar el espectador? Identifica el arco narrativo, los momentos clave y los ritmos emocionales.
2. Estructura — cuántas composiciones, cuáles son sub-composiciones vs. en línea, qué pistas llevan qué (video, audio, superposiciones, subtítulos).
3. Temporización — qué clips determinan la duración, dónde caen las transiciones, cuál es el ritmo.
4. Diseño — construye el estado final primero. Ver "Diseño Antes de la Animación" abajo.
5. Animar — luego añade movimiento usando las reglas de abajo.

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

Puerta de Identidad Visual

Verifica en este orden:

1. ¿Existe DESIGN.md en el proyecto? → Léelo. Usa sus colores exactos, fuentes, reglas de movimiento y restricciones de "Qué NO Hacer".
2. ¿Existe visual-style.md? → Léelo. Aplica su style_prompt_full y campos estructurados. (Nota: visual-style.md es un archivo específico del proyecto. visual-styles.md es la biblioteca de estilos con 8 presets nombrados — archivos diferentes).
3. ¿El usuario nombró un estilo (ej., "Swiss Pulse", "oscuro y técnico", "marca de lujo")? → Lee visual-styles.md para los 8 presets nombrados. Genera un DESIGN.md mínimo con: ## Style Prompt (un párrafo), ## Colors (3-5 valores hex con roles), ## Typography (1-2 familias de fuentes), ## What NOT to Do (3-5 anti-patrones).
4. ¿Ninguno de los anteriores? → Haz 3 preguntas antes de escribir cualquier HTML:
   • ¿Cuál es el estado de ánimo? (explosivo / cinematográfico / fluido / técnico / caótico / cálido)
   • ¿Lienzo claro u oscuro?
   • ¿Algún color, fuente o referencia visual específica de la marca? Luego genera un DESIGN.md mínimo a partir de las respuestas.

Cada composición debe rastrear su paleta y tipografía hasta un DESIGN.md, visual-style.md o dirección explícita del usuario. Si estás usando #333, #3b82f6 o Roboto — te saltaste este paso.

Para valores predeterminados de movimiento, tamaño, patrones de entrada y easing — sigue house-style.md. El estilo de casa maneja CÓMO se mueven las cosas. El DESIGN.md maneja QUÉ aspecto tienen.

Diseño Antes de la Animación

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

Por qué esto importa: Si posicionas elementos en su estado inicial animado (fuera de pantalla, escalados a 0, opacidad 0) y los interpolas hasta 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 añadir cualquier movimiento.

El proceso

1. Identifica el fotograma héroe para cada escena — el momento en que la mayoría de los elementos son simultáneamente visibles. Este es el diseño que construyes.
2. Escribe CSS estático para ese fotograma. El contenedor .scene-content DEBE llenar toda la escena 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 con posición absoluta se desbordan cuando el contenido es más alto que el espacio restante. Reserva position: absolute solo para decorativos.
3. Añade entradas con gsap.from() — anima DESDE fuera de pantalla/invisible HASTA la posición CSS. La posición CSS es la verdad fundamental; la interpolación describe el viaje para llegar allí.
4. Añade salidas con gsap.to() — anima HASTA fuera de 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 FUERA 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 héroe. 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 superpongan 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 sobre otro, una estadística cubriendo una etiqueta, contenido desbordándose del fotograma.

Atributos de Datos

Todos los Clips

Atributo	Obligatorio	Valores
id	Sí	Identificador único
data-start	Sí	Segundos o referencia de ID de clip ("el-1", "intro + 2")
data-duration	Obligatorio para img/div/composiciones	Segundos. Video/audio por defecto usa duración del medio.
data-track-index	Sí	Entero. Los clips de la misma pista no pueden superponerse.
data-media-start	No	Desplazamiento de recorte en la fuente (segundos)
data-volume	No	0-1 (por defecto 1)

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

Clips de Composición

Atributo	Obligatorio	Valores
data-composition-id	Sí	ID único de composición
data-start	Sí	Tiempo de inicio (composición raíz: usa "0")
data-duration	Sí	Tiene prioridad sobre la duración de la línea de tiempo GSAP
data-width / data-height	Sí	Dimensiones en píxeles (1920x1080 o 1080x1920)
data-composition-src	No	Ruta a un archivo HTML externo

Estructura de Composición

Las sub-composiciones cargadas mediante data-composition-src usan un envoltorio <template>. Las composiciones independientes (el archivo 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 renderización.

Estructura de sub-composició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>

Video y Audio

El video debe tener muted playsinline. El audio siempre es un elemento <audio> separado:

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

Contrato de Línea de Tiempo

• Todas las líneas de tiempo comienzan { paused: true } — el reproductor controla la reproducción
• Registra cada línea de tiempo: window.__timelines["<composition-id>"] = tl
• El framework anida automáticamente las sub-líneas de tiempo — NO las añadas manualmente
• La duración proviene de data-duration, no de la longitud de la línea de tiempo GSAP
• Nunca crees interpolaciones vacías para establecer la duración

Reglas (No Negociables)

Determinista: Sin Math.random(), Date.now() o lógica basada en tiempo. Usa un PRNG con semilla si necesitas valores pseudoaleatorios (ej., mulberry32).

GSAP: Solo anima propiedades visuales (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, transformaciones). NO animes visibility, display ni llames a video.play()/audio.play().

Conflictos de animación: Nunca animes la misma propiedad en el mismo elemento desde múltiples líneas de tiempo simultáneamente.

Sin repeat: -1: Las líneas de tiempo con repetición infinita rompen el motor de captura. Calcula el recuento exacto de repeticiones a partir de la duración de la composición: repeat: Math.ceil(duration / cycleDuration) - 1.

Construcción síncrona de líneas de tiempo: Nunca construyas líneas de tiempo dentro de async/await, setTimeout o Promesas. El motor de captura lee window.__timelines de forma síncrona después de cargar la página. Las fuentes están incrustadas por el compilador, por lo que están disponibles de inmediato — no es necesario esperar a que se carguen las fuentes.

Nunca hagas:

1. Olvidar el registro de window.__timelines
2. Usar video para audio — siempre video silenciado + <audio> separado
3. Anidar video dentro de un div temporizado — usa un envoltorio no temporizado
4. Usar data-layer (usa data-track-index) o data-end (usa data-duration)
5. Animar dimensiones de elemento de video — anima un div envoltorio
6. Llamar a play/pause/seek en medios — el framework controla la reproducción
7. Crear un contenedor de nivel superior sin data-composition-id
8. Usar repeat: -1 en cualquier línea de tiempo o interpolación — siempre repeticiones finitas
9. Construir líneas de tiempo de forma asíncrona (dentro de async, setTimeout, Promise)
10. Usar gsap.set() en elementos de clip de escenas posteriores — no existen en el DOM al cargar la página. Usa tl.set(selector, vars, timePosition) dentro de la línea de tiempo en o después del tiempo data-start del clip.
11. Usar <br> en el texto del contenido — salto de línea forzado