AnisAbdellatif/d2

Diagramas D2

D2 é uma linguagem declarativa: você descreve formas e as conexões entre elas, e um mecanismo de layout decide onde tudo vai. Você nunca coloca coordenadas manualmente. É por isso que um diagrama D2 é curto, fácil de diferenciar (diff) e fácil de editar depois, e também porque a maioria dos erros vem de peculiaridades de sintaxe e do mecanismo de layout, não do design.

Esta habilidade é um conhecimento operacional completo do D2 v0.9.x, verificado contra o compilador real. Cada exemplo em references/ e assets/templates/ compila.

Fluxo de trabalho

1. Verifique a ferramenta. Execute d2 --version (ou scripts/d2check.sh --version). Se d2 estiver faltando, informe o usuário e ofereça brew install d2 ou curl -fsSL https://d2lang.com/install.sh | sh -s --; não instale silenciosamente.
2. Escolha o tipo de diagrama e leia a referência correspondente (tabela abaixo). Comece a partir de um template em assets/templates/ quando um se adequar.
3. Escreva o arquivo .d2 próximo de onde o usuário o deseja (padrão: diagrams/<nome>.d2).
4. Compile e renderize com scripts/d2check.sh <arquivo.d2> [diretório_saída] [pdf|pptx|gif] (formata, compila, renderiza SVG, coloca uma prévia PNG em diretório_saída/preview/, e quaisquer formatos extras). Nunca confie apenas em d2 validate: ele apenas analisa a sintaxe. Nomes de forma ruins, estilos fora do intervalo, recursos de layout não suportados e imports ausentes passam pelo validate e falham na compilação.
5. Olhe a imagem. Abra o PNG em preview/ (ferramenta Read no .png) e julgue: rótulos sobrepostos, arestas emaranhadas, direção de fluxo errada, um layout desequilibrado. Corrija e re-renderize. Um diagrama que compila mas é ilegível não está pronto.
6. Entregue o código-fonte .d2 mais o arquivo renderizado, e diga qual mecanismo de layout, tema e direção você usou para que o usuário possa alterá-los.

Para algo rápido e único sem arquivos: echo 'a -> b' | d2 - out.svg.

Sintaxe em uma tela

direction: right                    # up | down | right | left (nível raiz; apenas TALA permite por contêiner)

# formas: chave, rótulo opcional, atributos opcionais
web: Web App {shape: rectangle}     # chave `web`, rótulo "Web App"
db: Postgres {shape: cylinder}
user: Customer {shape: person}

# conexões: -> <- <-> --  (sempre referencie as CHAVES, nunca os rótulos)
user -> web: usa
web -> db: SQL {style.stroke-dash: 3}
web -> cache: lê              # chaves não declaradas são criadas dinamicamente

# contêineres: pontos ou mapas aninhados
backend: {
  api -> worker: enfileira
  worker -> _.db: escreve         # _ = escopo pai
}
web -> backend.api: HTTPS

# estilo vive em atributos
db.style.fill: "#e6f2ff"         # cite qualquer coisa que comece com #
(web -> db)[0].style.stroke: red # estilize uma conexão por índice

# reutilização: classes, variáveis, globs
classes: {
  store: {shape: cylinder; style.fill: "#e6f2ff"}
}
cache.class: store
vars: {env: prod}
note: Executando em ${env}
*.style.border-radius: 8

Ponto e vírgula separa itens em uma linha. # inicia um comentário, """ ... """ é um comentário de bloco. Chaves são insensíveis a maiúsculas/minúsculas e declarações repetidas se mesclam (API, api e Api: Gateway são uma forma rotulada como "Gateway").

Citação: a fonte número um de erros

Strings não citadas são convenientes, mas vários caracteres têm significado. Cite o rótulo inteiro ("..." ou '...') sempre que ele contiver algum destes, ou o compilador ou erra ou, pior, trunca silenciosamente o rótulo:

Caractere	O que acontece sem citação	Exemplo de correção
# em qualquer lugar	resto da linha vira comentário: a: C# linguagem renderiza "C"	a: "C# linguagem"
[ no início	interpretado como array: a: [JSON/HTTPS] renderiza apenas "a"	a: "[JSON/HTTPS]"
. em uma chave	cria um contêiner: svc v1.2 vira svc v1 > 2	"svc v1.2"
& ou [ ] em uma chave	erro de parse (& é o marcador de filtro glob)	"P&D", "svc[0]"
$ seguido por qualquer coisa exceto {	"substituições devem começar com {"	aspas simples: 'custa $5'
{ } `	` no início do rótulo	abre um mapa ou string de bloco
palavras reservadas como chaves de forma (label, link, class, top, style, shape, icon, near, direction, vars ...)	"palavras-chave reservadas são proibidas em arestas"	"link" -> b, ou escolha uma chave diferente
-> ou : dentro de um rótulo de aresta	funciona na prática (a -> b: Tempo: 10s funciona)	nenhuma citação necessária
pontuação não-ASCII como ： (dois-pontos largura total)	não é reconhecida como dois-pontos	use : ; . ASCII

Cores hexadecimais devem ser citadas ("#fff") porque # inicia um comentário. Aspas simples também desabilitam a substituição ${...}.

Quebras de linha em rótulos: \n em um rótulo citado ou não citado, ou uma string de bloco |md ... | para texto rico.

Coisas que mordem (leia antes de depurar)

• Dagre, o mecanismo de layout padrão, não pode desenhar uma conexão entre um contêiner e seu próprio descendente (a -> a.b), não pode dimensionar contêineres (width/height), e não pode usar near: <objeto>. Ele erra em tempo de compilação. Mude para --layout=elk (ou vars.d2-config.layout-engine: elk) em vez de reescrever o diagrama.
• Palavras reservadas são correspondidas sem distinção de maiúsculas/minúsculas. Uma forma ou classe UML chamada Shape, Label, Class, Style, Link, Icon... colide com a palavra-chave (reserved field shape does not accept composite). Renomeie-a.
• Conecte chaves, não rótulos. Depois de be: Backend, Backend -> x cria uma nova forma chamada Backend. Use be -> x.
• Conexões repetidas não se mesclam; a -> b duas vezes desenha duas setas. Refira-se a elas como (a -> b)[0], (a -> b)[1].
• d2-legend é uma variável, não uma forma: coloque-a dentro de vars: { d2-legend: { ... } }. Um d2-legend: "" no nível superior é apenas uma forma comum chamada "d2-legend".
• Diagramas de sequência: ordem de declaração é a ordem na tela, atores devem ser declarados primeiro, e dentro de grupos você só pode referenciar atores que existem no nível superior.
• Tabelas SQL e classes UML: conecte linhas (orders.user_id -> users.id), e use ELK ou TALA para que as arestas caiam na linha exata.
• Formas de ponta de seta só renderizam em uma extremidade que tenha uma seta: A -> B com source-arrowhead.shape: diamond não desenha nada em A (e -- não desenha formas alguma). Inverta a aresta para que a forma fique no alvo, ou use <->.
• d2 fmt reescreve rótulos de palavras reservadas (lnk: Link vira lnk: link), e scripts/d2check.sh executa fmt em seu arquivo no lugar. Cite tais rótulos (lnk: "Link").
• Strings de bloco |md ... | terminam no próximo |. Um pipe literal dentro precisa de um delimitador maior: |md ... | ou ||md ... ||.
• Intervalos de estilo numérico são aplicados: stroke-width 0-15, opacity 0-1, font-size 8-100. text-transform aceita none|uppercase|lowercase|capitalize (o site diz title; o compilador rejeita). 3d funciona apenas em retângulo, quadrado e hexágono.
• Não adicione animated: true ou dark-theme-id a menos que solicitado. Animação implica fluxo de dados em tempo real; um tema escuro silenciosamente inverte cores para espectadores cujo SO está em modo escuro.
• Cores de preenchimento em formas substituem o tema. Prefira o tema e algumas classes; use cores explícitas apenas quando a cor carrega significado (e então adicione uma legenda).
• PNG/PDF/PPTX/GIF renderizam sem um navegador na v0.9+. Versões mais antigas (<0.8) precisam de Playwright/Chromium, que baixam no primeiro uso. Verifique d2 --version.
• TALA está incluído na v0.9 (--layout=tala) mas é não-determinístico: uma pequena mudança de rótulo pode reorganizar o layout. Fixe-o com data.tala-seeds se a reprodutibilidade for importante.
• Arquivos multi-quadro (layers/scenarios/steps) exportam SVG e PNG como diretórios (x/index.svg, x/layers/a.svg), e renderizar PNG para o mesmo nome substitui o diretório SVG. Mantenha formatos em pastas separadas (o script faz). Para uma entrega de detalhamento use PDF (uma página por quadro, clicável link: layers.x) e não desenhe formas "Voltar" manualmente: o exportador adiciona uma barra de navegação automaticamente. Veja references/composition.md.
• Arquivo de saída existente não significa sucesso. D2 pode escrever uma renderização parcial em caso de erro. Verifique o código de saída (o script faz).

Escolhendo layout, direção, tema

• Mecanismo de layout: dagre (padrão, rápido, arestas curvas) -> elk (roteamento ortogonal, melhor para arquitetura, tabelas SQL, arestas contêiner-para-contêiner) -> tala (simetria, direction por contêiner, near: objeto, top/left travados). Padrão para ELK para qualquer coisa com contêineres ou tabelas.
• Direção: right para pipelines, fluxos de solicitação e telas largas; down para hierarquias e organogramas. Escolha uma para todo o quadro.
• Tema: theme-id: 0 padrão; 4 Cool classics e 3 Flagship Terrastruct parecem modernos; 1 cinza neutro para documentos sóbrios; 8 é seguro para daltônicos; 300/301 terminal; 303 C4; 200/201 escuro. Tabela completa em references/cli-and-rendering.md.
• Coloque as configurações de renderização no arquivo para que viajem com ele:

vars: {
  d2-config: {
    layout-engine: elk
    theme-id: 4
    pad: 40
  }
}

(Flags CLI e variáveis de ambiente D2_* substituem este bloco.)

Orientação de design

• 3 a 12 formas por quadro. Além disso, divida com layers (zoom in), scenarios (variantes) ou steps (construção gradual), ou use contêineres para agrupar.
• Nomeie por chave, rotule para humanos: chaves curtas e estáveis (pg, auth), rótulos legíveis (pg: PostgreSQL).
• Rótulos de aresta são verbos ou protocolos (lê, publica, HTTPS), não frases e não o nome do alvo.
• Combine forma com significado: cylinder armazenamento, queue, person, cloud externo, diamond decisão, hexagon serviço, document/page, package, step. Não deixe tudo como retângulo.
• Cor codifica significado ou nada. No máximo ~5 categorias, aplicadas através de classes, com um d2-legend apenas quando as cores carregam informações que os rótulos não carregam.
• Um nível de abstração por quadro.
• D2 é para documentar software e sistemas em escala de quadro branco (até algumas centenas de formas). Ele deliberadamente não tem gráficos de Gantt, mapas mentais, diagramas de Venn, Sankey, gráficos de pizza/barras ou mapas geográficos, e um objeto não pode viver em dois contêineres. Diga isso e sugira outra ferramenta em vez de contorcer o D2.

Mapa de referência

Leia apenas o que a tarefa precisa.

Tarefa	Leia
Qualquer dúvida de sintaxe: chaves, rótulos, conexões, contêineres, strings, escaping, comentários, palavras-chave reservadas	references/language.md
Formas, cada chave de estilo e seu intervalo, pontas de seta, texto/markdown/LaTeX/código, ícones, posicionamento near, tamanhos, temas	references/shapes-and-styling.md
Diagramas de sequência, tabelas SQL (ERD), classes UML, grades, legendas, tooltips/links, C4	references/diagram-types.md
Classes, variáveis, globs e filtros, substituições e null, imports, modelos suspend	references/reuse-and-globs.md
Camadas, cenários, etapas, vinculação de quadros, imports para diagramas grandes, exportação multi-quadro	references/composition.md
Flags CLI, mecanismos de layout, tabela de temas, formatos de exportação, d2-config, incorporação em docs/CI, D2.js	references/cli-and-rendering.md
Padrões prontos por família de diagrama (arquitetura, fluxograma, estado, ERD, C4, organograma...)	references/recipes.md + assets/templates/*.d2
Conversão de Mermaid / PlantUML / Graphviz	references/recipes.md (seção de conversão)
Uma mensagem de erro ou um diagrama que renderiza errado	references/troubleshooting.md

Quando a compilação falha

Execute scripts/d2check.sh arquivo.d2. Erros vêm como arquivo:LINHA:COL: mensagem. Procure a mensagem em references/troubleshooting.md; os culpados usuais são citação (acima), um limite do mecanismo de layout (mude para ELK), uma forma desconhecida ou estilo fora do intervalo, e indentação de strings de bloco. Corrija um erro de cada vez e re-execute: erros posteriores são frequentemente consequências do primeiro.