2.5 KiB
| name | description |
|---|---|
| mermaid | Safe Mermaid diagram generation avoiding raw HTML entities and newlines. Use when generating, formatting, or updating Mermaid graphs or diagrams. |
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["<customer>-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.