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.
82 lines
1.9 KiB
Markdown
82 lines
1.9 KiB
Markdown
# 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 |
|
|
|
|
```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.
|