diagram-design

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:

1. Title: describes what the diagram shows, not a generic label
2. Legend: present if the diagram uses colors, shapes, line styles, or icons
3. Labeled relationships: every arrow has a verb phrase ("sends events to", "reads from")
4. Consistent arrow direction: one convention (data flow or dependency), stated explicitly
5. Boundaries: elements that share a deployment unit or logical grouping are visually grouped
6. 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.