# Mermaid Syntax Rules

Validate all Mermaid diagram blocks before writing them to files. Apply these rules whenever generating Mermaid diagrams.

## Common Pitfalls by Diagram Type

### stateDiagram-v2

| Pitfall | Bad | Good |
|---------|-----|------|
| Colon in note text | `note right of S : FC routing: HD / CC` | `note right of S : FC routing (HD, CC)` |
| Special chars in transition labels | `S1 --> S2 : All shipped/collected` | `S1 --> S2 : All shipped or collected` |
| Missing space before colon | `S1 --> S2: label` | `S1 --> S2 : label` |
| Unicode arrows in labels | `S1 --> S2 : A → B` | `S1 --> S2 : A then B` |
| Em dash in text | `note right of S : No changes — done` | `note right of S : No changes. Done` |
| Unquoted state with spaces | `state "My State" as MS` | OK (quoted is correct) |
| Duplicate state names without alias | Two states named `CREATED` for different entities | Use `state "CREATED" as FUL_CREATED` |

**Key rule:** After the `:` separator in notes and transitions, the remaining text must NOT contain `:`, `→`, `—`, or `/`.

### sequenceDiagram

| Pitfall | Bad | Good |
|---------|-----|------|
| Colon in message text | `A->>B: Read curbside.pickup.config` | `A->>B: Read curbside pickup config` |
| Colon in Note text | `Note over A,B: attrs: x, y` | `Note over A,B: attrs include x, y` |
| Arrow (→) in message | `A->>A: CREATED → BOOKED` | `A->>A: CREATED then BOOKED` |
| Participant name with special chars | `participant FC as FULFILMENT_CHOICE (CC)` | `participant FC as FULFILMENT_CHOICE` |
| Missing participant declaration | Using `WH` without declaring it | `participant WH as Webhook` |
| `<br/>` in messages | Works in some renderers | Prefer `\n` or split into separate messages |

**Key rule:** Message text after the `:` must not contain another `:`. Use commas, parentheses, or rephrase.

### flowchart (TD/LR)

| Pitfall | Bad | Good |
|---------|-----|------|
| Unicode arrows in node label | `A[READY → RECEIVED → PICKPACK]` | `A["READY - RECEIVED - PICKPACK"]` |
| Colon in node label | `A[type: CURBSIDE]` | `A["type CURBSIDE"]` or `A[type=CURBSIDE]` |
| Unquoted label with special chars | `A[Pick & Pack]` | `A["Pick & Pack"]` |
| Parentheses in unquoted label | `A[SendEvent(name)]` | `A["SendEvent(name)"]` |
| Subgraph with colon | `subgraph FC: Processing` | `subgraph FC Processing` |
| classDef with missing style | `classDef added` | `classDef added fill:#90EE90` |

**Key rule:** If a node label contains ANY special characters (`:`, `→`, `&`, `(`, `)`, `/`), wrap it in double quotes.

### erDiagram

| Pitfall | Bad | Good |
|---------|-----|------|
| Colon in attribute | `string ref : "order ref"` | `string ref "order ref"` |
| Relationship without label | `ORDER ||--o{ FULFILMENT` | `ORDER ||--o{ FULFILMENT : has` |

## Universal Rules

1. **No colons in free text** — After the initial `:` separator, never use another `:` in the same line
2. **No unicode arrows** — Replace `→` with `then`, `to`, or `-`; replace `←` with `from`
3. **No em dashes** — Replace `—` with `.` or `,` or rephrase
4. **No forward slashes in labels** — Replace `HD/CC` with `HD, CC` or `HD or CC`
5. **Quote complex labels** — Any flowchart node label with special characters must be in double quotes
6. **Validate state names** — State names in `stateDiagram-v2` must be alphanumeric + underscore only
7. **Consistent arrow style** — Use `-->` for state transitions, `->>` for sequence messages, `-->` for flowchart edges

## Validation Checklist

Before writing any file containing Mermaid blocks, verify each block:

- [ ] No colons in free text after the separator colon
- [ ] No unicode arrows anywhere in the diagram
- [ ] No em dashes in labels or notes
- [ ] No forward slashes in labels or notes
- [ ] Flowchart node labels with special chars are double-quoted
- [ ] All participants declared in sequenceDiagram
- [ ] stateDiagram-v2 state names are simple identifiers
- [ ] classDef declarations include style properties
