---
name: mermaid
description: "Use when creating, editing, reviewing, or repairing Mermaid diagrams; choose the narrowest model, preserve readable structure, and resolve theme from the active output context."
---

# 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 inside Pi's terminal, read [Pi terminal rendering](references/pi-terminal.md) before authoring; 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`
- schedule and duration → `gantt`
- quantities → chart type only when Mermaid adds enough value

Do not force every request into `flowchart`.

## Design

- one diagram → one claim
- preserve domain terminology
- keep IDs short, stable, and ASCII
- put human text in quoted labels
- label edges when unlabeled arrows hide meaning
- split dense diagrams; do not style around poor structure
- use shape semantics consistently
- introduce the diagram's claim in prose
- never communicate required meaning through color alone

Reader should know:

1. what diagram answers
2. where reading starts
3. what each boundary, shape, and edge means

## Source rules

- use `flowchart`, not legacy `graph`
- quote labels containing `()[]{}/\\:;#@!?<>|` or ambiguous punctuation
- do not use bare lowercase `end` as an identifier or label
- use `%%` comments only
- keep identifiers separate from labels
- quote edge labels containing brackets, pipes, parentheses, or colons
- use syntax supported by the target Mermaid renderer
- keep one model per `mermaid` fence

## Theme

Resolve theme at the output boundary.

Precedence:

1. explicit user theme or palette
2. active output context's visual contract
3. installed palette
4. renderer default

`auto` is a resolution policy, not Mermaid syntax.

- dynamic target → preserve target-controlled light/dark behavior
- static target → select matching light or dark palette
- target-owned theme → do not override it
- styling prohibited by the active contract → emit plain Mermaid

Installed palette is default. Read `references/palette.json` when applying it.
It is generated from Nugu; do not hand-edit it or derive it interactively.
Use semantic roles, not arbitrary hues:

- background → diagram background
- text → labels and titles
- accent → primary path and identity
- muted → secondary labels and borders
- focus → active path
- error → failure path
- warning → caution
- info → contextual annotation

Use generated Mermaid theme variables only where the target accepts in-band configuration.