D2

D2 — Diagram Composition Policies

Global rules for all D2 diagram generation. Every specialist and generation flow MUST enforce these. They are not optional.

CRITICAL — Every Diagram Must

1. Use snake_case IDs — api_gw: "API Gateway", NOT "API Gateway" as ID. Emojis go in labels only.
2. Set direction explicitly — direction: right for flows, direction: down for hierarchies. If unsure, use direction: right. Never omit.
3. Stay at one abstraction level — don't mix context actors with component internals.
4. Stay under visual budget — max 12 top-level nodes, 7 per group, 3 nesting levels, 4 outgoing edges.

Abstraction Levels

Every diagram operates at exactly ONE of these levels:

Rule: Do not mix levels. If the user's request implies multiple levels, normalize to the dominant level or generate separate diagrams.

Grouping Discipline

Every diagram uses exactly ONE grouping criterion:

Rule: Choose one. If the user's description mixes criteria, ask or default to the most prominent one.

Visual Budget

Hard limits:

When the budget is exceeded:

1. Simplify (remove low-value nodes)
2. If all nodes are essential: split into overview + detail diagrams

Orientation Heuristics

Rule: Always set direction explicitly. Never rely on the engine default.

Layout Engine Selection

Node IDs and Labels

• IDs: short, semantic, snake_case — api_gw, user_svc, orders_db
• Labels: descriptive but compact — API Gateway, User Service, Orders DB
• Emojis: in labels only, never in IDs
• Format: api_gw: "API Gateway" — not "API Gateway" as both ID and label

Compositional Patterns by Type

Defaults — override if the flow demands otherwise.

System Context

• Left: users, actors
• Center: system under design (single box, no internals)
• Right or below: external dependencies
• Max: 5-8 nodes

Container

• Left: entry points (users, gateways)
• Center: application tier (services, APIs)
• Right: data tier (databases, caches, queues)
• Below: async/supporting (workers, monitoring)
• Group by: layer (default) or domain

Component

• Scope: one container only
• Group by: layer or module (not both)
• No deployment concerns, no external systems
• Max: 8-10 nodes

Deployment

• Group by: environment or network boundary
• Separate: ingress / compute / data
• No business actors unless showing access paths

Sequence

• Max: 5-6 actors
• Use groups for happy path / error path
• Avoid self-messages — use notes instead
• Labels under 30 chars

ER

• Core entities: center
• Lookup/reference tables: periphery
• Crow's foot notation for cardinality
• Max: 10 tables per diagram (split by domain)

Class

• Interfaces/abstracts: top
• Implementations: below
• One package/module per diagram

Repair Pass

Before delivering ANY diagram, verify:

1. Level mixing: context-level actors mixed with component internals? Fix.
2. Grouping consistency: same criterion throughout? Fix.
3. Budget compliance: counts within limits? Simplify or split.
4. Labels: any label > 24 chars? Shorten.
5. Orphan nodes: any node with zero connections? Remove or connect.
6. Single-child groups: any group with 1 node? Dissolve.
7. Fanout: any node with > 4 outgoing edges? Add intermediary.
8. Self-loops (sequences): can they become notes? Convert.
9. Direction set? Is direction explicitly declared? Add it.
10. Engine appropriate? Complexity matches engine? Switch if needed.

Split Strategy

If the structural plan exceeds the visual budget:

1. Generate an overview diagram at one level higher of abstraction
2. Generate detail diagrams for each major group or subsystem
3. Naming: {type}-{scope}-overview-{date}.d2, {type}-{scope}-detail-{subsystem}-{date}.d2

Plugin Path Resolution

Run once before any file reads or script calls:

bashCopy code
PLUGIN_DIR=$(find "$HOME/.claude/plugins/cache" -type d -name "d2" -path "*/skills/d2" 2>/dev/null | head -1)

If empty (dev/repo usage):

bashCopy code
PLUGIN_DIR=$(find "$HOME" -maxdepth 8 -type d -name "d2" -path "*/skills/d2" 2>/dev/null | head -1)

If still empty: stop — "Plugin not found. Is it installed? Run /plugin install d2@claude-toolshed."

Config Reading

Read .claude/d2.json as a first step. Supported keys:

• theme_id (default: 0) — D2 theme ID
• layout (default: "dagre") — layout engine: dagre, elk, tala
• sketch (default: false) — hand-drawn style
• output_directory (default: "./diagrams")
• auto_validate (default: true)
• auto_render (default: false)
• output_format (default: "svg")

Embedded Config

Every generated .d2 file includes a vars block at the top:

d2Copy code
vars: {
  d2-config: {
    theme-id: 0
    layout-engine: dagre
    sketch: false
  }
}

Common Mistakes

Entry Points

Diagram Type Routing

Reference Guides