Mermaid Master

Expert guidance for creating valid, beautiful, and accessible Mermaid diagrams.

Core Principles

Validity First: Always produce syntactically correct Mermaid code
Visual Clarity: Design for immediate comprehension
Accessibility: Use descriptive labels and logical flow
Appropriate Complexity: Match diagram complexity to information needs

Diagram Type Selection

Choose the diagram type that best matches the information structure:

Flowchart: Processes, decisions, algorithms, workflows
Sequence: Time-based interactions, API calls, messaging flows
Class: Object-oriented designs, data structures, type hierarchies
State: State machines, lifecycle diagrams, status workflows
ER (Entity Relationship): Database schemas, data models
Gantt: Project timelines, schedules, resource planning
Pie: Proportional data, market share, budget allocation
Git Graph: Branch strategies, release flows, version history
User Journey: User experience flows, customer journeys
Quadrant Chart: Priority matrices, positioning maps
Timeline: Historical events, roadmaps

Universal Best Practices

Syntax Essentials

Critical syntax rules:

Always use
```
graph
```
or
```
flowchart
```
(never
```
flow
```
)
Direction syntax:
```
TD
```
(top-down),
```
LR
```
(left-right),
```
BT
```
,
```
RL
```
Node IDs must be unique within a diagram
Avoid special characters in IDs (use
```
nodeId["Label"]
```
for special chars)
Use proper quote escaping:
```
"text with \"quotes\""
```
Comments use
```
%%
```
prefix

Node shapes:

mermaid

A[Rectangle]
B(Rounded rectangle)
C([Stadium/Pill shape])
D[[Subroutine]]
E[(Database)]
F((Circle))
G>Flag/Asymmetric]
H{Decision diamond}
I{{Hexagon}}
J[/Parallelogram/]
K[\Reverse parallelogram\]
L[/Trapezoid\]
M[\Reverse trapezoid/]

Connection types:

```
-->
```
solid arrow
```
---
```
solid line (no arrow)
```
-.->
```
dotted arrow
```
-.-
```
dotted line
```
==>
```
thick arrow
```
===
```
thick line
```
--text-->
```
labeled arrow
```
---|text|---
```
labeled line

Visual Design Guidelines

Layout optimization:

Keep diagrams focused (5-15 nodes optimal, max 25)
Use consistent node shapes for similar concepts
Place most important elements at the top or left
Group related nodes visually using subgraphs
Avoid crossing lines when possible

Label clarity:

Use concise, descriptive labels (2-5 words ideal)
Keep text under 40 characters per node
Use title case for major nodes, sentence case for descriptions
Include action verbs in process steps ("Process Payment", not "Payment")

Hierarchy and grouping:

mermaid

flowchart TD
    subgraph Frontend
        A[Web App]
        B[Mobile App]
    end
    subgraph Backend
        C[API Server]
        D[Database]
    end
    A --> C
    B --> C
    C --> D

Styling and Theming

Class-based styling:

mermaid

flowchart TD
    A[Normal Node]
    B[Important Node]
    C[Critical Node]
    
    classDef important fill:#ff9,stroke:#333,stroke-width:2px
    classDef critical fill:#f99,stroke:#333,stroke-width:4px
    
    class B important
    class C critical

Individual node styling:

mermaid

flowchart TD
    A[Start]
    B[Process]
    C[End]
    
    style A fill:#9f9,stroke:#333,stroke-width:2px
    style C fill:#f99,stroke:#333,stroke-width:2px

Recommended color schemes:

Neutral:
```
fill:#f5f5f5,stroke:#333
```
Success/Start:
```
fill:#d4edda,stroke:#28a745
```
Warning:
```
fill:#fff3cd,stroke:#ffc107
```
Error/End:
```
fill:#f8d7da,stroke:#dc3545
```
Info:
```
fill:#d1ecf1,stroke:#17a2b8
```

Diagram Type Details

Flowcharts

Structure:

mermaid

flowchart TD
    Start([Start]) --> Input[/Input Data/]
    Input --> Process{Valid?}
    Process -->|Yes| Action[Process Data]
    Process -->|No| Error[Show Error]
    Action --> Output[/Output Result/]
    Error --> Input
    Output --> End([End])

Best practices:

Start with a clear entry point (oval/stadium shape)
Use diamonds for all decisions
Label decision branches clearly (Yes/No, True/False)
End with explicit termination point
Use parallelograms for input/output
Keep decision points binary when possible

Sequence Diagrams

Structure:

mermaid

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database
    
    User->>Frontend: Click Submit
    activate Frontend
    Frontend->>API: POST /api/data
    activate API
    API->>Database: INSERT query
    activate Database
    Database-->>API: Success
    deactivate Database
    API-->>Frontend: 200 OK
    deactivate API
    Frontend-->>User: Show confirmation
    deactivate Frontend

Best practices:

Use activate/deactivate to show execution context
Order participants left-to-right by interaction flow
Use
```
-->>
```
for returns/responses
Add
```
Note
```
for important context
Use
```
loop
```
,
```
alt
```
,
```
opt
```
,
```
par
```
for control flow
Keep interactions focused (max 8-12 messages)

Class Diagrams

Structure:

mermaid

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +bark() void
    }
    class Cat {
        +bool indoor
        +meow() void
    }
    
    Animal <|-- Dog
    Animal <|-- Cat

Relationships:

```
<|--
```
inheritance
```
*--
```
composition
```
o--
```
aggregation
```
-->
```
association
```
--
```
link
```
..>
```
dependency
```
..|>
```
realization

State Diagrams

Structure:

mermaid

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Approved: Approve
    Review --> Rejected: Reject
    Rejected --> Draft: Revise
    Approved --> Published: Publish
    Published --> Archived: Archive
    Archived --> [*]

Best practices:

Start with
```
[*]
```
initial state
End with
```
[*]
```
final state (if applicable)
Label all transitions clearly
Use composite states for complex substates
Include error/cancel paths

Entity Relationship Diagrams

Structure:

mermaid

erDiagram
    Customer ||--o{ Order : places
    Customer {
        string name
        string email
        int customer_id PK
    }
    Order ||--|{ OrderLine : contains
    Order {
        int order_id PK
        date order_date
        int customer_id FK
    }
    Product ||--o{ OrderLine : includes
    OrderLine {
        int order_id FK
        int product_id FK
        int quantity
    }
    Product {
        int product_id PK
        string name
        decimal price
    }

Cardinality symbols:

```
||--||
```
one-to-one
```
||--o{
```
one-to-many
```
}o--o{
```
many-to-many
```
||--||
```
exactly one
```
|o--o|
```
zero or one

Gantt Charts

Structure:

mermaid

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Planning
        Requirements     :done, req, 2024-01-01, 2024-01-15
        Design          :active, design, 2024-01-16, 2024-02-01
    section Development
        Frontend        :dev1, 2024-02-02, 30d
        Backend         :dev2, 2024-02-02, 30d
        Integration     :after dev1 dev2, 10d
    section Testing
        QA Testing      :test, after dev1 dev2, 15d
        UAT             :after test, 10d

Best practices:

Use meaningful section names
Include status indicators (done, active, crit)
Show dependencies with
```
after
```
keyword
Use consistent date format
Keep task names concise

Common Pitfalls to Avoid

Syntax errors:

❌
```
flow TD
```
→ ✅
```
flowchart TD
```
❌ Unescaped quotes in labels → ✅ Use
```
#quot;
```
or single quotes
❌ Special chars in node IDs → ✅ Use alphanumeric IDs only
❌ Missing semicolons in complex flows → ✅ Use them for clarity

Design issues:

❌ Too many nodes (>25) → ✅ Split into multiple diagrams
❌ Unclear labels → ✅ Use descriptive, action-oriented text
❌ Inconsistent node shapes → ✅ Define shape conventions
❌ No visual hierarchy → ✅ Use subgraphs and styling

Accessibility issues:

❌ Color-only differentiation → ✅ Also use shapes/labels
❌ Tiny text in complex diagrams → ✅ Simplify or split
❌ Unclear flow direction → ✅ Add explicit arrows

Advanced Techniques

Interactive Elements

Add links and tooltips:

mermaid

flowchart TD
    A[Homepage]
    B[Product Page]
    C[Checkout]
    
    click A "https://example.com" "Go to homepage"
    click B "https://example.com/products" "View products"

Complex Styling

Combine multiple styling approaches:

mermaid

flowchart LR
    A[Start] --> B{Decision}
    B -->|Path 1| C[Option A]
    B -->|Path 2| D[Option B]
    C --> E[End]
    D --> E
    
    classDef decision fill:#ffe6cc,stroke:#d79b00,stroke-width:2px
    classDef terminal fill:#d5e8d4,stroke:#82b366,stroke-width:2px
    
    class B decision
    class A,E terminal

Subgraph Styling

mermaid

flowchart TB
    subgraph cloud[Cloud Infrastructure]
        direction LR
        A[Load Balancer]
        B[App Server 1]
        C[App Server 2]
    end
    
    D[User] --> A
    A --> B
    A --> C
    
    style cloud fill:#e1f5ff,stroke:#01579b

Workflow

When creating a diagram:

Understand the requirement: What information needs to be visualized?
Select diagram type: Choose the most appropriate type
Plan structure: Sketch key elements and relationships
Build incrementally: Start simple, add detail progressively
Apply styling: Use consistent visual design
Validate syntax: Ensure code is valid Mermaid
Review clarity: Can the diagram be understood quickly?

Additional Resources

For complex diagrams with many nodes or advanced patterns, see:

references/diagram-patterns.md: Real-world examples and templates
references/syntax-reference.md: Complete syntax guide for all diagram types

Quality Checklist

Before finalizing a diagram:

Syntax is valid (no errors)
Labels are clear and concise
Flow direction is logical
Visual hierarchy guides the eye
Styling enhances (not distracts from) content
Complexity is appropriate (not overwhelming)
Diagram answers the original question/need

mermaid-master

NPX Install

Tags

SKILL.md Content

Mermaid Master

Core Principles

Diagram Type Selection

Universal Best Practices

Syntax Essentials

Visual Design Guidelines

Styling and Theming

Diagram Type Details

Flowcharts

Sequence Diagrams

Class Diagrams

State Diagrams

Entity Relationship Diagrams

Gantt Charts

Common Pitfalls to Avoid

Advanced Techniques

Interactive Elements

Complex Styling

Subgraph Styling

Workflow

Additional Resources

Quality Checklist