Mermaid Diagram Framework Skill

A Claude Code skill for creating technical diagrams with Mermaid — covering flowcharts, sequence diagrams, ERDs, class diagrams, Gantt charts, and architecture visualization in markdown.

When to Use This Skill

Choose this skill when:

• Creating architecture or system design diagrams
• Documenting API flows or user journeys
• Generating ERDs or class diagrams from code
• Building Gantt charts for project planning
• Adding visual documentation to README or docs
• Creating diagrams that stay in sync with code (text-based)

Consider alternatives when:

• You need pixel-perfect design mockups (use Figma)
• You need interactive diagrams (use D3.js or a diagramming library)
• You need presentation slides (use Marp or PowerPoint)

Quick Start

Copy
# Add diagrams directly in markdown files

```mermaid
flowchart TD
    A[User Request] --> B{Authenticated?}
    B -->|Yes| C[Process Request]
    B -->|No| D[Login Page]
    C --> E[Return Response]
    D --> F[Auth Service]
    F --> B

## Core Concepts

### Diagram Types

| Type | Syntax | Use Case |
|------|--------|----------|
| Flowchart | `flowchart TD` | Process flows, decision trees |
| Sequence | `sequenceDiagram` | API calls, message passing |
| Class | `classDiagram` | OOP design, type relationships |
| ERD | `erDiagram` | Database schema visualization |
| Gantt | `gantt` | Project timelines, schedules |
| State | `stateDiagram-v2` | State machines, lifecycle flows |
| Pie | `pie` | Data distribution visualization |
| Git | `gitgraph` | Branch and merge visualization |

### Sequence Diagram

```mermaid
sequenceDiagram
    actor User
    participant API
    participant Auth
    participant DB

    User->>API: POST /login
    API->>Auth: Validate credentials
    Auth->>DB: Query user
    DB-->>Auth: User record
    Auth-->>API: JWT token
    API-->>User: 200 OK + token

Entity Relationship Diagram

Copy
erDiagram
    USER ||--o{ ORDER : places
    USER { string email PK; string name; date created_at }
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER { uuid id PK; uuid user_id FK; decimal total }
    ORDER_ITEM }|--|| PRODUCT : references
    ORDER_ITEM { uuid order_id FK; uuid product_id FK; int quantity }
    PRODUCT { uuid id PK; string name; decimal price }

Architecture Flowchart

Copy
flowchart LR
    subgraph Client
        A[Browser] --> B[React App]
    end
    subgraph API Layer
        C[API Gateway] --> D[Auth Service]
        C --> E[User Service]
        C --> F[Order Service]
    end
    subgraph Data
        G[(PostgreSQL)]
        H[(Redis Cache)]
    end
    B --> C
    D --> G
    E --> G
    E --> H
    F --> G

Configuration

Parameter	Type	Default	Description
theme	string	"default"	Mermaid theme: default, dark, forest, neutral
direction	string	"TD"	Default flow direction: TD, LR, BT, RL
font_family	string	"arial"	Font family for labels
curve	string	"basis"	Line curve style: basis, linear, stepBefore
wrap	boolean	true	Enable text wrapping in nodes
max_width	number	200	Maximum node text width

Best Practices

1. Use the simplest diagram type for your purpose — a flowchart is easier to read than a sequence diagram for simple processes; choose the type that communicates most clearly with your audience.

2. Keep diagrams under 15-20 nodes — large diagrams become unreadable; break complex systems into multiple focused diagrams (overview + detail views) rather than one massive diagram.

3. Use subgraphs to group related components — subgraphs with labels make architecture diagrams clearer by visually grouping services, layers, or domains.

4. Store diagrams in markdown files alongside code — text-based Mermaid diagrams can be version-controlled, diffed, and reviewed like code; they stay in sync with the codebase they document.

5. Add meaningful labels to all edges — unlabeled arrows are ambiguous; A -->|"HTTP POST"| B communicates more than A --> B.

Common Issues

Diagram doesn't render in GitHub — GitHub supports Mermaid in markdown files and issues. Ensure the code block uses the mermaid language identifier. Some advanced features may not be supported in older Mermaid versions.

Text overlaps on complex diagrams — Nodes with long text cause overlapping. Use shorter labels and add detailed descriptions outside the diagram, or use \n for line breaks within node text.

Sequence diagram arrows are confusing — Use -->> for async calls, ->> for sync calls, and -->>- for async returns. Consistent arrow styles help readers understand the communication pattern.