HyperFrames Keyframes (Quadros-chave)
Quadros-chave são um contrato de pose: estados visíveis, identidade contínua do sujeito, execução segura para busca, pixels verificados.
Use hyperframes-animation para receitas de cena amplas.
Use hyperframes-cli para documentação completa de comandos.
Use references/keyframe-patterns.md apenas ao escolher mecanismos de implementação, não estilo visual.
Procedimento
- Identifique o sujeito animado, estados visíveis, estado final e tempo de execução.
- Escolha o menor mecanismo que comprove a instrução. Leia
references/keyframe-patterns.mdapenas se o mecanismo não estiver claro. - Crie quadros-chave seguros para busca no tempo de execução declarado. Construa de forma síncrona e registre a instância de tempo de execução.
- Verifique com lint, validate,
hyperframes keyframes, um--shotfocado e snapshots nos momentos de prova. - Se a prova falhar, corrija os quadros-chave de origem e reexecute o menor diagnóstico de falha antes de renderizar.
Contrato
- Nomeie o sujeito em movimento.
- Nomeie as poses necessárias para provar o movimento pretendido, incluindo o estado final.
- Aplique quadros-chave em canais visíveis, não em estado oculto auxiliar.
- Preserve a identidade do objeto quando a continuidade for importante.
- Faça crossfade apenas quando o movimento pretendido for substituição ou dissolução.
- Mantenha estados legíveis ou semânticos por tempo suficiente para serem vistos.
- O quadro final faz parte da animação, não é uma limpeza.
- Não retorne ao estado de repouso a menos que solicitado.
- Não termine em preto a menos que solicitado.
- Ao editar uma cena inicial, preserve layout, texto, assets, cores e estado final, a menos que seja solicitado um redesign.
Regras de Tempo de Execução
GSAP:
- construa de forma síncrona no carregamento da página
- use
gsap.timeline({ paused: true }) - registre como
window.__timelines[compositionId] - a chave do registro deve corresponder a
data-composition-id - não chame
tl.play()para movimentos críticos de renderização - mantenha repetições finitas
CSS keyframes:
- duração e contagem de iterações finitas
- atraso determinístico
animation-fill-mode: both- use
data-startquando o tempo pertencer a um clipe
Anime.js:
- crie de forma síncrona
autoplay: false- duração e loops finitos
- envie cada instância para
window.__hfAnime
WAAPI:
durationfinitofill: "both"- construção determinística
- a superfície de texto não lista WAAPI; verifique com
--shot(ele busca WAAPI) e snapshots
Nunca use para movimentos críticos de renderização:
Date.now()performance.now()Math.random()sem semente- gatilhos de hover/scroll
- timers
- timelines criadas de forma assíncrona
requestAnimationFramenão registrado- loops infinitos
Esqueleto GSAP
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
Use labels para estados semânticos.
Use parâmetros de posição em vez de atrasos encadeados.
Use immediateRender: false para tweens from()/fromTo() posteriores que toquem a mesma propriedade.
Formas de Quadros-chave
- Array de quadros-chave: escada de poses com duração/ease por etapa.
- Quadros-chave percentuais: tempo exato dentro de um tween.
- Arrays de propriedades: mudanças compactas de múltiplas paradas.
ease: "none"no pai quando cada parada carrega sua própria easing.easeEachquando cada segmento deve compartilhar a mesma sensação.
Não copie distâncias numéricas ou tempos de exemplos. Derive-os da geometria real da composição e duração.
Para um sujeito se movendo entre duas caixas, prefira um tween contínuo de transformação ou FLIP. Divida x/y/scale em vários quadros-chave com easing apenas quando o espectador deve sentir batidas distintas; cada segmento altera a velocidade e pode ser lido como um soluço.
Canais
Prefira canais do compositor/visuais:
x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, máscaras, variáveis CSS, valores de caminho/dash SVG, transformações de câmera, uniforms de shader.
Evite canais de layout/ciclo de vida:
top/left/right/bottom, width/height, margin/padding, display, visibility, criação tardia de DOM, overlays auxiliares fazendo movimento de sujeito.
Escolha do Mecanismo
Escolha o menor mecanismo que comprove a instrução:
| Necessidade | Mecanismo |
|---|---|
| Mesmo sujeito muda de caixa ou hierarquia | elemento compartilhado / FLIP |
| Sujeito percorre uma rota visível | viagem por caminho |
| Traço cresce ou traça | desenho de traço |
| Forma se torna outra forma | interpolação de forma |
| Fronteira de revelação é visível | clip, máscara, ou uniforme de shader |
| Muitos itens se movem com ordem | stagger / atraso indexado |
| O próprio texto se move | subdivisão de linha, palavra, caractere ou banda |
| Superfície dobra, estica ou corta | contra-transformada pai/filho |
| UI tem estados | máquina de estados explícita |
| Cena tem profundidade | DOM 3D, Three.js, ou quadros-chave de câmera/objeto WebGL |
Mecanismos podem combinar, mas cada um deve esclarecer a ideia. Decoração não é prova.
Tempo
- Antecipação apenas quando esclarece causa ou direção.
- Aceleração deixa o repouso.
- Pico de prova mostra o mecanismo inconfundivelmente.
- Acompanhamento vende energia e direção.
- Ultrapassagem apenas quando o sujeito deve parecer elástico ou tátil.
- Viagem em caminho a velocidade constante geralmente precisa de
ease: "none". - Estados discretos de UI geralmente precisam de um ease-out brusco.
- Elementos repetidos precisam de deslocamentos ordenados, não tempos idênticos.
- Travamentos finais precisam de retenções mais longas do que as poses de transição.
- Suavidade significa velocidade contínua no mesmo sujeito.
- Não sobreponha tweens que escrevem a mesma propriedade de transform, a menos que a sobreposição seja intencional e verificada.
- Evite animar grandes mudanças de
clip-path/máscara enquanto a mesma superfície hero também está escalando ou viajando; use revelações aninhadas após o movimento principal se estabilizar.
Texto
Preserve caixas de linha, espaçamento entre palavras, legibilidade e ajuste final. Se o texto se move internamente, mova os glifos ou bandas mascaradas, não apenas decorações ao redor do texto. Tire snapshot de quadros legíveis.
SVG
Para crescimento de traço, prefira DrawSVGPlugin, depois stroke-dasharray/stroke-dashoffset.
Para interpolação de forma, prefira MorphSVGPlugin; converta primitivas em caminhos quando necessário e divida silhuetas complexas em partes mais simples.
3D
Escala sozinha é profundidade falsa.
Use perspectiva em um pai estável, transform-style: preserve-3d, viagem em z, rotação, movimento de câmera/mundo, oclusão e ordem de camadas quando objetos se cruzam.
Use um ou dois ângulos de diagnóstico que exponham a relação de profundidade. Se a prova angulada não mostrar cruzamento de profundidade, melhore z/câmera/oclusão.
Canvas / WebGL
Aplique quadros-chave em posição da câmera, alvo da câmera, transformação do objeto, opacidade do material, uniforms de shader e intensidade de pós-processamento através de estado determinístico. Renderize a partir do tempo HyperFrames. Use --ghost porque caixas marcadoras não podem ver movimento interno do canvas.
Prova CLI
npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<arquivo>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<arquivo>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<arquivo>" --ghost --angle <ângulo>
npx hyperframes snapshot . --at <tempos>
Escolha <selector> para o sujeito animado real.
Escolha <tempos> para o primeiro quadro, poses de prova, final-menos-retenção, e final exato.
Escolha <ângulo> apenas quando a profundidade precisar ser provada.
| Ferramenta | Comprova |
|---|---|
keyframes | alvos, paradas explícitas, caminhos, traços, movimento composto pai/filho, paradas CSS, registro Anime |
--shot | fantasmas, forma da rota, espaçamento temporal, projeção DOM 3D, prova de seletor focado |
--layout strip | movimento no lugar, sobreposições, contato, escala/opacidade sutis, ondas de texto |
--ghost | canvas, WebGL, movimento de shader, 3D renderizado |
snapshot --at | máscaras, legibilidade de texto, estado completo, travamento final, caudas pretas/reset |
Se a prova do seletor parecer errada:
- reexecute
--json - encontre o destino animado real
- filme esse destino
- tire snapshot de quadros completos
- confie nos pixels pintados em vez de logs
Leitura de Diagnóstico
flat significa sem poses intermediárias explícitas. keyframes significa que existem paradas explícitas. motionPath significa que existe uma rota. trace significa desenho multitraço. composed with significa que o movimento filho herda o movimento pai.
Espaçamento uniforme de fantasmas significa velocidade constante. Fantasmas agrupados significam desaceleração ou estabilização. Grandes lacunas significam viagem rápida.
Um tiro de seletor auxiliar não é prova. Um tiro cebola sobre um quadro completo quebrado não é prova.
Tratamento de Erros
| Falha | Correção |
|---|---|
| apenas ponto final | adicione poses intermediárias, segure o pico de prova, reexecute --shot |
| quebra de identidade | mantenha um elemento vivo, use caixas de origem/destino compartilhadas, remova crossfade substituto |
| 3D falso | adicione viagem em z/câmera, oclusão, prova angulada |
| final errado | adicione retenção final, tire snapshot do final-menos-retenção e do final exato |
| tempo de execução não buscável | pause autoplay, registre a instância, remova timers, construa de forma síncrona |
| texto ilegível | preserve caixas de linha, reduza deslocamento, adicione retenção final, tire snapshot dos quadros de texto |
Pronto
Execute lint, validate, keyframes, um --shot focado e snapshots. Confirme o primeiro quadro, poses de prova, final-menos-retenção, final exato, movimento de propriedade do sujeito e sem overlays de debug.