Mermaid conventions

Mermaid diagrams compress structure into something a human can scan in seconds and a model can re-derive from text. They live inside the markdown — never as separate images.

🌳 evergreen tended 2026-05-08 convention diagrams mermaid

flowchart LR
  idea[structural idea] --> l0[L0: 5 nodes max]
  l0 --> l1[L1: layer detail]
  l1 --> l2[L2: full graph]
  l0 -.read first.-> l1
  l1 -.drill in.-> l2

Read next

• Patterns — pair every diagram with a level
• Map — L0/L1/L2 in practice
• Compressions — where mermaid sits in the family
• Inspiration — Tufte's info density

Diagrams are markdown. Re-derivable from text means version-controlled and diffable.

Mermaid diagrams are this repo's standard for compressing structure into something a human can scan in seconds and a model can re-derive from text. They live inside the markdown that explains them — never in a separate image file.

When to use mermaid

You have…	Use diagram type
a flow / decision / pipeline	flowchart LR
state transitions	stateDiagram-v2
time-ordered exchanges	sequenceDiagram
entities + fields + relations	classDiagram (or erDiagram)
a hierarchy / tree	flowchart TD
a map of dependencies	flowchart LR

If none fit cleanly, you don't need a diagram — write prose.

Compress / decompress levels

Every diagram is paired with a level. Same content, different resolution.

flowchart LR
  L0["L0: 1-2 nodes<br/>the headline"] --> L1["L1: 5-9 nodes<br/>the shape"] --> L2["L2: full graph<br/>the machinery"]

• L0 lives next to the page's TL;DR. ≤2 nodes. The reader who only reads L0 still leaves with the punchline.
• L1 lives in the overview. 5–9 nodes — Miller's number. The reader who reads L1 can recreate the system from memory.
• L2 lives in the deep dive. Unbounded — but if it exceeds ~30 nodes, split it.

Authors pick which levels to include. A short page may have only L0+L1.

Style rules

• Node labels are nouns or noun-phrases ("session start", not "starts session").
• Edge labels are short verbs or conditions ("reads", "if N≥3").
• Use --> for direction; --- for symmetric. Don't mix.
• One concept per node. If you need a comma in a label, split it.
• Keep node ids short (a, s1, commit) — labels do the talking.

Re-derivability

If a diagram captures something not stated in the surrounding prose, the prose is incomplete. Diagrams summarize — they don't replace text. A blind reader (no diagram support) should get the same conclusion from the prose alone.

Example: the swarm minimum cycle (L1)

flowchart LR
  orient[orient.py] --> order[task_order.py]
  order --> ask[question_gen.py]
  ask --> dispatch[dispatch_optimizer.py]
  dispatch --> act[act + diff]
  act --> compress[compress lesson]
  compress --> sync[sync_state + validate]
  sync --> push[git push]
  push --> orient

Six commands, one loop. Read SWARM.md §Minimum Cycle for L2.

Anti-patterns

• Decorative diagrams that don't add information beyond their caption.
• Skip-level diagrams (no L0, L1 only) — readers can't enter from the top.
• Stale diagrams: when text and diagram disagree, edit both in the same commit.