Mermaid Diagrams
Best practices for when to create Mermaid diagrams and how to write good ones. Use when writing or reviewing blueprints, initiatives, or briefs that need visual structure.
When to Create a Diagram
Create a diagram when:
- The relationships between 4+ entities matter and prose would bury the structure.
- A workflow has branching, parallelism, or conditional paths that are hard to follow linearly.
Do NOT create a diagram when:
- The content is a simple sequential list — a numbered list is better.
- A table communicates the same information more clearly — diagrams are for relationships, not tabular data.
In blueprints
Use diagrams for: architecture, data flow, system relationships, workflow sequences.
In initiatives
Use diagrams for: dependency chains, team handoff flows, milestone sequencing.
In briefs
Use diagrams for: task dependency graphs, integration points, data flow within the feature.
Mermaid Best Practices
Direction
- Always set
TD or LR explicitly — never rely on the default.
- Prefer
flowchart TD (top-down) for pipelines with 5+ nodes. Horizontal diagrams become unreadably wide.
- Use
flowchart LR (left-right) only when the diagram is naturally wide and shallow (2–3 rows of nodes).
- Aim for a roughly square aspect ratio. If the diagram is too wide or too tall, switch direction.
Structure
- Use subgraphs to group related nodes and create visual structure.
- Use
direction LR inside a subgraph to create horizontal sections within a vertical flow — good for grouping routines, side paths, or parallel tracks.
Links
- Use solid links (
-->) for the main flow.
- Use dashed links (
-.->) for alternative paths, optional branches, or cross-cutting concerns.
- Never mix more than 2 link styles. Solid = main, dashed = alternatives. That's it.
Labels and Shapes
- Keep node labels to 1–3 words. If a label needs more than 3–4 words, the diagram is too complex — split it.
- Use consistent node shapes: rectangles
[label] for processes, rounded (label) for start/end, diamonds {label} for decisions.
- Add a brief one-line caption above the diagram explaining what it shows.
Anti-Patterns
flowchart LR with 8+ nodes in a single row — becomes an unreadable horizontal strip. Switch to TD.
- Node labels that are full sentences — keep them to 1–3 words.
- Mixing too many link styles without clear meaning — pick 2 max (solid for main, dashed for alternatives).
- Diagrams that duplicate what a table or list already says — diagrams are for relationships, not tabular data.
- Overly nested subgraphs (3+ levels) — flatten or split into multiple diagrams.
- No direction specified — always set
TD or LR explicitly, never rely on default.
Examples
Example 1 — Vertical pipeline (good for workflows with many sequential steps)
flowchart TD
A[brainstorming] --> B[writing-plans]
B --> C[using-git-worktrees]
C --> D[subagent-driven-development]
D --> E[finishing-a-development-branch]
E --> F[verification]
Example 2 — Vertical flow with horizontal subgraph (good for main flow + grouped side concerns)
flowchart TD
A[start] --> B[main step]
B --> C[another step]
C --> D[finish]
subgraph side["Cross-cutting"]
direction LR
E[debugging]
F[parallel agents]
end
B -.-> E
C -.-> F
Example 3 — Horizontal flow (good for 2–3 wide, shallow diagrams)
flowchart LR
A[input] --> B[process] --> C[output]
Decision Guide: Diagram vs Prose vs Table vs List
| Format |
Use when |
| Diagram |
4+ entities with relationships that matter; branching/parallel/conditional workflows |
| Prose |
Narrative explanation, context, rationale — when the why matters more than the what connects to what |
| Table |
Comparing attributes across items; structured data with clear columns |
| List |
Simple sequential steps; items with no meaningful relationships between them |
1---2name: mermaid-diagrams3description: "Best practices for when to create Mermaid diagrams and how to write good ones — layout direction, readability, shape choice, and anti-patterns. Use when writing or reviewing blueprints, initiatives, or briefs that need visual structure, when deciding whether a diagram is the right format, or when a Mermaid diagram is already in a doc and needs review."4version: "1.0.0"5category: "Development"6metadata:7 source: https://skillmd.com/skills/gethamster/mermaid-diagrams8---910# Mermaid Diagrams1112Best practices for when to create Mermaid diagrams and how to write good ones. Use when writing or reviewing blueprints, initiatives, or briefs that need visual structure.1314## When to Create a Diagram1516**Create a diagram when:**1718- The relationships between 4+ entities matter and prose would bury the structure.19- A workflow has branching, parallelism, or conditional paths that are hard to follow linearly.2021**Do NOT create a diagram when:**2223- The content is a simple sequential list — a numbered list is better.24- A table communicates the same information more clearly — diagrams are for relationships, not tabular data.2526### In blueprints2728Use diagrams for: architecture, data flow, system relationships, workflow sequences.2930### In initiatives3132Use diagrams for: dependency chains, team handoff flows, milestone sequencing.3334### In briefs3536Use diagrams for: task dependency graphs, integration points, data flow within the feature.3738## Mermaid Best Practices3940### Direction4142- Always set `TD` or `LR` explicitly — never rely on the default.43- Prefer `flowchart TD` (top-down) for pipelines with 5+ nodes. Horizontal diagrams become unreadably wide.44- Use `flowchart LR` (left-right) only when the diagram is naturally wide and shallow (2–3 rows of nodes).45- Aim for a roughly square aspect ratio. If the diagram is too wide or too tall, switch direction.4647### Structure4849- Use subgraphs to group related nodes and create visual structure.50- Use `direction LR` inside a subgraph to create horizontal sections within a vertical flow — good for grouping routines, side paths, or parallel tracks.5152### Links5354- Use solid links (`-->`) for the main flow.55- Use dashed links (`-.->`) for alternative paths, optional branches, or cross-cutting concerns.56- Never mix more than 2 link styles. Solid = main, dashed = alternatives. That's it.5758### Labels and Shapes5960- Keep node labels to 1–3 words. If a label needs more than 3–4 words, the diagram is too complex — split it.61- Use consistent node shapes: rectangles `[label]` for processes, rounded `(label)` for start/end, diamonds `{label}` for decisions.62- Add a brief one-line caption above the diagram explaining what it shows.6364## Anti-Patterns6566- **`flowchart LR` with 8+ nodes in a single row** — becomes an unreadable horizontal strip. Switch to `TD`.67- **Node labels that are full sentences** — keep them to 1–3 words.68- **Mixing too many link styles without clear meaning** — pick 2 max (solid for main, dashed for alternatives).69- **Diagrams that duplicate what a table or list already says** — diagrams are for relationships, not tabular data.70- **Overly nested subgraphs (3+ levels)** — flatten or split into multiple diagrams.71- **No direction specified** — always set `TD` or `LR` explicitly, never rely on default.7273## Examples7475### Example 1 — Vertical pipeline (good for workflows with many sequential steps)7677```mermaid78flowchart TD79 A[brainstorming] --> B[writing-plans]80 B --> C[using-git-worktrees]81 C --> D[subagent-driven-development]82 D --> E[finishing-a-development-branch]83 E --> F[verification]84```8586### Example 2 — Vertical flow with horizontal subgraph (good for main flow + grouped side concerns)8788```mermaid89flowchart TD90 A[start] --> B[main step]91 B --> C[another step]92 C --> D[finish]9394 subgraph side["Cross-cutting"]95 direction LR96 E[debugging]97 F[parallel agents]98 end99100 B -.-> E101 C -.-> F102```103104### Example 3 — Horizontal flow (good for 2–3 wide, shallow diagrams)105106```mermaid107flowchart LR108 A[input] --> B[process] --> C[output]109```110111## Decision Guide: Diagram vs Prose vs Table vs List112113| Format | Use when |114| --- | --- |115| **Diagram** | 4+ entities with relationships that matter; branching/parallel/conditional workflows |116| **Prose** | Narrative explanation, context, rationale — when the *why* matters more than the *what connects to what* |117| **Table** | Comparing attributes across items; structured data with clear columns |118| **List** | Simple sequential steps; items with no meaningful relationships between them |