mermaid-diagram

name	mermaid-diagram
description	Creates syntactically correct mermaid diagrams (flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, mindmap) following official specifications. Prevents common errors like special characters in labels, subgraph syntax, note misuse, and reserved words. Use when creating or editing mermaid diagrams in documentation or design files.
allowed-tools	Write, Edit, Read

Mermaid Diagram Skill

Creates syntactically correct mermaid diagrams following official specifications and preventing common errors.

---

Overview

This skill helps you create error-free mermaid diagrams by:

• Following official mermaid syntax specifications
• Avoiding common pitfalls (special characters, reserved words, wrong note syntax)
• Providing correct structure for each diagram type
• Based on real experience: 76 diagrams fixed, 20+ iterations avoided

When to use:

• Creating flowcharts, sequence diagrams, class diagrams, etc.
• Editing existing mermaid diagrams
• Converting design ideas into visual diagrams

---

Quick Start

Flowchart Basic Syntax

flowchart TD
    Start[Start Process]
    Process[Process Data]
    Decision{Is Valid?}
    End[End]

    Start --> Process
    Process --> Decision
    Decision -->|Yes| End
    Decision -->|No| Process

Sequence Diagram Basic Syntax

sequenceDiagram
    participant A as Alice
    participant B as Bob

    A->>B: Hello Bob
    B->>A: Hi Alice

    Note right of B: Bob thinks

Class Diagram Basic Syntax

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }

    class Dog {
        +bark()
    }

    Animal <|-- Dog

---

Critical Rules (MUST FOLLOW)

Rule 1: Special Characters in Labels

Problem characters: :, (), [], {}, @, ;, ,

Solutions:

Option A: Use double quotes

flowchart LR
    A["Function: process()"]
    B["Array [1, 2, 3]"]

Option B: Use HTML entities

• : → :
• ( → (
• ) → )
• [ → [
• ] → ]
• ; → &#59;

WRONG:

flowchart LR
    A[Function: process()]  ❌ Colon breaks syntax

---

Rule 2: Reserved Words

"end" (lowercase):

flowchart TD
    Start --> End   ✅ Capitalized OK
    Start --> end   ❌ Breaks diagram
    Start --> END   ✅ All caps OK

"o" and "x" at edge start:

flowchart LR
    A --- oB  ❌ Creates circle edge
    A --- xB  ❌ Creates cross edge
    A --- oC  ✅ Add space: o B

---

Rule 3: Subgraph Syntax

CORRECT:

flowchart TD
    subgraph ID["Subgraph Title"]
        A[Node A]
        B[Node B]
    end

WRONG:

flowchart TD
    subgraph "Subgraph Title"  ❌ Missing ID
        A[Node A]
    end

---

Rule 4: Note Syntax (Diagram-Specific)

sequenceDiagram ONLY:

sequenceDiagram
    A->>B: Message
    Note right of B: This is valid ✅

flowchart/graph: NO note keyword

flowchart TD
    Note[Use regular node instead]  ✅

---

Rule 5: classDiagram Rules

Define before linking:

classDiagram
    class Animal {
        +name
    }
    class Dog

    Animal <|-- Dog  ✅ Both defined

Method syntax:

classDiagram
    class MyClass {
        +method(param) ReturnType  ✅
        +field: Type  ✅
    }

---

Diagram Types

Flowchart / Graph

Declaration:

• flowchart TD (Top-Down)
• flowchart LR (Left-Right)
• graph TD (alias)

Node shapes:

• A[Rectangle]
• B(Rounded)
• C{Diamond}
• `D([Stadium)])
• E[[Subroutine]]

Edges:

• A --> B (arrow)
• A --- B (line)
• A -.-> B (dotted arrow)
• A ==> B (thick arrow)
• A -->|label| B (labeled edge)

Subgraph:

flowchart TD
    subgraph SG1["Group 1"]
        A[Node A]
        B[Node B]
    end

    subgraph SG2["Group 2"]
        C[Node C]
    end

    A --> C

---

sequenceDiagram

Participants:

sequenceDiagram
    participant A as Alice
    participant B as Bob

Messages:

• A->>B: Solid arrow
• A-->>B: Dotted arrow
• A-)B: Async

Notes:

• Note right of A: Text
• Note left of B: Text
• Note over A,B: Text

Blocks:

• alt, opt, par, loop, rect

---

classDiagram

Class definition:

classDiagram
    class ClassName {
        +publicField: Type
        -privateField: Type
        +method(param) ReturnType
    }

Relationships:

• A <|-- B (inheritance)
• A *-- B (composition)
• A o-- B (aggregation)
• A --> B (association)
• A ..> B (dependency)
• A ..|> B (realization)

Edge labels:

classDiagram
    A --> B : label
    A ..> C : another label

---

stateDiagram-v2

stateDiagram-v2
    [*] --> State1
    State1 --> State2
    State2 --> [*]

    state State1 {
        [*] --> Nested1
        Nested1 --> [*]
    }

---

erDiagram

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

    CUSTOMER {
        string name
        int id
    }

---

gantt

gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Phase 1
    Task 1 :a1, 2025-01-01, 30d
    Task 2 :after a1, 20d

---

mindmap

mindmap
  root((Central Idea))
    Topic1
      Subtopic1
      Subtopic2
    Topic2

---

Common Errors and Solutions

Error 1: "Parse error on line X"

Cause: Special characters in labels

Solution: Use double quotes or HTML entities

flowchart LR
    A["Method: process()"]  ✅

---

Error 2: "Subgraph X not found"

Cause: Missing ID in subgraph declaration

Solution:

flowchart TD
    subgraph ID["Title"]  ✅
        A[Node]
    end

---

Error 3: "Syntax error in graph"

Cause: Reserved word "end" in lowercase

Solution: Capitalize: End, END

---

Error 4: "Note is not defined"

Cause: Using Note keyword in flowchart

Solution: Use regular node or switch to sequenceDiagram

---

Error 5: Unexpected edge type

Cause: "o" or "x" at edge start

Solution:

flowchart LR
    A --- B  ✅
    A --- oC  ❌ (creates circle edge)
    A --- " oC"  ✅ (add space)

---

Advanced Topics

For detailed specifications on specific diagram types, see:

• flowchart-reference.md - Complete flowchart syntax
• sequence-reference.md - Complete sequence diagram syntax
• class-reference.md - Complete class diagram syntax
• common-errors.md - Error patterns from 76 diagram corrections

---

Validation Checklist

Before finalizing a mermaid diagram:

• No special characters without quotes/escaping
• No lowercase "end" as node name
• Subgraphs have ID: subgraph ID["Title"]
• Note only in sequenceDiagram
• All referenced nodes are defined (classDiagram)
• No "o" or "x" at edge start in flowchart
• Proper diagram type declaration

---

Best Practices

1. Keep it simple: Start with basic syntax, add complexity only if needed
2. Use double quotes: For any label with special characters
3. Test incrementally: Add nodes/edges one at a time if diagram is complex
4. Consistent naming: Use clear, descriptive IDs
5. Avoid nesting: Deep nesting often causes issues

---

Examples from Swift-Selena Project

System Architecture (flowchart)

graph TB
    subgraph Server["MCP Server"]
        Main[SwiftMCPServer]
        LSP[LSPState]
    end

    subgraph Tools["Tools"]
        T1[Tool 1]
        T2[Tool 2]
    end

    Main --> LSP
    Main --> Tools

    style Server fill:#e3f2fd

LSP Protocol Flow (sequenceDiagram)

sequenceDiagram
    participant C as Client
    participant L as LSP

    C->>L: initialize
    L->>C: response
    C->>L: initialized

    Note over L: Ready for requests

    C->>L: textDocument/references
    L->>C: result

Data Model (erDiagram)

erDiagram
    ProjectMemory ||--o{ FileInfo : contains
    ProjectMemory ||--o{ Note : contains

    FileInfo {
        string path
        date lastModified
    }

---

Quick Reference

Escape special chars: Use " or &#XX; Subgraph: subgraph ID["Title"] Note: sequenceDiagram only Reserved: Avoid lowercase "end" classDiagram: Define before link

For complete syntax details, refer to supporting reference files.