D2 Diagrams

D2 Diagrams

Use D2 for clean source-controlled diagrams. Keep the .d2 file as the authoritative artifact.

Workflow

1. Determine diagram type: architecture, infrastructure, sequence-like flow, ERD, state machine, or method pipeline.
2. Inspect source files or paper notes before diagramming. Do not infer architecture from names alone.
3. Draft .d2 with stable node names and short labels.
4. Use clusters for subsystems, stages, datasets, or infrastructure boundaries.
5. Render to SVG/PNG only after the source is syntactically valid.
6. Report the .d2 source path and rendered path.

Style

• Prefer readable hierarchy over decorative complexity.
• Use color sparingly to encode ownership, stage, or risk.
• Keep long explanations in captions or Markdown, not node labels.
• For paper method figures, choose semantic stages and data transformations over implementation minutiae.

Boundaries

• If D2 is not installed, create valid .d2 source and state rendering was not run.
• Do not use D2 when the user explicitly needs editable draw.io output.
• Do not replace Mermaid in README contexts unless D2 gives a clear advantage.