HyperFrames
O HTML é a fonte da verdade para o vídeo. Uma composição é um arquivo HTML com atributos data-* para temporização, uma timeline GSAP para animação e CSS para aparência. O framework gerencia a visibilidade dos clipes, a reprodução de mídia e a sincronização da timeline.
Abordagem
Antes de escrever HTML, pense em um nível alto:
- O quê — o que o espectador deve experimentar? Identifique o arco narrativo, os momentos-chave e os batimentos emocionais.
- Estrutura — quantas composições, quais são sub-composições vs. inline, quais faixas carregam o quê (vídeo, áudio, sobreposições, legendas).
- Temporização — quais clipes determinam a duração, onde as transições ocorrem, qual é o ritmo.
- Layout — construa o estado final primeiro. Veja "Layout Antes da Animação" abaixo.
- Animar — depois, adicione movimento usando as regras abaixo.
Para pequenas edições (corrigir uma cor, ajustar o tempo, adicionar um elemento), vá direto para as regras.
Portão de Identidade Visual
Verifique nesta ordem:
- DESIGN.md existe no projeto? → Leia. Use suas cores, fontes, regras de movimento e restrições "O que NÃO Fazer" exatas.
- visual-style.md existe? → Leia. Aplique seu
style_prompt_fulle campos estruturados. (Nota:visual-style.mdé um arquivo específico do projeto.visual-styles.mdé a biblioteca de estilos com 8 predefinições nomeadas — arquivos diferentes.) - O usuário nomeou um estilo (ex.: "Pulso Suíço", "escuro e tecnológico", "marca de luxo")? → Leia visual-styles.md para as 8 predefinições nomeadas. Gere um DESIGN.md mínimo com:
## Prompt de Estilo(um parágrafo),## Cores(3-5 valores hex com funções),## Tipografia(1-2 famílias de fontes),## O que NÃO Fazer(3-5 antipadrões). - Nada disso? → Faça 3 perguntas antes de escrever qualquer HTML:
- Qual é o clima? (explosivo / cinematográfico / fluido / técnico / caótico / acolhedor)
- Tela clara ou escura?
- Alguma cor de marca, fonte ou referência visual específica? Em seguida, gere um DESIGN.md mínimo a partir das respostas.
Cada composição deve rastrear sua paleta e tipografia de volta a um DESIGN.md, visual-style.md ou direção explícita do usuário. Se você está recorrendo a #333, #3b82f6 ou Roboto — você pulou esta etapa.
Para padrões de movimento, dimensionamento, padrões de entrada e easing — siga house-style.md. O estilo da casa lida com COMO as coisas se movem. O DESIGN.md lida com a APARÊNCIA das coisas.
Layout Antes da Animação
Posicione cada elemento onde ele deve estar em seu momento mais visível — o quadro em que está totalmente inserido, corretamente posicionado e ainda não saindo. Escreva isso como HTML+CSS estático primeiro. Ainda sem GSAP.
Por que isso importa: Se você posicionar elementos no estado inicial animado (fora da tela, escalados para 0, opacidade 0) e os animar para onde acha que devem terminar, você está adivinhando o layout final. Sobreposições são invisíveis até o vídeo ser renderizado. Ao construir o estado final primeiro, você pode ver e corrigir problemas de layout antes de adicionar qualquer movimento.
O processo
- Identifique o quadro herói para cada cena — o momento em que o maior número de elementos está simultaneamente visível. Este é o layout que você constrói.
- Escreva CSS estático para esse quadro. O contêiner
.scene-contentDEVE preencher a cena inteira usandowidth: 100%; height: 100%; padding: Npx;comdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Use padding para empurrar o conteúdo para dentro — NUNCA useposition: absolute; top: Npxem um contêiner de conteúdo. Contêineres de conteúdo posicionados absolutamente transbordam quando o conteúdo é mais alto que o espaço restante. Reserveposition: absoluteapenas para elementos decorativos. - Adicione entradas com
gsap.from()— anime DE fora da tela/invisível PARA a posição CSS. A posição CSS é a verdade absoluta; o tween descreve a jornada para chegar lá. - Adicione saídas com
gsap.to()— anime PARA fora da tela/invisível DA posição CSS.
Exemplo
/* scene-content preenche a cena, padding posiciona o conteúdo */
.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;
}
/* O contêiner preenche qualquer tamanho de cena (1920x1080, 1080x1920, etc.).
O Padding posiciona o conteúdo. Flex + gap lidam com o espaçamento. */
ERRADO — dimensões fixas e posicionamento absoluto:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Passo 3: Anime PARA essas posições
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);
// Passo 4: Anime PARA FORA dessas posições
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);
Quando elementos compartilham espaço ao longo do tempo
Se o elemento A sai antes do elemento B entrar na mesma área, ambos devem ter posições CSS corretas para seus respectivos quadros herói. A ordenação da timeline garante que eles nunca coexistam visualmente — mas se você pular a etapa de layout, não perceberá o caso em que eles acidentalmente se sobrepõem devido a um erro de temporização.
O que conta como sobreposição intencional
Efeitos em camadas (brilho atrás do texto, elementos de sombra, padrões de fundo) e designs empilhados em z (pilhas de cartões, camadas de profundidade) são intencionais. A etapa de layout é sobre capturar sobreposições não intencionais — dois títulos caindo um em cima do outro, uma estatística cobrindo um rótulo, conteúdo sangrando para fora do quadro.
Atributos de Dados
Todos os Clipes
| Atributo | Obrigatório | Valores |
|---|---|---|
id | Sim | Identificador único |
data-start | Sim | Segundos ou referência de ID do clipe ("el-1", "intro + 2") |
data-duration | Obrigatório para img/div/composições | Segundos. Vídeo/áudio padrão é a duração da mídia. |
data-track-index | Sim | Inteiro. Clipes da mesma faixa não podem se sobrepor. |
data-media-start | Não | Deslocamento de corte na origem (segundos) |
data-volume | Não | 0-1 (padrão 1) |
data-track-index não afeta a camada visual — use CSS z-index.
Clipes de Composição
| Atributo | Obrigatório | Valores |
|---|---|---|
data-composition-id | Sim | ID único da composição |
data-start | Sim | Tempo de início (composição raiz: use "0") |
data-duration | Sim | Tem precedência sobre a duração da timeline GSAP |
data-width / data-height | Sim | Dimensões em pixels (1920x1080 ou 1080x1920) |
data-composition-src | Não | Caminho para arquivo HTML externo |
Estrutura da Composição
Sub-composições carregadas via data-composition-src usam um invólucro <template>. Composições independentes (o index.html principal) NÃO usam <template> — elas colocam a div data-composition-id diretamente no <body>. Usar <template> em um arquivo independente esconde todo o conteúdo do navegador e quebra a renderização.
Estrutura da sub-composição:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- conteúdo -->
<style>
[data-composition-id="my-comp"] {
/* estilos escopados */
}
</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 });
// tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
Carregue na raiz: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Vídeo e Áudio
O vídeo deve ser muted playsinline. O áudio é sempre um 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 da Timeline
- Todas as timelines começam
{ paused: true }— o player controla a reprodução - Registre cada timeline:
window.__timelines["<composition-id>"] = tl - O framework aninha automaticamente as sub-timelines — NÃO as adicione manualmente
- A duração vem de
data-duration, não do comprimento da timeline GSAP - Nunca crie tweens vazios para definir a duração
Regras (Não Negociáveis)
Determinístico: Sem Math.random(), Date.now() ou lógica baseada em tempo. Use um PRNG com semente se precisar de valores pseudo-aleatórios (ex.: mulberry32).
GSAP: Anime apenas propriedades visuais (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, transformações). NÃO anime visibility, display ou chame video.play()/audio.play().
Conflitos de animação: Nunca anime a mesma propriedade no mesmo elemento a partir de múltiplas timelines simultaneamente.
Sem repeat: -1: Timelines com repetição infinita quebram o mecanismo de captura. Calcule a contagem exata de repetições a partir da duração da composição: repeat: Math.ceil(duration / cycleDuration) - 1.
Construção síncrona da timeline: Nunca construa timelines dentro de async/await, setTimeout ou Promises. O mecanismo de captura lê window.__timelines de forma síncrona após o carregamento da página. As fontes são incorporadas pelo compilador, então estão disponíveis imediatamente — não há necessidade de esperar pelo carregamento da fonte.
Nunca faça:
- Esquecer o registro de
window.__timelines - Usar vídeo para áudio — sempre vídeo mudo +
<audio>separado - Aninhar vídeo dentro de uma div temporizada — use um invólucro não temporizado
- Usar
data-layer(usedata-track-index) oudata-end(usedata-duration) - Animar dimensões do elemento de vídeo — anime uma div invólucro
- Chamar play/pause/seek na mídia — o framework controla a reprodução
- Criar um contêiner de nível superior sem
data-composition-id - Usar
repeat: -1em qualquer timeline ou tween — sempre repetições finitas - Construir timelines de forma assíncrona (dentro de
async,setTimeout,Promise) - Usar
gsap.set()em elementos de clipe de cenas posteriores — eles não existem no DOM no carregamento da página. Em vez disso, usetl.set(selector, vars, timePosition)dentro da timeline no momento ou após o tempodata-startdo clipe. - Usar
<br>em texto de conteúdo — quebras de linha forçadas não consideram a largura real da fonte renderizada. Texto que quebra naturalmente + um<br>produz uma quebra extra indesejada, causando sobreposição. Deixe o texto quebrar viamax-widthcomo alternativa. Exceção: títulos de exibição curtos onde cada palavra está deliberadamente em sua própria linha (ex.: "THE\nIMMORTAL\nGAME" a 130px).
Transições de Cena (Não Negociáveis)
Cada composição com várias cenas DEVE seguir TODAS estas regras. Violar qualquer uma delas resulta em uma composição quebrada.
- SEMPRE use transições entre as cenas. Sem cortes secos. Sem exceções.
- SEMPRE use animações de entrada em cada cena. Cada elemento anima ENTRANDO via
gsap.from(). Nenhum elemento pode aparecer totalmente formado. Se uma cena tem 5 elementos, ela precisa de 5 tweens de entrada. - NUNCA use animações de saída exceto na cena final. Isso significa: NENHUM
gsap.to()que anima opacidade para 0, y para fora da tela, escala para 0, ou qualquer outra animação de "saída" antes de uma transição ser acionada. A transição É a saída. O conteúdo da cena de saída DEVE estar totalmente visível no momento em que a transição começa. - Cena final apenas: A última cena pode esmaecer elementos (ex.: fade para preto). Esta é a ÚNICA cena onde
gsap.to(..., { opacity: 0 })é permitido.
ERRADO — animação de saída antes da transição:
// PROIBIDO — isso esvazia a cena antes que a transição possa usá-la
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// a transição é acionada em um quadro vazio
CERTO — apenas entrada, a transição lida com a saída:
// Animações de entrada da Cena 1
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// NENHUM tween de saída — a transição em 7.2s lida com a mudança de cena
// Animações de entrada da Cena 2
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
Guardrails de Animação
- Desloque a primeira animação em 0.1-0.3s (não t=0)
- Varie os eases entre os tweens de entrada — use pelo menos 3 eases diferentes por cena
- Não repita um padrão de entrada dentro de uma cena
- Evite gradientes lineares em tela cheia em fundos escuros (bandamento H.264 — use radial ou sólido + brilho localizado)
- Títulos de 60px+, corpo de 20px+, rótulos de dados de 16px+ para vídeo renderizado
font-variant-numeric: tabular-numsem colunas de números
Quando nenhum visual-style.md ou direção de animação for fornecida, siga house-style.md para padrões estéticos.
Tipografia e Ativos
- Fontes: Basta escrever a
font-familyque deseja no CSS — o compilador incorpora as fontes suportadas automaticamente. Se uma fonte não for suportada, o compilador avisa. - Adicione
crossorigin="anonymous"à mídia externa - Para...