Communitygithub.com

khollingworth/d2-diagram-skill

Plugin Claude Code que renderiza diagramas de arquitetura D2 profissionais (TALA/ELK) com um loop de renderização e autocorreção.

O que é d2-diagram-skill?

Este skill permite que o Claude Code crie diagramas de arquitetura de software de alta qualidade usando a linguagem D2. Ele segue um fluxo de trabalho iterativo: planejar o diagrama, escrever código D2, renderizar para SVG/PNG, analisar visualmente a saída e corrigir problemas em um loop até que o resultado seja digno de entrega ao cliente. O skill suporta múltiplos mecanismos de layout — TALA (profissional, com licença), ELK (gratuito, fallback automático) e dagre — e usa um script de renderização que valida o ambiente, evita saídas com marca d'água e fornece feedback detalhado sobre erros de compilação e opções de tema, layout e escala. É especialmente útil para engenheiros que precisam documentar arquiteturas de sistemas reais com diagramas precisos e visualmente consistentes, sem perder tempo ajustando coordenadas manualmente. O skill também fornece referências completas sobre sintaxe D2, padrões de diagramas (arquitetura, sequência, ERD, C4, grid) e comportamento detalhado de cada mecanismo de layout.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add khollingworth/d2-diagram-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

ArquivoLeia quando
references/d2-language.mdEscrevendo qualquer D2 não trivial — sintaxe, formas, containers, classes, variáveis e as armadilhas silenciosas que compilam direito mas renderizam errado
references/layout-engines.mdEscolhendo ou depurando layout: TALA vs ELK vs dagre, licenciamento, sementes, diferenças de comportamento por mecanismo
references/diagram-patterns.mdEscolhendo 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 execute scripts/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 installed ou unlicensed → 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:

  1. 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.
  2. 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. Veja references/diagram-patterns.md para orientação estrutural por tipo.
  3. 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, escreva api -> db, nunca API 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 com class:. Evite style.fill em nós individuais; preenchimentos fixos brigam com o tema e quebram a renderização em modo escuro.
  • Defina direction: right para a maioria dos fluxos de arquitetura (leitura da esquerda para a direita é natural). Todos os mecanismos honram a direção raiz; o TALA adicionalmente suporta direction por container.
  • Salve o fonte como {name}.d2 pró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
  • --png também escreve output.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) e fallback: (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 de references/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 em references/diagram-patterns.md.
  • Se o usuário for iterar no diagrama por conta própria, mencione d2 --watch input.d2 para pré-visualização ao vivo no navegador.

Solução de problemas

SintomaCausa / correção
d2: command not foundExecute scripts/setup.sh (instalação guiada)
D2_LAYOUT "tala" is not bundledTALA não está no PATH — o script cai automaticamente para ELK; instale TALA apenas se o usuário quiser
Texto UNLICENSED na saídaTALA 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 funcionaA 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 problemaVersão d2/TALA incompatível — o script cai para fallback automaticamente; sugira atualizar ambos
Ícones ausentes na saídaURL do ícone retornou 403/404 — remova o ícone ou escolha outro em icons.terrastruct.com; teste ícones cedo

Habilidades Relacionadas