Mermaid Diagramming

Mermaid Diagramming

Create clear, professional Mermaid diagrams for technical documentation. Covers all major diagram types with both basic and styled variants, rendering guidance, and export recommendations.

When to Use This Skill

• Creating flowcharts for process documentation or decision trees
• Drawing sequence diagrams for API interactions or system communication
• Building ERDs for database schema documentation
• Designing state machine diagrams for workflow states
• Producing Gantt charts for project timelines
• Documenting system architecture with C4 or network diagrams
• Adding visual aids to README files, ADRs, or design docs

Quick Reference

---

Workflow Overview

Phase 1: Scope     → Identify what to visualize, audience, and diagram type
Phase 2: Draft     → Write base Mermaid code with correct syntax
Phase 3: Style     → Add theming, colors, and accessibility annotations
Phase 4: Deliver   → Provide rendering instructions and suggest iterations

---

Phase 1: Scope

Before writing any code, clarify:

1. What is the narrative? The diagram should tell a story or answer a question. 2. Who is the audience? Developers need detail; stakeholders need overview. 3. What entities and relationships exist? List nodes and edges before drawing. 4. Which diagram type fits? Use the selection guide below.

Diagram Type Selection

---

Phase 2: Draft

Structure Rules

1. One concept per diagram — split complex systems into multiple views 2. Limit nodes — keep under 15 nodes per diagram; split if larger 3. Meaningful labels — use descriptive text, not single letters 4. Consistent direction — prefer top-to-bottom (TB) or left-to-right (LR) 5. Group related nodes — use subgraph to cluster related elements

Code Conventions

%% Always start with a comment describing the diagram's purpose
%% Use consistent quoting for labels with special characters
flowchart LR
    A["User Request"] --> B{"Auth Check"}
    B -->|Valid| C["Process Request"]
    B -->|Invalid| D["Return 401"]

• Use double quotes for labels containing special characters
• Add comments (%%) explaining non-obvious relationships
• Prefer --> for solid lines, -.-> for dashed, ==> for thick
• Use descriptive edge labels: -->|"reason"| TargetNode

---

Phase 3: Style

Theming

Apply consistent styling using %%{init: ...}%% directives:

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4A90D9'}}}%%
flowchart TB
    A["Start"] --> B["End"]

Node Styling

flowchart LR
    A["Normal"]
    B["Highlighted"]:::highlight
    classDef highlight fill:#f9f,stroke:#333,stroke-width:2px

Accessibility

• Use high-contrast color combinations
• Do not rely on color alone to convey meaning — add labels and shapes
• Include alt text when embedding: ![Diagram description](path)
• Provide a text summary alongside complex diagrams

---

Phase 4: Deliver

Always Provide

1. Basic version — clean, unstyled diagram that renders anywhere 2. Styled version — themed variant with colors and emphasis 3. Rendering note — where to preview (GitHub, Mermaid Live, VS Code extension) 4. Suggestions — complementary diagrams or next iterations

Rendering Options

Export Formats

• SVG: Best for web and docs (scalable, searchable text)
• PNG: Fallback for platforms without Mermaid support
• PDF: For print or formal documentation

---

Best Practices

• Start simple — get the structure right before adding style
• Test rendering — verify on the target platform before committing
• Version diagrams — update diagrams when the underlying system changes
• Colocate with docs — keep diagrams in the same directory as related documentation
• Use subgraphs — group related nodes to reduce visual complexity

Anti-Patterns

• Putting too many nodes in one diagram (split at 15+ nodes)
• Using single-letter node IDs without labels
• Relying on color alone to convey meaning
• Hard-coding pixel widths that break on different renderers
• Leaving diagrams out of date after system changes

Mermaid Diagram Types Reference

Syntax, patterns, and code examples for every major Mermaid diagram type.

---

Flowchart

Best for: process flows, decision trees, system overviews.

Basic Syntax

flowchart TD
    A["Start"] --> B{"Decision?"}
    B -->|Yes| C["Action 1"]
    B -->|No| D["Action 2"]
    C --> E["End"]
    D --> E

Direction Options

Node Shapes

flowchart LR
    A["Rectangle — default"]
    B("Rounded rectangle")
    C(["Stadium / pill"])
    D[["Subroutine"]]
    E[("Database / cylinder")]
    F{"Diamond — decision"}
    G{{"Hexagon"}}
    H>"Asymmetric / flag"]
    I(("Circle"))
    J{{" Double circle"}}

Edge Types

flowchart LR
    A --> B
    A --- C
    A -.-> D
    A ==> E
    A --"label"--> F
    A -.."dashed label".-> G
    A =="thick label"==> H

Subgraphs

flowchart TB
    subgraph Frontend
        A["React App"] --> B["API Client"]
    end
    subgraph Backend
        C["API Server"] --> D["Database"]
    end
    B --> C

Styling

flowchart LR
    A["Normal"]:::default
    B["Success"]:::success
    C["Error"]:::error

    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
    classDef success fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef error fill:#f8d7da,stroke:#dc3545,stroke-width:2px

---

Sequence Diagram

Best for: API interactions, message passing, time-ordered communication.

Basic Syntax

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

    C->>S: POST /api/login
    activate S
    S->>DB: SELECT user WHERE email = ?
    DB-->>S: User record
    S-->>C: 200 OK + JWT token
    deactivate S

Arrow Types

Features

Activation boxes:

sequenceDiagram
    A->>B: Request
    activate B
    B->>C: Sub-request
    activate C
    C-->>B: Response
    deactivate C
    B-->>A: Response
    deactivate B

Loops and conditions:

sequenceDiagram
    Client->>Server: Request

    alt valid token
        Server-->>Client: 200 OK
    else expired token
        Server-->>Client: 401 Unauthorized
        Client->>Server: Refresh token
        Server-->>Client: New token
    end

    loop Every 30s
        Client->>Server: Heartbeat
    end

    opt Debug mode
        Server->>Logger: Log request details
    end

Notes:

sequenceDiagram
    A->>B: Message
    Note over A,B: This spans both participants
    Note right of B: This is a side note

---

Class Diagram

Best for: object models, inheritance, interfaces.

Basic Syntax

classDiagram
    class User {
        +String name
        +String email
        -String passwordHash
        +login(credentials) bool
        +logout() void
    }

    class Admin {
        +String[] permissions
        +grantRole(user, role) void
    }

    User <|-- Admin : extends

Relationship Types

Cardinality

classDiagram
    User "1" --> "*" Order : places
    Order "1" --> "1..*" LineItem : contains
    LineItem "*" --> "1" Product : references

---

State Diagram

Best for: lifecycle states, workflow transitions, finite state machines.

Basic Syntax

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Approved : approve
    Review --> Draft : request_changes
    Approved --> Published : publish
    Published --> Archived : archive
    Archived --> [*]

Composite States

stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> Idle
        Idle --> Processing : receive_request
        Processing --> Idle : complete
        Processing --> Error : failure
        Error --> Idle : retry
    }

    Active --> Shutdown : terminate
    Shutdown --> [*]

Transitions with Guards

stateDiagram-v2
    Pending --> Approved : review [score >= 80]
    Pending --> Rejected : review [score < 80]

---

Entity Relationship Diagram

Best for: database schemas, data models.

Basic Syntax

erDiagram
    USER {
        int id PK
        string name
        string email UK
        timestamp created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
        timestamp ordered_at
    }

    LINE_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }

    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }

    USER ||--o{ ORDER : "places"
    ORDER ||--|{ LINE_ITEM : "contains"
    PRODUCT ||--o{ LINE_ITEM : "referenced in"

Relationship Notation

---

Gantt Chart

Best for: project timelines, task scheduling, dependencies.

Basic Syntax

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    excludes weekends

    section Planning
    Requirements gathering :a1, 2026-01-06, 5d
    Architecture design    :a2, after a1, 3d

    section Development
    Backend implementation :b1, after a2, 10d
    Frontend implementation :b2, after a2, 8d
    Integration            :b3, after b1, 5d

    section Testing
    QA testing             :c1, after b3, 5d
    UAT                    :c2, after c1, 3d

    section Release
    Deployment             :milestone, after c2, 0d

Task Status

gantt
    section Tasks
    Completed task :done, t1, 2026-01-06, 3d
    Active task    :active, t2, after t1, 3d
    Future task    :t3, after t2, 3d
    Critical task  :crit, t4, after t3, 2d
    Milestone      :milestone, after t4, 0d

---

Pie Chart

Best for: proportional data, distribution breakdowns.

pie title Code Coverage by Module
    "Auth" : 92
    "API" : 87
    "Database" : 78
    "UI" : 65
    "Utils" : 95

---

Mindmap

Best for: hierarchical brainstorming, topic organization.

mindmap
  root((System Architecture))
    Frontend
      React SPA
      Mobile App
      Admin Dashboard
    Backend
      API Gateway
      Auth Service
      Business Logic
    Data Layer
      PostgreSQL
      Redis Cache
      S3 Storage
    Infrastructure
      Kubernetes
      CI/CD Pipeline
      Monitoring

---

Timeline

Best for: historical events, version history, milestones.

timeline
    title Product Release History
    2024 : v1.0 Launch
         : v1.1 Bug fixes
    2025 : v2.0 Major rewrite
         : v2.1 Performance improvements
         : v2.2 API expansion
    2026 : v3.0 Cloud-native architecture

---

Git Graph

Best for: branching strategies, release flows.

gitGraph
    commit id: "init"
    branch develop
    commit id: "feat-1"
    commit id: "feat-2"
    branch feature/auth
    commit id: "auth-impl"
    commit id: "auth-tests"
    checkout develop
    merge feature/auth
    checkout main
    merge develop tag: "v1.0.0"
    branch hotfix/security
    commit id: "patch"
    checkout main
    merge hotfix/security tag: "v1.0.1"

---

User Journey

Best for: user experience flows, satisfaction mapping.

journey
    title User Onboarding Experience
    section Sign Up
      Visit landing page: 5: User
      Fill registration form: 3: User
      Verify email: 2: User
    section First Use
      Complete tutorial: 4: User
      Create first project: 4: User
      Invite team member: 3: User
    section Activation
      Use core feature: 5: User
      Set up integration: 3: User

The number (1-5) represents user satisfaction at that step.

---

Styling Tips

Global Theme Configuration

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#4A90D9',
    'primaryTextColor': '#fff',
    'primaryBorderColor': '#2C6FAC',
    'lineColor': '#666',
    'secondaryColor': '#F5A623',
    'tertiaryColor': '#7ED321',
    'fontSize': '14px'
  }
}}%%

Available Themes

Accessibility Checklist

• [ ] Colors have sufficient contrast (WCAG AA minimum)
• [ ] Meaning is not conveyed by color alone (use labels and shapes)
• [ ] Diagrams have alt text when embedded in HTML/markdown
• [ ] Complex diagrams include a text summary
• [ ] Font size is readable (14px minimum)