d2-diagram

# 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: Order Service {
    class: service
  }
  
  payment_service: Payment Service {
    class: service
  }
  
  notification_service: Notification Service {
    class: service
  }
}

queues: Message Queues {
  order_queue: Order Queue {
    class: queue
  }
  
  notification_queue: Notification Queue {
    class: queue
  }
}

databases: Databases {
  user_db: User DB {
    class: database
  }
  
  order_db: Order DB {
    class: database
  }
  
  payment_db: Payment DB {
    class: database
  }
}

users -> gateway
gateway -> services.user_service
gateway -> services.order_service
gateway -> services.payment_service

services.user_service -> databases.user_db
services.order_service -> databases.order_db
services.payment_service -> databases.payment_db

services.order_service -> queues.order_queue: Publish
services.payment_service -> queues.order_queue: Subscribe

services.notification_service -> queues.notification_queue: Subscribe
```

## Best Practices

### Clarity and Simplicity

1. **Start Simple**: Begin with core elements, add complexity gradually
2. **Use Descriptive Labels**: Choose clear, informative names for all components
3. **Limit Complexity**: If diagram becomes cluttered, split into multiple diagrams or use layers
4. **Show Key Relationships**: Focus on important connections, omit trivial ones

### Visual Design

1. **Consistent Styling**: Apply uniform styles to similar component types using classes
2. **Color Coding**: Use colors purposefully to distinguish types or states
3. **Appropriate Shapes**: Match shapes to what they represent
4. **Balance Layout**: Distribute elements evenly, avoid crowding
5. **Direction Matters**: Choose flow direction that matches natural reading or process flow

### Icons and Shapes

1. **Verify Icon URLs**: Only use icons from `references/d2_validated_icons_list.md`
2. **Use Icons Sparingly**: Too many icons can clutter; use for key components
3. **Consistent Icon Style**: Stick to one icon set (e.g., all AWS, all tech icons)
4. **Fallback to Shapes**: If no suitable icon, use appropriate shape with label

### Containers and Grouping

1. **Logical Grouping**: Group related components together
2. **Nested Containers**: Use for hierarchical structures
3. **Clear Boundaries**: Make container purposes obvious through naming
4. **Avoid Over-Nesting**: Too many levels makes diagrams hard to read

### Connections

1. **Label Important Connections**: Add labels to clarify relationships
2. **Use Appropriate Arrows**: Choose arrow types that match relationship
3. **Connection Styling**: Style connections to show different types or states
4. **Avoid Crossing Lines**: Minimize connection crossings for clarity

## Common Pitfalls to Avoid

### ❌ Don't Use Fake Icon URLs

**Wrong:**
```d2
server: {
  icon: https://example.com/fake-icon.svg  # This will fail
}
```

**Right:**
```d2
server: {
  icon: https://icons.terrastruct.com/tech/docker.svg  # Verified URL
  shape: image
}
```

Or use a shape without an icon:
```d2
server: {
  shape: rectangle
}
```

### ❌ Don't Over-Complicate

**Wrong:**
```d2
# Too many nested levels
system.layer1.layer2.layer3.layer4.component
```

**Right:**
```d2
# Clear, manageable hierarchy
system: {
  frontend
  backend
  database
}
```

### ❌ Don't Forget Direction

**Wrong:**
```d2
# No direction specified, layout may be suboptimal
A -> B -> C -> D
```

**Right:**
```d2
direction: right  # Clear flow direction
A -> B -> C -> D
```

### ❌ Don't Mix Styling Approaches

**Wrong:**
```d2
# Inconsistent styling
element1: {
  style.fill: "#FF0000"
}

element2: {
  style.fill: "#00FF00"
}

element3: {
  style.fill: "#0000FF"
}
```

**Right:**
```d2
# Consistent styling with classes
classes: {
  primary: {
    style.fill: "#4A90E2"
  }
}

element1: { class: primary }
element2: { class: primary }
element3: { class: primary }
```

## Advanced Techniques

### Layout Optimization

```d2
vars: {
  d2-config: {
    layout-engine: elk  # Try 'elk' for better hierarchical layouts
    pad: 50             # Adjust padding
  }
}

# Use direction to control flow
direction: right

# Use grid for structured layouts
grid_container: {
  grid-rows: 2
  grid-columns: 3
  
  item1; item2; item3
  item4; item5; item6
}
```

### Reusable Styles with Classes

```d2
classes: {
  critical: {
    style.fill: "#FF5252"
    style.stroke: "#D32F2F"
    style.stroke-width: 3
  }
  
  normal: {
    style.fill: "#4CAF50"
    style.stroke: "#388E3C"
  }
  
  inactive: {
    style.fill: "#BDBDBD"
    style.opacity: 0.5
  }
}

# Apply classes
prod_server: { class: critical }
dev_server: { class: normal }
old_server: { class: inactive }
```

### Interactive Elements

```d2
component: {
  link: https://docs.example.com/component
  tooltip: Click to view documentation
}
```

### Notes and Annotations

```d2
important_element: Critical Component

important_element.note: |md
  This component handles:
  - User authentication
  - Session management
  - Rate limiting
| {
  shape: text
  near: top-center
}
```

## Output Format

Always provide:

1. **Complete D2 Code**: Ready to use, properly formatted
2. **Clear Comments**: Explain key sections
3. **Proper Syntax**: Follow D2 language specifications
4. **Working Icons**: Only use validated icon URLs

The output should be a complete `.d2` file that can be:
- Rendered using D2 CLI: `d2 diagram.d2 output.svg`
- Used in D2 playground: https://play.d2lang.com
- Integrated into documentation systems

## Resources

### Reference Files

- **`references/d2_syntax_reference.md`**: Comprehensive D2 syntax guide with examples
- **`references/d2_validated_icons_list.md`**: Verified icon URLs organized by category

### Quick Reference

**Basic Shape:**
```d2
element: Label
```

**Shape with Type:**
```d2
element: Label {
  shape: cylinder
}
```

**Connection:**
```d2
A -> B: Connection Label
```

**Container:**
```d2
container: Container Name {
  child1
  child2
  child1 -> child2
}
```

**Styling:**
```d2
element: {
  style.fill: "#4A90E2"
  style.stroke: "#2E5C8A"
}
```

**Icon:**
```d2
element: {
  icon: https://icons.terrastruct.com/tech/docker.svg
  shape: image
}
```

## Tips for Success

1. **Read References First**: Always consult syntax and icon references before starting
2. **Plan Before Coding**: Sketch out structure mentally or on paper
3. **Iterate**: Start simple, refine iteratively
4. **Test Layouts**: Try different directions and layout engines
5. **Use Examples**: Adapt provided examples to your needs
6. **Stay Organized**: Use containers to maintain structure
7. **Be Consistent**: Apply uniform styling throughout
8. **Document Choices**: Add comments explaining non-obvious decisions

## Troubleshooting

**Diagram looks cluttered?**
- Simplify: Remove non-essential elements
- Use containers to group related items
- Try different layout engine (elk vs dagre)
- Split into multiple diagrams or layers

**Icons not appearing?**
- Verify icon URL is from validated list
- Check URL is accessible (HTTPS required)
- Use `shape: image` to remove border
- Fallback to shapes if icon unavailable

**Layout not as expected?**
- Try different `direction` setting
- Experiment with layout engine (`elk` vs `dagre`)
- Adjust container groupings
- Use grid layouts for structured arrangements

**Connections crossing awkwardly?**
- Reorder element definitions
- Adjust container organization
- Try different flow direction
- Simplify connection paths

---

**Remember**: The goal is to create clear, informative diagrams that effectively communicate system structure and relationships. When in doubt, prioritize clarity over complexity.