d2-diagram

What this skill does

# D2 Diagram Creation Skill

## Overview

Generate clear, well-structured, and visually appealing D2 diagrams from textual descriptions. D2 is a modern diagram scripting language that transforms text into professional diagrams with support for icons, styling, containers, and multiple layout options.

## When to Use This Skill

Use this skill when:
- Creating system architecture diagrams
- Visualizing data flows or processes
- Drawing network topologies
- Illustrating software component relationships
- Creating flowcharts or decision trees
- Designing database schemas
- Showing microservices architectures
- Any request involving "create a diagram," "visualize," "draw," or "show relationships"

## Prerequisites

**CRITICAL**: Before creating any diagram, read the reference files to understand D2 syntax and available icons:
1. Read `references/d2_syntax_reference.md` for syntax patterns and examples
2. Read `references/d2_validated_icons_list.md` for available icon URLs

## Diagram Creation Workflow

### Step 1: Analyze the Requirements

Carefully review the provided description to identify:

1. **Core Components**: What are the main elements/entities?
2. **Relationships**: How do components connect or interact?
3. **Hierarchy**: Are there groupings or containers?
4. **Flow Direction**: What's the logical flow (left-to-right, top-to-bottom)?
5. **Special Requirements**: Styling, colors, icons, or specific visual needs?

**Example Analysis:**

Request: "Create a diagram showing a web application with users connecting to a load balancer, which distributes traffic to multiple app servers. The app servers connect to a database."

Analysis:
- Core: Users, Load Balancer, App Servers, Database
- Relationships: Users → Load Balancer → App Servers → Database
- Hierarchy: Could group app servers together
- Direction: Left-to-right flow
- Shapes: person for users, hexagon for load balancer, rectangles for servers, cylinder for database

### Step 2: Design the Structure

Create a mental model of the diagram structure:

1. **Identify Central Element**: Place the most important component centrally
2. **Plan Containers**: Group related elements together
3. **Arrange Flow**: Position elements to show natural progression
4. **Consider Symmetry**: Balance the layout for visual appeal

### Step 3: Select Shapes and Icons

Choose appropriate shapes and icons for each element:

**Shape Selection Guidelines:**
- `person` - Users, people, actors
- `cylinder` - Databases, data storage
- `hexagon` - Gateways, processors, services
- `cloud` - Cloud services, external systems
- `rectangle` - Default for most components, servers, applications
- `diamond` - Decision points, conditionals
- `circle` - Start/end points, events
- `queue` - Message queues, buffers
- `stored_data` - Data stores, caches

**Icon Selection:**
- Consult `references/d2_validated_icons_list.md` for available icons
- Match icons to component type (e.g., AWS Lambda for serverless functions)
- Use `shape: image` to display icon without border
- If no suitable icon exists, use appropriate shape with clear labeling

### Step 4: Apply Styling

Create consistent visual appearance:

1. **Define Classes**: Create reusable styles for similar components
2. **Use Color Coding**: Apply colors to distinguish different types or states
3. **Add Visual Hierarchy**: Use size, color, and positioning to show importance
4. **Maintain Consistency**: Apply uniform styling to similar elements

**Styling Best Practices:**
```d2
classes: {
  primary_service: {
    style.fill: "#4A90E2"
    style.stroke: "#2E5C8A"
    style.stroke-width: 2
  }
  
  database_style: {
    shape: cylinder
    style.fill: "#48C774"
    style.multiple: true
  }
}
```

### Step 5: Construct the Diagram

Build the diagram following D2 syntax:

1. **Start with Direction**: Set overall flow direction
2. **Define Core Elements**: Create main shapes with labels
3. **Add Containers**: Group related components
4. **Create Connections**: Link elements with appropriate arrows
5. **Apply Styling**: Add colors, icons, and visual properties
6. **Add Notes**: Include explanatory text where helpful

### Step 6: Review and Refine

Before finalizing:

**Quality Checklist:**
- [ ] All components clearly labeled
- [ ] Connections properly directed and labeled
- [ ] Appropriate shapes/icons used
- [ ] Consistent styling applied
- [ ] Logical flow is evident
- [ ] No overlapping or cluttered elements
- [ ] Container groupings make sense
- [ ] Icons are from validated list
- [ ] Overall layout is balanced

## Creating Specific Diagram Types

### System Architecture

```d2
direction: right

classes: {
  service: {
    style.fill: "#4A90E2"
    style.stroke: "#2E5C8A"
  }
  
  db: {
    shape: cylinder
    style.fill: "#48C774"
  }
}

users: Users {
  shape: person
  icon: https://icons.terrastruct.com/essentials/365-user.svg
}

frontend: Frontend {
  class: service
  icon: https://icons.terrastruct.com/tech/react.svg
}

backend: Backend Services {
  api: API Gateway {
    class: service
    icon: https://icons.terrastruct.com/aws/Networking%20&%20Content%20Delivery/Amazon-API-Gateway.svg
  }
  
  auth: Auth Service {
    class: service
  }
  
  data: Data Service {
    class: service
  }
}

database: PostgreSQL {
  class: db
  icon: https://icons.terrastruct.com/tech/postgresql.svg
}

users -> frontend: Access
frontend -> backend.api: REST API
backend.api -> backend.auth: Authenticate
backend.api -> backend.data: Fetch Data
backend.data -> database: Query
```

### Data Flow Diagram

```d2
direction: right

source: Data Source {
  shape: cylinder
  style.fill: "#E8F5E9"
  style.multiple: true
}

ingestion: Data Ingestion {
  shape: hexagon
  style.fill: "#FFF9C4"
}

processing: Data Processing {
  transform: Transform
  validate: Validate
  enrich: Enrich
  
  style.fill: "#E3F2FD"
}

storage: Data Warehouse {
  shape: stored_data
  style.fill: "#F3E5F5"
}

analytics: Analytics Layer {
  shape: rectangle
  style.fill: "#FCE4EC"
}

viz: Visualization {
  shape: page
  icon: https://icons.terrastruct.com/essentials/dashboard.svg
}

source -> ingestion: Extract {
  style.stroke: "#4CAF50"
  style.stroke-width: 2
}

ingestion -> processing.transform: Raw Data {
  style.animated: true
}

processing.transform -> processing.validate
processing.validate -> processing.enrich

processing.enrich -> storage: Store {
  style.stroke: "#2196F3"
  style.stroke-width: 2
}

storage -> analytics: Query
analytics -> viz: Display
```

### Network Topology

```d2
direction: down

internet: Internet {
  shape: cloud
  icon: https://icons.terrastruct.com/essentials/214-worldwide.svg
}

firewall: Firewall {
  shape: hexagon
  style.fill: "#FF5252"
  icon: https://icons.terrastruct.com/infra/firewall.svg
}

dmz: DMZ {
  direction: right
  
  lb: Load Balancer {
    shape: hexagon
    icon: https://icons.terrastruct.com/infra/load-balancer.svg
  }
  
  web1: Web Server 1 {
    shape: rectangle
  }
  
  web2: Web Server 2 {
    shape: rectangle
  }
  
  style.fill: "#FFF3E0"
}

internal: Internal Network {
  direction: right
  
  app1: App Server 1
  app2: App Server 2
  
  db: Database Cluster {
    shape: cylinder
    style.multiple: true
    icon: https://icons.terrastruct.com/tech/postgresql.svg
  }
  
  style.fill: "#E8F5E9"
}

internet -> firewall
firewall -> dmz.lb
dmz.lb -> dmz.web1
dmz.lb -> dmz.web2
dmz.web1 -> internal.app1
dmz.web2 -> internal.app2
internal.app1 -> internal.db
internal.app2 -> internal.db
```

### Microservices Architecture

```d2
direction: right

classes: {
  service: {
    shape: rectangle
    style.fill: "#E3F2FD"
    style.stroke: "#1976D2"
  }
  
  database: {
    shape: cylinder
    style.fill: "#C8E6C9"
  }
  
  queue: {
    shape: queue
    style.fill: "#FFF9C4"
  }
}

users: Users {
  shape: person
}

gateway: API Gateway {
  shape: hexagon
  style.fill: "#B39DDB"
}

services: Microservices {
  user_service: User Service {
    class: service
  }
  
  order_service: Or