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

---

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