9bfa4813a8
The \n literal often fails to render correctly in Mermaid nodes. The guidelines now require using actual newlines inside quoted text to ensure multiline content displays reliably.
1.9 KiB
1.9 KiB
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 for line breaks inside Mermaid nodes or labels. It does not always render correctly.
Instead, use actual line breaks (real newlines) inside quoted text.
✅ A["First line
Second line"]
❌ B["First line\nSecond line"]
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.