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