Mermaid Diagram Creator

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

Reference Files (load as needed)

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.

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.

Match density to audience:

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:

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.

Excluded Diagram Types

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

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.