Creating Mermaid Diagrams

Expert guidance for creating, editing, and validating Mermaid diagrams.

Supported Diagram Types

Quick Start

Flowchart

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

Sequence Diagram

sequenceDiagram
    participant U as User
    participant S as Server
    participant D as Database

    U->>S: Request
    S->>D: Query
    D-->>S: Results
    S-->>U: Response

Class Diagram

classDiagram
    class Animal {
        +String name
        +makeSound()
    }
    class Dog {
        +fetch()
    }
    Animal <|-- Dog

What Would You Like To Do?

1. •Create a new diagram - See workflows/create-diagram.md
2. •Edit an existing diagram - See workflows/edit-diagram.md
3. •Validate syntax - See workflows/validate-diagram.md
4. •Learn diagram syntax - See reference files above

Diagram Selection Guide

Visualizing processes or decisions?

• •Use Flowchart (TD for top-down, LR for left-right)

Showing interactions between systems?

• •Use Sequence Diagram for temporal flow

Modeling data or objects?

• •Use Class Diagram for code/type relationships
• •Use ER Diagram for database schema

Tracking state changes?

• •Use State Diagram for state machines

Planning timelines?

• •Use Gantt Chart for project schedules
• •Use Timeline for historical events

Showing proportions?

• •Use Pie Chart for distributions

Organizing ideas?

• •Use Mindmap for hierarchical brainstorming

Quick Validation

Validate with mermaid-cli:

# Using the skill's validation script
./scripts/validate-mermaid.sh diagram.md

# Or use npx directly
npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o output.svg

Manual verification: Paste at mermaid.live

Common Patterns

See references/common-patterns.md for:

• •Subgraphs for grouping related nodes
• •Styling nodes and edges
• •Multi-diagram markdown documents
• •Integration patterns

Styling and Themes

See references/styling-and-themes.md for:

• •Built-in themes: default, dark, forest, neutral
• •Custom CSS styling
• •Node and edge styling with classDef

Anti-Patterns to Avoid

Templates

Ready-to-use starter templates:

• •flowchart.md - Process flow template
• •sequence-diagram.md - API interaction template
• •class-diagram.md - OOP design template
• •architecture-diagram.md - System architecture
• •er-diagram.md - Database schema template

Requirements

For validation, one of:

• •npx (Node.js) - runs @mermaid-js/mermaid-cli on demand
• •GitHub/GitLab - renders Mermaid in markdown files
• •VS Code - with Mermaid preview extension

Guidelines

• •Always validate diagrams before finalizing
• •Prefer simple diagrams over complex ones
• •Use subgraphs when diagrams exceed ~15 nodes
• •Include labels on all decision branches
• •Match diagram type to information being visualized
• •Link to official Mermaid docs for advanced syntax not covered in quick references

Success Criteria

A well-crafted diagram:

• • Uses the correct diagram type for the information
• • Has clear, descriptive labels
• • Uses consistent styling
• • Validates without errors
• • Is readable at a reasonable size
• • Includes only necessary complexity

References

• •Common patterns
• •Styling and themes
• •Official Mermaid docs