d2-diagrams

D2 Diagrams

Expert in generating diagrams from declarative text definitions using D2 - a modern diagram scripting language.

When to Use This Skill

Use this skill when...	Use Mermaid instead when...
Rich styling with classes and themes	Embedding diagrams in GitHub Markdown
Complex nested container layouts	Simple flowcharts with minimal styling
Architecture diagrams with icons	Diagrams that render natively in docs platforms
Decision trees with colored edges	Sequence diagrams (Mermaid has richer syntax)
SQL table / ERD diagrams	Wide tool support is a priority

For a detailed feature comparison, see REFERENCE.md.

Core Expertise

• Declarative syntax: Describe what to diagram, D2 handles the layout
• Multiple layout engines: dagre (default), elk, tala (premium)
• Rich theming: 100+ built-in themes with dark mode support
• Multiple outputs: SVG, PNG, PDF, GIF (animated)
• Watch mode: Auto-regenerate on file changes

Installation

# mise (preferred)
mise install d2 && mise use -g d2

# macOS
brew install d2

# Linux/Windows (via curl)
curl -fsSL https://d2lang.com/install.sh | sh -s --

# Go install
go install oss.terrastruct.com/d2@latest

Essential Commands

Basic Rendering

# Convert to SVG (default)
d2 diagram.d2 diagram.svg

# Convert to PNG
d2 diagram.d2 diagram.png

# Convert to PDF
d2 diagram.d2 diagram.pdf

# Output to stdout
d2 diagram.d2 -

PNG prerequisite: The first PNG render downloads a bundled Chromium (~140 MB). Expect ~1 min delay on the initial run; subsequent renders are fast.

Watch Mode

# Watch and auto-regenerate
d2 --watch diagram.d2 diagram.svg

# Watch with browser preview
d2 --watch --browser diagram.d2

Theming

# List available themes
d2 themes

# Use specific theme (by ID)
d2 -t 101 diagram.d2 output.svg

# Dark theme (respects system preference)
d2 --dark-theme 200 diagram.d2 output.svg

# Combine light and dark themes
d2 -t 1 --dark-theme 200 diagram.d2 output.svg

Layout Engines

# List available layouts
d2 layout

# Use specific layout
d2 -l elk diagram.d2 output.svg
d2 -l dagre diagram.d2 output.svg

Sketch Mode

# Hand-drawn style
d2 --sketch diagram.d2 output.svg

D2 Syntax

Basic Shapes and Connections

# Shapes (auto-created)
server
database
client

# Connections
client -> server: request
server -> database: query
database -> server: result
server -> client: response

# Bidirectional
a <-> b

# Undirected
a -- b

Shape Types

# Explicit shapes
rect: {shape: rectangle}
oval: {shape: oval}
cyl: {shape: cylinder}
queue: {shape: queue}
pkg: {shape: package}
step: {shape: step}
page: {shape: page}
doc: {shape: document}
cloud: {shape: cloud}
diamond: {shape: diamond}
hex: {shape: hexagon}
para: {shape: parallelogram}
circle: {shape: circle}

Containers (Nesting)

server: {
  app: Application
  db: Database
  app -> db
}

client -> server.app

Labels and Icons

# Labels
a: "My Label"
a -> b: "connection label"

# Icons (from icon packs)
server: {
  icon: https://icons.terrastruct.com/essentials/004-server.svg
}

# Tooltip
node: {
  tooltip: Additional information shown on hover
}

# Links
github: {
  link: https://github.com
}

Styling

# Inline styles
styled: {
  style: {
    fill: "#ff6b6b"
    stroke: "#c92a2a"
    stroke-width: 2
    border-radius: 8
    shadow: true
    opacity: 0.9
    font-color: white
  }
}

# Connection styles
a -> b: {
  style: {
    stroke: red
    stroke-width: 3
    stroke-dash: 5
    animated: true
  }
}

Glob Patterns

# Style all shapes
*: {
  style.fill: lightblue
}

# Style all connections
* -> *: {
  style.stroke: gray
}

Classes (Reusable Styles)

Define named style sets and apply them to multiple nodes/edges.

classes: {
  error: {
    style: {
      fill: "#ffebee"
      stroke: "#c62828"
      font-color: "#c62828"
      border-radius: 8
    }
  }
  success: {
    style: {
      fill: "#e8f5e9"
      stroke: "#2e7d32"
      font-color: "#2e7d32"
      border-radius: 8
    }
  }
  decision: {
    shape: diamond
    style: {
      fill: "#fff3e0"
      stroke: "#e65100"
      font-color: "#e65100"
    }
  }
}

# Apply a class
start: Start {class: success}
check: Valid? {class: decision}
fail: Error {class: error}

start -> check
check -> fail: No

Variables

vars: {
  primary-color: "#4a90d9"
}

box: {
  style.fill: ${primary-color}
}

Configuration in File

vars: {
  d2-config: {
    layout: elk
    theme: 4
    dark-theme: 200
    pad: 20
    sketch: true
  }
}

# Diagram content
a -> b -> c

Common Diagram Patterns

System Architecture

direction: right

client: Client {
  icon: https://icons.terrastruct.com/essentials/user.svg
}

lb: Load Balancer {
  icon: https://icons.terrastruct.com/aws/Networking%20&%20Content%20Delivery/Elastic%20Load%20Balancing.svg
}

services: Services {
  api: API Server
  auth: Auth Service
  api -> auth: validate
}

data: Data Layer {
  db: PostgreSQL {
    shape: cylinder
  }
  cache: Redis {
    shape: cylinder
  }
}

client -> lb -> services.api
services.api -> data.db
services.api -> data.cache

Sequence-like Flow

direction: right

user: User
frontend: Frontend
api: API
db: Database

user -> frontend: 1. Click button
frontend -> api: 2. POST /action
api -> db: 3. INSERT
db -> api: 4. OK
api -> frontend: 5. 200 OK
frontend -> user: 6. Show success

Decision Tree / Flowchart

Uses classes for consistent styling, diamond shapes for decisions, and colored edges for Yes/No paths.

classes: {
  decision: {
    shape: diamond
    style: {
      fill: "#fff3e0"
      stroke: "#e65100"
      font-color: "#e65100"
    }
  }
  action: {
    shape: rectangle
    style: {
      fill: "#e3f2fd"
      stroke: "#1565c0"
      font-color: "#1565c0"
      border-radius: 8
    }
  }
  terminal: {
    shape: oval
    style: {
      fill: "#e8f5e9"
      stroke: "#2e7d32"
      font-color: "#2e7d32"
    }
  }
  warn: {
    shape: hexagon
    style: {
      fill: "#ffebee"
      stroke: "#c62828"
      font-color: "#c62828"
    }
  }
}

start: Start {class: terminal}
staged: Staged changes? {class: decision}
lint: Run linter {class: action}
pass: Lint pass? {class: decision}
commit: Create commit {class: action}
done: Done {class: terminal}
fix: Fix issues {class: warn}

start -> staged
staged -> lint: Yes {style.stroke: green}
staged -> done: No {style.stroke: red}
lint -> pass
pass -> commit: Yes {style.stroke: green}
pass -> fix: No {style.stroke: red}
fix -> lint
commit -> done

For additional patterns (Database ERD, Kubernetes Deployment), special shapes (sql_table, class, code blocks), layers, theme categories, and a full D2 vs Mermaid comparison, see REFERENCE.md.

Agentic Optimizations

Context	Command
Quick SVG	d2 diagram.d2 diagram.svg
Live preview	d2 --watch --browser diagram.d2
Dark theme	d2 --dark-theme 200 diagram.d2 output.svg
Sketch style	d2 --sketch diagram.d2 output.svg
ELK layout	d2 -l elk diagram.d2 output.svg
List themes	d2 themes
PNG export	d2 --scale 2 diagram.d2 output.png

Quick Reference

Flag	Description
-w, --watch	Watch and regenerate on changes
--browser	Open browser preview (with --watch)
-t, --theme	Theme ID (run d2 themes for list)
--dark-theme	Dark mode theme ID
-l, --layout	Layout engine: dagre, elk, tala
--sketch	Hand-drawn style
--scale	Output scale factor (e.g. 2 for 2x resolution)
--pad	Diagram padding in pixels
--center	Center the diagram
--animate-interval	Animation frame interval (ms)
-h, --help	Show help