mermaid-diagram

What this skill does

# 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

```bash
# 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:

```markdown
# 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`).**

```bash
# 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:

```markdown
## 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 = score ≤ 7)
Check EACH block/node:
- [ ] Block 1 "[Name]": Has correct label? Content correct?
- [ ] Block 2 "[Name]": Has correct label? Content correct?
- [ ] ... (check ALL blocks)

#### D. Completeness
- [ ] All components from user requirements are present
- [ ] All connections/arrows are correct
- [ ] Node labels are meaningful and match requirements

#### E. Visual Quality
- [ ] Layout is clean and readable
- [ ] Color scheme is professional (not rainbow)
- [ ] Text is readable at normal zoom
- [ ] Proper spacing (not cramped, not sparse)
- [ ] Data flow is traceable in 5 seconds

### ═══════════════════════════════════════════════════════════════

### Issues Found (BE SPECIFIC)
1. [Issue 1]: [EXACTLY what is wrong] → [How to fix]
2. [Issue 2]: [EXACTLY what is wrong] → [How to fix]

### Score: X/10

### Score Breakdown Guide:
- **10**: Perfect. No issues. Publication-ready.
- **9**: Excellent. Minor issues that don't affect understanding.
- **8**: Good but has noticeable issues (layout, styling).
- **7**: Usable but has clear problems (wrong arrows, missing labels).
- **6**: Has arrow direction errors or missing major components.
- **1-5**: Major issues. Unacceptable.

### Verdict
[ ] ACCEPT (score ≥ 9 AND all critical checks pass)
[ ] FIX (score < 9 OR any critical check fails — list EXACT fixes needed)
```

**If FIX: apply corrections to both `.mmd` and `.md` files, re-render, and re-verify. Loop until ACCEPT or MAX_ITERATIONS reached.**

### Step 6: Final Output Summary

When accepted, present to user:

```
✅ Mermaid diagram generated successfully!

Files:
  figures/<diagram-name>.mmd  — Raw Mermaid source (use with mmdc, editors, CI)
  figures/<diagram-name>.md   — Markdown preview (renders on GitHub, VS Code, etc.)
  figures/<diagram-name>.png  — Rendered image (if mmdc was available)

To re-render manually:
  mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png
```

## Architecture Diagram Best Practices

When generating `architecture-beta` diagrams, apply these layout techniques for complex diagrams:

### Use Junctions for Layout Control

Think of the diagram as an invisible grid. Use `junction` nodes as virtual anchor points on that grid to precisely control where each component is placed. This is especially useful when a direct edge between two serv