Skip to main content
command CX Codex

mermaid — Claude Code command: text-to-diagram renderer

The command renders Mermaid diagrams (flowcharts, sequence, state, class, ER, XY charts) as SVG, standalone HTML, or terminal ASCII.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/mermaid.md
Open on GitHub

What mermaid does

The command uses [email protected] to render six diagram types: flowchart, sequence, state (stateDiagram-v2), class, ER, and XY charts. Output targets include SVG for CoCo Platform React components, standalone HTML with ESM import from esm.sh, ASCII for terminal display, or SVG strings for backend use. Seven built-in themes ship with it: tokyo-night, catppuccin-mocha, github-dark, nord, dracula, plus two light variants.

The parser does not support journey, pie, gantt, or gitgraph — convert them to flowchart or XY chart instead. Node IDs must be alphanumeric; labels with spaces go in square brackets with quotes (A["Label"]). For CoCo Platform, the diagram renders automatically via <MermaidDiagram> component. For standalone HTML, the template requires a <script type="module"> with renderMermaidSVGAsync imported from the pinned ESM URL.

What it helps with

  • render a process flowchart or system architecture diagram
  • draw a sequence diagram showing service interactions
  • generate an ER diagram from a database schema
  • create a state machine diagram for a workflow
  • output an XY chart for reports or dashboards

Example prompts for the agent

  • Draw a flowchart of the user registration process with email verification
  • Build a sequence diagram showing the request flow between client, API, and database
  • Create an ER diagram for users, orders, and products tables

How to install mermaid

Manually: put the files in place

.claude/commands/mermaid.md

Call it with /mermaid. For all projects use ~/.claude/commands/

Questions about mermaid

How to install mermaid in Claude Code?

Place the file at .claude/commands/mermaid.md in the project root — Claude Code will pick it up automatically.

What does the mermaid command do?

It renders Mermaid diagrams (flowchart, sequence, state, class, ER, XY) via [email protected] and outputs SVG, HTML, or ASCII.

Which diagram types does mermaid support?

The command handles flowchart, stateDiagram-v2, sequence, class, ER, and xychart-beta. Types like journey, pie, gantt, and gitgraph are not parsed — replace them with flowchart or XY chart.

Source text

mermaid.md · MIT
---
description: "Use when the user asks for a diagram or chart: flowchart, sequence, state, class, ER, or XY chart, as SVG, HTML, or terminal ASCII. Builds beautiful-mermaid diagrams with themes, output templates, and parser-pitfall checks."
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
---

# /design-mermaid — Beautiful Mermaid Diagram Builder

You are a Mermaid diagram specialist. You use the `beautiful-mermaid` library (not standard Mermaid v10) for ALL diagram rendering.

**Package:** `[email protected]`, imported from `https://esm.sh/[email protected]` (the version pinned in every template below). Run `npm i [email protected]` to read the source locally when you need API details, parser capabilities, or edge-case syntax.

## Quick Reference

| Diagram Type | Syntax Prefix | Example |
|-------------|---------------|---------|
| Flowchart | `graph TD` / `flowchart LR` | `graph TD; A --> B --> C` |
| State | `stateDiagram-v2` | `stateDiagram-v2; [*] --> Idle` |
| Sequence | `sequenceDiagram` | `sequenceDiagram; Alice->>Bob: Hello` |
| Class | `classDiagram` | `classDiagram; Animal <\|-- Duck` |
| ER | `erDiagram` | `erDiagram; USER \|\|--o{ ORDER : places` |
| XY Chart | `xychart-beta` | `xychart-beta; bar [10, 20, 30]` |

**Directions:** `TD` (top-down), `LR` (left-right), `BT` (bottom-top), `RL` (right-left)

## How to Use

### Step 1: Understand the request

Ask clarifying questions if needed:
- What entities/concepts should be in the diagram?
- What type of diagram best represents the data? (flow, state machine, sequence, ER, class, chart)
- Is this for the CoCo Platform UI, a standalone HTML file, or terminal output?

### Step 2: Build the diagram

Write the mermaid source code. Follow these rules:

**Syntax rules (beautiful-mermaid parser):**
- Node IDs must be alphanumeric (no spaces, hyphens, or dots in IDs)
- Use `["Label with spaces"]` for labels: `A["My Node"] --> B["Other Node"]`
- Subgraphs: `subgraph Title; ... end`
- Edge labels: `A -->|"label"| B`
- Styling: `style A fill:#f00,color:#fff`
- Link styling: `linkStyle 0 stroke:#ff0000,stroke-width:2px`
- Line breaks in labels: `A["Line 1<br/>Line 2"]`

**XY Chart syntax:**
```
xychart-beta
    title "Chart Title"
    x-axis [Cat1, Cat2, Cat3]
    y-axis "Label" 0 --> 100
    bar [30, 50, 80]
    line [25, 45, 70]
```
- `horizontal` keyword after `xychart-beta` for horizontal orientation
- Multiple `bar` and `line` declarations for multi-series

### Step 3: Render

Choose output based on context:

#### A) CoCo Platform (React component)

If the diagram is for the CoCo Platform frontend, it renders automatically via the `<MermaidDiagram>` component. Just output the mermaid code in a fenced block:

````
```mermaid
graph TD
    A --> B
```
````

The `RichContent` component detects and renders it with:
- Theme: CSS variables from CoCo (auto dark/light)
- Lazy-loaded elkjs (only when diagram present)
- Copy source + fullscreen buttons
- DOMPurify sanitized SVG

#### B) Standalone HTML file

For standalone documents or reports, use the ESM import pattern:

```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline' https://esm.sh; connect-src 'self' https://esm.sh; style-src 'self' 'unsafe-inline'; img-src 'self' data:;">
<title>Diagram</title>
<style>
  body { font-family: Inter, system-ui, sans-serif; background: #1a1b26; color: #a9b1d6; max-width: 900px; margin: 40px auto; padding: 0 20px; }
  .diagram { background: #1a1b26; border-radius: 12px; padding: 16px; margin: 16px 0; }
  .diagram svg { max-width: 100%; height: auto; display: block; }
</style>
</head>
<body>
<div class="diagram" data-code="graph TD; A --> B"></div>

<script type="module">
import { renderMermaidSVGAsync } from 'https://esm.sh/[email protected]'

const theme = { bg: '#1a1b26', fg: '#a9b1d6', accent: '#7aa2f7', transparent: true }

for (const el of document.querySelectorAll('[data-code]')) {
  try {
    el.innerHTML = await renderMermaidSVGAsync(el.dataset.code, theme)
  } catch (e) {
    el.innerHTML = `<pre style="color:#ff453a">${e.message}</pre>`
  }
}
</script>
</body>
</html>
```

**Available themes (built-in):**
| Theme | bg | fg | accent |
|-------|-----|-----|--------|
| tokyo-night | #1a1b26 | #a9b1d6 | #7aa2f7 |
| catppuccin-mocha | #1e1e2e | #cdd6f4 | #cba6f7 |
| github-dark | #0d1117 | #e6edf3 | #4493f8 |
| nord | #2e3440 | #d8dee9 | #88c0d0 |
| dracula | #282a36 | #f8f8f2 | #bd93f9 |
| zinc-light | #ffffff | #27272a | (derived) |
| github-light | #ffffff | #1f2328 | #0969da |

#### C) Terminal / ASCII output

For CLI tools or terminal display:

```typescript
import { renderMermaidASCII } from 'beautiful-mermaid'
const ascii = renderMermaidASCII('graph LR; A --> B', { colorMode: 'truecolor' })
```

#### D) Node.js / Backend

```typescript
import { renderMermaidSVG } from 'beautiful-mermaid'
const svg = renderMermaidSVG('graph TD; A --> B', { bg: '#fff', fg: '#000' })
// svg is a string — write to file, embed in HTML, etc.
```

### Step 4: Validate

If the diagram fails to render:
1. **Check syntax** — read the parser source in `[email protected]` (`node_modules/beautiful-mermaid/src/parser.ts`) for exact parser rules
2. **Check diagram type** — only 6 types supported (flowchart, state, sequence, class, ER, xychart)
3. **Simplify** — strip to minimal reproducing case
4. **Fallback** — show raw mermaid source in a styled code block

**Common parser pitfalls:**
- `stateDiagram` (v1) is NOT supported — use `stateDiagram-v2`
- `journey` diagrams are NOT supported
- `pie` charts are NOT supported (use `xychart-beta` bar chart instead)
- `gantt` diagrams are NOT supported
- `gitgraph` is NOT supported
- Node IDs cannot start with numbers
- Semicolons work as line separators: `graph TD; A --> B; B --> C`

## Failsafe Process

If `beautiful-mermaid` cannot parse the diagram:

1. **Read the parser source**: install the pinned package (`npm i [email protected]`) and read `node_modules/beautiful-mermaid/src/parser.ts`
2. **Check tests for examples**: `node_modules/beautiful-mermaid/src/__tests__/`
3. **Try the async renderer**: `renderMermaidSVGAsync()` — same output, different execution path
4. **Degrade to code block**: Wrap in ``` ```mermaid ``` ``` with a note that it needs a standard Mermaid renderer
5. **Convert to supported type**: e.g., `journey` → flowchart, `pie` → xychart bar, `gantt` → flowchart with timeline

## Multi-Diagram Documents

For documents with multiple diagrams (like PLATFORM-ANALYSIS.md). This is a `<script>`
fragment, not a full document — ensure the `<head>` it's inserted into carries the same
CSP meta tag as the standalone template above (`script-src`/`connect-src` scoped to
`https://esm.sh`):

```html
<script type="module">
import { renderMermaidSVGAsync } from 'https://esm.sh/[email protected]'

const theme = { bg: '#1a1b26', fg: '#a9b1d6', accent: '#7aa2f7', transparent: true }
const els = document.querySelectorAll('[data-code]')

// Yield between diagrams to avoid blocking
for (const el of els) {
  await new Promise(r => requestAnimationFrame(r))
  try {
    el.innerHTML = await renderMermaidSVGAsync(el.dataset.code, theme)
  } catch (e) {
    el.innerHTML = `<pre style="color:#ff453a">${e.message}</pre>`
  }
}
</script>
```

ARGUMENTS: $ARGUMENTS

© coco-research · MIT · coco-research/coco

Similar slash commands

All slash commands for Design →

From the same set82

The whole set →
gsd-research-synthesizer gsd-research-synthesizer combines four research agents’ findings into SUMMARY.md and derives recommendations for a project roadmap. It runs as part of /gsd-new-project. CX Codex ★ 328repo stars refactoring-specialist refactoring-specialist cleans up code smells and reduces complexity step by step while maintaining existing behavior through constant test runs. CX Codex ★ 328repo stars code-reviewer code-reviewer — a subagent for code, architecture and security review. Checks SOLID, DDD, vulnerabilities, API design and performance before merging PRs. CX Codex ★ 328repo stars coco-ads Turns your project code into a short launch video (15–25 seconds). Triggers on /coco-ads or phrases like "make a launch video". CX Codex +1 ★ 328repo stars maker-mdap maker-mdap — a Claude Code skill for designing long LLM workflows with fine-grained decomposition, voting, and rejection of suspicious outputs. CX Codex +1 ★ 328repo stars arch Command to build and validate .arch/index.json, which maps each architecture component to the files implementing it. Detects when files and component descriptions have drifted apart. CX Codex +1 ★ 328repo stars develop develop runs a multi-agent build and bugfix pipeline that shards file edits across specialized agents and validates changes with regression evidence. CX Codex +1 ★ 328repo stars data-specialist data-specialist — a subagent for exploratory data analysis, machine learning workflows, and SQL query tuning across PostgreSQL, MySQL, SQL Server, and Oracle. CX Codex ★ 328repo stars

Project sponsors

Companies that keep this analytics open