Animação de Mecanismo (mechanism-animation)
Transforme "como funciona" em uma animação passo a passo em uma página: o leitor rola e avança um passo, cada passo conta apenas uma coisa, e os elementos na imagem aparecem, movem-se e desaparecem um por um em ordem causal.
Referência do produto final: assets/template.html, um modelo com um pequeno exemplo de 4 passos (sem cache → adicionar uma camada de cache), que pode ser aberto diretamente no navegador.
0. Primeiro, Decida: Devo Fazer uma Animação?
Comece pela abordagem mais barata e vá subindo. Se a etapa anterior for suficiente para explicar, não avance:
| Nível | O que usar | Quando é suficiente |
|---|---|---|
| 1 | Escrever diretamente | Duas ou três frases são suficientes para explicar |
| 2 | Passos numerados (1. 2. 3.) | É um processo, mas cada passo é uma frase, e o leitor não precisa "ver" |
| 3 | Passos numerados + 2–3 imagens estáticas (antes/depois) | Estrutura, relações; ou um processo que pode ser entendido com duas ou três imagens fixas |
| 4 | Esta skill: Animação passo a passo | Explica para onde algo vai, a ordem, quem compartilha os mesmos dados, qual etapa foi pulada; três imagens fixas ainda não são suficientes |
Regra de ouro: Se a imagem for congelada em qualquer quadro e o leitor ainda entender, uma imagem estática é suficiente; se for preciso ver o movimento para entender, faça a animação.
Duas barreiras:
- Custo. A animação é várias vezes mais cara que imagens estáticas (verificar fatos, organizar a sequência, ajustar o tempo, testar, refazer). Quando ninguém pedir explicitamente uma animação, primeiro sugira, explique por que os três níveis anteriores não são suficientes, e só comece após a concordância; não comece por padrão.
- A animação serve apenas para "entender pela primeira vez", não como material de consulta: não pode ser escaneada, não pode ser pesquisada, e não cabe em um documento. Portanto, o final da página deve ter uma "visão geral de todo o processo" (o modelo gera automaticamente: uma linha por passo); o documento original deve manter a versão em texto, com um link para a página de animação, e não substituir o documento pela animação.
1. Fluxo de Trabalho
- Verificar os fatos. A animação tornará os erros muito vívidos. Antes de desenhar, verifique o mecanismo a ser explicado em relação ao código / documento de design / artigo, e distinga entre "o design diz isso", "o código atualmente faz isso", "outros (artigo, valores padrão) fazem isso". Se não tiver certeza, escreva "inferido, aguardando teste".
- Escreva o storyboard (sem escrever código). Siga
references/storyboard.mdpara criar uma tabela: uma linha por passo, descrevendo claramente o que este passo conta, o que aparece / se move em sequência na tela, o que resta no final e a frase à esquerda. Só comece a desenhar depois que o storyboard passar pelas regras de apresentação da Seção 2 abaixo. Se houver muitos passos (> 6) ou se não tiver certeza sobre a apresentação, primeiro discuta com a pessoa que solicitou: envie apenas a tabela com uma pergunta que ele precisa responder, não um documento completo; se a pessoa estiver acostumada a ver o resultado final, vá direto para a implementação. - Comece a partir do modelo:
cp assets/template.html <diretório_de_saída>/<nome>.html. Só altere três lugares:- O
<title>no HTML, a página inicial (#top), oaria-labelda imagem e a página final (#where, incluindo o rodapé com "Atualizado em: mês/ano · versão verificada") — essas partes no modelo ainda são conteúdo de exemplo, substitua uma por uma; - Seção A do script:
PAGE,MODULES(módulos, passos, texto, duração de cada passo); - Seção C do script: cena (quais objetos, como cada passo se move).
As seções B1/B2 são o mecanismo, geralmente não são alteradas. Veja
references/engine.mdpara escrever, ferramentas pequenas e padrões existentes.
- O
- Auto-teste:
node scripts/check.js <página.html> <diretório_de_capturas>, 10 itens sem FAIL (containserá SKIP se a página não tiver marcadores de pertencimento, normal), depois veja cada captura de tela uma por uma:step-NN(final de cada passo),mid-NN(meio de cada passo),page-NN(página inteira). O script só pode verificar "se parou, se espremeu texto, se saiu da caixa, se a fonte é grande o suficiente", não pode verificar "se explicou bem". Uma página de 4 passos leva cerca de 1 minuto, 12 passos cerca de 3 minutos. Veja o final de engine.md para instalação de dependências e uso. 4.5 (Para muitos passos ou para leigos) Teste com uma "pessoa que vê pela primeira vez": Crie um subagente que não conhece o mecanismo e não leu nenhum material. Dê a ele apenas as capturas de tela de cada passo da página, veja em ordem e, em seguida, repita de memória o que cada passo explicou, se foi a imagem ou o texto que o informou, e o que ele não entendeu. O que ele não entendeu é um problema da página, não dele — é mais eficaz do que você mesmo revisar dez vezes. - Entrega: Envie a página (um único HTML, sem dependências de outros arquivos) para a pessoa que solicitou. Cada vez que fizer uma alteração, execute o auto-teste novamente antes de entregar.
- (Quando o conteúdo for importante) Verificação técnica: Após a página ser finalizada, execute uma rodada de verificação somente leitura, verificando cada frase e número na página em relação ao código e documentos, e produza uma lista de "errado / enganoso / impreciso", deixando que a pessoa que solicitou decida o que alterar. A verificação é apenas sobre fatos; a qualidade da apresentação é decidida pela pessoa que solicitou.
2. Regras de Apresentação (A Mais Importante, Aprendidas Após Refações)
Ordem
- Do fácil ao difícil, primeiro a situação normal, depois a situação problemática. O leitor precisa ver o que é normal primeiro para entender onde está o problema. Exemplo: primeiro, muitos contêineres em uma máquina virtual compartilham memória (sem problemas); depois, quando são muitas máquinas virtuais, cada uma armazena uma cópia (problema); e, por fim, a solução.
- Primeiro o básico, depois o avançado, camada por camada. Primeiro, apenas o host → dados do disco para a memória do host → a máquina virtual aparece → dados para a máquina virtual → por fim, o programa dentro dela. Não coloque todas as caixas desde o início, nem faça o programa aparecer antes dos dados.
- Se houver causalidade entre várias coisas em um passo, coloque-as em sequência, não simultaneamente. "O contêiner sai" → "sua memória fica livre" → "devolvida ao host".
- A imagem só aparece quando a rolagem parar; a animação do primeiro passo começa do início; o modelo já trata disso, não quebre.
O que Cada Passo Explica
- Um passo explica apenas uma coisa, e o título é essa coisa ("Cada página lê uma vez"), não um substantivo ("Fase de leitura").
- A linha principal mostra apenas a prática real. Valores padrão, abordagens de outros, soluções históricas, coloque-as nos pontos-chave do passo com uma frase "por que fazer isso especificamente". Não faça delas um passo separado — caso contrário, o leitor achará que a prática real também precisa passar por aquele passo. (Exemplo negativo: primeiro mostrar "relatar a cada 2 MB" e depois "relatar a cada 4 KB", e o leitor pergunta: "De onde veio o 2 MB? Qual é o correto?")
- Dois passos que parecem iguais, o leitor achará que são a mesma coisa. Se dois cenários têm diferenças, desenhe essas diferenças (várias setas convergindo para os mesmos dados, um círculo indicando a cópia compartilhada), não apenas no texto.
- Cada número e palavra na imagem deve ter uma origem. Números não explicados anteriormente ("18", "2 MB") farão o leitor travar; ou explique ou remova.
- Quando um problema pertence a uma solução específica, coloque-o no módulo dessa solução, não na introdução geral, para que o leitor não pense que todos têm esse problema.
- Use exemplos concretos que o leitor reconhece, não símbolos abstratos. Várias linhas, pontos, pequenas barras se movendo; o leitor não sabe o que são (palavras do leitor: "Aquelas 4 barras de progresso... não entendo o que significam"). Substitua por algo que possa ser descrito: quem, para quem, disse o quê (o Agente do "sistema de pagamento" pergunta ao Agente da "plataforma de dados" "Como chamar a interface de pedidos?", e o outro responde "O documento da interface foi enviado"); use símbolos que o leitor já viu antes (como as linhas na lista anterior), não invente novos. Um exemplo bem explicado é melhor do que três pares de interações abstratas; se o exemplo for bom, adicione outro diferente, não repita o mesmo exemplo três vezes.
- Não desenhe camadas e objetos que não são usados neste passo. "Camada por camada" não significa que todas as camadas devem aparecer: ao explicar "o contêiner devolve a memória à máquina virtual", não desenhe o host, pois o leitor precisará reconhecer mais uma camada sem entender mais nada (palavras do leitor: "Não precisa mostrar o host novamente, está ficando complicado"). Antes de desenhar, pergunte: se eu remover isso, a frase deste passo ainda faz sentido? Se sim, remova.
- Após explicar, responda "e daí?". No último passo de cada módulo ou na página final, escreva claramente o que isso significa para o leitor e em que estágio estamos agora (já implantado / apenas em ambiente de teste / ainda não feito).
- Aprofundamento definido pelo leitor. Antes de começar, escreva "quem é o leitor, o que ele já sabe, o que não lhe interessa": para especialistas, explicar o básico será tedioso; para leigos, muitos detalhes de implementação serão considerados muito específicos.
Texto
- Cada passo: uma frase (lead) + no máximo 2–3 pontos-chave. Negrito apenas para números ou palavras conclusivas. Se o texto à esquerda for muito longo, remova detalhes, coloque-os na página final ou em notas pequenas no canto inferior direito da imagem.
- Não faça referência a algo que será explicado depois. Palavras como "não armazena mais uma cópia", "ainda", "também", "aquela cópia" devem se referir a algo que já apareceu antes. Após reorganizar a ordem das seções, leia o texto movido para frente do início ao fim na nova ordem.
- Explique o termo na primeira aparição com meia frase, e use o mesmo nome para a mesma coisa em toda a página.
- Não use nomes internos na página: números de RFC, números de PR, nomes de arquivos, nomes de funções, nomes de comandos, nomes de máquinas internas. Exceção quando o leitor é o próprio desenvolvedor do código.
- Não quebre linhas entre termos e "número + unidade": envolva em
{{ }}, como{{4 KB}},{{1,38 bilhões de tokens}}. - No rodapé, escreva "Atualizado em: mês/ano · versão do código verificada". A página é um instantâneo daquele dia; o código mudará.
- Inferido, não testado: escreva "inferido", "aguardando teste"; números de outros escreva claramente de quem são ("artigo", "POC", "main").
Imagem
- A mesma coisa é o mesmo objeto do início ao fim: o bloco de dados "voa" do disco para a memória, depois "voa" para a máquina virtual, e não desaparece aqui e aparece lá. O leitor usa isso para acompanhar o processo.
- Cores têm significados fixos, consistentes em toda a página (por exemplo: ciano = dados, roxo = programa, laranja = ação em andamento, azul = conclusão / devolvido). Coloque a legenda apenas para as cores usadas.
- Ações também têm significados fixos, não mude o uso em toda a página (por exemplo: linha laranja desenhada = fazendo uma solicitação, bloco de cor voando = dados entregues, círculo laranja = a cópia compartilhada por todos, grupo inteiro escurecendo = não é mais usado). Ações do mesmo tipo têm a mesma velocidade: as que percorrem distâncias maiores demoram mais, não as force a ter a mesma duração.
- Use cores para estados e apenas duas ou três: por exemplo, "azul = em uso, cinza = liberado". O leitor pode contar de relance quantos azuis e cinzas existem; só assim ele entenderá quando "o cinza for removido". Não use cor, ícone e texto para o mesmo estado.
- Texto a ser lido não se move: se uma frase precisa ser transmitida de A para B, deixe a frase parada ao lado de quem fala e envie um pequeno marcador ao longo da linha; o leitor lê o texto parado e observa o caminho do marcador. Se o texto voar, o leitor não verá nem um nem outro.
- Primeiro mova, depois pare: a ação principal do passo deve terminar nos primeiros 60% do tempo, depois a imagem fica parada para o leitor ler a frase à esquerda; duas ações importantes não ocorrem ao mesmo tempo; movimentos grandes não devem ser menores que meio segundo, e os que atravessam a imagem inteira não devem ser menores que 0,7 segundos, ou o olho não acompanha.
- Como veio, como vai: caixas desenhadas com linhas devem ser retiradas pelas linhas quando saírem; o que voou para dentro deve voar para fora. Use apenas dois ou três métodos de entrada e saída em toda a página; fade in/fade out não deve ser o padrão.
- Quando várias linhas convergem para o mesmo alvo, entre por diferentes direções (lado esquerdo, topo, lado direito, cada uma), não as alinhe na mesma borda: eventualmente se sobreporão ou passarão por trás de outros gráficos (palavras do leitor: "A linha do telefone e a linha do cliente se sobrepuseram, e o telefone bloqueou a linha do cliente").
- Se o significado está correto, mas não está bonito, também não está completo (palavras do leitor sobre uma nuvem: "O significado está certo, mas a nuvem está muito feia e rígida"). Para gráficos críticos (aqueles que aparecem repetidamente em toda a página, aqueles sobre os quais o último passo repousa), desenhe duas ou três versões lado a lado e escolha uma; ao escolher, pergunte: as linhas têm a mesma sensação do resto da página? As proporções são confortáveis? Distinguem-se das linhas de fundo?
- Marcadores de ênfase (círculos, setas, pequeno texto laranja) aparecem apenas quando são mencionados e saem quando terminam, o mais tardar no início do próximo passo, não os carregue para os passos seguintes. A imagem no final de cada passo deve ser compreensível por si só (
step-NN.pngé essa imagem). - Para enfatizar compartilhamento/unicidade: várias setas convergem em uma única que cai no mesmo alvo, mais um círculo laranja.
- "Foi pulado", "foi devolvido" deve ser mostrado: o objeto voa para a seção correspondente na barra de ocupação, somente após pousar essa seção encolhe; não encolha enquanto voa. A posição para onde voa deve corresponder à seção que encolhe.
- Quando a proporção não corresponde ao real, escreva "ilustrativo" e não deixe que o tamanho da grade ilustrativa sugira uma unidade inexistente.
- Aninhamento de caixas e nomes seguem a afiliação real: antes de desenhar, liste uma tabela "objeto → em qual espaço de rede/contêiner/processo/serviço ele realmente está". Contêineres ou processos independentes (sidecar, proxy) são desenhados como caixas paralelas, não dentro do contêiner de negócios; a caixa externa deve escrever claramente o que é ("espaço de rede de um grupo de contêineres"), o nome da caixa deve ser o nome pelo qual o leitor o conhece ("contêiner de negócios", não "contêiner principal"); para coisas com o mesmo nome, esclareça a afiliação (quando dois serviços têm um componente chamado sidecar, use nomes completos fixos para cada um), e não os misture na imagem ou na coluna esquerda.
- Quanto menos curvas nas linhas, melhor: as extremidades devem estar nas bordas opostas das duas caixas, não mire no centro da caixa; se as duas caixas se sobrepõem em altura, uma linha reta; se precisar curvar, use apenas um ponto de curva definido (no máximo dois em forma de U para contornar obstáculos), e o ponto de curva deve evitar o texto; pacotes de dados, linhas vermelhas, etc., que seguem o mesmo caminho compartilham esses pontos de curva. Pequenas curvas serão interpretadas pelo leitor como "há um significado especial aqui". O item
bendsdocheck.jsbloqueará. - Coloque notas explicativas pequenas nas bordas das caixas, não sobre os objetos dentro delas.
- O texto na imagem não deve ser menor que 14 unidades de canvas. A imagem será reduzida para cerca de 0,8x em laptops de 13 polegadas; se for menor, ficará ilegível; o item
fontsizedocheck.jsbloqueará abaixo de 11px em 1280 × 720. Se não couber, remova conteúdo, não reduza a fonte. O modelo tem um botão "ampliar imagem" (botão no topo / tecla F), que é uma opção para o leitor, não um remendo para fonte pequena.
3. Retrabalhos Comuns (Ao Receber Este Feedback, Corrija Assim)
| Feedback | Causa Provável | Como Corrigir |
|---|---|---|
| "A animação deste passo não terminou / tem problema no final" | Os quadros-chave estão após o final deste passo, ou o fade in termina exatamente no momento final | Todas as ações deste passo devem começar antes de T(id, 0.88) e parar antes de T(id, 1); o item still do check.js reportará |
| "O texto saiu da caixa / posição errada" | A caixa pai e o conteúdo não começam a se mover ao mesmo tempo; um quadro-chave extra foi escrito apenas para mudar a cor, fixando a posição | Use os mesmos momentos para pai e filho; marque-os com data-box / data-in e verifique quadro a quadro com o item contain. Não use outros indicadores (tamanho da fonte, transparência) como substitutos para "dentro da caixa" |
| "O passo N e o passo M parecem iguais" | A diferença está apenas no texto | Desenhe a diferença (veja acima: setas convergentes + círculo) |
| "De onde veio o X?" | Há um número/unidade não explicado na imagem | Explique a origem ou remova da imagem, mencionando apenas no "porquê" |
| "Ordem errada, deveria ser A antes de B" | Não foi ordenado por causalidade / camada | Reordene os momentos deste passo de acordo com "primeiro o básico, depois o avançado"; aproveite para verificar também os outros passos com o mesmo critério |
| "XX é estranho, nunca foi mencionado antes" | O texto faz referência a algo que será explicado depois | Use grep para "não, ainda, também, aquela cópia, comparação" e verifique se cada referência já apareceu |
| "Muito texto / não dá para ler / muito pequeno" | Detalhes acumulados na coluna esquerda; texto na imagem menor que 14 | Remova até uma frase + pontos-chave; ajuste o texto na imagem para 14 ou mais; se não couber, remova; os itens fontsize e text do check.js reportarão |
| "Ao rolar da página inicial para o primeiro passo, não há animação / após atualizar, não há animação" | A lógica de entrada no mecanismo foi danificada | Não mexa nas linhas enteredFirst, pendingShow e iniciais da seção B2; o item wheel do check.js reportará |
| "Por que há essa curva?" (com captura de tela) | A seta aponta para o centro da outra caixa, ou os pontos de curva são calculados separadamente, resultando em um pequeno vai-e-vem; pacotes de dados e linhas no mesmo caminho seguem caminhos diferentes | Coloque as extremidades nas bordas opostas; se possível, linha reta; no máximo um ponto de curva; pacotes de dados e linhas compartilham o ponto de curva; o item bends do check.js reportará. Verifique todas as linhas da imagem com o mesmo critério |
| "O X é um Y independente? Desenhá-lo dentro de Z é apropriado?" "Este bloco deveria ser chamado de... não é mais preciso?" | O aninhamento das caixas não segue a afiliação real (sidecar desenhado dentro do contêiner de negócios), ou o nome da caixa usa um nome interno | Primeiro, liste a tabela "objeto → afiliação real" e depois corrija o aninhamento; escreva claramente o que é a caixa externa; mude o nome da caixa para o nome do leitor; verifique todas as caixas semelhantes em toda a página juntas |
Após receber um feedback, primeiro pense se ele também se aplica a outros passos e corrija tudo de uma vez, não espere que a pessoa aponte um por um.
4. Arquivos
| Arquivo | Conteúdo |
|---|---|
assets/template.html | Modelo (mecanismo + exemplo de 4 passos) |
scripts/check.js | Script de auto-teste (10 itens + capturas de tela) |
references/storyboard.md | Como escrever um storyboard, um storyboard real de 12 passos |
references/engine.md | Estrutura do modelo, ferramentas pequenas, padrões de cena, armadilhas, como executar o auto-teste |
references/lessons.md | Registro de feedback de várias páginas concluídas (origem das regras); quando as regras não cobrirem um caso, procure aqui pelo mais semelhante |