D2 Diagramming Language

D2 is a text-to-diagram language. Write .d2 files and render them to SVG/PNG via the d2 CLI or https://play.d2lang.com.

---

When to Use

• Creating architecture or system diagrams for plans and documentation
• Drawing sequence diagrams for API or workflow interactions
• Building data model diagrams with SQL table shapes
• Laying out grid-based comparison or dashboard diagrams
• Visualizing deployment topologies, state machines, or flowcharts

---

Quick Reference

Concept	Syntax
Shape	name or name: Label
Connection	a -> b or a -> b: label
Reverse / bidirectional	a <- b / a <-> b
Line (no arrow)	a -- b
Container	parent: { child1; child2 }
Dot nesting	parent.child.grandchild
Set shape type	name.shape: oval
Style	name.style.fill: "#ff0000"
Icon	name.icon: https://url/icon.svg
Tooltip	name.tooltip: hover text
Link	name.link: https://example.com
Class	classes: { c: { style: {...} } } then name.class: c
Variable	vars: { k: v } then ${k}
Direction	direction: right
Comment	# single line comment
SQL table	name.shape: sql_table then col: type {constraint: pk}
Sequence diagram	name.shape: sequence_diagram
Grid	name.grid-rows: 3 or name.grid-columns: 3
Layers	layers: { name: { ... } }
Scenarios	scenarios: { name: { ... } } (inherits parent)
Steps	steps: { 1: { ... } 2: { ... } } (each inherits previous)
Import	a: @file or ...@file (spread)
Glob	*.style.fill: red / **.style.fill: red
Null (delete)	x: null / (a -> b)[0]: null

---

Core Syntax

Shapes

Any identifier becomes a shape. The default shape is rectangle.

server
database: My Database
api: API Gateway {
  shape: hexagon
}

All shape types: rectangle, square, page, parallelogram, document, cylinder, queue, package, step, callout, stored_data, person, diamond, oval, circle, hexagon, cloud, text, code, class, sql_table, image, sequence_diagram, c4-person.

Connections

a -> b: request
b -> a: response
a <-> b: bidirectional
a -- b: line (no arrowhead)

# Multiple connections between same shapes are indexed
a -> b: first   # (a -> b)[0]
a -> b: second  # (a -> b)[1]

Connection References

Style existing connections by referencing them:

a -> b: request
(a -> b)[0].style.stroke: red
(a -> b)[0].style.stroke-dash: 5

Arrowheads

a -> b: {
  source-arrowhead: 1 {
    shape: diamond
  }
  target-arrowhead: * {
    shape: cf-many
  }
}

Arrowhead shapes: triangle (default), arrow, diamond, circle, cf-one, cf-many, cf-one-required, cf-many-required.

Containers (Nesting)

cloud: AWS {
  vpc: VPC {
    subnet: Private Subnet {
      ec2: Web Server
      db: Database {
        shape: cylinder
      }
    }
  }
}

# Dot notation shorthand
cloud.vpc.subnet.ec2 -> cloud.vpc.subnet.db: query

Labels and Text

# Markdown labels
explanation: |md
  # Architecture Overview
  This system uses **microservices**.
|

# Code blocks
snippet: |go
  func main() {
    fmt.Println("hello")
  }
|

# LaTeX
formula: |latex
  \\frac{n!}{k!(n-k)!}
|

Direction

Controls layout flow. Values: up, down (default), left, right.

direction: right
a -> b -> c

Null (Deletion)

Remove shapes, connections, or attributes:

x: {style.fill: red}
x.style.fill: null    # remove fill
x: null                # remove shape entirely
(a -> b)[0]: null      # remove connection

Comments

# This is a comment
server  # Inline comment

"""
This is a block comment
spanning multiple lines
"""

---

Positions (near)

Position items at fixed points around the diagram:

title: Architecture Overview {
  shape: text
  near: top-center
  style.font-size: 28
}

legend: {
  near: bottom-right
}

Values: top-left, top-center, top-right, center-left, center-right, bottom-left, bottom-center, bottom-right.

Label/icon positioning (additional values):

node: {
  label.near: outside-top-center
  icon: https://icons.terrastruct.com/aws/Compute/Amazon-EC2.svg
  icon.near: outside-left-center
}

Extra values for label/icon: outside-top-left, outside-top-center, outside-top-right, outside-left-center, outside-right-center, outside-bottom-left, outside-bottom-center, outside-bottom-right.

---

Dimensions

node: {
  width: 200
  height: 100
}

Cannot be set on containers (they resize to fit children).

---

Configuration via Vars

vars: {
  d2-config: {
    theme-id: 4
    dark-theme-id: 200
    pad: 50
    center: true
    sketch: true
    layout-engine: elk
  }
}

Layout engines: dagre (default, free), elk (free, more features), tala (premium).

---

Resource Files

For detailed guidance, read these on-demand:

• shapes-and-connections.md — Complete shape catalog, connection types, arrowheads
• styling-and-layout.md — All style properties, classes, themes, layout engines
• special-diagrams.md — Sequence diagrams, grid layouts, SQL tables, class diagrams
• composition-and-advanced.md — Vars, globs, imports, layers, scenarios, steps

---

Input / Output

This skill defines no input parameters or structured output.