Skip to content
Documentation

ADR-022: Mermaid Diagram Selection

Decision

Choose the Mermaid chart family by the reader’s question, not by convenience, and wrap complex diagrams in InteractiveMermaid while leaving small inline ones as static fences.

Key rules

  • Match the chart family to the reader’s question: topology or process -> flowchart; actor handoffs -> sequence; lifecycle -> state; audit or records -> ER; role boundaries -> class; trends over time -> XY.
  • Prefer the flowchart keyword over the legacy graph keyword.
  • Use the InteractiveMermaid wrapper when the reader needs pan, zoom, or download; use a static Mermaid fence for small inline diagrams.
  • Never route an unsupported syntax through InteractiveMermaid: gitGraph, gantt, pie, journey, timeline, and quadrantChart must stay as static fences.
  • Keep diagrams legible: 5 to 9 primary nodes, 2 to 4 named groups, one main path, and one exception loop.
  • Do not use classDef or class styling in beautiful-mermaid flowcharts; apply direct style lines instead.
  • When a person drives the flow, start the diagram with that actor.

Why

Selecting the chart family by the question the diagram answers keeps documentation diagrams readable and consistent, and the node and group limits prevent the dense, unscannable graphs that defeat the purpose of a diagram. Routing only complex diagrams through InteractiveMermaid reserves pan/zoom/download for cases that need it while keeping small diagrams lightweight, and excluding unsupported syntaxes from the wrapper avoids silent render failures. This record reconciles to current dmwd-io practice: the global Mermaid hard rule requires invoking the technical-writing skill (which now owns the diagram rules) before emitting any Mermaid fenced code block, so the pre/post-generation checklist runs even for a single-node diagram.

Applies when

You are creating or editing any Mermaid diagram in Storybook, MDX docs, ADRs, GitOps guidance, or interactive diagram stories.

  • ADR-016 — Storybook IA and navigation (where doc diagrams live).
  • ADR-017 — documentation truthfulness (diagrams must tell the truth about the system).