SuperAPI AI Directory

d2

General & other

View repository

Updated 10-16 07:20

About this skill

D2 Diagram Skill

Generate diagrams using D2's declarative syntax. D2 produces clean, modern-looking diagrams with excellent auto-layout, nested containers, and multiple layout engines.

When to use D2:

  • Architecture diagrams with nested components (D2's container nesting is excellent)
  • Clean, modern aesthetic without manual positioning
  • User has d2 installed or prefers it
  • Network/infrastructure diagrams
  • Deployment diagrams with hierarchical grouping

When another format is better:

  • Maximum visual customization (SVG)
  • Diagrams in GitHub/GitLab markdown (Mermaid -- D2 doesn't render natively)
  • Whiteboard/sketch aesthetic (Excalidraw)
  • ER diagrams, Gantt charts (Mermaid has better support)

Consult the design-system skill for color, composition, and quality rules.

Syntax Quick Reference

Basic Connections

server -> database: query
database -> server: results
client -> server: HTTPS

Arrow types:

  • -> directed (default)
  • <-> bidirectional
  • -- undirected

Shapes and Labels

# Named with label
api: API Gateway

# Shapes
db: Database {
  shape: cylinder
}
user: User {
  shape: person
}
decision: Route? {
  shape: diamond
}
queue: Messages {
  shape: queue
}

Available shapes: rectangle (default), square, page, parallelogram, document, cylinder, queue, package, step, callout, stored_data, person, diamond, oval, circle, hexagon, cloud.

Containers (Nested)

D2's killer feature -- nested containers for hierarchy:

aws: AWS {
  vpc: VPC {
    public: Public Subnet {
      alb: Load Balancer {
        shape: hexagon
      }
    }
    private: Private Subnet {
      app: App Server
      db: Database {
        shape: cylinder
      }
      app -> db: SQL
    }
    public.alb -> private.app: HTTP
  }
}

Sequence Diagrams

shape: sequence_diagram

client: Client
server: Server
db: Database

client -> server: POST /users
server -> db: INSERT INTO users
db -> server: OK
server -> client: 201 Created

SQL Tables

users: Users {
  shape: sql_table
  id: int {constraint: primary_key}
  name: varchar
  email: varchar {constraint: unique}
}

orders: Orders {
  shape: sql_table
  id: int {constraint: primary_key}
  user_id: int {constraint: foreign_key}
  total: decimal
}

users -> orders: has many

Classes

classes: {
  UserService: {
    shape: class
    +getUser(id): User
    +createUser(data): User
    -validateEmail(email): bool
  }
}

Styling

server: Server {
  style: {
    fill: "#EFF6FF"
    stroke: "#2563EB"
    border-radius: 8
    font-color: "#1E293B"
    shadow: true
  }
}

# Connection styling
server -> db: {
  style: {
    stroke: "#64748B"
    stroke-dash: 4
  }
}

Themes

D2 has built-in themes. Set at the top of the file:

vars: {
  d2-config: {
    theme-id: 200
  }
}

Theme IDs: 0 (default), 1 (neutral grey), 3 (flagship terrastruct), 4 (cool classics), 100 (mixed berry blue), 200 (grape soda), 300 (aubergine). Dark themes: 200-302.

Layout Engines

D2 supports multiple layout engines:

Engine Best For Install
dagre (default) General purpose, fast Built-in
ELK Complex hierarchies, wide graphs Built-in
TALA Architecture diagrams (proprietary) Requires license

Set via CLI flag: d2 --layout elk diagram.d2 output.svg

Common Mistakes to Avoid

  1. Undeclared connections -- reference nodes before connecting: define a: Label before a -> b
  2. Missing colons -- labels need a colon: server: API Server not server API Server
  3. Nested path separators -- use . for nested references: aws.vpc.app not aws/vpc/app
  4. Forgetting shape -- containers don't need explicit shape; leaf nodes default to rectangle
  5. Style outside element -- styles must be inside the element block: server: { style: { ... } }
  6. Too deep nesting -- 3-4 levels max for readability

Output Format

Save as .d2 file. Render to SVG or PNG:

# Render to SVG
d2 diagram.d2 diagram.svg

# Render to PNG
d2 --format png diagram.d2 diagram.png

# Watch mode (live preview)
d2 --watch diagram.d2 diagram.svg

Setup Detection

Before generating D2, check if the user has it installed:

command -v d2 && d2 --version

If not installed, suggest:

# macOS
brew install d2

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

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

Quality Checklist

Before presenting a D2 diagram:

  • Connections reference defined nodes
  • Container nesting is max 3-4 levels deep
  • Labels are present on all connections that need explanation
  • Shapes are semantically appropriate (cylinder for DB, person for user)
  • Theme specified if not using default
  • File saves with .d2 extension