tellmotion

TellMotion — ideia → tema → animação

Um fluxo repetível, barato em tokens. Funciona para qualquer tópico que caiba em 2D: diagramas, processos, arquiteturas, algoritmos, linhas do tempo, conceitos. (Não para vídeo 3D ou live-action.)

Layout desta skill: themes/ (catálogo theme.json) · tools/ (Node, zero dependências) · assets/base (template Motion Canvas, com receitas de cena) · assets/packs/ (pacotes opcionais de componentes) · scripts/new-project.sh · references/.

1. Briefing (uma rodada, pergunte apenas o que faltar)

Se o usuário já forneceu conteúdo/estrutura, não pergunte novamente. Use AskUserQuestion (máximo 4 perguntas) para o que faltar:

1. Tópico e conteúdo (se ausente: proponha um inventado e diga isso).
2. Duração / ritmo (padrão: ritmo calmo, cenas de 20-60 s) e fps (padrão 30 pré-visualização / 60 renderização).
3. Design — sempre ofereça estas três opções:
   • Modelo: usar um tema do catálogo. Execute node tools/list-themes.mjs (lista compacta) e peça o id; para navegar visualmente execute node tools/build-catalog.mjs <tmpdir> e abra gallery.html (sirva com node tools/serve.mjs <tmpdir>).
   • Design personalizado: escreva 3 propostas contrastantes de theme.json (veja references/theme-format.md), renderize pré-visualizações e deixe o usuário escolher (passo 2).
   • Traga o seu: o usuário fornece cores/marcas próprias ou um arquivo Figma → derive um theme.json a partir disso.
4. Pacotes: infira do tópico, não pergunte a menos que esteja incerto, e adicione apenas o que as cenas personalizadas usarão: cloud (arquiteturas), algorithms (ordenação, árvores), charts (dados), flowchart (processos), timeline (história/roadmaps), code (programação, CLI), typography (introduções, citações, A vs B), science (ciclos, camadas, ondas), math (equações, funções), ui (demonstrações de produto, fluxos de usuário), maps (lugares, jornadas). Combine livremente; references/packs.md lista cada componente.

2. Design personalizado (pule quando um modelo foi escolhido)

1. Escreva 3 propostas como arquivos theme.json em uma pasta temporária (copie o tema mais próximo do catálogo e mude os tokens; famílias diferentes, ex. técnica / lúdica / editorial).
2. node tools/validate.mjs <arquivo> para cada um, depois node tools/build-catalog.mjs <saída> --themes <pasta>.
3. Mostre pré-visualizações: abra <saída>/gallery.html no painel do navegador (serve.mjs) ou envie os SVGs. Aguarde a escolha do usuário.
4. Rota opcional de alta fidelidade com Figma (apenas se o usuário quiser e o conector Figma existir): references/figma.md.
5. Salve o tema escolhido como <projeto>/theme.custom.json (e ofereça contribuí-lo ao catálogo).

3. Storyboard (o usuário aprova antes de qualquer animação)

Reescrever uma animação é caro; reescrever uma lista de cenas não é. Pule esta etapa apenas para uma única cena ou se o usuário pedir.

1. Leia references/storyboard.md e references/recipes.md, depois escreva storyboard.json: uma entrada por cena, com sua receita (ou custom), o que mostra, seus segundos e seu texto real.
2. node tools/storyboard.mjs validate <arquivo>, depois node tools/storyboard.mjs preview <arquivo> --theme <id|arquivo> --out <tmpdir>. Mostre a página com o painel do navegador (serve.mjs) e também liste as cenas no chat.
3. Aguarde a aprovação do usuário. Altere o storyboard, não o código, até que ele concorde. Pare o servidor de pré-visualização depois.

Após a aprovação, trabalhe autonomamente até a entrega.

4. Projeto

bash <skill>/scripts/new-project.sh <nome> --theme <id|caminho.json> [--pack a,b|all] [--demos]

(--demos copia a cena de demonstração de cada pacote: útil para aprender uma API, depois delete as demos.) Execute a partir da pasta que deve conter o projeto. Um projeto por tópico; adicione cenas a ele para novos vídeos. Ele copia o template, aplica o tema (src/theme.ts, src/fonts.ts), instala dependências e registra o projeto em .claude/launch.json. Altere o tema depois: node <skill>/tools/apply-theme.mjs <tema> <projeto> depois npm install.

5. Cenas

node tools/storyboard.mjs generate <arquivo> <projeto> escreve cada cena e src/project.ts. Cenas com receita são finalizadas. Cada cena custom é um placeholder funcional com seu título, legendas e duração: escreva sua animação, mantendo-os. Para essas, leia references/motion-guide.md (API central, receita de layout, armadilhas) e references/packs.md (componentes dos pacotes). Reexecutar generate mantém as cenas que você editou. Regras fixas:

• Uma cena por bloco em src/scenes/, registrada em src/project.ts (+ um arquivo .meta por cena).
• Use prepareScene(view, title); chame enter() primeiro e leave() por último; legendas via sub.say(text).
• Texto ≥ 28 px em 1920x1080; legendas ≤ 85 caracteres; uma cor de categoria por tipo de elemento + legenda em src/config.ts (LEGEND).
• Mostre apenas o necessário por cena; use glow() no elemento ativo e dim() no restante.
• Texto editável, timings e cores como constantes no topo de cada cena (comentário EDITABLE TEXT); velocidade global em PACE.
• Una peças com connect(root, a, b). Requisições e eventos viajam com send(root, arrow.points, {shape: 'dot' | 'diamond', to: piece}), para que a forma os diferencie e a peça reaja ao chegar.
• Nunca codifique cores ou fontes fixas nas cenas: use C, S, FONT, fs() de config.ts para que os temas sejam intercambiáveis.

6. Verificar (barato)

1. npm run typecheck no projeto, depois node tools/storyboard.mjs duration <projeto>: se uma cena estiver longe do plano aprovado, corrija-a ou avise o usuário.
2. preview_start (nome do projeto de .claude/launch.json), resize_window 1700x950, depois clique na linha do tempo e zoom em [215,0,800,330]; agrupe vários cliques+zooms em um browser_batch. scroll right na linha do tempo para alcançar cenas posteriores.
3. Quando terminar: resize_window preset desktop, preview_stop. Não renderize mp4 a menos que pedido.

7. Renderizar (quando solicitado)

npm run render no projeto escreve output/<nome>/<nome>.mp4 e render.json (duração por cena, tamanhos dos arquivos), sem abrir o editor. Opções (após npm run render --):

• --format mp4,webm,gif · --thumb ou --thumb-at <segundos> · --fps <n> · --scale <n>. Codificação WebM é lenta (minutos): solicite apenas quando necessário.
• --aspect 9:16,1:1: encaixa o vídeo dentro com barras no fundo do tema (--pad-color substitui); não re-organiza a cena, então o texto encolhe para cerca de 56%. Avise o usuário.
• --draft: 30 fps com metade do tamanho, em output/<nome>-draft/. Use para revisar.
• --info: duração de cada cena, nada renderizado. Barato: prefira-o a renderizar para verificar o ritmo.
• --dry-run: faixa de tamanho por arquivo a partir de amostras renderizadas, nada salvo. Use antes de uma renderização grande ou quando o usuário se preocupar com o tamanho.

Requer Chrome, Edge ou Chromium (CHROME substitui o caminho). Projetos criados antes deste script existir: node <skill>/tools/render.mjs <projeto>. A fonte é tools/render.mjs.

8. Entregar

Liste cenas (nome → o que mostra), como executar (npm start), como renderizar (npm run render), como alterar ritmo (PACE), textos (constantes por cena), tema (apply-theme.mjs). Indique o que não foi verificado. Se o workspace tiver um CLAUDE.md, adicione o novo projeto a ele.

Economia de tokens

• Não releia arquivos que acabou de escrever; use Edit.
• Use list-themes.mjs em vez de ler arquivos JSON de tema; leia um único tema apenas ao personalizar.
• Agrupe capturas de tela/zooms; evite capturas de página inteira.
• Reutilize assets/ em vez de regenerar componentes.