name: aha-mermaid-diagram model: fast version: 1.1.0 description: > Create professional software diagrams using Mermaid syntax. Expert in all diagram types: Class, Sequence, Flowchart, ERD, C4 Architecture, State, Git Graphs, Gantt Charts. Includes HTML rendering, theming, styling, and interactive features. Triggers: diagram, visualize, model, architecture, flow, domain model, ERD, sequence. tags: [diagrams, mermaid, visualization, architecture, documentation, modeling, class-diagram, flowchart, sequence-diagram]

Aha Mermaid Diagram Expert#

Professional Mermaid.js diagrams for software architecture, domain modeling, and system visualization.

Installation#

CDN (HTML)#

html

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>
<pre class="mermaid">
  flowchart LR
    A --> B
</pre>

CLI Export#

bash

npm install -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.png -w 1920 -H 1080

Core Syntax#

All Mermaid diagrams:

text

diagramType
  definition content

Key principles:

• First line declares type: classDiagram, sequenceDiagram, flowchart, erDiagram, C4Context, stateDiagram, gantt
• Use %% for comments
• Line breaks improve readability
• Unknown words break diagrams; invalid parameters fail silently
• Avoid {} in comments

Diagram Type Selection#

TypeUse ForBest PracticeClass DiagramDomain modeling, OOP design, entity relationshipsShow attributes + methodsSequence DiagramAPI flows, auth flows, component interactionsUse activations, autonumberFlowchartProcesses, algorithms, decision trees, user journeysKeep <15 nodes per diagramERDDatabase schemas, table relationshipsUPPERCASE entity namesC4 DiagramsSystem context, containers, components, architecture4 levels: Context→Container→Component→CodeState DiagramState machines, lifecycle statesUse choice nodes for transitionsGit GraphsBranching strategiesShow merges clearlyGantt ChartsProject timelines, schedulingGroup by category

Class Diagram (Domain Model)#

Rendering diagram...

Visibility modifiers: + public, - private, # protected, ~ package

Relationships:

• -- Association (loose relationship)
• *-- Composition (strong ownership, child dies with parent)
• o-- Aggregation (weak ownership, child can exist alone)
• <|-- Inheritance ("is-a")
• <.. Dependency (parameter/local variable)
• <|.. Implementation (interface)

Sequence Diagram (API Flow)#

Rendering diagram...

Message types: ->> solid request, -->> dotted response, -) async

Structures: alt/else/end, opt, par/and/end, loop, break

Tips: Use activations ( +/ -), autonumber, descriptive notes

Flowchart (Process/Decision)#

Rendering diagram...

Directions: TD/TB (top-down), BT (bottom-up), LR (left-right), RL (right-left)

Node shapes:

• [Text] Rectangle
• ([Text]) Stadium/pill
• [[Text]] Subroutine
• [(Text)] Cylinder (database)
• ((Text)) Circle
• {Text} Rhombus (decision)
• {{Text}} Hexagon
• [/Text/] Parallelogram (IO)
• [>Text] Asymmetric/flag

Connections: --> arrow, --- open, -.-> dotted, ==> thick

ERD (Database Schema)#

Rendering diagram...

Cardinality: || exactly one, |o zero or one, }{ one or many, }o zero or many

Constraints: PK (primary key), FK (foreign key), UK (unique), NN (not null)

C4 Architecture Diagrams#

Rendering diagram...

Levels: C4Context → C4Container → C4Component → Class diagrams

Elements: Person, System, System_Ext, SystemDb, SystemQueue, Container, ContainerDb, ContainerQueue, Component

Advanced Configuration#

Theme Variables#

javascript

mermaid.initialize({
  theme: 'dark',
  themeVariables: {
    primaryColor: '#3b82f6',
    primaryTextColor: '#f1f5f9',
    primaryBorderColor: '#8b5cf6',
    lineColor: '#06b6d4',
    background: '#111827',
    mainBkg: '#1e293b'
  }
});

Available themes: default, forest, dark, neutral, base

Layout Options#

javascript

// Dagre (default) - balanced layout
// ELK - better for complex diagrams
mermaid.initialize({
  layout: 'elk',
  elk: {
    mergeEdges: true,
    nodePlacementStrategy: 'BRANDES_KOEPF'
  }
});

Look Options#

javascript

mermaid.initialize({
  look: 'classic'   // Traditional
  // or
  look: 'handDrawn' // Sketch-like
});

HTML Rendering Config#

javascript

mermaid.initialize({
  startOnLoad: false,
  maxTextSize: 99999,
  fontSize: 14,
  securityLevel: 'loose'
});

Styling#

Node Styling#

Rendering diagram...

Link Styling#

Rendering diagram...

Subgraph Styling#

Rendering diagram...

Interactive Features#

Click Events & Links#

Rendering diagram...

Tooltips#

Rendering diagram...

Export Options#

MethodCommandLive Editorhttps://mermaid.liveCLI PNGmmdc -i diagram.mmd -o output.pngCLI SVGmmdc -i diagram.mmd -o output.svgCustom Sizemmdc -i input.mmd -o output.png -w 1920 -H 1080Dark BGmmdc -i input.mmd -o output.svg -b "#111827"

HTML Template#

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Mermaid Diagram</title>
  <style>
    body { margin: 0; background: #111827; }
    .mermaid { display: flex; justify-content: center; padding: 20px; }
    .mermaid svg { max-width: 100%; height: auto; }
  </style>
</head>
<body>
  <div class="mermaid">
flowchart LR
    A[Start] --> B[Process] --> C[End]
  </div>

  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({
      startOnLoad: true,
      theme: 'dark',
      themeVariables: {
        primaryColor: '#3b82f6',
        background: '#111827',
        mainBkg: '#1e293b',
        fontSize: '14px'
      }
    });
  </script>
</body>
</html>

Best Practices#

1. Start simple — begin with core entities, add details incrementally
2. Use meaningful names — clear labels make diagrams self-documenting
3. Comment extensively — use %% comments to explain complex relationships
4. Keep focused — one diagram per concept; split large diagrams
5. Version control — store .mmd files alongside code
6. Add context — include titles and notes to explain purpose
7. Iterate — refine diagrams as understanding evolves

Common Pitfalls#

ErrorCauseSolutionNodes undefinedChinese class namesUse English identifiersNo diagram typeSyntax errorValidate in mermaid.liveDiagram too smallMissing configSet useMaxWidth: false``Mermaid not definedLoad orderUse waitForMermaid()Lines crossingComplex layoutUse ELK layoutTruncated textToo many nodesSplit into multiple diagrams

NEVER Do#

1. NEVER create diagrams with >15 nodes — unreadable; split into focused views
2. NEVER leave arrows unlabeled — every connection should explain the relationship
3. NEVER create diagrams without a title — context-free diagrams are useless
4. NEVER use diagrams as sole documentation — pair with prose explaining the "why"
5. NEVER let diagrams go stale — update when architecture changes
6. NEVER use Mermaid for data visualization — it's for architecture, not charts

Quick Reference#

Entity with Methods Template#

Rendering diagram...

Complete Relationship Set#

Rendering diagram...

Flowchart Complete Shapes#

Rendering diagram...