| name | mermaid-builder |
| description | 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. |
| allowed-tools | Read 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 references/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
Data Lineage Patterns
See references/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.
