berhjoan/motion-graphics

Instalação de plugins: Antes de comandos de configuração ou atualização, siga as regras de execução de plugins quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantenham as instruções de atualização abaixo.

Primeiro, mantenha esta skill atualizada — confirme com o usuário antes de executar: npx hyperframes skills update motion-graphics. Uma operação rápida sem efeito quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio principais das quais ela depende antes de você usá-las.

origem figma: Se o logotipo/ativo/animação para construir vier de uma URL figma.com, execute /figma primeiro — exportação de ativos, tokens de marca e tradução Motion→GSAP se o gráfico for uma importação do Figma Motion — depois construa a partir de sua saída. Não dirija o Figma diretamente via ferramentas MCP brutas: isso pula a sanitização SVG, a proveniência .media/manifest.jsonl e a vinculação var() do token de marca, de modo que uma alteração posterior da marca não pode ser propagada sem uma reimportação completa.

motion-graphics — ponto de entrada

A porta da frente é /hyperframes. Esta skill cria um gráfico em movimento curto, orientado por design, sem narração (o movimento é a mensagem; ~menos de 10s, sem voz-over). Qualquer coisa mais longa, narrada ou com várias cenas — ou qualquer incerteza → leia /hyperframes primeiro: a camada de intenção possui cada decisão de rota.

Este fluxo de trabalho é autônomo por design — no máximo uma pergunta esclarecedora (agents/director.md), depois construa através da verificação sem revisão intermediária. A camada de intenção (/hyperframes → references/intent-interview.md) roteia aqui diretamente sem perguntas de formato de execução; um storyboard e sessão de companhia adicionam pouco a uma peça tão curta. A renderização ainda é controlada pelo usuário: após verificações e snapshots de prova passarem, abra a pré-visualização do Studio e faça a pergunta canônica "renderizar agora ou o que mudar?" de ../hyperframes/references/brief-contract.md. Quando um BRIEF.md existir, leia-o antes da pergunta do diretor.

Um gráfico em movimento curto e orientado por design. Asset-first: decida a estratégia de ativos e obtenha material real antes de projetar o shot, então projete o shot em torno do que você tem, depois componha reutilizando as capacidades do catálogo. Todos os artefatos vão para PROJECT_DIR = videos/<nome-do-projeto>/ (criado na Etapa 0); todos os caminhos abaixo são relativos a ele.

Fase	Execução	Artefato principal	Fluxo detalhado
init	Bash	hyperframes.json	Etapa 0
plan	subagente — decidir busca? + classificar + estratégia de ativos	shot-plan.json (rascunho: categoria, consultas asset_needs, briefing)	agents/director.md (Parte 1)
fonte ◇	Bash — resolver mídia-uso (pular se asset_needs estiver vazio)	assets/ + assets/index.md	phases/source/guide.md
design	subagente — design do shot em torno dos ativos resolvidos	shot-plan.json (final: bloco(s) + layout + movimento + posições)	agents/director.md (Parte 2)
construir	subagente — composição reutilização-primeiro	compositions/index.html	agents/builder.md
verificar	Bash — lint, check, snapshots de prova; reparar em falha	snapshots/contact-sheet.jpg	Etapa 5
aprovar	Abrir a pré-visualização; perguntar renderizar ou mudanças; aguardar a resposta	aprovação explícita de renderização	Etapa 6
renderizar	Bash — hyperframes render (MP4, ou --format webm/mov para sobreposição)	renders/video.mp4 ou sobreposição transparente	Etapa 6

◇ fonte é executada apenas quando a categoria escolhida declara ativos. Categorias puramente de código/texto (ex.: kinetic-type, a maioria charts/stat) têm asset_needs: [] e pulam direto do planejamento para o design.

Categorias — divididas pela decisão de busca

A primeira decisão do plan é: isso precisa de uma busca? Essa bifurcação divide as categorias em dois grupos; então a categoria específica é escolhida — para busca-orientada, pelo tipo de conteúdo que a busca retorna. Cada categoria é um categories/<id>/module.md (suas regras de planejamento + construção); o vocabulário de movimento compartilhado vive em references/motion-vocabulary.md (→ regras/blueprints hyperframes-animation + blocos de registro).

Categorias de formulário — sem busca; o usuário fornece o conteúdo:

Categoria	Intenção	Baseia-se em
kinetic-type	linha / citação / título impactante, texto primeiro-movimento	blocos caption-* + regras de animação
stat	número herói único / contagem-crescente + anel	apple-money-count / rules/{counting-dynamic-scale, stat-bars-and-fills}
charts	barra / linha / pizza / corrida / % a partir de dados	bloco data-chart
logo-reveal	logotipo / selo de marca (logotipo do usuário)	logo-outro / rules/svg-path-draw
lower-thirds	barras de nome / título, chamadas, sobreposições sociais	caption-* + blocos de sobreposição do registro
maps	movimento geográfico — destacar regiões, conectar lugares, zoom em um local (via vetor, ou via mapa base fixo)	família us-map / world-map + bake-basemap.mjs

Categorias orientadas por busca — busque primeiro, depois anime por tipo de conteúdo (o caminho RWA):

Conteúdo retornado	Categoria	Animação
página da web / link	webpage	animação de página / UI (rolagem, revelar, cursor, chamadas)
artigo de notícias	news	revelação de manchete + cartão de fonte + chamadas de fato-chave
tweet	tweet	cartão de tweet animado
imagem / entidade	asset-fusion	a geometria do ativo torna-se o gráfico (fusão diegética RWA)

Ordem de construção: um de cada vez, cobertura-primeiro (rascunho é suficiente). kinetic-type portado do protótipo; o resto segue.

Pré-requisitos

macOS Apple Silicon ou Linux x64. Ferramentas de sistema: brew install node ffmpeg. npx hyperframes doctor uma vez. Renderização GPU macOS: export PRODUCER_BROWSER_GPU_MODE=hardware.

Chaves opcionais (fallbacks locais se não definidas) — necessárias apenas por categorias que obtêm/geram ativos via mídia-uso:

Chave	Usada para	Fallback
GEMINI_API_KEY / GOOGLE_API_KEY	geração de imagem (resolução de mídia-uso)	pular geração / apenas busca
(provedores de busca/scout de ativos)	busca de ativos reais webpage/news/tweet + asset-fusion	categoria degrada para sem ativos

Fluxo

Etapa 0 — Inicializar

O diretório de trabalho (cwd) é a raiz do workspace do agente; escreva todos os artefatos sob PROJECT_DIR = videos/<nome-do-projeto>/. <nome-do-projeto>: use o diretório que o usuário deu, senão um nome curto em kebab-case da intenção (<assunto>-motion). Não o nome base do workspace ou um timestamp.

Apenas quando $PROJECT_DIR/hyperframes.json estiver ausente:

PROJECT_DIR="${MOTION_GRAPHICS_DIR:-videos/<nome-do-projeto>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=motion-graphics

init verifica as skills instaladas em relação às mais recentes no GitHub e atualiza o conjunto global se alguma estiver desatualizada.

Restrições: nunca hyperframes init na raiz do workspace; nunca aninhe outro hyperframes/ dentro de PROJECT_DIR; todo comando Bash (mestre + subagentes) é um subshell (cd "$PROJECT_DIR" && ...) — nunca cd puro.

Etapa 1 — Planejar (subagente: Diretor Parte 1)

Despache um subagente. prompt = agents/director.md completo + ## Contexto do despacho (SKILL_DIR / PROJECT_DIR / a solicitação do usuário / Schema: <SKILL_DIR>/references/shot-plan-ir.md). Ele deve:

1. Decidir: isso precisa de uma busca? (a primeira bifurcação)
   • Não → escolha uma categoria de formulário (kinetic-type / stat / charts / logo-reveal / lower-thirds / maps); o conteúdo é fornecido pelo usuário; asset_needs: [].
   • Sim → emita um plano de busca em asset_needs[] (notícias / web / tweet / imagem; consultas de dois polos). A categoria orientada por busca específica (webpage / news / tweet / asset-fusion) é confirmada pelo tipo de conteúdo retornado na Etapa 2 e finalizada na Etapa 3.
2. Escreva um rascunho shot-plan.json (envelope + categoria de formulário escolhida ou intenção de busca + asset_needs + um briefing de shot de um parágrafo). Esquema: references/shot-plan-ir.md.

Validação: [ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo ausente.

Etapa 2 — Fonte ◇ (Bash: mídia-uso, condicional)

Se shot-plan.json.asset_needs não estiver vazio, resolva ativos (buscar / gerar / buscar → caminhos locais congelados do projeto + registro). Veja phases/source/guide.md (envolve media-use resolve; as categorias orientadas por busca usam a busca de notícias/web/tweet/imagem). Se asset_needs estiver vazio, pule para a Etapa 3.

Degrade graciosamente: se uma busca/provedor estiver indisponível, a categoria cai para sem ativos (anote em context.log).

Etapa 3 — Projetar (subagente: Diretor Parte 2)

Despache um subagente (prompt = agents/director.md Parte 2 + contexto de despacho incluindo o assets/index.md resolvido se a Etapa 2 executou + catalog-map.md). Ele projeta o shot em torno dos ativos disponíveis: escolha o(s) bloco(s) do catálogo + as regras/blueprints hyperframes-animation, o layout, o movimento, as batidas e (para asset-fusion) as element_positions + paleta de conta-gotas. Finaliza shot-plan.json (content.block + content.customize + conteúdo por categoria).

Etapa 4 — Construir (subagente: Construtor, reutilização-primeiro)

Inclua os princípios de movimento compartilhados no contexto de despacho do Construtor. Para charts e stat, inclua também dados em movimento. O Construtor lê esses guias antes de escrever a linha do tempo.

Despache um subagente. prompt = agents/builder.md completo + contexto de despacho (shot-plan.json, catalog-map.md, o module.md da categoria, references/motion-vocabulary.md, references/builder-contract.md). Reutilização-primeiro: npx hyperframes add <bloco> + personalize no local; escreva manualmente apenas lacunas + o recurso de fusão de ativos. Saída compositions/index.html honrando o contrato HF (linha do tempo GSAP pausada em window.__timelines, class="clip" + ids estáveis, tl.seek(0), determinístico).

Etapa 5 — Verificar (Bash → subagente de reparo em caso de falha)

(cd "$PROJECT_DIR" && npx hyperframes check .)
(cd "$PROJECT_DIR" && npx hyperframes snapshot --at <tempos-de-prova>)

Escolha tempos de prova que mostrem o estado de abertura, o movimento característico e a retenção final. Inspecione a folha de contato ou snapshot gerada antes de continuar. Em caso de falha de lint, check ou snapshot, despache o subagente de reparo (agents/finalize.md) para uma passagem de correção no local, depois reexecute o portão com falha. Nunca altere uma duração fixa meramente para esconder um defeito.

Etapa 6 — Aprovar e renderizar (Bash)

Abra o Studio, depois faça uma pergunta: "renderizar agora ou o que mudar?" Após revisões, retorne ao mesmo portão:

(cd "$PROJECT_DIR" && npx hyperframes preview --background)

Renderize apenas após uma resposta explícita de renderização:

(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q high -o ./renders/video.mp4)
# variante de sobreposição transparente: --format webm (ou mov)

Verifique se a saída existe, não está vazia e tem a duração pretendida. A entrega final nomeia o artefato, duração real, composição ou id do frame, tempos de prova e a folha de contato ou snapshot inspecionada. Sinalizadores vivem em /hyperframes-cli → references/preview-render.md.

Tabela de retomada

Estado	Continuar de
sem shot-plan.json	Etapa 1 (planejar)
shot-plan.json tem asset_needs, sem assets/	Etapa 2 (fonte)
shot-plan.json final, sem compositions/index.html	Etapa 3/4 (projetar+construir)
compositions/index.html existe, snapshots de prova ausentes	Etapa 5 (verificar)
verificações e snapshots de prova passam, sem renderização aprovada	Etapa 6 (aprovação)
renderização aprovada existe	verificar saída, depois relatar

Notas de design (mantenedores — a execução não lê isso)

• Racionamento de asset-first

...

[truncado para tradução]