Anatomy em 2026: Diagramas Isométricos Interativos para Documentação

Olá HaWkers, explicar um sistema técnico com uma imagem bonita é relativamente fácil; explicar o que muda quando alguém interage com ele é outra história. O projeto aberto Anatomy propõe transformar uma ideia em uma máquina isométrica interativa, construída principalmente com SVG. O repositório descreve também opções com WebGL e um modo 3D ainda experimental. Em vez de tratar o desenho como decoração, ele tenta fazer cada peça corresponder a uma parte da explicação.

Você já publicou um diagrama que parecia claro para quem o criou, mas deixou o leitor sem saber por onde começar? Aqui você vai aprender a formular um pedido útil ao Anatomy, decidir o formato de saída, revisar a interação e construir uma versão pequena em SVG para entender os princípios por trás do resultado. O objetivo é sair com um método de documentação visual, não com uma imagem que só funciona na apresentação.

O que o Anatomy faz e onde ele entra

Anatomy é uma skill para um agente de programação. Segundo a documentação do projeto, você descreve um conceito ou objeto, define onde a figura será usada e recebe código-fonte para uma ilustração interativa. O núcleo usa peças isométricas em SVG com sombreamento; efeitos como água, luz e fumaça podem usar WebGL. O modo de peças que giram em 3D aparece como beta no próprio README. Isso é diferente de solicitar uma imagem estática a um gerador: há estado, comportamento e uma relação que precisa fazer sentido entre o valor exibido e o movimento das partes.

O repositório oferece saídas como página HTML independente, SVG isolado ou componentes para React e Next.js. Também inclui exemplos e scripts de captura e auditoria. Essas opções não significam que toda figura precise de um renderizador sofisticado. Para um guia de API, um SVG legível e bem rotulado pode comunicar mais do que uma cena cheia de partículas. WebGL só ajuda quando o fenômeno visual faz parte da explicação, como fluxo, brilho ou refração.

Pense no leitor antes de pensar na câmera. Quem chega por uma busca quer identificar a peça principal, reconhecer uma mudança de estado e descobrir o que fazer com essa informação. Se a animação não mostra uma relação causal, ela ocupa espaço e atenção sem ensinar. O mesmo vale para uma figura que só revela seu conteúdo ao passar o mouse: no celular e no teclado, essa informação pode desaparecer.

Escolha uma pergunta que o desenho consiga responder

Um bom ponto de partida é uma pergunta delimitada: “por que a requisição espera quando todas as conexões estão ocupadas?” Isso dá ao agente um evento observável. Já “desenhe uma arquitetura moderna” abre espaço para caixas genéricas, setas arbitrárias e nenhum critério de correção. O README do Anatomy recomenda nomear a ideia, informar números reais quando eles existirem e dizer em que formato a figura deve ser entregue. Se você não conhece os números de produção, identifique os valores como exemplo didático; não transforme uma suposição em métrica do seu sistema.

Imagine um pool com três conexões fictícias e uma fila. A figura deve responder: qual conexão está livre, o que ocorre quando chega uma quarta requisição e quando a fila anda? Há estados claros para representar: livre, ocupada e aguardando. O desenho de uma oficina com bancadas pode ajudar, desde que a metáfora não esconda a regra: uma conexão só volta ao pool depois de ser liberada. O texto ao lado deve repetir essa regra de modo direto.

Escreva primeiro uma pequena especificação: público, pergunta, objetos visíveis, estados, transições e saída esperada. Só depois peça geometria, cores e movimento. Essa ordem evita que um detalhe estético determine o funcionamento do sistema. Também facilita revisar o código gerado: você sabe que cada movimento deve corresponder a uma transição definida, e consegue rejeitar peças que são apenas enfeite.

Se a documentação já usa SVG animado, vale consultar também o artigo sobre animação de SVG com CSS. Ele ajuda a separar uma transição visual simples de uma interação que precisa de JavaScript e de estado explícito.

Instalação e pedido inicial

O README oficial mostra instalação pelo catálogo de skills ou por Git. A opção abaixo instala a skill para Claude Code no escopo do usuário. Confira o repositório e as instruções antes de executar código de terceiros no seu ambiente; a instalação copia os arquivos do projeto para a pasta de skills.

# Instala a skill para Claude Code no perfil do usuário.
npx skills add wheresryan22/anatomy -g -a claude-code

# Alternativa local para um projeto: leia o repositório antes de adotá-lo.
git clone https://github.com/wheresryan22/anatomy.git .claude/skills/anatomy

Depois, o pedido deve conter a explicação, a interação e o destino. Um exemplo útil seria: “Crie uma figura sobre um pool de conexões com três conexões ilustrativas; mostre uma requisição aguardando quando todas estiverem ocupadas, permita avançar com botão e teclado, entregue HTML independente e mantenha um resumo textual sempre visível”. Os três elementos são valores da demonstração, não uma recomendação de capacidade para bancos de dados reais. Peça também um estado inicial que já comunique algo sem movimento, porque alguns leitores reduzem animações ou usam tecnologias assistivas.

Ao revisar a primeira entrega, confira se o projeto forneceu código que você consegue manter. Descubra onde ficam o modelo de estado, a projeção isométrica, os rótulos e os eventos. Não aceite um resultado que só permite editar texto mexendo em coordenadas espalhadas por dezenas de arquivos. A documentação do Anatomy diz que as figuras podem vir com script de construção e página gerada; trate o script como a fonte e a página como o artefato que será publicado.

Um exemplo mínimo para entender estado e interação

Antes de avaliar uma figura complexa, vale montar uma miniatura manual. O exemplo a seguir não é saída do Anatomy: é um HTML independente, criado aqui para mostrar a regra que você deve cobrar de qualquer ilustração interativa. Um botão alterna entre uma conexão livre e ocupada. O texto visível e o texto anunciado às tecnologias assistivas são atualizados pela mesma função que muda a cor. Salve o conteúdo como pool.html e abra no navegador.

<!doctype html>
<html lang="pt-BR">
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Estado de uma conexão</title>
  <h1>Pool de conexões: exemplo didático</h1>
  <p id="estado" role="status">A conexão está livre.</p>
  <svg viewBox="0 0 320 180" width="320" role="img" aria-labelledby="titulo descricao">
    <title id="titulo">Uma conexão do pool</title>
    <desc id="descricao">O bloco muda de cor quando a conexão é ocupada.</desc>
    <polygon points="70,70 160,25 250,70 160,115" fill="#a7d8c9" />
    <polygon id="bloco" points="70,70 160,115 160,155 70,110" fill="#28745d" />
    <polygon points="160,115 250,70 250,110 160,155" fill="#1e5848" />
  </svg>
  <p><button id="alternar" type="button">Ocupar conexão</button></p>
  <script>
    // Um estado alimenta a forma, o rótulo e a ação seguinte.
    let ocupada = false;
    const bloco = document.querySelector('#bloco');
    const estado = document.querySelector('#estado');
    const botao = document.querySelector('#alternar');

    botao.addEventListener('click', () => {
      ocupada = !ocupada;
      bloco.setAttribute('fill', ocupada ? '#b85342' : '#28745d');
      estado.textContent = ocupada
        ? 'A conexão está ocupada; novas requisições aguardam.'
        : 'A conexão está livre.';
      botao.textContent = ocupada ? 'Liberar conexão' : 'Ocupar conexão';
    });
  </script>
</html>

O botão nativo já responde a teclado e toque. A referência do MDN para <title> em SVG explica que ele fornece uma descrição curta acessível; a descrição mais longa pode ir em <desc>. O par de elementos melhora a compreensão do gráfico, mas não substitui o estado textual fora dele. Quem não percebe a mudança de cor ainda precisa saber o que aconteceu. Em uma figura real, também seria necessário verificar contraste, foco, zoom, preferências de movimento e leitura em tela estreita.

Observe que o polígono faz uma isometria simplificada, sem biblioteca. Para um sistema com muitas peças, o valor do Anatomy está em construir e verificar uma composição que seria demorada manualmente. Ainda assim, o princípio permanece: dado e movimento devem partir do mesmo estado. Se o visor diz “livre” enquanto a máquina mostra “ocupada”, a figura ensina o contrário do que promete.

Como revisar uma figura gerada sem confiar apenas na aparência

Comece pela pergunta original. Faça a interação completa e tente responder sem ler o código: o estado inicial está evidente? Cada ação tem um efeito previsível? O texto confirma a mudança? Uma animação que exige adivinhar a parte clicável pode funcionar em uma demonstração, mas falha em documentação. Coloque instruções curtas perto do controle e teste o caminho pelo teclado, por toque e com o ponteiro. Se um estado só aparece durante hover, acrescente uma alternativa explícita.

Depois, revise o modelo. Procure valores repetidos manualmente em rótulos, movimentos e painéis. O Anatomy descreve como objetivo obter leituras e movimento a partir do mesmo modelo pequeno. É uma boa régua para qualquer ferramenta: se você alterar a capacidade do exemplo, todas as representações devem mudar juntas. Também confirme se os valores publicados correspondem ao produto real ou se estão identificados como demonstração.

Por fim, compare as saídas. O SVG isolado pode ser adequado para uma página leve e sem interação. A página HTML independente facilita compartilhar um protótipo. Um componente React pode integrar melhor a documentação existente, mas adiciona decisões sobre renderização, estado e empacotamento. Escolha o formato conforme a infraestrutura onde a figura viverá. Uma saída 3D em beta exige ainda mais atenção a desempenho e suporte, especialmente em aparelhos modestos.

O repositório tem scripts de captura e auditoria para alguns exemplos. Isso ajuda a encontrar defeitos geométricos, mas não certifica que o conceito está correto nem que a experiência é acessível. Revisão humana continua necessária: compare os estados com a especificação inicial, peça a outra pessoa que explique a figura e registre onde ela hesitou.

Publicação, manutenção e segurança do artefato

Uma figura interativa entra no ciclo de manutenção da documentação. Guarde o prompt ou a especificação, o código-fonte e uma captura de cada estado importante no repositório. Quando uma regra do produto mudar, atualize primeiro o modelo e o texto; só depois ajuste a geometria. Isso reduz o risco de publicar um painel tecnicamente bonito com uma regra de negócio antiga.

Inclua uma verificação básica no processo de revisão. O comando seguinte não substitui testes no navegador: ele apenas confirma que o arquivo existe, contém os controles esperados e termina com um documento HTML. É útil para evitar publicar por engano uma captura vazia ou uma versão sem interação. Execute na pasta em que você salvou pool.html.

# Confere a presença dos elementos essenciais do exemplo.
test -s pool.html
python3 - <<'PY'
from pathlib import Path

pagina = Path('pool.html').read_text(encoding='utf-8')
for trecho in ('id="estado"', 'id="alternar"', 'aria-labelledby', "addEventListener('click'"):
    assert trecho in pagina, f'Elemento ausente: {trecho}'
print('Estrutura básica encontrada; revise a interação no navegador.')
PY

Como o Anatomy é composto por instruções e scripts locais, leia o código e os comandos antes de executá-los em uma máquina com dados sensíveis. A política de segurança do projeto informa que alguns scripts de captura iniciam o Chrome em modo headless e que um deles executa JavaScript fornecido pelo usuário na página. Use esses scripts apenas com páginas em que você confia. Se for incorporar HTML gerado a um site público, revise dependências, referências externas, política de conteúdo e o que o script tenta carregar.

Esse cuidado vale também para links e imagens da página. Um artefato que funciona localmente pode depender de um caminho absoluto, de uma fonte não licenciada para redistribuição ou de uma API que só existe no ambiente do autor. Abra a saída em uma sessão limpa e faça a mesma sequência de interações que um leitor faria. Assim, o teste cobre a experiência publicada, não apenas o script que a produziu.

Quando usar Anatomy e quando simplificar

Use Anatomy quando uma relação espacial ajuda a entender o processo: fluxo entre peças, ocupação de recursos, mudanças de estado ou funcionamento de uma máquina. Ele parece especialmente adequado a explicações em que o leitor precisa descobrir o que se move e por quê. Uma figura sobre cache, pool de conexões ou etapas de uma operação tem uma pergunta concreta para orientar a animação.

Simplifique quando a resposta cabe em uma tabela, um trecho de código ou uma frase. Uma comparação de preços, uma lista de parâmetros de API e uma decisão de configuração normalmente não ficam mais claras porque foram projetadas em isometria. O custo de manutenção da figura só se justifica se ela revelar algo que o texto estático esconde. Para começar, faça um protótipo pequeno e peça a alguém para explicar o conceito depois de interagir com ele.

Também considere o público. Em uma página de referência consultada rapidamente, uma imagem estática com legendas pode ser melhor. Em um tutorial de conceitos, a interação permite experimentar estados e construir uma intuição. A escolha não precisa ser definitiva: uma mesma especificação pode gerar um SVG estático para leitura rápida e uma versão interativa para exploração detalhada.

Perspectivas para documentação visual em 2026

O ponto promissor do Anatomy é oferecer código e modelo para uma explicação, em vez de apenas uma imagem pronta. Isso pode aproximar ilustração, documentação e teste: quando o sistema muda, a figura pode mudar junto. A promessa, porém, depende de revisão cuidadosa. Uma cena bonita não corrige um dado inventado, um estado incoerente ou um controle inacessível.

Se você experimentar a ferramenta, comece por uma única dúvida frequente dos usuários. Defina uma pergunta, escreva os estados e peça uma figura simples. Teste com teclado e celular, confira o código entregue e peça feedback a alguém que não participou da criação. A melhor ilustração é aquela que deixa o mecanismo mais fácil de explicar depois que a animação termina.

Bora pra cima! 🦅

📚 Quer Acompanhar o Que Vem Por Aí?

Este artigo cobriu diagramas isométricos com Anatomy, mas o ecossistema muda toda semana e nem tudo vira artigo aqui.

No X eu compartilho o que estou testando, os bastidores dos projetos e as novidades que aparecem antes de virarem post.

Me Segue Lá

👉 Seguir @jeffbruchado no X

💡 Conteúdo diário sobre desenvolvimento, carreira e as ferramentas que eu realmente uso