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 (

$%&

:,;

()[]

Login

Process

Node1

When in doubt, use quotes. It never hurts.

Quick Reference

Flowchart Shapes

["Text"]

("Text")

{"Text"}

[("Text")]

(("Text"))

Arrow Types

-->

---

-.->

==>

Diagram Types

flowchart TD

sequenceDiagram

classDiagram

stateDiagram-v2

gantt

erDiagram

pie

Directions:

TB

TD

BT

LR

RL

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

A[User Login]

A["User Login"]

A -> B

A --> B

A[Cost: $100]

A["Cost: $100"]

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

• Mermaid Docs
• Live Editor
• Syntax Reference

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