mira-animator

name

mira-animator

description

Cria e evolui a animação de um slide como METÁFORA visual animada (o M de MIRA): destila o conceito, acha uma analogia concreta do cotidiano e a anima com loop interno obrigatório, em D3.js v7+ ou CSS 3D, no padrão dos decks de mira-templates/decks/ (glass-card, icon-hero, attribute-pills, replay-btn). Dois modos, CRIAR um slide animado novo e SUBSTITUIR a animação de um slide existente no lugar. Use SEMPRE que o usuário disser "/mira-animator", "criar slide animado", "novo slide com animação", "adicionar card com D3", "anima essa figura", "transforma isso num slide animado", "slide criativo para o deck", "looping na animação", "animação contínua", "metáfora animada", "transforma em metáfora", "cria uma analogia", "vira metáfora", "quero uma metáfora pra esse conceito", "metáfora visual", ou pedir para animar, reanimar ou reexpressar um conceito do deck.

Skill: Metáfora Animada com Looping Interno

MIRA é Metáforas Inteligentes Responsivas Animadas. A metáfora não é um modo especial desta skill, é o produto dela.

REGRA ZERO

METÁFORA PRIMEIRO. ANIMAÇÃO DEPOIS. Diante de qualquer conceito, texto, PDF ou pedido de slide, a primeira pergunta é "qual é a melhor maneira visual de fazer alguém compreender esta ideia?", nunca "como animar isso". A pergunta certa não é "que objeto representa esta palavra?", é "que transformação, comportamento ou situação visual permite compreender este conceito?". A animação é consequência da representação escolhida; escolher elementos gráficos primeiro e tentar dar significado depois é o método invertido.

Toda animação DEVE ser uma metáfora, DEVE ser uma história e DEVE ter loop interno perpétuo.

• Metáfora: analogia concreta do cotidiano, nunca o diagrama do próprio conceito.
• História: começo, transformação e desfecho. Se a cena couber em "o ícone A vira o ícone B" ou "os elementos pulsam", está rasa. Morph, draw e motion path são vocabulário a serviço da história, não a história.
• Loop: entrar com fade-up e parar é proibido. Algo continua em movimento depois da entrada.

Antes de codar você tem que conseguir dizer as três frases. Ex.: "débito técnico é uma torre que ganha um bloco sozinha", "ela inclina até alguém tirar um bloco", "a cada ciclo entra um bloco novo".

Se o deck tem conceito alinhado, ele é REFERÊNCIA

Alguns decks têm uma pasta storyboard/ com concept-brief.md e quadros em approved/. Ela nasce quando o autor pede explicitamente o /mira-concept-align e o /mira-storyboard, porque a ideia estava confusa e ele quis clarear antes de produzir. É fluxo alternativo, não o caminho normal.

Deck sem essa pasta: nada muda. Comportamento de hoje, byte por byte. É a maioria dos decks.

Existindo a pasta, uma obrigação só:

Leia o storyboard/concept-brief.md antes de escrever a animação, e não contrarie o que está lá. A metáfora, os elementos obrigatórios e as interpretações proibidas já foram decididos pelo autor; você implementa, não reinventa. É material de consulta, do mesmo jeito que references/.

Enxergando necessidade de contradizer (a metáfora aprovada não funciona visualmente, um elemento obrigatório não cabe): argumente ao autor, citando a seção do brief. Não decida sozinho, e não obedeça cegamente. A autoridade sobre o significado é dele.

Opcionalmente, e só se ajudar, declare qual quadro o slide realiza:

<!-- @MIRA:CONCEPT quadro="approved/slide-03.svg" intent="a distância para a fonte original aumenta" -->

O marcador não é obrigatório. Ele serve ao npx mira-animator storyboard verify <deck>, que o autor roda quando quiser conferir se a referência chegou nos slides. Nada trava sem ele.

Método obrigatório: A/B, portões, escolha

Rode ANTES de qualquer linha de código, em qualquer modo e template. É proibido implementar a primeira metáfora plausível, e o custo disso é baixo de propósito: um A/B, não um brainstorm.

1. Dinâmica como causa: Quando [causa], [estado] muda de [A] para [B] porque [mecanismo]. Se [falha], [consequência].
2. A/B, duas candidatas e só. A é a que veio à cabeça primeiro, anote sem julgar. B é obrigatoriamente de outra família de domínio (casa, rua, trabalho manual, natureza, corpo, transporte, comércio, jogo): se A é cozinha, B não pode ser restaurante. Proibido pensar em coreografia ou técnica aqui, só sistemas do mundo. É a distância entre as famílias que mata o clichê, não a quantidade de candidatas.
3. Mapeie papel, estado, ação causal e evidência visual de cada uma. ❌ Rejeite quem preserva os substantivos mas troca direção, condição, ordem ou consequência, e quem deixa parte sem correspondente dos dois lados.
4. Contrafactual: a MESMA cena mostra o que acontece se uma parte falha, atrasa ou não age. ❌ Se precisar de outra analogia para mostrar a falha, é rasa.
5. Especificidade. ❌ Se a cena servir sem alteração para três conceitos não relacionados, é decoração.
6. Distância útil. ❌ A associação lexical imediata (orquestração → maestro, fluxo → rio, memória → gaveta) perde o desempate: só vence se a outra falhar num portão duro.
7. História: estado inicial, causa, transformação, consequência, recuperação. ❌ Se só der "A vira B" ou "tudo pulsa", volte ao passo 2.
8. Loop da AÇÃO PRINCIPAL em uma frase. Ambiente, brilho, órbita e pulso não contam. ❌ Sem loop descritível, não serve.

Compare A e B nos portões e implemente quem ganhar. A pode vencer, desde que vença; proibido é implementar A sem olhar para B. Gere uma terceira candidata só se as duas falharem ou empatarem de verdade, de família ainda não usada. Rodada extra por hábito é token à toa.

Se o usuário rejeitar a metáfora entregue, não conserte a animação: a analogia é que está errada. Volte ao passo 2, descarte a família inteira e traga outra. Polir metáfora reprovada é polir o erro.

Exemplo de calibração

Conceito: orquestração de agentes. Candidata A: maestro e naipes pulsando em uníssono. Parece boa, e é fraca: é a associação lexical de "orquestração" (passo 6), mostra sincronia e não integração de entregas parciais (passo 3), nada acontece se um naipe atrasa (passo 4), e "todos pulsam juntos" serve igual para colaboração, consenso ou rede (passo 5).

Candidata B: cozinha profissional com passe de expedição. Comanda = tarefa, estações = agentes, expedidor = orquestrador, componentes do prato = dependências, prato completo = resultado, espaço vazio no prato = falha. História: a comanda entra, cada estação faz sua parte no próprio ritmo, o expedidor monta o prato, vê uma parte faltando, segura a saída, recebe o atrasado e libera. Loop: o prato sai e outra comanda entra. Carrega dependência, atraso e consequência, que a orquestra não carrega.

Isto é padrão de processo, não biblioteca: não reutilize cozinha, comanda ou passe sem justificativa causal própria.

Deck inteiro: método em lote

Escopo de um slide só: rode o método normal. Escopo do deck todo (caso comum do modo SUBSTITUIR sem slide indicado): não repita o método inteiro slide a slide, isso estoura o contexto e o método vira teatro. Faça em duas passadas. O lote muda ONDE cada portão roda, nunca dispensa nenhum.

Passada 1, quadro de metáforas do deck, uma vez só, rodando os passos 1, 2, 3, 5 e 6:

1. Frase causal de cada slide.
2. Com as frases lado a lado, distribua as famílias de domínio entre os slides antes de inventar qualquer cena. O deck não pode morar em duas famílias.
3. A/B de cada slide, compartilhando o pool: candidata já usada em outro slide está queimada, e isso só se vê com o quadro montado.
4. Aplique os portões baratos (mapeamento, especificidade, distância lexical). São eles que ELEGEM a metáfora; escolher antes inverte o método.
5. Feche o quadro: slide, frase causal, metáfora eleita, família, verbo causal, assinatura temporal. O quadro já é o ledger preenchido, planejado em vez de checado depois.

Passada 2, slide a slide, com os passos 4, 7 e 8 sobre a metáfora eleita (contrafactual, história, loop), depois beat sheet, rubrica e código.

Reprovou na passada 2? Use a candidata perdedora do A/B daquele slide, se for de família livre, ou gere uma substituta dentro da família atribuída. O quadro segue válido; só reapresente se a própria família mudar. Acima de 4 slides, apresente o quadro ao usuário antes de codar: vetar ali é barato, depois de implementado é caro.

Refinamento sob demanda

A primeira entrega é sempre a geração normal: A/B, portões, uma metáfora boa por slide, sem exploração extra. A exploração pesada só existe depois, quando o usuário vê o resultado e pede refinamento ("outra metáfora", "menos óbvia", "mais impacto", "simplifica", "troca a ideia").

• Escopo por slide. Refinar o slide 6 não regenera os outros. Slide aprovado fica intacto, e o quadro de metáforas do deck segue válido para ele.
• Trava de exploração liberada, só aqui. No refinamento vale gerar várias candidatas de famílias diferentes, comparar nos portões e buscar mais originalidade ou outra narrativa visual. O limite "A/B e só" é da primeira geração, não do refinamento.
• Ledger e rubrica continuam valendo. A metáfora nova não pode colidir com os vizinhos aprovados, e o corte segue 85 sem veto.
• Rejeição troca a analogia, nunca pole a animação (regra do método: descarte a família e traga outra).

Ledger de diversidade

Antes de aprovar, anote de cada slide animado do mesmo deck: sistema do cotidiano, família de domínio, verbo causal, silhueta dominante, organização espacial, movimento principal e assinatura temporal. Assinaturas possíveis: acumulação com colapso, rajada com pausa, fluxo interrompido, alternância, onda em cascata, perseguição, compressão e liberação.

Rejeite a candidata que: reutiliza sistema do cotidiano de qualquer outro slide; repete a família de um vizinho; coincide com um vizinho em 4 dos 6 eixos (verbo, silhueta, espaço, movimento, tempo, reinício); repete o movimento dominante de um adjacente; ou usa partícula, órbita ou pulso como movimento dominante quando outro slide do deck já usa.

Repetição só vale como motivo narrativo pedido pelo usuário, e aí varia mecanismo, consequência, enquadramento e ritmo. Ao entregar, informe a assinatura: domínio | verbo | silhueta | espaço | movimento | tempo.

Direção de movimento

Temperamento, escolha antes da beat sheet

O temperamento decide quantos beats cabem e que easing vale, então ele vem primeiro. sereno é o padrão. tenso só entra quando o usuário pede tensão na cena (uma torre desabando, um alarme). Pedido implícito não conta.

	sereno (padrão)	natural	tenso
Ciclo do loop	9 a 14 s	7 a 10 s	4,5 a 7 s
Beats	4 a 5	5 a 6	6 a 7
Janela mínima entre eventos focais	1200 ms	800 ms	500 ms
Repouso antes de reiniciar	1,2 a 2,0 s	0,8 a 1,2 s	0,4 a 0,7 s
Atraso causa e efeito	250 a 500 ms	150 a 350 ms	120 a 250 ms
Famílias de easing	sine, power1, power2	power2, power3	power4, expo, back
Atores em movimento simultâneo	1 focal, 1 ambiente	1 focal, 2 apoios	livre
Duração de cue de câmera	1,5 a 2,5 s	1,0 a 1,8 s	0,3 a 0,8 s
Cues de câmera por cena	no máximo 2	no máximo 3	livre

As duas últimas linhas só valem em cena com câmera. Sem câmera, são inertes, não impedimento.

Regra do repouso. Todo ciclo contém pelo menos um trecho de 1 segundo em que nada focal se move. Só ambiente. É a respiração da cena, e é o que separa uma animação de um letreiro luminoso. Some as durações mais o repouso: se não sobrar janela contínua de 1000 ms sem evento focal, tire um beat ou estenda o repouso. Nunca encurte a janela.

O ciclo longo é deliberado. O slide é visto enquanto alguém fala por cima dele. Ciclo longo não cansa, ciclo curto sim. Se 4 beats parecerem pouco para 9 segundos, aumente a duração de cada beat ou resolva o estado vivo por deriva lenta; não acrescente beat.

Declare o temperamento na primeira linha da beat sheet: Temperamento: sereno · ciclo 11 s · 4 beats · repouso 1,6 s.

Beat sheet

Antes de codar, escreva uma beat sheet com acontecimento, ator focal, duração, easing ou física, estado resultante. O número de beats e a duração do ciclo saem da tabela do temperamento escolhido.

1. Uma ação por vez. Em qualquer janela de 500 ms, no máximo um acontecimento focal. O resto apoia.
2. Causa antes do efeito. O efeito começa depois da causa, no atraso da linha "atraso causa e efeito" do temperamento. Mesmo frame vira decoração sincronizada.
3. Antecipação. Preparação curta antes da ação (recuo, compressão, inclinação, pausa), 8% a 15% do tempo dela.
4. Peso. Pesado acelera devagar, arco menor, quase sem overshoot. Leve acelera rápido, admite overshoot e follow-through maior.
5. Easing semântico. Fluxo uniforme linear; queda ease-in; chegada e dissipação ease-out; orgânico sine-in-out. Deslocamento de objeto (ator viajando de A a B) usa por padrão o perfil explode-assenta: miraMotionBlur.explodeAssenta(h, k) do mira/mira-motion-blur.js (instale o helper se o deck não tiver), explosão em velocidade máxima até a metade do tempo e chegada em cauda longa, rastejando. Em sereno, alongue a janela do deslocamento em vez de trocar a curva; pedido do autor veta ou troca. Nunca o mesmo easing em tudo, e sempre dentro da família do temperamento. back, elastic e bounce ficam fora do padrão, liberados só em tenso ou quando a física da metáfora os exigir (uma mola é uma mola, e a beat sheet declara o motivo). São as curvas que produzem overshoot visível, e overshoot repetido faz a cena parecer agitada mesmo quando é lenta.
6. Hierarquia. Um ator primário e no máximo dois movimentos secundários. Durante a ação principal o ambiente perde contraste, amplitude e velocidade.
7. Leitura da consequência. Segure o estado resultante antes de reiniciar, pelo tempo da linha "repouso" do temperamento.
8. Follow-through. Depois de impacto ou parada, partes flexíveis e rastros continuam 150 a 500 ms.
9. Arcos. Objeto transportado, lançado ou articulado não anda em reta sem justificativa mecânica.
10. Loop invisível. Reinicie na saída de quadro, oclusão, retorno natural ou troca de ciclo. Nunca teletransporte o estado inteiro na cara do espectador. Em sereno, a forma preferida do estado vivo é deriva lenta contínua: algo que respira, oscila devagar ou avança de forma quase imperceptível, em vez de repetir visivelmente o gesto focal. Ação focal repetindo a cada 5 segundos é o que mais cansa numa apresentação longa.

Movimento ambiente não é narrativa. Se a beat sheet puder ser trocada por "tudo pulsa", volte à metáfora.

Autoavaliação antes de entregar

Pontue com uma evidência concreta por linha. Polimento não compensa causalidade fraca.

Critério	Peso	Veto
Fidelidade causal. Papéis, direção, condição, ordem e mecanismo correspondem.	25	Só associação temática ou lexical.
Consequência e contrafactual. A causa muda estado visível, e a cena aguenta a falha.	20	Movimento sem mudança de estado.
Ganho pedagógico e especificidade. Ensina o que o título não dá, não serve para conceito alheio.	20	Cena intercambiável.
História e loop. Estado inicial, causa, transformação, consequência e reinício legíveis, corte escondido.	15	Entrada seguida de ambiente.
Direção de movimento. Timing, antecipação, peso, easing, hierarquia e follow-through coerentes.	10	Tudo junto ou mesmo easing em tudo.
Diversidade. Passa no ledger e contrasta com os vizinhos.	10	Repete domínio, silhueta, composição e movimento.

Corte: 85 de 100 e nenhum veto. Abaixo disso, volte ao A/B ou à beat sheet. Não entregue "o que deu para fazer".

A nota é avaliada com o cinema desligado. Câmera, luz, grade de cor e atmosfera entram depois de a cena passar, nunca para fazê-la passar. Se ao desligar os quatro a animação deixa de contar a história, a história não existia.

A nota é sobre o plano, antes de codar. Não invente que assistiu à animação: a conferência no navegador é do usuário. Ao entregar, diga o que ele deve olhar (a história aparece com o título escondido? o corte do loop aparece? o Replay deixa dois atores correndo juntos?).

Os dois modos

Mesma skill nos dois casos, o que muda é onde o resultado pousa.

CRIAR (padrão, etapa 5 do pipeline): slide novo em decks/<tema>/index.html (ou decks/<tema>/index.html, conforme o fluxo). Você monta o card inteiro. Se o deck não existir, crie a partir de um esqueleto de mira-templates/decks/ (mira-default é o padrão; também aula-capitulo, pitch-projeto, demo-tecnica, sandeco-just-animation-template).

SUBSTITUIR (retrofit de palco existente, "transforma esses slides em metáforas", "essa animação está fraca"):

• Troca a animação no lugar: mesmo id de stage (#st-XXXX / #sv-XXXX), mesmo título, subtítulo e pílulas. Só o palco muda, com no máximo um ajuste leve de subtítulo para amarrar a analogia.
• Não reescreve título, pílulas nem cores, não reordena o deck, não cria slide novo.
• Reescreva a função daquele stage no <script>, mantendo trigger e Replay, e reinicie o marcador para <!-- @MIRA:SIZE 3/10 -->.
• Escopo: slide indicado → só aquele. Sem indicação → todos os animados do deck.

Vocabulário de coreografia

Arrumações espaciais que o Mira já sabe montar. São vocabulário de última hora: a beat sheet já decidiu quem age e com que consequência, aqui você só acha a geometria que serve.

Hub-and-spoke, staircase com um ator subindo, duas colunas em confronto com centro que arbitra, flip cards 3D, grade que reage em cascata, trajetória entre nós com carga que viaja.

Não existe mapa conceito para formato. Se pensou "isso é comparação, então battle arena", parou no atalho: volte à beat sheet e pergunte que geometria a HISTÓRIA exige. Se outra metáfora qualquer pudesse ocupar a mesma composição com os mesmos tempos, refaça. Pulso em uníssono, órbita e partícula genérica ficam fora desta lista de propósito, viraram muleta. E nada de "8 cards retangulares enfileirados" (o usuário já reclamou).

Motion blur (efeito de velocidade)

Efeito opcional para DISPAROS: um ator que estava parado cruza o quadro rápido. Nunca é padrão: slide sem disparo não recebe nada, e "sem motion blur" no pedido do autor veta o efeito. Dose: o rastro é o corpo do efeito e cabe em qualquer disparo; o blur é acabamento e só aparece no pico da velocidade.

Helper: mira/mira-motion-blur.js (copie de templates/authoring/ ou de mira-templates/authoring/ se o deck não tiver), com a tag logo após o d3: <script src="mira/mira-motion-blur.js"></script>. A API está documentada no cabeçalho do próprio arquivo. Três regras que não se negociam:

• Força = velocidade normalizada (miraMotionBlur.forca(vel, pico)), com vel por diferença central da função do movimento. Parado, tudo desliga sozinho e o repouso fica limpo.
• Rastro analítico (.eco()): o fantasma k é a posição de onde o ator estava há k*passo ms, tirada da própria função do movimento. Nunca guarde histórico de posições: o regente congela e zera o relógio, e histórico vira lixo na tela.
• Blur direcional: movimento reto usa .filtro() aplicado no grupo rastro + ator, o conjunto borra num risco contínuo. Trajetória curva usa .ator(), que gira o blur para o ângulo do voo, com o rastro fora do rig, nítido.

O perfil de velocidade padrão do disparo é o explode-assenta (miraMotionBlur.explodeAssenta(), regra 5 da beat sheet): normalize a força com o .pico anexado à função (picoMs = ease.pico / duraçãoMs do disparo).

Ícone flat como ator, não bolinha

O círculo (dot, partícula, satélite, anel, pulso radial) é legítimo só para o genuinamente abstrato: fluxo, energia, sinal, conexão, propagação. Para o resto, empobrece.

Com referente concreto, o ator é um ícone reconhecível. Se dá para nomear o objeto (livro, engrenagem, foguete, chave, moeda, funil, bússola), anime o objeto. Vale igual para o que a metáfora trouxe: se a analogia é a despensa, desenhe a despensa.

Flat é o estilo, silhueta cheia, cantos suaves, pouco detalhe, leitura instantânea na projeção. É o oposto do traço fino vazado do Lucide, que fica só na moldura do card.

• Inline como <path> no mesmo <svg> da animação. Dentro do SVG nunca use <i data-lucide>.
• O ícone é o ator do loop: age, sofre a consequência e se recupera dentro da beat sheet. Parado no centro é proibido. Evite resolver o loop com órbita ou pulso, que é a muleta que esta regra veio corrigir.
• Cor da paleta do deck, preenchimento cheio. No deck card laranja/preto, recolore para laranja e neutros. Nunca cor fora do tema num deck card.
• Fonte aberta apenas, licenças MIT, Apache-2.0, CC0 ou CC-BY: Google Material Symbols (eixo fill) ou API do Iconify. Prefira path único, viewBox 0 0 24 24. Embuta inline, o deck roda offline por file://. Atribuição no CREDITS.md se a licença pedir; recuse IP protegida e sugira arte original.
• Slide inteiro de morph de ícones já é o /mira-icon-morph.

Proibido desenhar à mão

Ícone flat resolve objeto. Não resolve o que tem anatomia. Estes referentes nunca viram path escrito por você: figura humana (inteira ou parte), mão, braço, perna, rosto ou feição, animal, veículo, anatomia articulada, objeto de uso cheio de detalhe. Sai trapézio com bola em cima, e já saiu.

Caiu na lista, chame o /mira-asset-scout: ele acha o SVG em fonte aberta e o embute inline, ou pede o arquivo ao autor com plano B. Só volte a desenhar quando ele devolver DESENHAR.

Texto e título

• Idioma: siga agents/_shared/idioma.md. Português brasileiro, acentuação correta, UTF-8 direto, <meta charset="UTF-8">. Nunca Unicode escapes (é) nem entidades (é).
• Proibido travessão (—) em qualquer texto: use vírgula, dois-pontos ou reescreva. Ênfase via <span class="primary-color italic">.