Mermaid Diagram Instructions

Edge Labels

Use -- "text" --> syntax, not -->|text| syntax.

| inside -->|label| breaks parsing if the label contains a pipe character (e.g. curl | bash). Quoted syntax always works:

✅  A -- "curl | bash" --> B
❌  A -->|curl | bash| B

Line Breaks (Multiline Text)

Do not use \n, <br>, or <br/> for line breaks inside Mermaid nodes or labels. They do not always render correctly. Instead, use actual line breaks (real newlines) inside quoted text.

✅ A["First line
Second line"]

❌ B["First line\nSecond line"]
❌ C["First line<br/>Second line"]

Angle Brackets and Special Characters

Do not use raw < or > characters in Mermaid nodes or labels (e.g. <customer>-idp-deployment), as they are often parsed as HTML tags and break rendering. Instead, use HTML entities < and >.

✅ A["&lt;customer&gt;-idp-deployment"]

❌ B["<customer>-idp-deployment"]

Color Contrast — CRITICAL

All Mermaid diagrams MUST have sufficient color contrast. AI-generated diagrams often fail this.

Rule: always pair background with explicit text color.

Background type	Text color
Light (`#e6ffe6`, `#ffcccc`, `#fff3cd`)	`color:#000`
Dark (`#009900`, `#cc0000`, `#0055cc`)	`color:#fff`
Default (no fill)	no color needed

graph LR
    A[Input]:::good --> B[Process]:::bad --> C[Output]:::good
    classDef good fill:#009900,color:#fff
    classDef bad  fill:#cc0000,color:#fff

Never:

style NodeA fill:#ffcccc              ❌ no text color — unreadable
style NodeB fill:#66ff66              ❌ bright color, no contrast defined

Size

Abstract diagram: max 5-7 nodes — full scope, high level
Section diagrams: max 3-5 nodes — one subsystem only
Too many arrows = diagram is wrong scope, split it

When to Use What

Situation	Use
Flows, sequences, architecture	Mermaid `graph` or `sequenceDiagram`
File/folder structure	ASCII tree
Timeline	Mermaid `gantt`
Both structure and flow needed	Both, separately

If Diagram Would Be Too Complex

Do not simplify by removing important nodes. Instead: split into two diagrams — one high-level, one zoomed-in detail.

2.3 KiB Raw Blame History