D2 Diagrams
Escreva código-fonte D2, renderize-o para SVG e então olhe para a renderização e corrija o que vê — em um loop, até que o diagrama esteja pronto para ser entregue. Um diagrama que você não viu é um diagrama que você não terminou.
Arquivos de referência — carregue sob demanda
| Arquivo | Leia quando |
|---|---|
references/d2-language.md | Escrevendo qualquer D2 não trivial — sintaxe, formas, containers, classes, variáveis e as armadilhas silenciosas que compilam direito mas renderizam errado |
references/layout-engines.md | Escolhendo ou depurando layout: TALA vs ELK vs dagre, licenciamento, sementes, diferenças de comportamento por mecanismo |
references/diagram-patterns.md | Escolhendo um tipo e estrutura de diagrama — arquitetura, sequência, ERD, grid, C4; temas, ícones, modo escuro, incorporação no GitHub |
Passo 0 — Verificação da ferramenta
Execute uma vez por sessão antes da primeira renderização (scripts/ aqui significa o próprio diretório deste skill — no Claude Code ${CLAUDE_SKILL_DIR} resolve para ele):
bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
d2: ok→ prossiga.d2: MISSING→ avise o usuário, então executescripts/setup.sh(sem flags) para instalar via Homebrew quando disponível, ou mostre os comandos de instalação impressos. Não renderize às cegas — nada mais neste skill funciona sem d2.tala: not installedouunlicensed→ tudo bem. ELK é o fallback automático e produz bons layouts. Mencione TALA uma única vez se o diagrama for de arquitetura de software (onde TALA é significativamente melhor) e o usuário parecer interessado na qualidade da saída; nunca insista.
Passo 1 — Planeje antes de escrever
Decida três coisas primeiro:
- A mensagem. O que um leitor deve concluir em cinco segundos? Um diagrama argumenta algo — "as requisições se distribuem aqui", "este serviço é o gargalo", "estes dois caminhos nunca se tocam". Se você não consegue enunciar o argumento, está prestes a desenhar uma coleção de caixas rotuladas.
- O tipo. Arquitetura/topologia → formas simples e containers. Interação ao longo do tempo →
sequence_diagram. Modelo de dados →sql_table. Alinhamento rígido (matriz, painel, muita legenda) → grid. Vejareferences/diagram-patterns.mdpara orientação estrutural por tipo. - A escala. 5–15 nós são bem legíveis; 15–25 precisam de containers para agrupar; além de ~25, divida em múltiplos diagramas ou use
layers. Prefira um segundo diagrama a um mural.
Para diagramas técnicos de sistemas reais, use nomes reais — nomes reais de serviços, tabelas e eventos do código-fonte ou descrição do usuário. Faça grep no código se disponível. Service A -> Service B desperdiça a confiança do leitor.
Passo 2 — Escreva o D2
Leia references/d2-language.md antes de escrever qualquer coisa além de um diagrama trivial. As regras que previnem 90% das saídas quebradas:
- Conecte chaves, não rótulos. Após
api: API Gateway, escrevaapi -> db, nuncaAPI Gateway -> db— este último silenciosamente cria uma forma duplicada. - Coloque aspas em rótulos que contenham
#ou;—#sem aspas inicia um comentário no meio do rótulo e;sem aspas divide a linha em duas formas, ambos compilam sem erro. Colocar aspas em qualquer rótulo com pontuação é o hábito seguro. - Estilize através de
classes:, não de estilos por nó — uma definição, aplicada comclass:. Evitestyle.fillem nós individuais; preenchimentos fixos brigam com o tema e quebram a renderização em modo escuro. - Defina
direction: rightpara a maioria dos fluxos de arquitetura (leitura da esquerda para a direita é natural). Todos os mecanismos honram a direção raiz; o TALA adicionalmente suportadirectionpor container. - Salve o fonte como
{name}.d2próximo de onde a saída pertence (padrão:./diagrams/no projeto).
Passo 3 — Renderize
Sempre renderize através do script empacotado — ele escolhe o mecanismo de layout, protege contra saída com marca d'água e valida primeiro:
bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
--pngtambém escreveoutput.png— você precisa dele para o Passo 4 (a ferramenta de leitura visualiza imagens raster, não SVG).- O script imprime
engine:(o que realmente renderizou) efallback:(por que, se TALA não foi usado). Repasse uma nota de uma linha ao usuário somente quando ele perguntou sobre mecanismos ou explicitamente queria TALA. - Flags úteis:
--theme N,--dark-theme 200(o SVG responde ao esquema de cores do leitor),--sketch,--pad N,--seed N(nova tentativa do TALA),--engine tala|elk|dagre(forçar),--allow-watermark(avaliação TALA). - Em caso de falha, o script imprime o erro de compilação d2 com
arquivo:linha:coluna— corrija o fonte naquela localização e reexecute. Se o erro não estiver claro, verifique a seção de armadilhas dereferences/d2-language.md.
Nunca renderize saída TALA para entrega com marca d'água a menos que o usuário aceite explicitamente; o script impõe isso caindo para ELK como fallback.
Passo 4 — Olhe e corrija (não opcional)
O fonte .d2 não diz nada sobre como a renderização realmente ficou — o layout é decisão do mecanismo, não sua. Abra o PNG com a ferramenta de leitura e audite-o em duas passagens:
Passagem 1 — o argumento é defendido?
- O olho entra onde a história começa e sai onde ela termina?
- A direção do fluxo é consistente (sem voltar atrás ou ler de baixo para cima involuntariamente)?
- Os agrupamentos em containers correspondem aos agrupamentos lógicos que você planejou?
- O elemento mais importante é visualmente proeminente, ou está enterrado?
Passagem 2 — defeitos de layout (mecanismos de layout automático produzem todos estes):
- Rótulos de arestas se afastaram muito de sua aresta, ou ambíguos sobre qual aresta descrevem
- Arestas sobrepondo em execuções paralelas, cruzando através de nós ou containers, ou fazendo desvios absurdos
- Texto truncado ou colidindo com formas/ícones
- Uma região apertada enquanto outra está vazia; um container vastamente maior que seu conteúdo
- Nó tão pequeno que seu rótulo domina, ou tamanhos de nós extremamente inconsistentes
- Qualquer coisa que você teria que explicar pedindo desculpas se mostrasse ao usuário
Corrija com as alavancas do D2, não ajustando pixels (layout automático significa que você muda entradas, não coordenadas): mude direction; agrupe ou reagrupe com containers; encurte rótulos de arestas (rótulos longos se deslocam pior no ELK); mescle arestas paralelas em uma aresta rotulada; mova legendas/títulos para fora do fluxo com near; divida um diagrama sobrecarregado em layers; ajuste --pad; no TALA, tente novamente com --seed N (tente 2–3 sementes — os layouts variam significativamente); como último recurso, troque de mecanismo para esta forma de diagrama (veja references/layout-engines.md).
Re-renderize, re-visualize, repita. Planeje dois a quatro ciclos de renderização — uma primeira renderização que sobrevive a ambas passagens é rara. Pronto significa: ambas passagens limpas, e nada na imagem precisa de desculpa ou explicação.
Passo 5 — Entregue
- Confirme os caminhos finais do
.svg(e do fonte.d2) — sempre dê ambos ao usuário; o.d2é o artefato editável. - Se o diagrama for viver em um README do GitHub ou site de documentação, ofereça uma variante consciente de modo escuro: re-renderize com
--dark-theme 200(SVG único que segue o esquema de cores do leitor). Padrões para incorporação PNG/<picture>estão emreferences/diagram-patterns.md. - Se o usuário for iterar no diagrama por conta própria, mencione
d2 --watch input.d2para pré-visualização ao vivo no navegador.
Solução de problemas
| Sintoma | Causa / correção |
|---|---|
d2: command not found | Execute scripts/setup.sh (instalação guiada) |
D2_LAYOUT "tala" is not bundled | TALA não está no PATH — o script cai automaticamente para ELK; instale TALA apenas se o usuário quiser |
Texto UNLICENSED na saída | TALA sem licença — o script de renderização re-renderiza com ELK automaticamente; uma chave de licença vai em TSTRUCT_TOKEN ou ~/.config/tstruct/auth.json |
| Exportação PNG falha, SVG funciona | A primeira renderização PNG baixa um navegador headless; repita uma vez. Se bloqueado (offline/CI), entregue SVG e inspecione convertendo com qualquer rasterizador SVG disponível |
Erro de compilação sob --layout tala que o ELK renderiza sem problema | Versão d2/TALA incompatível — o script cai para fallback automaticamente; sugira atualizar ambos |
| Ícones ausentes na saída | URL do ícone retornou 403/404 — remova o ícone ou escolha outro em icons.terrastruct.com; teste ícones cedo |