--- name: d2 description: D2 (Declarative Diagramming) language reference — syntax for shapes, connections, containers, styling, SQL tables, sequence diagrams, UML classes. Load when working with D2 diagram code. license: MIT --- # d2 skill ## D2 Language Reference D2 is a declarative diagramming language that turns text into diagrams. It stands for **Declarative Diagramming** — describe what you want diagrammed, it generates the image. **Official Resources:** - Docs: - Playground: - Cheat Sheet: --- ## Shapes ### Basic Declaration ```d2 # Simple shape (default: rectangle) shape_name # Custom label key: "Display Label" # Multiple on one line (semicolon separated) shape1; shape2; shape3 ``` ### Shape Types ```d2 database.shape: cylinder decision.shape: diamond process.shape: hexagon cloud_service.shape: cloud user.shape: person ``` | Shape | Use Case | | --------------- | ------------------------ | | `rectangle` | Default, general purpose | | `square` | 1:1 ratio | | `circle` | States, nodes (1:1) | | `oval` | Start/end points | | `diamond` | Decisions, conditions | | `hexagon` | Processes | | `cloud` | Cloud services | | `cylinder` | Databases, storage | | `person` | Users, actors | | `parallelogram` | Input/output | | `document` | Documents | | `page` | Page shape | | `queue` | Queue shape | | `package` | Package shape | | `step` | Step shape | | `callout` | Speech bubble | | `stored_data` | Data storage | ### 1:1 Ratio Shapes `circle` and `square` maintain equal width and height. Long labels will expand both dimensions. --- ## Connections ### Arrow Types ```d2 a -> b # Forward arrow a <- b # Backward arrow a -- b # Line (no arrow) a <-> b # Bidirectional ``` ### Connection Labels ```d2 client -> server: "HTTP request" database <- api: "query" ``` ### Chaining ```d2 a -> b -> c -> d ``` ### Repeated Connections Repeated connections create new edges, they don't override: ```d2 Database -> S3: backup Database -> S3: backup # Creates second edge ``` ### Cycles ```d2 Stage One -> Stage Two -> Stage Three -> Stage Four -> Stage One ``` ### Arrowheads ```d2 a -> b: { source-arrowhead: { shape: diamond label: "start" } target-arrowhead: { shape: arrow label: "end" } } ``` **Arrowhead shapes:** `triangle` (default), `arrow`, `diamond`, `circle`, `box`, `cross`, `cf-one`, `cf-many` --- ## Containers (Nested Shapes) ### Nested Syntax ```d2 Frontend: { React App Redux } Backend: { API Layer Services } Frontend -> Backend: HTTP ``` ### Container Labels ```d2 # Shorthand clouds: Cloud Services # Or using label keyword clouds: { label: Cloud Services aws gcloud } ``` ### Reference Parent Use `_` to reference the parent container from inside: ```d2 christmas: { presents -> _.birthdays.presents: regift } birthdays: { presents } ``` --- ## Direction ```d2 # Global direction direction: right # up, down, left, right ``` **Note:** Per-container direction only works with TALA layout engine. --- ## Styling ### Style Block ```d2 component: { style: { fill: "#E3F2FD" stroke: "#1976D2" stroke-width: 2 stroke-dash: 3 opacity: 0.9 shadow: true font-size: 14 font-color: "#333" bold: true italic: true underline: true border-radius: 5 } } ``` ### Dot Notation ```d2 component.style.fill: "#4CAF50" connection.style.animated: true ``` --- ## Special Objects ### SQL Tables ```d2 users: { shape: sql_table id: int {constraint: primary_key} name: varchar(255) email: varchar(255) {constraint: unique} role_id: int {constraint: foreign_key} } orders: { shape: sql_table id: int {constraint: primary_key} user_id: int {constraint: foreign_key} total: decimal } # Foreign key connection users.id <-> orders.user_id: "has many" ``` **Constraint shortcuts:** `primary_key` → PK, `foreign_key` → FK, `unique` → UNQ ### UML Classes ```d2 User: { shape: class +id: int +name: string -password: string #internalField: string +getEmail(): string +setEmail(email: string): void } ``` Visibility: `+` public, `-` private, `#` protected ### Sequence Diagrams ```d2 api_flow: { shape: sequence_diagram client server database client -> server: request server -> database: query database -> server: results server -> client: response } ``` **Key rules:** - Order of definitions matters (appears in that order) - Children share scope (same `alice` throughout) - Groups: containers with no connections but internal connections - Spans: nested objects on actors - Notes: nested objects with no connections ```d2 # Group example Office chatter: { shape: sequence_diagram alice bob group: { label: "awkward small talk" alice -> bob: hi bob -> alice: hello } } ``` ### Code Blocks ```d2 code_example: { shape: code language: typescript content: |` const response = await fetch('/api'); return response.json(); `| } ``` **Language aliases:** `md` → markdown, `tex` → latex, `js` → javascript, `go` → golang, `py` → python, `ts` → typescript ### Markdown / Text ```d2 # Standalone markdown description: |md # Header - Bullet point - Another point | # Text shape (no markdown) note: { shape: text label: "Plain text here" } ``` ### LaTeX ```d2 formula: |latex \frac{-b \pm \sqrt{b^2-4ac}}{2a} | ``` --- ## Variables ```d2 vars: { primary-color: "#4A90D9" db-color: "#2ECC71" } database.style.fill: ${primary-color} ``` --- ## Layout Engines | Engine | Best For | Command | | ------- | ----------------------------------- | ------------------- | | `dagre` | General purpose, hierarchical | `d2 --layout=dagre` | | `elk` | Complex graphs, better edge routing | `d2 --layout=elk` | | `tala` | Software architecture, nested | `d2 --layout=tala` | **Engine-specific features:** - `near` to another object: TALA only - `width`/`height` on containers: ELK only - Per-container direction: TALA only - `top`/`left` positioning: TALA only --- ## Themes ```bash # Apply theme by ID d2 -t 101 input.d2 out.svg # Theme ranges: 0-7, 101-104, 200-204, 300-303 ``` --- ## CLI Reference ```bash # Compile to SVG d2 input.d2 output.svg # Export formats d2 input.d2 output.png d2 input.d2 output.pdf # Watch mode d2 --watch input.d2 out.svg # Format D2 file d2 fmt input.d2 # List layouts d2 layout ``` --- ## Common Patterns ### Layered Architecture ```d2 direction: down Presentation: { UI Components Views } Business: { Services Domain Logic } Data: { Repositories Database } Presentation -> Business Business -> Data ``` ### Event-Driven System ```d2 Producer -> "Event Bus": Publish "Event Bus" -> Consumer A: Subscribe "Event Bus" -> Consumer B: Subscribe "Event Bus".shape: parallelogram ``` ### Microservices ```d2 direction: right Gateway: {shape: hexagon} Auth Service: {style.fill: "#E3F2FD"} User Service: {style.fill: "#FFF3E0"} Order Service: {style.fill: "#FCE4EC"} Gateway -> Auth Service Gateway -> User Service Gateway -> Order Service ``` --- ## Installation ```bash # Install curl -fsSL | sh -s -- # Verify d2 --version # Uninstall curl -fsSL | sh -s -- --uninstall ``` --- ## Available Tools When working with D2 in this environment, you have access to these tools: ### `d2_render` Render D2 code to an image file (SVG, PNG, or PDF). ```typescript // Render inline code d2_render({ code: "a -> b: hello", format: "svg" }); // Render from file d2_render({ file: "diagram.d2", format: "png" }); // With options d2_render({ code: "...", format: "svg", theme: "dark", // default, dark, terminal, earth, cool, grape, asteroid, flagship layout: "elk", // dagre, elk, tala pad: 50, // padding in pixels (0-500) returnBase64: true, // return base64 instead of saving to file }); ``` **Parameters:** - `code` - D2 diagram code (required if file not specified) - `file` - Path to a .d2 file (required if code not specified) - `format` - Output format: `svg` (default), `png`, or `pdf` - `theme` - Visual theme: `default`, `dark`, `terminal`, `earth`, `cool`, `grape`, `asteroid`, `flagship` - `layout` - Layout engine: `dagre`, `elk`, or `tala` - `pad` - Padding around diagram in pixels (0-500) - `returnBase64` - Return base64 encoded output instead of saving to file **Output:** Saves to `.output/` directory (e.g., `.output/diagram.svg`) unless `returnBase64: true` ### `d2_check` Check if D2 CLI is available and get version information. ```typescript d2_check(); // Returns: { available: true, version: "0.6.0", ... } ``` ### `d2_themes` List available D2 themes with descriptions. ```typescript d2_themes(); // Returns: { themes: [...], usage: "...", example: "..." } ``` ### `d2_layouts` List available layout engines with pros/cons. ```typescript d2_layouts(); // Returns: { layouts: [...], usage: "...", example: "..." } ``` --- ## Workflow with Tools 1. **Check availability** (optional): `d2_check()` 2. **Write D2 code** using the syntax in this reference 3. **Render** with `d2_render({ code: "...", format: "svg" })` 4. **Iterate** based on the output ### Example Session ```typescript // Check D2 is installed d2_check(); // Render a simple diagram d2_render({ code: ` direction: right User -> Server: Request Server -> Database: Query Database -> Server: Result Server -> User: Response `, format: "svg", theme: "dark", }); // Output: .output/diagram-1234567890.svg // Or return as base64 for immediate use d2_render({ code: "a -> b", returnBase64: true, }); // Output: data:image/svg+xml;base64,... ```