| name | diagram-design |
| description | Design and review guidance for software architecture diagrams (Mermaid, Draw.io). Use when creating, reviewing, or editing diagrams in any markdown documentation. Triggered by: diagram, flowchart, sequence diagram, mermaid, drawio, architecture diagram, data flow, state machine, ER diagram, class diagram, C4 model, system context, high-level overview. Covers readability, accessibility, notation, abstraction levels, tool selection (mermaid vs drawio), and platform-specific rendering rules (GitHub vs Azure DevOps). Do not use for markdown text formatting rules (use documentation-style) or for code visualization/debugging. |
Diagram Design
Principles
A diagram exists to help someone understand something. Before creating one, ask: who is the audience and what question does this diagram answer?
- Business stakeholders need system context: what the system does, who uses it, what it connects to. Omit internals and technology.
- Developers need technical clarity: components, data flows, technology choices.
- A diagram that tries to serve both audiences usually serves neither.
Zoom, don't cram. Each diagram should answer one question at one level of abstraction. Use separate diagrams for context, containers, components, and code, like zooming into a map.
Keep it simple. When a diagram feels cluttered, split it. Avoid crossing arrows, limit to ~15 elements, and prefer clarity over completeness.
Every element must be meaningful. Each box needs a name and a responsibility (one sentence). Add technology labels only for technical audiences. If you cannot describe what an element does, remove it.
Diagrams complement text. Add a short paragraph for context the visual cannot convey (why, constraints, what is not shown). Do not repeat in text what the diagram already shows.
Review Checklist
Apply before considering a diagram done:
- Title: describes what the diagram shows, not a generic label
- Legend: present if the diagram uses colors, shapes, line styles, or icons
- Labeled relationships: every arrow has a verb phrase ("sends events to", "reads from")
- Consistent arrow direction: one convention (data flow or dependency), stated explicitly
- Boundaries: elements that share a deployment unit or logical grouping are visually grouped
- No orphan elements: every element has at least one relationship
Visual Design
Shapes help distinguish element types at a glance (rectangle for services, cylinder for data stores, person for actors, cloud for external systems). Pick a consistent mapping and apply it throughout the project.
Colors add information but should not be the only differentiator (~8% of males have color vision deficiency). Pair color with shape, pattern, or label so diagrams remain readable in grayscale. Limit to 4-5 colors, avoid red/green as sole distinguishing pair, and document the mapping in the legend.
Icons (Draw.io) add recognition but must complement text labels, not replace them. Use official service icon sets and do not mix providers. Read references/drawio-guide.md for creation and export workflow.
Tool Selection: Mermaid vs Draw.io
| Factor | Mermaid | Draw.io |
|---|
| Complexity | Simple to medium (< 15 elements) | Medium to complex, or spatial layout matters |
| Icons | No native support | Rich icon libraries (cloud providers, UML) |
| Version control | Text-based diff in markdown | Binary .drawio (XML, harder to review) |
| Rendering | Inline in GitHub/Azure DevOps | Exported as .drawio.png, referenced as image |
Start with Mermaid. Switch to Draw.io when the diagram needs spatial freedom, icons, or more than ~15 elements.
Mermaid Syntax Notes
- Line breaks: use
<br/> inside labels and node text. Mermaid does not interpret \n as a line break; it renders as literal text.
Mermaid Diagram Types
| What you want to show | Mermaid type |
|---|
| System context, containers, components | C4Context, C4Container, C4Component |
| Request/response flow between services | sequenceDiagram |
| Process or data flow | flowchart LR or flowchart TD |
| State transitions | stateDiagram-v2 |
| Entity relationships | erDiagram |
| Class structure | classDiagram |
Use LR (left-to-right) for flows and pipelines; TD (top-down) for hierarchies.
Mermaid Platform Rendering
Detect from the git remote (git config --get remote.origin.url):
- GitHub (
github.com): use code block with ```mermaid and ```
- Azure DevOps (
dev.azure.com or visualstudio.com): use :::mermaid and :::
Convert existing Mermaid blocks to the correct platform format when editing markdown files.
