Communitygithub.com

s2530786-cell/ION-DEX

Crie composições de vídeo, animações, cartelas de título, sobreposições, legendas, narrações, visuais reativos a áudio e transições de cena em HyperFrames HTML.

O que é ION-DEX?

Este skill capacita agentes de IA a construir fluxos de trabalho completos de produção de vídeo usando HTML como fonte da verdade, aproveitando o framework HyperFrames. Ele suporta criação de cenas, legendas sincronizadas, narração por texto-para-fala, animações reativas a áudio (como batidas, brilho e pulsos), realce de texto animado (marcadores, círculos desenhados à mão, linhas de explosão, rabiscos, esboços) e transições entre cenas (crossfades, cortinas, revelações, transições com shaders). A abordagem segue etapas estruturadas: descoberta de intenção, configuração de design system (com base em design.md), expansão de prompt, planejamento (narrativa, estrutura, ritmo, tempo e layout) e, em seguida, animação com GSAP, sempre com a regra de 'Layout antes da Animação' para evitar sobreposições. As plataformas principais incluem HyperFrames e a linha de comando `hyperframes-cli` e `hyperframes-media` para pré-processamento. O skill é aplicável a uma ampla gama de necessidades de conteúdo de vídeo, desde mídias sociais e páginas de herói de sites até demonstrações de produtos e apresentações internas.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

HyperFrames

O HTML é a fonte da verdade para 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, reprodução de mídia e sincronização da timeline.

Abordagem

Descoberta (apenas para solicitações exploratórias)

Para pedidos abertos ("faça um vídeo de lançamento de produto", "crie algo para nossa marca") onde o usuário não se comprometeu com uma direção, entenda a intenção antes de escolher cores:

  • Público — quem assiste isso? Desenvolvedores? Executivos? Consumidores em geral?
  • Plataforma — onde será exibido? Redes sociais (15s), herói do site, demonstração de produto, interno?
  • Prioridade — o que é mais importante? Qualidade do movimento? Precisão do conteúdo? Fidelidade da marca? Velocidade?
  • Variações — o usuário quer opções, ou uma única melhor versão?

Para solicitações específicas ("adicione uma cartela de título", "corrija o tempo na cena 3"), pule a descoberta.

Para solicitações exploratórias, considere oferecer 2-3 variações que diferem de forma significativa — não apenas trocas de cor, mas ritmos diferentes, níveis de energia ou abordagens estruturais. Uma segura/esperada, uma ambiciosa. Não torne isso obrigatório — é uma ferramenta disponível quando apropriado.

Passo 1: Sistema de design

Se design.md ou DESIGN.md existir no projeto, leia-o primeiro (verifique ambas as grafias — são arquivos diferentes no Linux). É a fonte da verdade para cores da marca, fontes e restrições. Use seus valores exatos — não invente cores nem substitua fontes. Qualquer formato funciona (frontmatter YAML, prosa, tabelas — apenas extraia os valores).

Se ele nomear fontes que não podem ser encontradas localmente (nenhum diretório fonts/ com arquivos .woff2, nem uma fonte embutida), avise o usuário antes de escrever HTML: "design.md especifica [nome da fonte] mas nenhum arquivo de fonte encontrado. Adicione arquivos .woff2 em fonts/ ou vou usar [alternativa embutida mais próxima]."

Se nenhum design.md existir, ofereça ao usuário uma escolha:

  1. O usuário nomeou um estilo ou clima? → Leia visual-styles.md para os 8 presets nomeados. Escolha o mais próximo.
  2. Quer navegar por opções visualmente? → Execute o seletor de design: leia references/design-picker.md para o fluxo completo. Isso serve uma página visual de seletor. O usuário configura clima, paleta, tipografia e movimento no navegador, então copia o design.md gerado e cola de volta na conversa.
  3. Quer pular e ir rápido? → Pergunte: clima, claro ou escuro, alguma cor/fonte da marca? Então escolha uma paleta de house-style.md.

design.md define a marca. Não define regras de composição de vídeo. Essas vêm de references/video-composition.md e house-style.md. Use cores da marca em escala apropriada para vídeo — não na opacidade da interface web.

Passo 2: Expansão de prompt

Sempre execute em cada composição (exceto peças de uma única cena e edições triviais). Este passo ancora a intenção do usuário em relação a design.md e house-style.md e produz um intermediário consistente que todo agente downstream lê da mesma forma.

Leia references/prompt-expansion.md para o processo completo e formato de saída.

Passo 3: Planejamento

Antes de escrever HTML, pense em alto nível:

  1. O quê — o que o espectador deve experimentar? Identifique o arco narrativo, momentos-chave e batidas emocionais.
  2. Estrutura — quantas composições, quais são sub-composições vs inline, quais faixas carregam o quê (vídeo, áudio, sobreposições, legendas).
  3. Ritmo — declare seu ritmo de cena antes de implementar. Quais cenas são rápidas, quais são pausadas, onde os shaders aparecem, onde a energia atinge o pico. Nomeie o padrão: rápido-rápido-DEVAGAR-rápido-SHADER-pausa. Leia references/beat-direction.md para modelos de ritmo.
  4. Tempo — quais clipes determinam a duração, onde as transições acontecem, qual é o ritmo.
  5. Layout — construa o estado final primeiro. Veja "Layout antes da Animação" abaixo.
  6. Animar — então adicione movimento usando as regras abaixo.

Construa o que foi pedido. Um pedido de "uma cartela de título" não é um pedido de "uma cartela de título + 3 cenas de apoio + música ambiente + legendas." Cada cena, cada elemento, cada interpolação deve merecer seu lugar. Se cenas ou elementos adicionais melhorariam genuinamente a peça, proponha-os — não os adicione.

Para pequenas edições (corrigir uma cor, ajustar o tempo, adicionar um elemento), vá direto para as regras.

Layout antes da Animação

Posicione cada elemento onde ele deve estar em seu momento mais visível — o quadro onde ele entrou completamente, está corretamente colocado e ainda não está saindo. Escreva isso como HTML+CSS estático primeiro. Sem GSAP ainda.

Por que isso importa: Se você posicionar elementos em seu estado inicial animado (fora da tela, escalados para 0, opacidade 0) e interpolar para onde você acha que eles devem chegar, você está adivinhando o layout final. Sobreposições são invisíveis até o vídeo renderizar. Ao construir o estado final primeiro, você pode ver e corrigir problemas de layout antes de adicionar qualquer movimento.

O processo

  1. 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.
  2. Escreva CSS estático para esse quadro. O contêiner .scene-content DEVE preencher a cena inteira usando width: 100%; height: 100%; padding: Npx; com display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Use padding para empurrar o conteúdo para dentro — NUNCA use position: absolute; top: Npx em um contêiner de conteúdo. Contêineres de conteúdo com posicionamento absoluto transbordam quando o conteúdo é mais alto que o espaço restante. Reserve position: absolute apenas para elementos decorativos.
  3. Adicione entradas com gsap.from() — anime DE fora da tela/invisível PARA a posição CSS. A posição CSS é a verdade absoluta; a interpolação descreve a jornada para chegar lá. (Em sub-composições carregadas via data-composition-src, prefira gsap.fromTo() — veja regras GSAP de suporte de carga em references/motion-principles.md.)
  4. 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 cuidam do 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óis. 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 é para detectar sobreposição não intencional — dois títulos principais caindo um em cima do outro, uma estatística cobrindo um rótulo, conteúdo vazando para fora do quadro.

Atributos de Dados

Todos os Clipes

AtributoObrigatórioValores
idSimIdentificador único
data-startSimSegundos ou referência de ID do clipe ("el-1", "intro + 2")
data-durationObrigatório para img/div/composiçõesSegundos. Vídeo/áudio usa a duração da mídia por padrão.
data-track-indexSimInteiro. Clipes na mesma faixa não podem se sobrepor.
data-media-startNãoDeslocamento de corte na fonte (segundos)
data-volumeNão0-1 (padrão 1)

data-track-index não afeta a camada visual — use CSS z-index.

Clipes de Composição

AtributoObrigatórioValores
data-composition-idSimID único da composição
data-startSimTempo de início (composição raiz: use "0")
data-durationSimTem precedência sobre a duração da timeline GSAP
data-width / data-heightSimDimensões em pixels (1920x1080 ou 1080x1920)
data-composition-srcNãoCaminho para arquivo HTML externo
data-variable-valuesNãoObjeto JSON de substituições de variáveis por instância em um host de sub-comp

No elemento <html> raiz:

AtributoObrigatórioValores
data-composition-variablesNãoArray JSON de variáveis declaradas (id/type/label/default) — impulsiona a UI de edição do Studio e fornece padrões para getVariables()

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 o 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="minha-comp-template">
  <div data-composition-id="minha-comp" data-width="1920" data-height="1080">
    <!-- conteúdo -->
    <style>
      [data-composition-id="minha-comp"] {
        /* estilos com escopo */
      }
    </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 });
      // interpolações...
      window.__timelines["minha-comp"] = tl;
    </script>
  </div>
</template>

Carregar na raiz: <div id="el-1" data-composition-id="minha-comp" data-composition-src="compositions/minha-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

Variáveis (Composições Parametrizadas)

Renderize a mesma composição com conteúdo diferente — título, cor do tema, preços, legendas — sem editar o HTML de origem.

Padrão de três etapas:

  1. Declare variáveis na raiz <html> da composição com data-composition-variables. Cada entrada precisa de id, type (um de string, number, color, boolean, enum), label e default. Entradas enum também precisam de options: [{value, label}, ...].
  2. Leia os valores resolvidos dentro do script da composição com window.__hyperframes.getVariables(). Retorna o resultado mesclado dos padrões declarados + substituições por instância + substituições da CLI.
  3. Substitua no momento da renderização com npx hyperframes render --variables '{...}' (nível superior) ou com data-variable-values='{...}' no elemento host (por instância para sub-comps).
<!doctype html>
<html
  data-composition-variables='[
  {"id":"titulo","type":"string","label":"Título","default":"Olá"},
  {"id":"tema","type":"enum","label":"Tema","default":"claro","options":[
    {"value":"claro","label":"Claro"},
    {"value":"escuro","label":"Escuro"}
  ]}
]'
>
  <body>
    <div data-composition-id="raiz" data-width="1920" data-height="1080">
      <h1 id="heroi" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { titulo, tema } = window.__hyperframes.getVariables();
        document.getElementById("heroi").textContent = titulo;
        document.body.dataset.tema = tema;
      </script>
    </div>
  </body>
</html>
# Pré-visualização de desenvolvimento usa os padrões declarados
npx hyperframes preview

# Renderizar com substituições
npx hyperframes render --variables '{"titulo":"Relatório Q4","tema":"escuro"}' --output q4.mp4

# Ou de um arquivo JSON
npx hyperframes render --variables-file ./vars.json

Valores por instância da sub-composição: o mesmo getVariables() funciona dentro de sub-comps carregadas via data-composition-src. Cada elemento host passa seus próprios valores:

<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-variable-values='{"titulo":"Pro","preco":"$29"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-variable-values='{"titulo":"Enterprise","preco":"$99"}'
></div>

Substituições da CLI têm a maior precedência, depois data-variable-values no host, depois padrões de data-composition-variables.

Sub-composições

Composições dentro de composições. O HTML de cada sub-comp está em seu próprio arquivo (compositions/nome.html), usa o wrapper <template> e exporta uma timeline. A composição raiz (index.html) as carrega como elementos <div> com data-composition-src.

Por que sub-composições: Reutilização (mesmo cartão com dados diferentes), Isolamento (estilos e scripts com escopo), Paralelismo (cada <script src="gsap"> dentro do template cria seu próprio timeline, evitando conflitos de variáveis globais) e Delegação (diferentes agentes podem trabalhar em sub-composições diferentes).

Carga em lote: Para muitas sub-composições, carregue GSAP uma vez na raiz e não dentro de cada template. Isso reduz solicitações HTTP e tamanho total do HTML. A raiz precisa de <script src="gsap.min.js"></script> antes de qualquer div de composição. Os templates de sub-comp omitem o script do GSAP e dependem da instância global da raiz.

Quando Sub-composições vs Inline

  • Inline: Clipes de curta duração (1-4s de duração, especialmente clipes sem script), cenas onde você precisa de transições CSS visíveis entre clipes HTML (sub-comps são carregadas de forma assíncrona e podem não estar disponíveis quando a transição começa) e prototipagem rápida onde mover para um arquivo separado não vale o atrito.
  • Sub-composição: Cenas reutilizáveis entre projetos, cenas com script intenso (manter o script da raiz enxuto), cenas longas (50+ linhas de HTML/CSS), e qualquer cena que se beneficie de escopo isolado ou carregamento paralelo.

Gerenciamento de Clipes e Mídia

Tipos de clipe: <video>, <audio>, <img>, <div> (para animações GSAP), e composições aninhadas.

Clipes não cronometrados: Elementos com data-start mas sem data-duration herdam a duração da composição. Elementos sem data-start ou data-duration são exibidos durante toda a duração da composição. Isso é útil para fundos, decorações persistentes e música que preenche o espaço restante. Faixas de áudio sem duração são tratadas como "loop para preencher seu espaço alocado".

truncado para tradução

Habilidades Relacionadas