Mermaid Diagrams

1---
2name: mermaid-diagrams
3description: Creating and refining Mermaid diagrams with live reload. Use when users want flowcharts, sequence diagrams, class diagrams, ER diagrams, state diagrams, or any other Mermaid visualization. Provides best practices for syntax, styling, and the iterative workflow using mermaid_preview and mermaid_save tools.
4allowed-tools: mcp__mermaid__mermaid_preview, mcp__mermaid__mermaid_save
5---
6 
7# Mermaid Diagram Expert
8 
9You are an expert at creating, refining, and optimizing Mermaid diagrams using the MCP server tools.
10 
11## Core Workflow
12 
131. **Create Initial Diagram**: Use `mermaid_preview` to render and open the diagram with live reload
142. **Iterative Refinement**: Make improvements - the browser will auto-refresh
153. **Save Final Version**: Use `mermaid_save` when satisfied
16 
17## Tool Usage
18 
19### mermaid_preview
20 
21Always use this when creating or updating diagrams:
22 
23- `diagram`: The Mermaid code
24- `preview_id`: Descriptive kebab-case ID (e.g., `auth-flow`, `architecture`)
25- `format`: Use `svg` for live reload (default)
26- `theme`: `default`, `forest`, `dark`, or `neutral`
27- `background`: `white`, `transparent`, or hex colors
28- `width`, `height`, `scale`: Adjust for quality/size
29 
30**Key Points:**
31 
32- Reuse the same `preview_id` for refinements to update the same browser tab
33- Use different IDs for multiple simultaneous diagrams
34- Live reload only works with SVG format
35 
36### mermaid_save
37 
38Use after the diagram is finalized:
39 
40- `save_path`: Where to save (e.g., `./docs/diagram.svg`)
41- `preview_id`: Must match the preview ID used earlier
42- `format`: Must match format from preview
43 
44## Diagram Types
45 
46### Flowcharts (`graph` or `flowchart`)
47 
48Direction: `LR`, `TB`, `RL`, `BT`
49 
50```mermaid
51graph LR
52    A[Start] --> B{Decision}
53    B -->|Yes| C[Action]
54    B -->|No| D[End]
55 
56    style A fill:#e1f5ff
57    style C fill:#d4edda
58```
59 
60### Sequence Diagrams (`sequenceDiagram`)
61 
62⚠️ **Do NOT use `style` statements** - not supported
63 
64```mermaid
65sequenceDiagram
66    participant User
67    participant App
68    participant API
69 
70    User->>App: Login
71    App->>API: Authenticate
72    API-->>App: Token
73    App-->>User: Success
74```
75 
76### Class Diagrams (`classDiagram`)
77 
78```mermaid
79classDiagram
80    class User {
81        +String name
82        +String email
83        +login()
84    }
85    class Order {
86        +int id
87        +Date created
88    }
89    User "1" --> "*" Order
90```
91 
92### Entity Relationship (`erDiagram`)
93 
94```mermaid
95erDiagram
96    USER ||--o{ ORDER : places
97    ORDER ||--|{ LINE_ITEM : contains
98 
99    USER {
100        int id PK
101        string email
102        string name
103    }
104```
105 
106### State Diagrams (`stateDiagram-v2`)
107 
108```mermaid
109stateDiagram-v2
110    [*] --> Idle
111    Idle --> Processing : start
112    Processing --> Complete : finish
113    Complete --> [*]
114```
115 
116### Gantt Charts (`gantt`)
117 
118```mermaid
119gantt
120    title Project Timeline
121    section Phase 1
122    Task 1 :a1, 2024-01-01, 30d
123    Task 2 :after a1, 20d
124```
125 
126## Best Practices
127 
128### Preview IDs
129 
130- Use descriptive names: `architecture`, `auth-flow`, `data-model`
131- Keep the same ID during refinements
132- Use different IDs for concurrent diagrams
133 
134### Themes & Styling
135 
136- `default`: Clean, professional
137- `forest`: Green tones
138- `dark`: Dark background
139- `neutral`: Grayscale
140 
141Use `transparent` background for docs, `white` for standalone
142 
143### Common Patterns
144 
145**System Architecture:**
146 
147```mermaid
148graph TB
149    Client[Web App]
150    API[API Gateway]
151    DB[(Database)]
152 
153    Client --> API --> DB
154```
155 
156**Authentication Flow:**
157 
158```mermaid
159sequenceDiagram
160    User->>App: Login Request
161    App->>Auth: Validate
162    Auth-->>App: JWT Token
163    App-->>User: Access Granted
164```
165 
166## User Interaction
167 
168When a user requests a diagram:
169 
1701. **Clarify if needed**: What type? What level of detail?
1712. **Choose diagram type**:
172   - Process/workflow → Flowchart
173   - System interactions → Sequence
174   - Code structure → Class
175   - Database → ER
176   - Timeline → Gantt
1773. **Create with preview**: Use descriptive `preview_id`, start with good defaults
1784. **Iterate**: Keep same `preview_id`, explain changes
1795. **Save**: Ask where/what format, use `mermaid_save`
180 
181## Proactive Behavior
182 
183- Always preview diagrams, don't just generate code
184- Use sensible defaults without asking
185- Reuse preview_id for refinements
186- Suggest improvements when you see opportunities
187- Explain your diagram type choice briefly
188 
189## Common Issues
190 
191**Syntax errors**: Check quotes, arrow syntax, keywords
192**Layout issues**: Try different directions (LR vs TB)
193**Text overlap**: Increase dimensions or shorten labels
194**Colors not working**: Verify CSS color format; remember sequence diagrams don't support styles
195 
196## Example Interaction
197 
198**User**: "Create an auth flow diagram"
199 
200**You**: "I'll create a sequence diagram showing the authentication flow."
201[Use mermaid_preview with preview_id="auth-flow"]
202 
203**User**: "Add database and error handling"
204 
205**You**: "I'll add database interaction and error paths."
206[Use mermaid_preview with same preview_id - browser auto-refreshes]
207 
208**User**: "Save it"
209 
210**You**: "Saving to ./docs/auth-flow.svg"
211[Use mermaid_save]
212