pma-d2

What this skill does

# D2 Diagram Author

Generate idiomatic `.d2` source files — diagrams encoded as declarative text, rendered by the official `d2` CLI to SVG / PNG / PDF / GIF. The output is human-readable, diffable, and embeds anywhere D2 embeds (GitHub, Notion, VS Code, docs sites, Oxide's play.d2lang.com).

Keep this entry file small. Load only the reference packs that match the current diagram.

## Always-On Rules

1. **Output is `.d2` text, nothing else.** The skill never invokes a renderer; the user runs `d2 input.d2 out.svg` or opens play.d2lang.com. Quality must be enforceable by reading the source.
2. **Idiomatic D2 over clever D2.** Prefer declarative node names (`api -> db`) over IDs + labels when the name reads naturally. Reach for `label:` only when the natural name would be awkward or duplicated.
3. **Shape type matches concept.** A database is `shape: cylinder`, a queue is `shape: queue`, an actor is `shape: person`. Never default everything to `rectangle`. Full catalog in `references/shapes.md`.
4. **Direction declared up front.** Set `direction: down | right | up | left` on the root (and per container if needed). Layout direction is a communication choice, not an incidental default.
5. **Semantic edge style, not ornamental.** `stroke-dash` for async / weak dependency; `animated: true` for streams; `stroke` color to encode criticality / failure paths. Catalog in `references/connections.md`.
6. **Group by container, not by proximity.** If nodes belong to one domain (a subsystem, a cloud, a bounded context), nest them in a container map. Containers are D2's native grouping — use them instead of manual placement.
7. **One concept per diagram.** If a diagram answers two questions, split into two `layers:` or two files. Don't compress.
8. **Classes for repetition.** ≥ 2 nodes share styling → define a class in `classes: {}` and apply with `.class: name` or a glob.
9. **No invented shapes.** All `shape:` values must come from `references/shapes.md`. D2 silently falls back to rectangle on typos, which is the worst failure mode: it looks right but isn't.
10. **Commit-ready source.** File ends with a newline, uses 2-space indentation, no trailing whitespace, comments explain intent not mechanics. D2 is git-friendly — keep it that way.

## Core Workflow

### Step 1: Choose Diagram Family

| Family | D2 primitive | Use when |
|---|---|---|
| **Architecture / flow** | default (nodes + connections) | Systems, pipelines, dependency graphs |
| **Sequence** | `shape: sequence_diagram` | Protocol exchanges, API call flows, timing |
| **ERD / schema** | `shape: sql_table` per table | Data model, foreign keys |
| **UML class** | `shape: class` per class | OO design, type relationships |
| **Grid / matrix** | `grid-rows` / `grid-columns` | Tabular layouts, comparison matrices, k8s cluster views |
| **Multi-board** | `layers:` / `scenarios:` / `steps:` | Before/after, drill-down, animation |

Details per family in `references/special-diagrams.md` and `references/composition.md`.

### Step 2: Pick Layout Engine

- **dagre** (default, free, bundled): DAG-oriented, good for most architecture diagrams.
- **elk** (free, bundled since v0.7): cleaner for nested hierarchies and orthogonal routing. Worth trying for multi-container diagrams.
- **tala** (paid, separate binary): best-in-class for complex, dense diagrams. Note in the file header if required so the user knows what to install.

Pick once per file via `vars.d2-config.layout-engine`. Don't fight the engine with manual positions — D2 has no `x,y`.

### Step 3: Draft Structure

1. Sketch the top-level containers first: which systems / domains exist.
2. Add nodes inside each container with the correct `shape:`.
3. Add connections — direction first, labels after topology is right.
4. Apply `classes:` to collapse repetition.
5. Add `vars.d2-config` block (theme, layout engine) at the top.

### Step 4: Style Pass

- Walk every connection — is its style (solid / dashed / animated / color) semantically distinct from its neighbors'?
- Walk every node — does its `shape:` and class carry information?
- Remove ornamentation that doesn't encode meaning (decorative colors, gratuitous shadows).

### Step 5: Validate & Hand Off

Run the pre-flight in `references/validation.md`. Tell the user:

- The output path (default `docs/architecture/<name>.d2`).
- The render command: `d2 <name>.d2 <name>.svg` (or whatever target they need).
- The chosen layout engine and whether it requires a separate install.
- Any icons referenced by URL (so they can mirror internally if needed).

## Section-by-Section for Large Diagrams

1. Write the `vars` + `direction` header and one container.
2. Append one container per edit; prefix child IDs by container if they'd otherwise collide.
3. Cross-container edges use dotted paths (`aws.api -> gcp.auth`); verify the path exists before emitting the edge.
4. When a diagram grows past ~60 nodes, split into `layers:` or separate `.d2` files composed via `@file` imports (`references/composition.md`).

## Output

- **File**: `docs/architecture/<name>.d2` by default, or a path the user specifies.
- **Render (user runs)**:
  - `d2 name.d2` → `name.svg` (default)
  - `d2 name.d2 name.png` / `name.pdf` / `name.gif`
  - `d2 --watch name.d2` → live preview on localhost
  - `d2 --theme <id> --dark-theme <id> name.d2` → theme pairing
- **Web preview**: paste into <https://play.d2lang.com/> for instant rendering without installing D2.
- **Embedding**: see `references/integration.md` for MDX, GitHub READMEs (checked-in SVG), docs sites (live render at build time), and CI pipelines.

## Reference Packs

- `references/syntax.md`
  Core grammar: identifiers, labels, maps, comments, escaping, the shorthand rules D2 is full of.
- `references/shapes.md`
  Every built-in shape with picture description, data semantics, and "use when" guidance.
- `references/connections.md`
  Edge operators (`->`, `<-`, `<->`, `--`), chaining, arrowheads, labels, semantic styling patterns.
- `references/containers.md`
  Nesting, `_` parent refs, dotted paths, the difference between a container and a shape, when to flatten vs nest.
- `references/classes.md`
  `classes:` block, applying via `.class:`, multi-class arrays, glob-based mass application.
- `references/styles.md`
  Complete style key catalog (fill, stroke, stroke-dash, shadow, 3d, multiple, animated, fill-pattern, border-radius, font-size, bold/italic/underline, opacity).
- `references/layouts.md`
  Direction, grid layouts, dagre vs elk vs tala tradeoffs, `near:` positioning for titles and legends.
- `references/special-diagrams.md`
  Sequence diagrams (actors, spans, notes, groups), `sql_table` ERDs, `class` UML, markdown / code / LaTeX blocks.
- `references/composition.md`
  `layers:` (isolated boards), `scenarios:` (inherit + override), `steps:` (animation), `@file` imports, `...@file` spread.
- `references/vars.md`
  `vars:` block, `${var}` substitution, `d2-config` (theme-id, dark-theme-id, sketch, pad, center, layout-engine), nested vars for design tokens.
- `references/templates.md`
  Copy-paste starter files: 3-tier web, microservices, data pipeline, CI/CD, sequence (OAuth), ERD, k8s cluster (grid).
- `references/design.md`
  Concept→pattern mapping, isomorphism test, when D2 beats ReactFlow / Mermaid / Excalidraw, when it loses.
- `references/validation.md`
  Pre-flight algorithm and checklists; common D2 mistakes (silent shape fallback, missing container path, label vs comment collisions).
- `references/render.md`
  CLI flags, watch mode, playground, icon catalogs (terrastruct icons, svgrepo), theme gallery.
- `references/integration.md`
  MDX / Docusaurus / Nextra embedding, GitHub README via checked-in SVG, docs-site build pipelines, pre-commit render.

## Quick Routing

- New to D2 syntax: load `syntax.md` + `shapes.md` + `connections.md`.
- Architecture / system diagram: `shapes.md` + `containers.md` + `layouts.md` + `templates.md`.
- Sequence / SQL / UML: `special-diagrams.md` + `