mermaid-diagram

name	mermaid-diagram
description	Generate syntactically valid Mermaid.js diagrams. Use when user says "create a mermaid diagram", "generate a flowchart", "draw a sequence diagram", "visualize with mermaid", "mermaid architecture diagram", "create a class diagram", "make a state diagram", "ER diagram", "Gantt chart", "gitGraph", or when generating any Mermaid code block in markdown. Also use when asked to fix or debug a broken Mermaid diagram.
allowed-tools	[]
model	sonnet

Mermaid.js Diagram Generator

Generate valid Mermaid.js diagrams that render without syntax errors on the first attempt. When outputting a diagram, always wrap it in a fenced code block with the mermaid language tag.

Syntax Rules

Follow every rule below. Violating any one will produce a render failure.

1. One Node Per Line

%% CORRECT
A[Service A]
B[Service B]

%% WRONG
A[Service A] B[Service B]

2. Alphanumeric Node IDs Only

No spaces, hyphens, or special characters in IDs. Display names go in brackets.

%% CORRECT
AuthService[Auth Service]
UserDB[User Database]

%% WRONG
Auth-Service[Auth Service]
User DB[User Database]

3. Quote Labels with Special Characters

Wrap in double quotes if a label contains parentheses, brackets, colons, math operators, or anything that could be parsed as Mermaid syntax.

%% CORRECT
A["Process (async)"]
B["array[0]"]
C["ratio: 3/4"]
D["calculate(x, y)"]

%% WRONG
A[Process (async)]
B[array[0]]

4. No HTML or Markdown in Labels

Use commas or semicolons instead of <br> or \n.

%% CORRECT
A["Input: raw data, Output: processed"]

%% WRONG
A[Input: raw data<br>Output: processed]

5. No Chained Arrows

Write each connection on its own line.

%% CORRECT
A --> B
B --> C

%% WRONG
A --> B --> C

6. Comments on Their Own Lines

%% comments must not appear at the end of code lines.

%% CORRECT
%% This is a comment
A --> B

%% WRONG
A --> B %% connection

7. Style Only Defined Nodes

Apply style directives only after the node has been defined.

%% CORRECT
A[Server]
style A fill:#f9f,stroke:#333

%% WRONG
style A fill:#f9f,stroke:#333
A[Server]

8. Subgraph Names

Use underscores or wrap in quotes — no bare spaces.

%% CORRECT
subgraph Backend_Services
subgraph "Backend Services"

%% WRONG
subgraph Backend Services

9. Validate Before Presenting

Trace through the diagram to confirm:

• Every node on its own line with unique alphanumeric ID
• No chained arrows
• Special-character labels double-quoted
• No HTML/Markdown in labels
• Comments on own lines
• Styles reference defined nodes only
• Subgraph names quoted or underscored

Diagram Type Quick Reference

Type	Directive	Use For
Flowchart	flowchart TD / flowchart LR	Architecture, data flow, decisions
Sequence	sequenceDiagram	API calls, request/response
Class	classDiagram	Type relationships, OOP
State	stateDiagram-v2	State machines, lifecycles
ER	erDiagram	Database schemas, entities
Gantt	gantt	Timelines, schedules
Git	gitGraph	Branch strategies, merges

Common Patterns

Architecture Diagram

flowchart TD
    Client[Browser Client]
    API[API Gateway]
    Auth[Auth Service]
    DB[(Database)]

    Client --> API
    API --> Auth
    Auth --> DB

Sequence Flow

sequenceDiagram
    participant C as Client
    participant S as Server
    participant D as Database

    C->>S: POST /api/data
    S->>D: INSERT query
    D-->>S: Result
    S-->>C: 201 Created

Fixing Broken Diagrams

When asked to fix a broken Mermaid diagram:

1. Identify the error type — parse errors almost always come from one of: chained arrows, unquoted special characters, bare subgraph names, or HTML in labels.
2. Apply the relevant rules above — check each rule against the broken code line by line.
3. Rewrite the offending lines — fix only what is broken; preserve the diagram's intent.
4. Re-validate using the checklist in Rule 9 before presenting the corrected diagram.

If the diagram is structurally ambiguous (missing nodes, unclear relationships), ask one clarifying question before rewriting.