Manual de vídeo animado

Manual de Vídeo

Transforme capturas de tela de um produto em um curto vídeo guiado com legendas: um cursor animado clica nas telas, destaca e amplia para direcionar a atenção, e texto animado explica cada etapa.

O trabalho tem quatro etapas. O usuário decide; você faz a produção.

Etapa	O usuário	Você
1. Projeto do produto	informa para quem é o produto, define cor da marca, modelo de fundo, logotipo, guia de marca	deriva as regras de voz e ajusta a animação
2. Cenas	anexa capturas de tela ou um link do Figma	importa quadros do Figma
3. Rascunho do storyboard	define as telas principais, sua ordem e o texto	elabora um rascunho para o usuário editar
4. Vídeo	assiste, edita texto e ordem, comenta nos quadros	adiciona as ações, verifica cada quadro, revisa com base nos comentários, renderiza

A redação e a ordem são o que mais importa para os usuários, por isso são definidas na etapa 3 antes de qualquer trabalho de produção e permanecem editáveis na etapa 4 até que o MP4 seja renderizado.

Converse com o usuário no idioma dele. Escreva as legendas no idioma da interface do produto, a menos que seja instruído de outra forma.

Duas formas de trabalhar

Com o Studio (padrão). Um aplicativo web local exibe as quatro etapas. O usuário trabalha nele; botões marcados com ✦ colocam solicitações na fila que você pega, atende e responde. Leia references/studio.md antes de iniciá-lo — é o protocolo para esse ciclo.

Apenas na conversa. Quando o usuário prefere não abrir um navegador ou você não pode executar um servidor local, faça as mesmas quatro etapas perguntando e mostrando na conversa. Veja "Sem o Studio" abaixo.

De qualquer forma, os arquivos são idênticos, então um projeto pode transitar entre os dois.

Estrutura do projeto

Tudo fica em video-manual/ no projeto do usuário, para que um perfil atenda a todos os manuais feitos para o produto:

video-manual/
├── product-profile.json     # um por produto: público, voz, animação, fundo
├── brand/                   # guide.md (guia de marca colado), logotipo
├── requests.json            # solicitações enfileiradas do Studio
└── <manual-slug>/           # uma pasta por vídeo, ex.: create-task/
    ├── screens/             # 01-board.png, 02-new-task.png, ...
    ├── storyboard.json      # rascunho primeiro, depois o storyboard completo
    ├── comments.json        # comentários dos quadros do Studio
    └── out/                 # manual.html, manual.mp4, stills/, frames/

Configuração

Os scripts ficam na pasta scripts/ desta habilidade. A renderização precisa das dependências uma vez:

cd <skill-dir>/scripts && npm install

Em seguida, inicie o Studio em segundo plano e forneça ao usuário seu endereço:

node <skill-dir>/scripts/studio.mjs video-manual --open

Diga a eles em uma frase o que acontece a seguir: eles preenchem a etapa 1, e você pegará o que eles enviarem com um botão ✦. Em seguida, aguarde as solicitações conforme descrito em references/studio.md.

Etapa 1 — Projeto do produto

Se video-manual/product-profile.json já tiver um bloco voice, o produto está configurado: use-o como está. A consistência entre os vídeos de um produto é mais importante do que ajustar cada um.

Caso contrário, o usuário preenche o formulário (nome, domínio, B2C/B2B, faixa etária alvo, dispositivo, cor de destaque, modelo de fundo, logotipo opcional e guia de marca) e envia uma solicitação profile. Então:

1. Leia o bloco product e brand/guide.md.
2. Escreva o bloco voice — o registro, finais de frases, maior legenda, palavras a evitar, termos do produto. Leia references/voice-guide.md. O guia de marca do usuário substitui o conselho geral.
3. Ajuste a animação para o mesmo público. Leia references/motion-profiles.md. O usuário escolheu o predefinido e o fundo; você ajusta ritmo, tamanhos e suavização onde o público deles exigir.
4. Adicione uma rationale de uma ou duas frases.

Esses três fatos — faixa etária alvo, domínio, B2C ou B2B — decidem cada legenda. Se o formulário deixar um deles em branco ou as telas o contradisserem, pergunte antes de escrever as regras de voz.

Etapa 2 — Cenas

Uma imagem por estado de tela distinto, em screens/, numerada na ordem de aparecimento. Um estado que muda visivelmente (um modal abre, um menu suspenso se expande, um formulário é preenchido) precisa de sua própria imagem: o vídeo mostra o resultado de um clique cortando para a próxima captura de tela.

O usuário geralmente faz upload delas no Studio. Em uma solicitação scenes com um link do Figma, exporte cada quadro como PNG e registre sua largura lógica para coordWidth; leia também os metadados das camadas — limites exatos dos elementos são muito mais confiáveis do que estimar a partir de pixels.

Se faltar um estado que o passo a passo precise, diga qual é e peça, em vez de pular a etapa. Um salto que o espectador não consegue seguir anula o propósito de um manual.

Etapa 3 — Rascunho do storyboard

Em uma solicitação draft, leia cada tela e o perfil, depois escreva o rascunho em storyboard.json: as cenas em ordem, cada uma com sua caption e uma note descrevendo o que acontece nela. Ainda sem ações. Leia references/manual-script.md para saber como definir o escopo do vídeo e escrever o texto, e escreva cada linha na voz do perfil.

O usuário edita o rascunho no Studio e pressiona "Solicitar o vídeo" quando a redação e a ordem estiverem corretas. Essa solicitação produce é a aprovação. Não adicione ações antes dela chegar.

Etapa 4 — Vídeo

Produzir

Leia references/storyboard-schema.md e transforme o rascunho aprovado no storyboard completo: siga a note de cada cena, adicione as ações, defina coordWidth. As legendas permanecem exatamente como aprovadas.

As coordenadas são a parte com maior probabilidade de erro. Use limites exatos quando os tiver (metadados do Figma, rects do DOM). Quando você tiver apenas a imagem, observe atentamente e estime; a verificação abaixo existe para pegar o que você errar.

Verificar antes de o usuário ver

Construa, depois renderize stills — um quadro a cada clique, mudança de texto e legenda, e no final de cada cena:

node <skill-dir>/scripts/build.mjs video-manual/<slug>/storyboard.json
node <skill-dir>/scripts/render.mjs video-manual/<slug>/out/manual.html --stills video-manual/<slug>/out/stills

build.mjs valida o storyboard, verifica cada legenda em relação às regras de voz do perfil e imprime o tempo de cada cena. Corrija os erros. Para avisos de voz sobre texto escrito pelo usuário, mantenha a redação dele e mencione o aviso em sua resposta.

Leia os stills e verifique cada um:

• A ponta do cursor está no elemento que a legenda nomeia?
• O anel de destaque envolve o elemento inteiro e nada mais?
• Após um zoom, o alvo está totalmente visível e legível?
• O texto digitado está dentro do campo e cobre o placeholder?
• Cada legenda está totalmente visível, no máximo em duas linhas?
• Cada chamada aponta para o elemento certo sem cobri-lo ou cobrir o cursor?

Corrija o storyboard, reconstrua e renderize novamente até que cada quadro passe, então responda à solicitação. Um cursor que clica ao lado do botão faz todo o manual parecer errado, então o usuário nunca deve ser o primeiro a encontrar isso.

Ciclo de revisão

Na etapa 4 do Studio, o usuário pode:

• editar qualquer legenda, título ou texto na tela e reordenar cenas — salvo diretamente em storyboard.json, sem solicitação envolvida;
• pausar em um quadro, fixar uma posição e escrever um comentário, depois enviar os comentários como uma solicitação revise.

Lide com revise conforme descrito em references/studio.md: renderize o quadro comentado para ver o que eles viram, mude apenas o que o comentário trata, confirme em um novo quadro que está corrigido e responda a cada comentário. Depois que eles reordenarem as cenas, verifique se cada clique ainda leva à tela que o segue; uma corrente quebrada é algo para informar, não para reparar silenciosamente.

Este ciclo se repete até que fiquem satisfeitos.

Renderizar

O usuário exporta o MP4 do Studio com um botão. Para renderizar você mesmo:

node <skill-dir>/scripts/render.mjs video-manual/<slug>/out/manual.html --out video-manual/<slug>/out/manual.mp4

A renderização leva aproximadamente o mesmo tempo que o próprio vídeo, às vezes duas ou três vezes mais em uma máquina mais lenta; execute-a em segundo plano para manuais com mais de um minuto. Informe o caminho de saída, duração e tamanho do arquivo.

Sem o Studio

Faça as mesmas quatro etapas na conversa:

1. Projeto — deduza a faixa etária alvo, domínio e B2C/B2B das telas e do texto da interface, declare sua leitura e peça ao usuário para confirmar em uma pergunta. Depois escreva o perfil inteiro você mesmo, incluindo predefinição, destaque e fundo.
2. Cenas — copie as imagens que o usuário fornecer para screens/, ou capture-as você mesmo se tiver um navegador ou ferramenta Figma.
3. Rascunho — escreva o rascunho do storyboard, mostre-o como uma tabela (etapa, tela, o que acontece, legenda, texto na tela) com a duração estimada, e aguarde a aprovação. Se eles disseram de antemão para ir direto, prossiga e diga onde está o rascunho.
4. Vídeo — produza e verifique como acima, depois diga a eles onde está out/manual.html. Essa página independente reproduz o vídeo e tem seu próprio painel para editar texto e ordem; "Baixar edições" fornece um storyboard.edited.json que eles podem devolver. Quando o fizerem, liste o que mudou para que eles possam confirmar que você leu como eles pretendiam, salve como storyboard.json, reconstrua e re-verifique os stills. Depois renderize.

Alterações posteriores

• Redação ou ordem: o usuário edita no Studio, ou informa você.
• Voz ("muito formal", "nossos usuários são mais velhos que isso"): altere o bloco voice do perfil, depois reescreva as legendas para corresponder.
• Sensação ("muito lento", "muito saltitante"): altere os tokens de animação no perfil, não cenas individuais — veja a tabela de ajustes em references/motion-profiles.md.
• Uma etapa parece errada: corrija as ações dessa cena e re-verifique seus stills.

Reconstrua e re-verifique os stills após qualquer alteração antes de renderizar novamente.

Limites

Diga claramente quando uma solicitação encontrar um destes:

• As telas são imagens estáticas. Rolagem, estados de hover e animação no aplicativo não são reproduzidos; mostre-os como capturas de tela separadas.
• Sem narração ou música. Legendas e texto na tela carregam a explicação.
• O Studio edita texto e ordem das cenas. O que uma etapa clica ou destaca muda por meio de um comentário para você.
• A saída é 16:9 por padrão. Defina meta.width e meta.height no storyboard para outros formatos.

Solução de problemas

• playwright-core is not installed: execute npm install na pasta de scripts.
• no browser found: instale o Google Chrome ou execute npx playwright install chromium na pasta de scripts.
• ffmpeg not found: instale o ffmpeg ou defina FFMPEG_PATH. npm install normalmente fornece um através de ffmpeg-static.
• Uma solicitação permanece "aguardando" no Studio: ninguém está executando studio.mjs wait. Execute-o, ou studio.mjs pending.
• A etapa 4 mostra erros em vez do vídeo: uma cena aponta para uma imagem ausente ou tem uma coordenada fora de sua tela. build.mjs nomeia a cena.
• Uma fonte parece errada: o vídeo usa fontes instaladas na máquina. Defina font.family no perfil para uma que esteja instalada.