--- name: mermaid description: "Create/edit/review/fix Mermaid; pick narrow model, keep readable, fit the target renderer." --- # Mermaid Use Mermaid when relationships, order, states, or structure communicate more than prose. Use prose when a diagram would only decorate the answer. For diagrams displayed in Pi's terminal, read [Pi terminal rendering](references/pi-terminal.md) before authoring and validate with Pi's installed renderer through stdin, never temporary diagram files. For browser/HTML targets, retain their own renderer and theme contract. ## Choose the narrowest model - order between actors → `sequenceDiagram` - lifecycle and transitions → `stateDiagram-v2` - bounded process, decision, or dependency flow → `flowchart` - entities and cardinality → `erDiagram` - conceptual type relationships → `classDiagram` - chronology → `timeline` - proportions → `pie` - schedule or duration → `gantt` for browser targets only; Pi's terminal renderer returns null - quantities → chart type only when Mermaid adds enough value Do not force every request into `flowchart`. ## Design - one diagram → one claim; introduce the claim in prose - preserve domain terminology; put human text in quoted labels - keep IDs short, stable, and ASCII - label edges when unlabeled arrows hide meaning - split dense diagrams instead of styling around poor structure - never communicate required meaning through color alone ## Source rules - use `flowchart`, not legacy `graph` - quote labels and edge labels containing `()[]{}/\|:;#@!?<>` or other ambiguous punctuation - do not use bare lowercase `end` as an identifier or label - keep one model per `mermaid` fence; use syntax the target renderer supports - Pi's terminal rejects diagrams with any renderer warning, even when partial art exists ## Theme - dynamic targets preserve their own light/dark behavior; do not override it - Pi's terminal renders with Pi's theme; emit plain Mermaid without in-band styling