pm7y-mermaid-diagram

What this skill does

# 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

```mermaid
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

```mermaid
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

```mermaid
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**

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

**Option B: Use HTML entities**

- `:` → `&#58;`
- `(` → `&#40;`
- `)` → `&#41;`
- `[` → `&#91;`
- `]` → `&#93;`
- `;` → `&#59;`

**WRONG:**

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

---

### Rule 2: Reserved Words

**"end" (lowercase):**

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

**"o" and "x" at edge start:**

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

---

### Rule 3: Subgraph Syntax

**CORRECT:**

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

**WRONG:**

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

---

### Rule 4: Note Syntax (Diagram-Specific)

**sequenceDiagram ONLY:**

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

**flowchart/graph: NO note keyword**

```mermaid
flowchart TD
    Note[Use regular node instead]  ✅
```

---

### Rule 5: classDiagram Rules

**Define before linking:**

```mermaid
classDiagram
    class Animal {
        +name
    }
    class Dog

    Animal <|-- Dog  ✅ Both defined
```

**Method syntax:**

```mermaid
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:**

```mermaid
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:**

```mermaid
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:**

```mermaid
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:**

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

---

### stateDiagram-v2

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

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

---

### erDiagram

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

    CUSTOMER {
        string name
        int id
    }
```

---

### gantt

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

---

### mindmap

```mermaid
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

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

---

### Error 2: "Subgraph X not found"

**Cause:** Missing ID in subgraph declaration

**Solution:**

```mermaid
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:**

```mermaid
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](flowchart-reference.md) - Complete flowchart syntax
- [sequence-reference.md](sequence-reference.md) - Complete sequence diagram syntax
- [class-reference.md](class-reference.md) - Complete class diagram syntax
- [common-errors.md](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)

```mermaid
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)

```mermaid
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)

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

    FileInfo {
        string path
        date lastModified
    }
```

---

## Quick Reference

**Escape special chars:** Use `"` or `&#XX;`
**Subgr