Diagram Types
| Type | Keyword | Best For |
|---|---|---|
| Flowchart | flowchart TB/LR | Decision flows, processes |
| Sequence | sequenceDiagram | API interactions, protocols |
| Class | classDiagram | OOP structure, interfaces |
| State | stateDiagram-v2 | Lifecycle, state machines |
| ER | erDiagram | Database schemas |
| Gantt | gantt | Project timelines |
| Pie | pie | Distribution, composition |
| Mindmap | mindmap | Hierarchical mind maps |
| Timeline | timeline | Chronological events |
| Git Graph | gitGraph | Branch visualization |
| Kanban | kanban | Task boards |
| Quadrant | quadrantChart | 2x2 matrix |
Processing Limits
- File chunk limit: 1000 files per diagram (HARD LIMIT)
- Visual limit: ~200 nodes max per diagram
- Large codebases: split by subsystem/layer; generate overview first then details
Standalone HTML Output Mode
Trigger phrases: "export as HTML", "standalone diagram", "interactive diagram"
Generate a self-contained HTML file with embedded Mermaid.js CDN, dark/light toggle button, and responsive CSS (max-width: 1200px):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>TITLE</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({ startOnLoad: true, theme: 'dark' });
</script>
<style>
body {
font-family: system-ui;
max-width: 1200px;
margin: 2rem auto;
background: #1e1e2e;
color: #cdd6f4;
}
</style>
</head>
<body>
<h1>TITLE</h1>
<button
onclick="let d=!d;mermaid.initialize({startOnLoad:false,theme:d?'dark':'default'});document.querySelector('.mermaid').removeAttribute('data-processed');mermaid.run()"
>
Toggle Theme
</button>
<div class="mermaid">MERMAID_CONTENT</div>
</body>
</html>Default: dark mode (background: #1e1e2e, color: #cdd6f4) Output: .claude/context/artifacts/diagrams/{subject}-{YYYY-MM-DD}.html
Output Location
- Mermaid files:
.claude/context/artifacts/diagrams/{subject}-{type}-{YYYY-MM-DD}.mmd - HTML files:
.claude/context/artifacts/diagrams/{subject}-{YYYY-MM-DD}.html
Iron Laws
- Mermaid syntax only — no ASCII art or PlantUML.
- Never exceed 200 nodes per diagram.
- Never write diagrams outside
.claude/context/artifacts/diagrams/. - Label all non-obvious connections.
- Enforce 1000-file hard limit — chunk large codebases.
Mermaid Plugin Generation Pattern
Generate diagrams from code analysis using the Claude Code plugin pattern (ref: agentic-coding-school/mermaid-diagram-plugin):
Step 1: Analyze Codebase Structure
# Identify components to diagram
pnpm search:code "class|interface|module|service|component" | head -50Step 2: Generate Mermaid Source
Use Claude to transform code analysis into diagram syntax. Always request a specific diagram type and scope:
"Generate a Mermaid flowchart TB of the authentication flow in src/auth/"
"Create an ER diagram for the database tables in prisma/schema.prisma"
"Make a sequence diagram for the API request lifecycle in src/api/"Step 3: Render Interactive HTML
For standalone shareable diagrams, use the full HTML template:
// Plugin invocation pattern (from mermaid-diagram-plugin)
const mermaidContent = `
flowchart TB
A[User Request] --> B{Auth Check}
B -- Valid --> C[Route Handler]
B -- Invalid --> D[401 Response]
C --> E[Database Query]
E --> F[Response]
`;
// Render to interactive HTML
const html = `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>${title}</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({ startOnLoad: true, theme: 'dark' });</script>
<style>
body { font-family: system-ui; max-width: 1200px; margin: 2rem auto;
background: #1e1e2e; color: #cdd6f4; }
.controls { margin-bottom: 1rem; }
button { padding: 0.5rem 1rem; margin-right: 0.5rem; cursor: pointer; }
</style>
</head>
<body>
<h1>${title}</h1>
<div class="controls">
<button onclick="toggleTheme()">Toggle Theme</button>
<button onclick="downloadSVG()">Download SVG</button>
</div>
<div class="mermaid">${mermaidContent}</div>
<script>
let dark = true;
function toggleTheme() {
dark = !dark;
mermaid.initialize({ startOnLoad: false, theme: dark ? 'dark' : 'default' });
document.querySelector('.mermaid').removeAttribute('data-processed');
mermaid.run();
}
function downloadSVG() {
const svg = document.querySelector('.mermaid svg');
if (!svg) return;
const blob = new Blob([svg.outerHTML], { type: 'image/svg+xml' });
const a = document.createElement('a'); a.href = URL.createObjectURL(blob);
a.download = '${title.replace(/\s+/g, '-')}.svg'; a.click();
}
</script>
</body>
</html>`;Step 4: Save Output
# Save interactive HTML to standard location
# .claude/context/artifacts/diagrams/{subject}-{YYYY-MM-DD}.htmlPlugin Invocation from Agent
When an agent needs a diagram as part of a workflow:
// Invoke diagram-generator skill, then request specific type
Skill({ skill: 'diagram-generator' });
// Then describe what to diagram with context
// "Create a class diagram for src/lib/routing/ — show all classes and their relationships"When to invoke
Skill({skill: 'diagram-generator'}) for architecture diagrams, HTML exports, mindmaps, timelines, git visualizations, kanban boards, and quadrant charts.