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:

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

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

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

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

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:

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

Right:

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

Or use a shape without an icon:

server: {
  shape: rectangle
}

❌ Don't Over-Complicate

Wrong:

# Too many nested levels
system.layer1.layer2.layer3.layer4.component

Right:

# Clear, manageable hierarchy
system: {
  frontend
  backend
  database
}

❌ Don't Forget Direction

Wrong:

# No direction specified, layout may be suboptimal
A -> B -> C -> D

Right:

direction: right  # Clear flow direction
A -> B -> C -> D

❌ Don't Mix Styling Approaches

Wrong:

# Inconsistent styling
element1: {
  style.fill: "#FF0000"
}

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

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

Right:

# Consistent styling with classes
classes: {
  primary: {
    style.fill: "#4A90E2"
  }
}

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

Advanced Techniques

Layout Optimization

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

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

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

Notes and Annotations

# Simple note attached to an element
important_element: Critical Component
important_element.note: |md
  This component handles:
  - User authentication
  - Session management
  - Rate limiting
|

# Standalone floating note (root-level only)
# 'near' with constants only works on ROOT-LEVEL shapes
# Valid positions: top-left, top-center, top-right, center-left, center-right, bottom-left, bottom-center, bottom-right
diagram_note: Architecture Overview {
  shape: text
  near: top-center
  style.font-size: 14
}

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:

element: Label

Shape with Type:

element: Label {
  shape: cylinder
}

Connection:

A -> B: Connection Label

Container:

container: Container Name {
  child1
  child2
  child1 -> child2
}

Styling:

element: {
  style.fill: "#4A90E2"
  style.stroke: "#2E5C8A"
}

Icon:

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.