Contribuir para o Registro HyperFrames
Guie o usuário desde a ideia até um PR mesclado para um novo bloco ou componente do registro.
Fluxo de Trabalho
1. Clarificar → 2. Estruturar → 3. Construir → 4. Validar → 5. Pré-visualizar → 6. Enviar
Etapa 1: Clarificar
Pergunte o que eles estão construindo. O registro tem dois tipos de itens:
- Bloco (
registry/blocks/, tipohyperframes:block) — uma composição completa e independente com dimensões e duração fixas. Estilos de legenda, efeitos VFX, cartelas de título, vinhetas inferiores. - Componente (
registry/components/, tipohyperframes:component) — um snippet reutilizável sem dimensões ou duração fixas. Efeitos CSS, tratamentos de texto, sobreposições que se adaptam a qualquer tamanho de composição.
Depois, pergunte:
- Descrição em uma frase do efeito
- Referência visual (URL, captura de tela ou descrição)
- Quem usa isso e quando?
Etapa 2: Estruturar
Crie a estrutura do registro:
Para blocos:
registry/blocks/{nome-do-bloco}/
{nome-do-bloco}.html
registry-item.json
Para componentes:
registry/components/{nome-do-componente}/
{nome-do-componente}.html
registry-item.json
Convenção de nomenclatura:
| Nome do item | Prefixo do ID | Exemplos de IDs |
|---|---|---|
cap-hormozi | hz | hz-cg-0, hz-cw-3 |
cap-typewriter | tw | tw-cg-0, tw-ch-0-5 |
vfx-chrome | vc | vc-canvas |
Use um prefixo de 2 a 3 letras. TODOS os IDs de elementos DEVEM usar este prefixo para evitar colisões em subcomposições.
registry-item.json para blocos:
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{nome-do-bloco}",
"type": "hyperframes:block",
"title": "{Título Humano}",
"description": "{uma frase}",
"dimensions": { "width": 1920, "height": 1080 }, // ajuste: 1080x1920 para retrato/redes sociais
"duration": 10, // ajuste para sua composição
"tags": ["{categoria}", "{subcategoria}"],
"files": [
{
"path": "{nome-do-bloco}.html",
"target": "compositions/{nome-do-bloco}.html",
"type": "hyperframes:composition"
}
]
}
registry-item.json para componentes (sem dimensions ou duration):
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{nome-do-componente}",
"type": "hyperframes:component",
"title": "{Título Humano}",
"description": "{uma frase}",
"tags": ["{categoria}"],
"files": [
{
"path": "{nome-do-componente}.html",
"target": "compositions/components/{nome-do-componente}.html",
"type": "hyperframes:snippet"
}
]
}
Etapa 3: Construir
Aplique o modelo correto com base no tipo. Consulte templates.md para iniciadores de copiar e colar.
Blocos de legenda
Regras de legenda não negociáveis:
- Fonte: Mínimo de 96px para fontes proporcionais. 64–72px aceitável para monoespaçadas (caracteres mais largos precisam de menos tamanho).
- Legibilidade:
-webkit-text-stroke: 2-3pxOUtext-shadowem múltiplas camadas - Estouro: chame
window.__hyperframes.fitTextFontSize()em cada grupo - Karaokê: destaque a palavra ativa via
tl.to(wordEl, { color/scale }, WORDS[wi].start) - Parada forçada:
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)em CADA grupo - Nunca use
tl.from(el, { opacity: 0 })na mesma posição detl.set(el, { opacity: 1 })— o from sobrescreve o set. Usetl.to.
Animação por caractere (máquina de escrever, embaralhamento):
- Envolva cada caractere em
<span>com ID{prefixo}-ch-{grupo}-{caractere} - Escalone via
tl.setem intervalos calculados a partir dos timestamps das palavras - Cursores/elementos decorativos: use
tl.setem intervalos — NÃO animação CSS (não buscável)
Variantes de posicionamento:
- Centralizado:
display: flex; align-items: center; justify-content: center; - Terço inferior:
position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center; - Alinhado à esquerda:
position: absolute; bottom: 100px; left: 120px; text-align: left;
Blocos VFX (Three.js)
- Use
[email protected]do CDN (script global) tl.eventCallback("onUpdate", renderScene); renderScene();— NÃO use requestAnimationFrame- Padrão de proxy de estado: GSAP anima um objeto JavaScript simples, a função de renderização o lê
- PRNG com semente (
mulberry32) para aleatoriedade
Todos os tipos
data-composition-idDEVE corresponder awindow.__timelines["id"]- Todos os IDs de elementos prefixados com a abreviação do bloco
gsap.timeline({ paused: true })— sempre pausada- Sem
Math.random(), semDate.now()
Etapa 4: Validar
hyperframes lint # 0 erros obrigatórios
hyperframes validate --no-contrast # 0 erros de console obrigatórios
Etapa 5: Visualizar
# Renderizar vídeo de pré-visualização
hyperframes render -o preview.mp4
# Snapshot para QA visual
hyperframes snapshot --at "1.0,3.0,5.0,7.0"
# Publicar em hyperframes.dev para revisão
npx hyperframes publish
Imagem de pré-visualização do catálogo — O cartão do catálogo usa um PNG em docs/images/catalog/{kind}/{name}.png (onde {kind} é blocks ou components). Gere a partir de um snapshot, então:
- Colaboradores internos da HeyGen: execute
scripts/upload-docs-images.sh(requer perfil AWSengineering-767398024897) - Colaboradores externos: anexe o MP4 de pré-visualização à descrição do seu PR. Um mantenedor gerará e fará o upload da imagem do catálogo antes de mesclar.
Etapa 6: Enviar
Todas as etapas são obrigatórias. A falta de qualquer uma produz uma entrada quebrada no catálogo.
{kind} é blocks ou components dependendo do que você construiu na Etapa 1.
# 1. Criar branch
git checkout -b feat/registry-{nome}
# 2. Formatar HTML
npx oxfmt registry/{kind}/{nome}/*.html
# 3. Atualizar registry/registry.json — adicionar entrada ao array "items":
# { "name": "{nome}", "type": "hyperframes:block" } (ou "hyperframes:component")
# 4. Gerar página de documentação do catálogo
npx tsx scripts/generate-catalog-pages.ts
# 5. Publicar em hyperframes.dev para que revisores possam visualizar
npx hyperframes publish
# 6. Preparar tudo
git add registry/{kind}/{nome}/ registry/registry.json docs/catalog/
# 7. Commitar
git commit -m "feat(registry): adicionar {nome} — {uma frase}"
# 8. Empurrar e abrir PR com link do hyperframes.dev
git push origin feat/registry-{nome}
gh pr create --title "feat(registry): {nome}" --body "preview: {hyperframes.dev-url}"
Se você não tiver uma conta GitHub: você precisa de uma para abrir um PR. Cadastre-se em https://github.com/signup, depois execute gh auth login.
Portão de Qualidade
-
hyperframes lint→ 0 erros -
hyperframes validate→ 0 erros de console -
npx oxfmt --checkpassa -
registry/registry.jsonatualizado com nova entrada -
scripts/generate-catalog-pages.tsexecutado (página de documentação gerada) -
npx hyperframes publishexecutado (reivindique a URL do seu projeto) - MP4 de pré-visualização anexado ao PR (externo) ou PNG do catálogo enviado (interno)
- Todos os IDs únicos e prefixados