D2: The New Standard for Declarative Diagramming
Table of Contents
Documentation has always been the Achilles’ heel of software engineering. We love writing code, but we dread maintaining the diagrams that explain it. Binary images (JPEGs, PNGs) go stale the moment a refactor happens, and traditional GUI-based drawing tools feel disconnected from our version-control workflows.
This friction gave birth to the Diagram-as-Code (DaC) movement. While early pioneers like Graphviz and PlantUML laid the groundwork, they often produced visuals that looked more like 1990s academic papers than modern architecture docs.
Enter D2 (Declarative Diagramming). Created by the team at Terrastruct, D2 is designed to be the modern, engineer-friendly successor to the diagramming tools of the past. Let’s unpack why it exists, how it works, and why it might be the last diagramming tool you’ll ever need to learn.
The Genesis: Why D2?
Terrastruct, a company specializing in architecture visualization, noticed a recurring problem: existing open-source tools required developers to choose between simplicity and capability.
- The Aesthetic Gap: Tools like Graphviz and PlantUML are powerful but produce diagrams with dated defaults. Engineers spent more time fighting with CSS-like overrides than actually modeling their systems.
- Syntax Friction: Many older tools use verbose, keyword-heavy syntax that feels more like programming in an esoteric language than writing a declaration.
- Layout Engine Bottlenecks: Most tools rely on the same few open-source layout engines (like Dagre), which often struggle with complex nested containers or edge crossings in large-scale software architectures.
D2 was built to solve these “pain points” by prioritizing modern defaults, a clean syntax inspired by Go and CSS, and a specialized layout engine called TALA (proprietary but integrated with D2) that handles nested structures with unparalleled grace.
A Brief History
- July 2022: Terrastruct introduces D2 in alpha as a core component of their “D2 Studio” platform.
- November 2022: The D2 language and its CLI are officially open-sourced under the MPL 2.0 license. The goal was to establish D2 as a portable, vendor-neutral standard for diagramming.
- 2023–2025: The ecosystem exploded. D2 added “Sketch mode” (for that hand-drawn whiteboard look), interactive tooltips, SQL table support, and native integration into major IDEs like VS Code and Vim.
D2 in Action: The Syntax
The beauty of D2 lies in its readability. You don’t “draw” nodes; you declare relationships.
Basic Connections
A simple connection is as easy as two labels and an arrow:
User -> Web Server: Auth Request
Web Server -> Database: Query
Database -> Web Server: User Profile
Web Server -> User: Welcome!Containers and Nesting
One of D2’s strongest features is how it handles nested groups. In other tools, this often requires complex “subgraph” definitions. In D2, it’s just a block:
Cloud Provider: {
Region A: {
Load Balancer
API Service
}
Region B: {
Backup Service
}
}
Cloud Provider.Region A.API Service -> Cloud Provider.Region B.Backup Service: SyncModern Styling
D2 treats styling as a first-class citizen. You can apply themes or specific styles using a syntax that feels very familiar to anyone who has touched CSS:
My Node: {
style: {
stroke: "#7c3aed"
fill: "#f5f3ff"
stroke-width: 4
border-radius: 8
}
}Why D2 Wins for Engineers
- Single Binary (Go): D2 is written in Go. It’s a single, fast binary with no heavy dependencies like the Java Virtual Machine (PlantUML) or complex JavaScript runtimes.
- Modern Defaults: Diagrams look presentation-ready out of the box. You don’t need to style them, but you can if you want to.
- Layout Variety: D2 supports multiple layout engines. You can use the built-in Dagre, the academic ELK engine, or the ultra-refined TALA engine for complex architectures.
- Developer Experience (DX): Features like
d2 fmt(auto-formatter) and a built-in watch mode (d2 --watch) make the feedback loop between writing code and seeing a diagram near-instant.
The Trade-offs
No tool is perfect. While D2 is open-source, its most advanced layout engine (TALA) is a proprietary offering from Terrastruct. While the open-source engines (Dagre, ELK) are excellent for 90% of use cases, the absolute best layout performance currently requires a TALA subscription.
Additionally, because D2 is newer than tools like Mermaid, browser-native support (like rendering directly in a GitHub README) is still evolving through browser extensions and CI/CD actions rather than native platform integrations.
Conclusion
D2 represents a paradigm shift in how we approach technical documentation. It eliminates the friction of maintaining diagrams, makes architecture visual, and ensures that visual docs can be versioned, reviewed, and updated exactly like source code.
By treating diagrams as a declarative language rather than a drawing task, D2 bridges the gap between development and design—creating documentation that stays alive, stays accurate, and stays elegant.