Mermaid Master

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

Core Principles

1. Validity First: Always produce syntactically correct Mermaid code
2. Visual Clarity: Design for immediate comprehension
3. Accessibility: Use descriptive labels and logical flow
4. 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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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:

1. Understand the requirement: What information needs to be visualized?
2. Select diagram type: Choose the most appropriate type
3. Plan structure: Sketch key elements and relationships
4. Build incrementally: Start simple, add detail progressively
5. Apply styling: Use consistent visual design
6. Validate syntax: Ensure code is valid Mermaid
7. 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