mermaid-diagram

Mermaid Diagram Creator

Generate .mmd files (or fenced ```mermaid blocks in .md files when embedding in docs).

Reference Files (load as needed)

File	Load when...
references/types/<type>.md	After choosing diagram type (Step 6). Full syntax, examples, layout tips, line-break rules, and pitfalls for that type.
references/syntax-pitfalls.md	Render fails or you need to debug syntax. Covers quoting rules, <br> compatibility matrix (Section 9), reserved words, and common errors.
references/mermaid-theme.md	The single theming file. Dark/light mode color guidelines, classDef semantic style recipes (trigger, success, error, ai, decision), and per-diagram-type support notes.
references/render_mermaid.sh	The render script. Invoked via bash, not read. See Render & Validate below.
references/examples/	Validated .mmd examples (architecture.mmd, sequence-api.mmd). Review for inspiration or to verify your syntax against known-good patterns.

Customization

To customize brand styles, edit references/mermaid-theme.md — this is the single source of truth for all theming (semantic node styles and dark/light mode color guidelines).

---

Core Philosophy

Diagrams should ARGUE, not DISPLAY.

A diagram isn't formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning.

The Isomorphism Test: If you removed all text, would the structure alone communicate the concept? If not, redesign.

The Education Test: Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches—it shows actual formats, real event names, concrete examples.

Bad (Displaying)	Good (Arguing)
5 equal boxes with labels	Each concept has a shape that mirrors its behavior
Card grid layout	Visual structure matches conceptual structure
Icons decorating text	Shapes that ARE the meaning
Same container for everything	Distinct visual vocabulary per concept

---

Design Process

Step 0: Assess Depth and Audience

Before anything else, determine what level of detail this diagram needs:

• Simple/Conceptual: Abstract shapes, labels, relationships. Use when explaining a mental model, the audience already knows the details, or the concept IS the abstraction.
• Comprehensive/Technical: Concrete examples, code snippets, real data. Use when diagramming a real system, creating educational content, or showing how technologies integrate.

Simple Diagram	Comprehensive Diagram
Generic labels: "Input" → "Process" → "Output"	Shows what the input/output actually looks like
Named boxes: "API", "Database", "Client"	Named boxes + real requests/responses
"Events" or "Messages" label	Real event/message names from the spec
~30 seconds to explain	~2-3 minutes of teaching content
Viewer learns the structure	Viewer learns the structure AND the details

Match density to audience:

Audience	Node Count	Detail Level
Executive / overview	5–7	High-level boxes, no attributes
Technical documentation	10–15	Subgraphs, edge labels, evidence artifacts
Deep reference	15–20, then split	Full attributes, Notes, companion files

When the same system needs multiple audiences, create separate diagrams — not one diagram that tries to serve everyone.

Step 1: Research (Comprehensive diagrams only)

Before drawing anything technical, research the actual specifications.

If you're diagramming a protocol, API, or framework:

1. Look up the actual JSON/data formats
2. Find the real event names, method names, or API endpoints
3. Understand how the pieces actually connect
4. Use real terminology, not generic placeholders

Bad: "Protocol" → "Frontend" Good: "AG-UI streams events (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()"

Step 2: Understand Deeply

Read the content. For each concept, ask:

• What does this concept DO? (not what IS it)
• What relationships exist between concepts?
• What's the core transformation or flow?
• What would someone need to SEE to understand this? (not just read about)

Step 3: Map Concepts to Patterns

For each concept, find the visual pattern that mirrors its behavior:

If the concept...	Use this pattern
Spawns multiple outputs	Fan-out (single node, multiple outgoing edges)
Combines inputs into one	Convergence (multiple nodes into one target)
Has hierarchy/nesting	Tree (mindmap or subgraph nesting)
Is a sequence of steps	Timeline (timeline diagram or sequence diagram)
Loops or improves continuously	Spiral/Cycle (state self-transitions or back-edges)
Transforms input to output	Assembly line (flowchart pipeline)
Compares two things	Side-by-side (parallel subgraphs)
Separates into phases	Gap/Break (subgraph boundaries)

Step 4: Ensure Variety

For multi-concept diagrams: each major concept must use a different visual pattern. No uniform cards or grids.

Step 5: Sketch the Flow

Before writing syntax, mentally trace how the eye moves through the diagram. There should be a clear visual story.

Step 6: Generate Mermaid Syntax

1. Choose diagram type using the Decision Matrix below, then load references/types/<chosen-type>.md for full syntax.
2. Write the syntax — start with a %% comment block naming the diagram type and describing each section.
3. Use meaningful node IDs (not A, B, C — use authService, dbWrite, userInput).
4. Add classDef for semantic styling (trigger, success, error, ai, decision) — pull from references/mermaid-theme.md (Section 2). Follow the color selection guidelines in Section 1 to ensure dark/light mode compatibility.
5. Output format: Create a .mmd file by default. Use a fenced ```mermaid block when the user says "embed", "add to docs", "in README", or the target is a .md file.

Evidence Artifacts (Comprehensive diagrams)

Include concrete examples that prove accuracy and help viewers learn:

• Notes (sequence diagrams) for data payloads and message formats.
• Multi-line node labels using <br> for concise inline evidence.
• Subgraph titles to label regions.
• Companion .md files for large payloads or code snippets that won't fit in node text.

The key principle: show what things actually look like, not just what they're called.

Multi-Zoom (Comprehensive diagrams)

Aim for three zoom levels simultaneously:

1. Summary Flow — simplified overview of the full pipeline (Input → Processing → Output)
2. Section Boundaries — labeled subgraphs grouping related components (by responsibility, phase, or team)
3. Detail Inside Sections — evidence artifacts and concrete examples within each section

Splitting Large Diagrams

• Keep nodes to ~20 max before splitting into multiple diagrams.
• For complex systems: one .mmd per layer (Context → Container → Component).
• Break dense subgraphs into separate files with cross-references in prose.

Step 7: Render & Validate

Run the render script and validate the output. See the Render & Validate section below.

---

Diagram Type Decision Matrix

Quick lookup: match the visual pattern you need to the best diagram type, then open its reference file.

Visual Pattern	Best Diagram Type	Reference
Fan-out (one-to-many)	Flowchart	references/types/flowchart.md
Convergence (many-to-one)	Flowchart	references/types/flowchart.md
Sequence of steps / interactions	Sequence Diagram	references/types/sequence.md
Hierarchy / tree	Mindmap	references/types/mindmap.md
State machine / lifecycle	State Diagram	references/types/state.md
Object structure / relationships	Class Diagram	references/types/class.md
System architecture / context	C4 Diagram	references/types/c4.md
Timeline / ordered events	Timeline Diagram	references/types/timeline.md
Spiral/Cycle (loop)	State Diagram or Flowchart	references/types/state.md references/types/flowchart.md
Side-by-side comparison	Flowchart (parallel subgraphs)	references/types/flowchart.md
Data schema / entity relationships	ER Diagram	references/types/er-diagram.md
Flow volumes / resource allocation	Sankey Diagram	references/types/sankey.md

Excluded Diagram Types

Do not use these types — they lack structural argument capability or are too narrowly specialized:

Type	Reason Excluded
Pie Chart	Simple percentages; lacks structural argument capability
Gantt	Specifically for project scheduling, not conceptual mapping
Git Graph	Limited to git branch visualization
XY Chart	Quantitative data charting rather than structural diagramming
User Journey	Overly specific; typically better represented as a Sequence Diagram

---

Render & Validate (MANDATORY)

How to render:

bash .claude/skills/mermaid-diagram-skill/references/render_mermaid.sh <path.mmd> [output.png]

First run downloads mmdc via npx — may take ~30s.

The loop:

1. Write Mermaid syntax.
2. Run render script. 3a. If mmdc fails with a syntax error: read the error message, fix the syntax. Consult references/syntax-pitfalls.md for the most common failures (usually: unquoted special chars, wrong keyword, missing end). 3b. If mmdc succeeds: view the PNG, assess the layout.
3. If layout is poor: restructure — reorder node/edge declarations to change placement, switch rankDir (TD ↔ LR), add or remove subgraphs.
4. Re-render → repeat until the layout communicates the concept cleanly.

Label quoting rule: Always use ["label text"] instead of [label text] whenever the label contains parentheses, commas, @, /, <, >, or :. When in doubt, quote it — ["My label"] is always safer than [My label]. This single rule prevents ~50% of render failures. See references/syntax-pitfalls.md for the full list.

flowchart not graph: Always use flowchart TD (modern), never graph TD (legacy). graph lacks subgraph direction support and other modern features.

end is reserved: A node whose entire label is end will be parsed as a block terminator. Always quote it: B["end"].

You cannot pixel-position elements. All layout improvements come from declaration order, rankDir, subgraphs, and hidden lines — not coordinate adjustments.

Line crossing reduction — the primary visual quality challenge in auto-generated diagrams:

• Declaration order matters: The layout engine assigns ranks based on source order. Declare nodes in reading order (top→bottom or left→right). Earlier declarations get higher or leftmost ranks.
• Minimize back-edges: Every edge flowing "backwards" to an earlier node forces a crossing. For cycles, use State diagrams or isolate the back-edge in a subgraph.
• Group related nodes in source: Keep nodes in the same logical group adjacent in code. Scattered declarations → scattered placement → crossings.
• Subgraphs as layout hints: Wrapping related nodes in a subgraph constrains placement, preventing global crossings. Each subgraph can define its own direction (e.g., direction LR) to resolve density issues.
• Reduce fan-out: A single node with 5+ outgoing edges creates spider-web layouts. Insert a dispatcher/group node to flatten.
• Switch orientation: When crossings persist, try the orthogonal rankDir (TD ↔ LR). This alone often eliminates most crossings.
• Hidden lines: Consider whether invisible edges would help constrain node placement.

When to stop: syntax valid, layout communicates the concept, line crossings minimized, no overlapping labels, eye flows correctly through the diagram.

---

Quality Checklist

Concept & Depth (check first for technical diagrams):

1. Research done: looked up actual specs, formats, event names?
2. Evidence artifacts: Notes, multi-line node labels, companion .md for large payloads?
3. Multi-zoom: summary flow + section subgraphs + detail labels?
4. Concrete over abstract: real API names, real event names, not generic "Process"?
5. Educational value: could someone learn from this diagram?

Diagram Design: 6. Isomorphism Test: does visual structure mirror the concept's behavior? 7. Argument: does the diagram SHOW something text alone couldn't? 8. Variety: does each major concept use a different visual pattern or node shape? 9. Diagram type chosen intentionally (matches the concept's pattern from decision matrix)? 10. Node IDs are readable, not single letters?

Mermaid-Specific: 11. classDef used for semantic styling (trigger, success, error, ai, decision)? 12. Every classDef sets fill, stroke, AND color? (never omit color — see references/mermaid-theme.md Section 1 for dark/light mode guidelines) 13. Output format correct (.mmd vs fenced block)? 14. No excluded diagram types used? (Excluded: Pie Chart, Gantt, Git Graph, XY Chart, User Journey — see Decision Matrix above) 15. Node/edge declaration order follows reading direction (minimize line crossings)? 16. No single node has 5+ edges without a dispatcher split? 17. Back-edges isolated (cycles handled in State diagram or contained subgraph)?

Render Validation (mandatory): 18. Syntax validated: mmdc runs without error? 19. PNG viewed: layout visually inspected? 20. No overlapping labels or crossed text? 21. Eye flows naturally through the diagram? 22. Line crossings minimized (tried reordering + rankDir if needed)?

Cleanup Once a user is happy with the output, remove any temporary output like pngs or mmd files.