Diagram Generator
Turn any input into a clean diagram. Supports the full Mermaid diagram set so one skill handles flowcharts, sequence diagrams, state machines, ER diagrams, journeys, mindmaps, timelines, gantt charts, sankey, quadrants, class diagrams, and git graphs.
Inputs
- Ticket / PRD / spec — read it and pick the right diagram type.
- File path — read the file and diagram from contents.
- Verbal description — diagram directly from the prompt.
- Existing diagram — refactor / restyle / fix.
Workflow
Step 1 — Pick the diagram type
If the input is unambiguous, pick directly. Otherwise ask which fits best:
| User intent | Mermaid type |
|---|
| Process flow, decision tree, "if X then Y" | flowchart |
| API calls, message passing, who-talks-to-whom over time | sequenceDiagram |
| Object lifecycle, finite-state machine | stateDiagram-v2 |
| Database schema, entities + relationships | erDiagram |
| End-to-end customer/user experience with sentiment | journey |
| Hierarchical brainstorm, taxonomy, idea tree | mindmap |
| Dated events, milestones | timeline |
| Project schedule with durations + dependencies | gantt |
| Flow of quantity between sources/targets | sankey-beta |
| 2x2 categorization (importance/urgency, effort/impact) | quadrantChart |
| OOP class hierarchy with methods | classDiagram |
| Git branching strategy | gitGraph |
Step 2 — Extract the diagram content
From the input, pull out the right primitives for the chosen type:
- Flowchart: decision points, actions, states, edge cases, scenarios.
- Sequence: actors, messages, ordering, async vs sync.
- State: states, transitions, triggers, terminal states.
- ER: entities, attributes, relationships, cardinality.
- Journey: stages, tasks per stage, sentiment scores.
- Mindmap: root concept + branches.
- Timeline: sections + events per section.
- Gantt: sections + tasks with dates/durations + dependencies.
- Sankey: source → target → value rows.
- Quadrant: axis labels + items with (x, y) scores.
- Class: classes + members + inheritance/composition.
- GitGraph: branches, commits, merges.
If multiple distinct scenarios exist (e.g., happy path + error path), produce SEPARATE diagrams rather than one mega-diagram.
Step 3 — Emit Mermaid syntax
Always wrap output in:
```mermaid
{type-specific code}
```
Follow the type-specific rules below.
Step 4 — Offer a preview file (optional)
After printing the Mermaid block, ask: "Want me to generate a single-file HTML preview that renders this locally?"
If yes, write diagram.html to the current directory using the template under "HTML preview template" below.
Type-specific rules
Flowchart
- Line breaks in labels: ALWAYS
<br>, NEVER \n.
- Node shapes:
([text]) — start / end (stadium)[text] — action / process{text} — decision[[text]] — subroutine[(text)] — database((text)) — circle (event)
- Direction:
flowchart TD for processes, flowchart LR for timelines/pipelines.
- Edge labels:
-- text --> for conditional paths.
- Colors (apply via
style lines at the end):
fill:#4CAF50,color:#fff — success / start (green)fill:#EF5350,color:#fff — error / blocked (red)fill:#FF9800,color:#fff — warning / modified (orange)fill:#2196F3,color:#fff — informational (blue)
- Subgraphs: group related items with
subgraph Name ... end.
- No special characters (quotes, colons, pipes) inside node labels.
- Node text: max 4 lines.
Sequence diagram
- Use
participant X as Display Name to set readable labels.
- Use
->> for sync, -->> for async, --x for failed.
- Use
Note over X,Y: text for callouts.
- Use
loop, alt / else, par, opt for control flow.
- Use
activate X / deactivate X to show lifelines.
State diagram (v2)
- Use
[*] --> StateName for start, StateName --> [*] for end.
- Use
state ChoiceName <<choice>> for branching.
- Use composite states for nesting:
state Group { ... }.
ER diagram
- Cardinality glyphs:
||--o{ (one-to-many), }o--o{ (many-to-many), ||--|| (one-to-one).
- Use lowercase plural entity names.
- Attribute lines:
{type} attributeName "comment".
Journey
- Three columns per task:
Task name: <score 1-5>: Actor1, Actor2.
- Group tasks under
section Name.
Mindmap
- Indentation defines hierarchy.
- Node shapes:
((text)), [text], (text), {{text}}.
Timeline
section Name then events as : YYYY : event text.
Gantt
- Always start with
dateFormat YYYY-MM-DD.
- Tasks:
Name :status, id, start, duration or Name :status, id, after otherId, duration.
- Status keywords:
done, active, crit.
Sankey-beta
- One source-target-value row per line:
Source,Target,42.
- No header. Comma-separated. Values numeric.
Quadrant chart
- Required:
title, x-axis Low --> High, y-axis Low --> High, four quadrant labels.
- Items:
Item Name: [x, y] where x and y are 0-1.
Class diagram
Class : +method() for public, - private, # protected.- Relationships:
<|-- inherits, *-- composition, o-- aggregation, --> association.
GitGraph
commit, branch name, checkout name, merge name.- Order matters; reads top-to-bottom.
Output structure
## {Diagram Title}
**Summary:** {one-line description of what the diagram shows}
```mermaid
{code}
Key callouts:
- {anything non-obvious about the diagram}
If multiple diagrams (e.g., happy + error paths), use a header per diagram and render each separately.
## HTML preview template
When the user asks for a local preview, write this single file (no build, no npm; mermaid loaded from CDN):
```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Diagram preview</title>
<style>
body{margin:0;padding:48px;font:16px/1.5 system-ui,sans-serif;background:#F5F1EA;color:#15140F}
.wrap{max-width:1100px;margin:0 auto}
h1{font-weight:500;font-size:28px;margin:0 0 24px}
.mermaid{background:#fff;border:1px solid #D8D2C5;border-radius:10px;padding:24px;overflow:auto}
</style>
</head>
<body>
<div class="wrap">
<h1>{TITLE}</h1>
<pre class="mermaid">
{MERMAID_CODE}
</pre>
</div>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true, theme: 'base', themeVariables: {
primaryColor: '#F5F1EA', primaryTextColor: '#15140F', primaryBorderColor: '#15140F',
lineColor: '#15140F', fontFamily: 'system-ui, sans-serif'
}});
</script>
</body>
</html>
Replace {TITLE} and {MERMAID_CODE} with the actual content. Preview opens directly in the browser (file:// works; no server needed).
Anti-Patterns
- Don't pick the wrong diagram type to "force fit" the input — ask if it's ambiguous.
- Don't cram multiple scenarios into one diagram; split them.
- Don't use
\n for line breaks in flowchart node labels — always <br>.
- Don't put quotes, colons, or pipes inside node labels (they break Mermaid).
- Don't skip the
style lines on flowcharts — color coding makes diagrams scannable.
- Don't reach for D3, ReactFlow, or custom HTML; Mermaid is the right tool for almost every case. (If the user wants the magazine-grade animated process flow, point them to the
interactive-flowchart-builder skill instead.)
- Don't auto-generate the HTML preview unless the user asks — most users just want the Mermaid block.
Quality Checklist