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.