/mermaid-diagram

name: mermaid-diagram
description: "Generate Mermaid diagrams from user requirements. Supports flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, and 18 more diagram types."
argument-hint: "[diagram description or requirements]"
allowed-tools: Bash(*), Read, Write, Edit, Glob, Grep

Mermaid Diagram Generator

Generate high-quality Mermaid diagram code based on user requirements, with file output and verification.

Constants

• **OUTPUT_DIR = `figures/`** — Output directory for all generated files
• **MAX_ITERATIONS = 3** — Maximum refinement rounds for syntax errors

Workflow: MUST EXECUTE ALL STEPS

Step 0: Pre-flight Check

# Create output directory
mkdir -p figures

Step 1: Understand Requirements & Select Diagram Type

Parse the input: **$ARGUMENTS**

1. Analyze user description to determine the most suitable diagram type 2. Read the corresponding syntax reference documentation (see Diagram Type Reference below) 3. **If the diagram involves mathematical notation** (formulas, equations, Greek letters, subscripts, superscripts, fractions, matrices, etc.), apply the math syntax rules from the **Math Formulas in Diagrams** section below 4. Identify all components, connections, and data flow 5. Plan the diagram structure

Step 2: Read Documentation

Select the appropriate diagram type based on the use case. Use your built-in knowledge of Mermaid syntax, or fetch up-to-date docs via the context7 MCP server if needed.

| Type | Use Cases | | ---- | --------- | | Flowchart | Processes, decisions, steps | | Sequence Diagram | Interactions, messaging, API calls | | Class Diagram | Class structure, inheritance, associations | | State Diagram | State machines, state transitions | | ER Diagram | Database design, entity relationships | | Gantt Chart | Project planning, timelines | | Pie Chart | Proportions, distributions | | Mindmap | Hierarchical structures, knowledge graphs | | Timeline | Historical events, milestones | | Git Graph | Branches, merges, versions | | Quadrant Chart | Four-quadrant analysis | | Requirement Diagram | Requirements traceability | | C4 Diagram | System architecture (C4 model) | | Sankey Diagram | Flow, conversions | | XY Chart | Line charts, bar charts | | Block Diagram | System components, modules | | Packet Diagram | Network protocols, data structures | | Kanban | Task management, workflows | | Architecture Diagram | System architecture | | Radar Chart | Multi-dimensional comparison | | Treemap | Hierarchical data visualization | | User Journey | User experience flows | | ZenUML | Sequence diagrams (code style) |

Configuration & Themes

• **Theming** - Custom colors and styles
• **Directives** - Diagram-level configuration
• **Layouts** - Layout direction and spacing
• **Configuration** - Global settings
• **Math** - LaTeX math support (see Math Formulas in Diagrams section below)

Step 3: Generate Mermaid Code & Save Files

Generate the Mermaid code following the reference specification, then save TWO files:

File 1: `figures/<diagram-name>.mmd` — Raw Mermaid source

The `.mmd` file contains ONLY the raw Mermaid code (no markdown fences). Example:

flowchart TD
    A[Start] --> B{Condition}
    B -->|Yes| C[Execute]
    B -->|No| D[End]
    C --> D

File 2: `figures/<diagram-name>.md` — Markdown with embedded Mermaid

The `.md` file wraps the same code in a mermaid code block for preview rendering, plus a title and description. Example:

# Diagram Title

Brief description of what this diagram shows.

​```mermaid
flowchart TD
    A[Start] --> B{Condition}
    B -->|Yes| C[Execute]
    B -->|No| D[End]
    C --> D
​```

**Naming convention**: Use a descriptive kebab-case name derived from the user's request (e.g., `auth-flow`, `system-architecture`, `database-er`).

Step 4: Verify Mermaid Syntax (MANDATORY)

**Claude MUST verify the generated Mermaid code by running the Mermaid CLI (`mmdc`).**

# Check if mermaid-cli is available
if command -v mmdc &> /dev/null; then
    # Render to PNG to verify syntax is correct
    mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparent
    echo "✅ Syntax valid — PNG rendered to figures/<diagram-name>.png"
else
    # Try npx as fallback
    npx -y @mermaid-js/mermaid-cli@latest -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparent
    echo "✅ Syntax valid — PNG rendered to figures/<diagram-name>.png"
fi

**If the verification fails:** 1. Read the error message carefully 2. Fix the syntax issue in both `.mmd` and `.md` files 3. Re-run verification 4. Repeat up to MAX_ITERATIONS (3) times

Step 5: Claude STRICT Visual Review & Scoring (MANDATORY)

After successful rendering, Claude MUST read the generated PNG and perform a STRICT review:

## Claude's STRICT Review of <diagram-name>

### What I See
[Describe the rendered diagram in DETAIL - every block, every arrow, every label]

### Files Generated
- `figures/<diagram-name>.mmd` — Raw Mermaid source
- `figures/<diagram-name>.md` — Markdown with embedded diagram
- `figures/<diagram-name>.png` — Rendered PNG (if mmdc available)

### ═══════════════════════════════════════════════════════════════
### STRICT VERIFICATION CHECKLIST (ALL must pass for score ≥ 9)
### ═══════════════════════════════════════════════════════════════

#### A. File Correctness
- [ ] `.mmd` file contains valid Mermaid syntax (no markdown fences)
- [ ] `.md` file has the mermaid code wrapped in ```mermaid``` fences
- [ ] `.mmd` and `.md` contain IDENTICAL Mermaid code
- [ ] Diagram renders without errors (via mmdc)

#### B. Arrow Correctness Verification (CRITICAL - any failure = score ≤ 6)
Check EACH arrow:
- [ ] Arrow 1: [Source] → [Target] — Does it point to the CORRECT target?
- [ ] Arrow 2: [Source] → [Target] — Does it point to the CORRECT target?
- [ ] ... (check ALL arrows)

#### C. Block Content Verification (any failure = sco