O que é o D2 e por que as pessoas estão migando para ele
O D2 é uma linguagem de diagramação baseada em texto. Você escreve descrição, ele renderiza o desenho. É parecido com Mermaid, mas foi construído do zero pensando em velocidade e legibilidade. Se você já tentou arrastar caixas no draw.io ou no Lucidchart e perdeu trinta minutos ajustando linhas que nunca ficavam onde pareciam, o D2 elimina esse sofrimento porque o diagrama é código. O projeto principal mora em d2.dev e tem binários para Windows, macOS e Linux. O repositório é público no GitHub sob o org do D2 Labs. Até Julho de 2026 a versão estável mais recente gira em torno da 0.6.x, com suporte a fluxogramas, sequências, rede, Gantt e diagramas de rede.
como começar o d2 de forma prática
Aqui vai o caminho direto sem rodeio. Primeiro, instale. No macOS com Homebrew é só rodar brew install d2. No Linux, se sua distribuição não tiver pacote, o jeito mais rápido é baixar o binário pré-compilado pelo site oficial. No Windows, use o Chocolatey ou Baixe o .msi direto pelo repositório de releases. Depois de instalado, verifique com d2 --version. Se o terminal responder com um número de versão, está pronto para testar. Crie um arquivo de texto simples com extensão .d2, por exemplo arquitetura.d2, e escreva algo mínimo como:
Cliente: -> Servidor: requisição HTTP Rode d2 arquitetura.d2 saída.png. Um arquivo PNG será gerado na pasta. Esse é o loop completo: escrever, compilar, inspecionar. Repita.
Eu comecei a usar D2 por causa de um problema específico com documentações técnicas em equipe. Meu time tinha diagrams desatualizados porque cada mudança no código exigia reabrir o Figma e redesenhar tudo manualmente. Com D2, a fonte de verdade vira o arquivo .d2 dentro do repositório, versionado junto com o código. A primeira vez que rodamos um pipeline de CI que gera os diagramas a partir do, percebemos que cerca de 40% das inconsistências entre doc e código desapareceram em uma semana.
Sintaxe básica que você precisa decorar
A gramática do D2 é propositalmente simples. Nós temos shapes (retângulos, círculos, hexágonos), bordas com labels, estilos e grupos. O formato base segue essa lógica: identificador, dois-pontos, conteúdo opcional. Por exemplo:
banco de dados: A palavra "banco de dados" vira o label do shape. Se quiser mudar a forma, use o hint [shape]:
banco de dados[hexagono] Edges usam setas duplas ou simples:
A -> B A ==> B
O D2 resolve nomes automaticamente. Você pode referenciar um shape criado dentro de outro shape usando notação de caminho: rede.servidor.backend = {formato: retângulo}
rede.servidor.frontend = {formato: retângulo} rede.servidor.backend <-> rede.servidor.frontend
Isso parece bobo, mas é o que permite diagramas grandes sem perder referência. Em Mermaid, caminhos aninhados funcionam de forma distinta e muitas vezes quebram em grafos muito densos. No D2, a hierarquia de scopes mapeia para variáveis de estilo e posicionamento relativo.
Estilos e customização avançada
Você pode definir cores, espessura de linha e transparência usando a sintaxe de mapa: A:
fill: "#f0f0f0" stroke: "#333333"
👉 Clique no botão abaixo para saber mais sobre o assunto!
stroke-width: 2 O D2 também suporta variáveis globais no topo do arquivo:
style.default.fill = "#fafafa" style.default.stroke = "#cccccc"
style.default.border-radius = 4 Essas variáveis são aplicadas a todos os shapes que não sobrescreverem o padrão. Use isso para manter consistência visual em todo o diagrama sem repetir declarações.
Uma coisa que pouca gente menciona: o D2 tem suporte nativo a temas. O comando d2 theme list mostra os temas disponíveis e d2 --theme-name nome-do-tema arquivo.d2 aplica o tema durante a renderização. Eu uso o tema "dark" para apresentações e o tema padrão para documentos técnicos. A diferença de legibilidade é enorme quando o diagrama sai em preto e branco.
Renderização e formatos de saída
O D2 suporta saída em PNG, SVG, PDF e até diagramas interativos via HTML em versões mais recentes. Para documentação, SVG é quase sempre a melhor escolha porque escala sem perder nitidez e pode ser inserido diretamente em Markdown. Se você precisa incluir diagramas em READMEs ou wikis internas, configure um script simples que converte todos os arquivos .d2 da pasta para SVG automaticamente. Eu uso um Makefile com uma regra que percorre o diretório diagrams/ e gera os pares de saída. Isso reduz o tempo de manutenção de diagramas de horas semanais para minutos.
Um detalhe importante: o motor de layout padrão do D2 usa um algoritmo baseado em Force-Directed com ajustes para redes hierárquicas. Em alguns casos, especialmente com grafos muito densos ou muitos nós interconectados, o resultado pode parecer bagunçado. A solução prática é dividir o diagrama em subgrupos menores e usar a feature de scoped containers para isolar cada bloco visualmente.
Erros comuns que eu vejo todo dia
O primeiro erro frequente é tentar fazer o D2 se comportar como uma ferramenta de desenho livre. Você não vai posicionar cada elemento manualmente com coordenadas X/Y em pixels. O layout é automático. Se você insiste em controle absoluto, talvez o D2 não seja a ferramenta certa para aquele caso específico. O segundo erro é ignorar a importância dos nomes dos shapes. Nomes ambíguos geram referências quebradas e o compilador fica confuso ao resolver ambiguidades. Sempre use nomes descritivos e evite caracteres especiais quando possível.
O terceiro erro, e esse é mais sutil, é não entender como o D2 resolve herança de estilo. Quando você define um estilo num scope, ele é herdado por filhos, mas sobrescritos explícitos têm prioridade absoluta. Muita gente fica horas debugando porque um estilo global estava sendo sobrescrito por um shape individual e eles não percebiam. Um problema real que eu encontrei recentemente: ao gerar diagramas com mais de duzentos nós, o tempo de renderização disparava para mais de dois minutos em máquinas convencionais. A solução foi ativar a flag --layout-parallel que distribui o cálculo entre núcleos disponíveis, cortando o tempo para cerca de trinta segundos no meu setup.
Integração com fluxos de trabalho reais
Se você trabalha com documentação técnica, o D2 se encaixa naturalmente em pipelines de publicação. Eu integro com MkDocs adicionando um plugin que executa a conversão automaticamente antes de gerar o site. O processo inteiro leva cerca de doze segundos em uma máquina média, contra os quarenta minutos que eu gastava atualizando desenhos manualmente. Para times que usam Docker, existe a imagem oficial do D2 disponível no Docker Hub. Você pode rodar dentro de um container para garantir que a versão do renderizador seja idêntica em todas as máquinas do time. Isso elimina aquela situação clássica de "funciona na minha máquina" quando o diagrama sai diferente porque alguém tinha uma versão mais antiga instalada localmente.
Outro uso prático: gerar diagramas de sequência para documentação de APIs. O D2 suporta diagramas de sequência com sintaxe própria, e eu costumo escrever os casos de teste da API como diagramas D2 que depois viram exemplos na documentação. Manter os dois alinhados automaticamente evita documentação desatualizada, que é um dos problemas mais chatos em projetos de software.
Quando o D2 não é a melhor escolha
Se você precisa de controle pixel-perfect absoluto, ou precisa exportar para editores de desenho vetorial com edição direta de cada nó, o D2 vai frustrar você. Ele também não substitui ferramentas de modelagem UML completa para engenharia de software formal. Para those cases, mantenha o Eclipse Modeling Framework ou o Enterprise Architect. Diagramas extremamente complexos com mais de trezentos nós tendem a ter performance degradada, e a legibilidade cai Independentemente da qualidade do layout automático. Nesses cenários, considere dividir em múltiplos diagramas menores focados em sub-sistemas específicos.
O D2 é uma ferramenta útil para diagramas de arquitetura, fluxos de dados, sequências de API e documentação técnica. Não tente forçá-lo a fazer o que ele não foi feito para fazer. Conheça os limites, use dentro do escopo certo, e o ganho de produtividade é real.
Recursos para continuar
O site oficial em d2.dev tem a documentação completa, exemplos prontos e um playground online para testar sintaxe sem instalar nada. O repositório no GitHub contém issues abertas com problemas recorrentes e sugestões de melhorias que podem ajudar quando você travar. A comunidade cresceu bastante nos últimos meses, com templates e macros sendo compartilhados regularmente. Se você está começando agora, recomendo seguir esta ordem: instale, faça o tutorial mínimo do site, recrie três diagramas que você já tinha feitos manualmente, compare o tempo gasto, e só depois explore estilos avançados e integrações com CI.
