hup-dev/promo-animation-skill

Animação de Produto

Você está produzindo uma animação MP4 finalizada para o produto da base de código atual. A skill é um motor de animação determinístico + metodologia, não um formato fixo — você decide o padrão que se encaixa no que o usuário pediu (demo estilo chat, introdução de marca, revelação de estatística, passeio de workflow, antes/depois, etc.).

O que permanece constante em todos os padrões:

• Ativos reais da marca extraídos do repositório (logo SVG, tokens de design, fontes).
• Polimento visual nível Linear/Vercel/Stripe (sombras suaves, tipografia real, momento heroico único).
• Linha do tempo determinística __setTime(t) para que o Playwright capture quadros perfeitos a cada renderização.
• Conteúdo específico e nomeado sempre que a animação fizer uma afirmação — sem cópia genérica do tipo "IA economiza dinheiro".

A referência completa do que faz isso funcionar é methodology.md — leia-a antes de fazer qualquer outra coisa. Detalhes concretos sobre estilo visual, temporização, matemática de câmera, flags do ffmpeg e as 10 armadilhas que pegam iniciantes.

Alvo de saída

Padrão: 1920×1080 @ 30fps, H.264 com música opcional + fade de 1s no final. A duração depende do padrão:

• Introdução de marca / revelação de logo: 5–8s
• Revelação de estatística: 6–10s
• Promo de produto (estilo chat ou outro): 15–22s
• Passeio de workflow: 20–40s

Confirme a duração e proporção com o usuário se ele não especificou. Use como padrão 16:9 1920×1080 a menos que tenha pedido redes sociais/vertical.

Quando dois cortes fizerem sentido (ex.: câmera estática + câmera cinematográfica), entregue ambos.

Verificação pré-voo

Antes de fazer qualquer coisa, confirme que o ambiente pode fazer isso:

which ffmpeg && ffmpeg -version | head -1
which node && node --version
ls ~/Library/Caches/ms-playwright/ 2>/dev/null | head -3   # cache playwright macOS

Se o chromium do Playwright não estiver em cache, execute npx playwright install chromium. ffmpeg é obrigatório.

Crie o espaço de trabalho:

mkdir -p product-animation/frames
cd product-animation

O pipeline de 4 fases

Execute as fases 1–3 em paralelo como subagentes (trabalho independente) antes de iniciar a fase 4.

Fase 1 — Descoberta de marca e ativos (subagente)

Spawne o extrator de marca com o prompt em agents/01-brand-extractor.md. Passe para ele:

• O caminho raiz do repositório
• Algumas dicas sobre o que o produto faz

Ele retorna um JSON com: caminho real do logo SVG, tokens hex exatos, pilha de fontes, convenções de UI heroicas (border-radius, padding, estilo do botão primário), nome do produto + slogan.

Copie o wordmark SVG real para o espaço de trabalho (ex.: <produto>-wordmark.svg). Ativos de marca inline, sem rasters.

Fase 2 — Conceito + roteiro (subagente)

Spawne o escritor de roteiro com o prompt em agents/02-script-writer.md. Passe para ele o resumo da marca da fase 1, o que o produto faz e que tipo de animação o usuário pediu (promo, introdução de marca, revelação de estatística, etc.).

Ele retorna:

• Padrão de animação escolhido para este produto (ex.: "chat-demo", "stat-reveal", "brand-intro")
• Storyboard com temporizações de cena: abertura fria → conteúdo principal → encerramento
• O texto/números/visuais exatos a destacar em cada cena

Se o padrão for chat-demo, o template em templates/chat-demo.html é um ponto de partida completo e funcional — preencha a estrutura de dados CASES.BIGGEST com o conteúdo do roteiro. Para outros padrões, construa o HTML do zero usando o motor de animação descrito em methodology.md § 2 — mesmo driver __setTime(t), mesmo kit de ferramentas de easing, mesma captura Playwright.

Fase 3 — Pesquisa de conteúdo (subagente)

Spawne o pesquisador de casos com o prompt em agents/03-case-researcher.md. Passe para ele o domínio do produto e o padrão de animação.

O que ele retorna depende do padrão:

• Demo de chat / promo: UM antes/depois canônico, nomeado e dramático com números reais (o "momento Converse Chuck Taylor" do domínio) + 3-4 casos secundários.
• Revelação de estatística: UMA métrica pública grande que o produto pode legitimamente possuir, com citação.
• Introdução de marca / revelação de logo: a manchete real da empresa, número real de clientes, história de lançamento real — qualquer coisa verificável para colocar na tela.
• Passeio de workflow: a jornada de usuário real mais comum, etapas nomeadas do próprio produto.

Específico, nomeado, verificável sempre que a animação fizer uma afirmação.

Fase 4 — Construção e renderização

Combine as saídas no template HTML escolhido (ou em um que você escreveu do zero), renderize quadros com Playwright, codifique com ffmpeg.

Fase de construção

A construção difere ligeiramente por padrão. A forma compartilhada:

1. Copie ou escreva o HTML da animação.

   • Se o escritor de roteiro escolheu chat-demo, copie templates/chat-demo.html para o espaço de trabalho e edite o objeto de dados CASES.BIGGEST com o conteúdo do roteiro da fase 2 + pesquisa da fase 3. Também troque os :root { --tokens } da marca, texto do cabeçalho ("Atlas Trade", "Intelligence", badge), barra de URL, <img src> do wordmark, e slogan + CTA do encerramento do logo.
   • Para outros padrões (introdução de marca, revelação de estatística, passeio, antes/depois), escreva o HTML do zero usando o motor de animação — methodology.md § 2 mostra o padrão de linha do tempo determinística. Reutilize as regras de design de reference/design-rules.md, a matemática de câmera de reference/camera-modes.md, e o mesmo contrato de renderização Playwright.

2. Copie um script de renderização. Para chat-demo use templates/render-chat-demo.js (525 quadros, ~17,5s) ou render-chat-demo-zoom.js (585 quadros, ~19,5s, câmera cinematográfica). Para padrões personalizados, copie um dos scripts de renderização e atualize a constante DURATION — o resto funciona como está.

3. Verifique no navegador primeiro. Abra o HTML diretamente — a animação toca automaticamente em loop. Dê uma olhada em cada cena. 5 minutos no navegador economizam 3 minutos de renderização por iteração.

4. Renderização de teste — 6 a 8 quadros-chave nos limites das cenas antes de se comprometer com a renderização completa. Veja scripts/smoke.js para o padrão. Detecta sobreposição de layout, fallback de fonte, elementos fora da tela em 30s.

Fase de renderização

Instale o Playwright no espaço de trabalho:

npm install [email protected] --no-save --no-audit --no-fund --silent

Renderize os quadros:

node render-<padrão>.js          # escreve frames/f_*.png  (~3-5 quadros por segundo de duração × FPS)

Codifique com ffmpeg. Ajuste -t para a duração da sua animação e afade=t=out:st=X para posicionar o fade 1s antes do final:

ffmpeg -y -framerate 30 -i frames/f_%05d.png \
  -i /caminho/para/musica.mp3 \
  -c:v libx264 -pix_fmt yuv420p -crf 18 -preset medium -movflags +faststart \
  -c:a aac -b:a 192k -af "afade=t=out:st=<DURACAO-1>:d=1.0" \
  -t <DURACAO> -shortest animation.mp4

yuv420p é obrigatório para reprodução em Slack/LinkedIn/Twitter. +faststart permite streaming. crf 18 é quase visualmente sem perdas.

Se nenhum áudio for fornecido, remova -i music.mp3, -c:a aac -b:a 192k, e as flags -af. scripts/encode.sh encapsula isso com padrões sensatos.

Portão de qualidade — leia antes de declarar concluído

Universal (todo padrão):

• Wordmark de marca real inline (SVG <img>, não Inter Tight bold estilizado como logo).
• Todas as cores são dos tokens do produto — nunca hex inventado.
• Animação referenciada a partir da base de código — sua UI, fontes, expressões idiomáticas reconhecíveis.
• Momento heroico único. Um número, uma revelação, um CTA — não 12 pontos focais concorrentes.
• Qualquer número que incrementa usa tabular-nums (não tremer horizontalmente).
• Animações aterrissam — nenhum elemento aparece no exato instante em que outro desaparece; respeite as janelas de entrada/saída.
• Logo segura tempo suficiente no final (≥ 3s para encerramentos com marca).
• MP4 reproduz no QuickTime, exatamente a resolução alvo × fps, tamanho de arquivo razoável (1–6 MB típico).
• Abra o MP4 com open <nome>.mp4 para o usuário.

Para chat-demo especificamente, verificações adicionais (veja reference/design-rules.md):

• Número $ herói é JetBrains Mono / peso 800 / 6 dígitos ou mais.
• Cadeia de ferramentas tem ~8 chips, ritmo ~3s — qualquer coisa mais curta parece falsa.
• Balão de usuário aparece DEPOIS da barra limpar, nunca simultaneamente.
• Balão de pensamento desliza para cima e para fora antes do resultado aparecer — nunca ambos opacos.
• Cursor só aparece durante a digitação, nunca no placeholder.

Limpe antes de declarar concluído:

rm -rf frames frames-zoom node_modules package.json package-lock.json smoke_*.png

O espaço de trabalho final deve conter: o HTML, script(s) de renderização, wordmark SVG e o(s) MP4(s) finalizado(s).

Mapa de arquivos

~/.claude/skills/promo-animation/
├── SKILL.md                  ← você está aqui
├── methodology.md            ← referência aprofundada, LEIA PRIMEIRO — o motor de animação universal
├── agents/
│   ├── 01-brand-extractor.md   ← prompt do subagente da fase 1
│   ├── 02-script-writer.md     ← prompt do subagente da fase 2
│   └── 03-case-researcher.md   ← prompt do subagente da fase 3
├── templates/
│   ├── chat-demo.html              ← padrão chat-demo canônico (exemplo funcional)
│   ├── render-chat-demo.js         ← renderizador Playwright modo estático
│   ├── render-chat-demo-zoom.js    ← renderizador modo zoom
│   └── atlas-wordmark.svg          ← SVG placeholder
├── scripts/
│   ├── smoke.js                ← teste de fumaça de quadro-chave
│   └── encode.sh               ← encapsulador ffmpeg
└── reference/
    ├── design-rules.md         ← regras visuais condensadas
    ├── camera-modes.md         ← decisão estático vs zoom
    └── timing-blueprint.md     ← temporizações de cena

Em caso de dúvida, leia templates/chat-demo.html — é um exemplo funcional completo que você pode renderizar agora (um cenário fictício de reclassificação "Atlas Trade" / Converse Chuck Taylor). É a referência canônica para o padrão chat-demo E o motor de animação determinístico — toda regra visual, decisão de temporização e armadilha em methodology.md está codificada naquele arquivo.

Para outros padrões de animação, você escreve o HTML do zero — mas o motor de animação (§ 2 do methodology.md), o contrato de renderização (§ 5) e as regras de design (reference/design-rules.md) todos se aplicam inalterados.