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.