Mermaid Diagram Rules

Always follow these rules when writing Mermaid diagrams. After writing or editing any Mermaid block, validate with the co-located script: scripts/check-mermaid.sh <file>.

Syntax Rules (Critical)

1. Always quote labels that contain special characters

Any label with (), [], <>, ", ,, <br/>, or emoji must be wrapped in ["..."]:

%% ✅ GOOD — quoted labels
A["Turn 1: user"] --> B["blocks list"]
C["UI Panels (Thread, Tool)"]

%% ❌ BAD — unquoted special chars cause parse errors
A[Turn 1: user<br/>"Write a story"] --> B[blocks[]]
C[UI Panels (Thread, Tool)]

2. Quote edge labels that contain special characters

Edge labels with (), <>, <br/>, or [] must be quoted with |"..."|:

%% ✅ GOOD
A -->|"StreamEvents (Delta, Block)"| B
A -->|"JSON DTOs"| B

%% ❌ BAD — parentheses in edge labels
A -->|StreamEvents<br/>(Delta, Block)| B
A -->|JSON (DTOs)| B

3. Never use `<br/>` inside labels — use multiline with `\n` or separate lines

%% ✅ GOOD — no <br/>
A["Turn 1\nuser message"]

%% ❌ BAD — <br/> inside labels often breaks
A["Turn 1<br/>user message"]

Note: <br/> works in some Mermaid versions but not all. \n is safer.

4. Escape or avoid `[]` inside node text

%% ✅ GOOD
Store -->|"blocks list"| UI["Chat UI"]

%% ❌ BAD — nested [] conflicts with node shape syntax
Store -->|blocks[]| UI[Chat UI]

5. No emoji in node IDs or unquoted labels

%% ✅ GOOD
A["Step complete ✓"] --> B

%% ❌ BAD — emoji in unquoted context
A[Step ✓] --> B

6. Do not hardcode colors — rely on Mermaid's built-in themes

Hardcoded style / classDef colors override Mermaid's theme engine and break when switching between light and dark mode. Let the built-in dark / default themes handle node colors.

%% ✅ GOOD — no hardcoded colors, theme handles it
A[Service] --> B[Database]

%% ❌ BAD — hardcoded fill/color overrides theme
style A fill:#2d7d2d,color:#fff
classDef foo fill:#1a5276,color:#fff

For sequence diagram rect grouping, use near-transparent fills so they work in both themes:

rect rgba(128, 128, 128, 0.08)
    Note over A,B: Phase label
end

7. Semicolons in sequence diagrams

Sequence diagram statements must end with a newline, not a semicolon followed by more statements on the same line:

%% ✅ GOOD
Note over A: First
Note over A: Second

%% ❌ BAD — multiple statements on one line with semicolons
Note over A: First; isLoading=false

Quick Reference: When to Quote

Context	Needs quotes?	Example
Simple text only	No	`A[Hello World]`
Contains `()`	Yes	`A["Config (optional)"]`
Contains `[]`	Yes	`A["items list"]` (avoid `[]` entirely)
Contains `<br/>`	Avoid	Use `\n` instead
Contains emoji	Yes	`A["Done ✓"]`
Contains `"`	Escape	`A["Say 'hello'"]`
Edge with specials	Yes	`A -->\|"data (raw)"\| B`

Validation

The validation script lives at scripts/check-mermaid.sh within this skill directory. It extracts each ```mermaid block, validates it with mmdc, and reports file + line number for failures.

# Validate specific file
scripts/check-mermaid.sh path/to/file.md

# Validate all .md files recursively from cwd
scripts/check-mermaid.sh

# Validate a directory
scripts/check-mermaid.sh docs/features/

mermaid