| name | mermaid-helper |
| description | USE WHEN the user wants to draw an architecture diagram, sequence diagram, flowchart, ER diagram, or state machine. Picks the right mermaid type, writes correct syntax, validates before returning. |
mermaid-helper — draw the right diagram in mermaid
Pick the right diagram type
| Want to show | Use |
|---|
| Box-and-arrow architecture | flowchart TD |
| Who calls whom across time | sequenceDiagram |
| Step-by-step process | flowchart LR |
| Entity relationships (DB schema) | erDiagram |
| State transitions | stateDiagram-v2 |
| Class structure | classDiagram |
| Gantt / project timeline | gantt |
| Pie chart of percentages | pie title … |
| Git branch flow | gitGraph |
If unsure, default to flowchart TD (top-down) for static structure and
sequenceDiagram for temporal interactions.
Common gotchas
- Spaces in node names must be quoted:
A["Order Service"], not
A[Order Service] (the latter works but breaks if the label has
punctuation).
- HTML in labels needs
& escapes: A & B → A & B.
- Edge labels:
A -->|publishes event| B, the pipes are required.
- Subgraphs need explicit
end: subgraph X\n A\n B\nend.
- classDef for styling:
classDef warn fill:#fee,stroke:#900; then
class A,B warn;.
- Sequence diagrams: use
participant A as Alice to give friendly names;
use Note over A: text for inline annotations.
Validation checklist (before returning)
Output
Return a fenced mermaid block:
```mermaid
flowchart TD
…
```
After the diagram, one short paragraph explaining the key flow. Skip the
explanation if the diagram is trivial.
Anti-patterns
- Don't make a flowchart with 50 nodes — split into multiple diagrams
- Don't use ASCII art "diagrams" inside the mermaid block
- Don't add color for decoration; only when it carries meaning
- Don't write a sequence diagram for static structure
