mermaid-builder

Expert guidance for creating syntactically correct Mermaid diagrams. Use when creating flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, ER diagrams, or data lineage visualizations.

⭐13stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

The Mermaid Builder skill provides expert-level assistance in creating syntactically correct and visually clear Mermaid.js diagrams. It specializes in a wide range of visualizations including flowcharts, sequence diagrams, ER diagrams, and Gantt charts, specifically addressing common syntax pitfalls like label quoting to ensure seamless rendering in documentation and development environments.

Use Cases

  • System Architecture Documentation: Designing complex sequence and class diagrams to visualize software component interactions and OOP structures.
  • Database Schema Mapping: Generating precise Entity Relationship (ER) diagrams to define data models, primary keys, and table relationships.
  • Business Process Modeling: Creating clear flowcharts and decision trees to map out organizational workflows and SOPs.
  • Project Timeline Management: Developing Gantt charts to track project schedules, milestones, and resource allocation.
  • State Machine Visualization: Modeling software state transitions and logic flows using state diagrams to improve code reliability.
  • Data Lineage Tracking: Visualizing ETL pipelines and data flows across systems to maintain data governance and transparency.
namemermaid-builder
descriptionExpert guidance for creating syntactically correct Mermaid diagrams. Use when creating flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, ER diagrams, or data lineage visualizations.
allowed-toolsRead, Write, Edit, MultiEdit, Grep, Glob, Bash, WebSearch, WebFetch

Mermaid Builder

Core Philosophy

  • Correctness: Follow Mermaid syntax rules strictly
  • Clarity: Diagrams communicate complex ideas simply
  • Simplicity: Avoid overloading with unnecessary detail
  • Modularity: Break complex diagrams into subgraphs

Critical: Label Quoting Rule

RULE: Wrap labels in double quotes if they contain spaces, special characters, or punctuation.

%% CORRECT - labels with spaces quoted
flowchart LR
    A["User Login"] --> B["Process Request"]
    C["Pay $100?"] --> D["Confirm (Yes/No)"]

%% WRONG - will fail to render
flowchart LR
    A[User Login] --> B[Process Request]

Must quote: Spaces, special chars ($%&), punctuation (:,;), operators (()[]) Optional: Simple alphanumeric (Login, Process, Node1)

When in doubt, use quotes. It never hurts.

Quick Reference

Flowchart Shapes

Syntax Shape
["Text"] Rectangle
("Text") Rounded
{"Text"} Diamond (decision)
[("Text")] Cylinder (database)
(("Text")) Circle

Arrow Types

Syntax Type
--> Solid arrow
--- Solid line
-.-> Dotted arrow
==> Thick arrow
`--> Label

Diagram Types

Type Declaration Use Case
Flowchart flowchart TD Processes, workflows, decisions
Sequence sequenceDiagram Component interactions, API flows
Class classDiagram OOP structure, models
State stateDiagram-v2 State transitions
Gantt gantt Timelines, scheduling
ER erDiagram Database schema
Pie pie Proportional data

Directions: TB/TD (top-down), BT (bottom-up), LR (left-right), RL (right-left)

See resources/diagram-examples.md for complete examples of each diagram type.

Minimal Examples

Flowchart

flowchart TD
    Start["Start"] --> Check{Valid?}
    Check -->|Yes| Process["Process"]
    Check -->|No| Error["Error"]
    Process --> End["End"]

Sequence

sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response

ER Diagram

erDiagram
    USER ||--o{ ORDER : "places"
    USER { int id PK string email }
    ORDER { int id PK int user_id FK }

Subgraphs for Organization

flowchart TD
    subgraph "Frontend"
        A["UI"]
    end
    subgraph "Backend"
        B["API"]
        C[("DB")]
    end
    A --> B --> C

Styling

flowchart TD
    A["Success"] --> B["Error"]

    classDef successStyle fill:#C8E6C9,stroke:#388E3C
    classDef errorStyle fill:#FFCDD2,stroke:#D32F2F

    class A successStyle
    class B errorStyle

Common Errors to Avoid

Error Wrong Correct
Unquoted spaces A[User Login] A["User Login"]
Invalid arrow A -> B A --> B
Unquoted special A[Cost: $100] A["Cost: $100"]
Missing bracket A["Node --> B A["Node"] --> B

Validation Checklist

  • Labels with spaces are quoted
  • Labels with special characters quoted
  • Brackets properly matched
  • Arrow syntax correct (--> not ->)
  • Node IDs unique and meaningful
  • Comments explain complex sections
  • Previewed without errors

Data Lineage Patterns

See resources/data-lineage.md for:

  • ETL pipeline patterns
  • Multi-layer data architecture
  • Cross-system data flows
  • Database schema lineage
  • Streaming data lineage
  • Column-level lineage

Resources


Remember: The quoting rule is the #1 cause of Mermaid rendering failures. When in doubt, quote it.