# 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 `&lt;` and `&gt;`.

```
✅ 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 |

```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.