103 lines
2.5 KiB
Markdown
103 lines
2.5 KiB
Markdown
---
|
|
name: mermaid
|
|
description: Safe Mermaid diagram generation avoiding raw HTML entities and newlines. Use when generating, formatting, or updating Mermaid graphs or diagrams.
|
|
category: workflow
|
|
impact: low
|
|
---
|
|
|
|
# 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 |
|
|
|
|
```mermaid
|
|
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.
|