Mermaid Diagrams skill for Claude Code

Done well means: the diagram type matches the question being answered, it renders without errors in the target (GitHub, docs site, mmdc), it fits on one screen with at most ~15–20 nodes per view, labels are short and specific, and you actually rendered it once to catch syntax errors rather than trusting it by eye.

Pick the type

Question	Diagram	Header
What steps/decisions happen?	Flowchart	flowchart TD / flowchart LR
Who calls whom, in what order?	Sequence	sequenceDiagram
What tables exist and how do they relate?	Entity relationship	erDiagram
What states can an object be in?	State	stateDiagram-v2
What classes/types and relationships?	Class	classDiagram
When does work happen?	Gantt	gantt
What happened when?	Timeline	timeline
How do ideas branch?	Mindmap	mindmap
System context/containers	Flowchart with subgraphs, or C4 (see c4-diagrams)

More types (gitGraph, quadrantChart, xychart-beta, sankey-beta, block-beta, architecture-beta, kanban, pie) and full syntax per type are in references/syntax.md; read it when you need a type not covered below or an unusual feature.

Workflow

- [ ] 1. State the question the diagram answers and the audience
- [ ] 2. Pick the type; list nodes/participants from the real system (code, schema, spec)
- [ ] 3. Draft at most ~15–20 nodes; split into several diagrams if larger
- [ ] 4. Render with mmdc (or the target's preview) and fix errors
- [ ] 5. Check readability: direction, crossing edges, label length, contrast in dark mode

Flowchart

flowchart LR
  user([User]) --> web[Web app]
  web -->|REST, JWT| api[API service]
  api --> db[(Postgres)]
  api -.->|async| q[[Job queue]]
  q --> worker[Worker]
  worker --> s3[(S3 bucket)]
  subgraph vpc [Private VPC]
    api
    db
    q
    worker
  end
  classDef store fill:#eef,stroke:#557
  class db,s3 store

Shapes: [rect], (rounded), ([stadium]), [(cylinder)], {decision}, [[subroutine]], ((circle)), >flag]. Newer Mermaid (v11.3+) also accepts id@{ shape: cyl, label: "Postgres" } for an expanded shape set — use it only if the target renderer is current (GitHub and docs sites can lag).

Edges: -->, ---, -.-> (dotted), ==> (thick), --o, --x, labels with -->|label| or -- label -->. Chain: a --> b & c --> d.

Flowchart traps:

• The word end in lowercase as a node label breaks parsing; write End or ["end"].
• A node ID starting with o or x right after -- is read as an edge type (A---oB); add a space or rename.
• Quote labels with special characters: A["Price (USD) / unit"]. Use #quot; for a literal double quote inside a quoted label; <br> for line breaks.
• Define each node’s label once; later references use the bare ID.
• subgraph IDs must not collide with node IDs. Set direction inside with direction TB.
• Too many crossings: switch TD↔LR, reorder node declarations (Mermaid lays out in declaration order), or split the diagram.

Sequence diagram

sequenceDiagram
  autonumber
  actor U as User
  participant W as Web
  participant A as API
  participant S as Stripe
  U->>W: Click "Pay"
  W->>+A: POST /checkout
  A->>+S: Create PaymentIntent
  S-->>-A: client_secret
  A-->>-W: 200 {client_secret}
  alt card requires 3DS
    W->>U: Show challenge
  else success
    W->>U: Show receipt
  end
  Note over A,S: Webhook confirms payment asynchronously

Arrows: ->> sync request, -->> response, -) async, -x failure. +/- on arrows activate/deactivate lifelines. Blocks: alt/else, opt, loop, par/and, critical, break, rect rgb(...) for highlighting — each closed with end. Keep message labels under ~40 characters; put payload details in notes.

ER diagram

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : "appears in"
  CUSTOMER {
    uuid id PK
    string email UK
    timestamptz created_at
  }
  ORDER {
    uuid id PK
    uuid customer_id FK
    numeric total
  }

Cardinality: || exactly one, o| zero or one, }| one or more, }o zero or more. -- identifying (solid), .. non-identifying (dashed). Generate from the real schema (migrations, \d output, Prisma schema) rather than from memory; show only the tables relevant to the question.

State diagram

stateDiagram-v2
  [*] --> Draft
  Draft --> Submitted: submit()
  Submitted --> Approved: approve()
  Submitted --> Rejected: reject(reason)
  Rejected --> Draft: edit()
  Approved --> [*]
  state Submitted {
    [*] --> AwaitingReview
    AwaitingReview --> InReview: assign()
  }

Every non-terminal state should have an exit; label transitions with the event or method that causes them.

Gantt

gantt
  title Launch plan
  dateFormat YYYY-MM-DD
  excludes weekends
  section Build
    API endpoints      :done,   api, 2026-03-02, 8d
    Web UI             :active, ui,  after api, 10d
  section Release
    Beta               :        beta, after ui, 5d
    GA                 :milestone, ga, after beta, 0d

Theming and config

Use frontmatter config (the %%{init: ...}%% directive still works but is deprecated):

---
title: Order flow
config:
  theme: neutral
  flowchart:
    curve: basis
---
flowchart LR
  a --> b

• Themes: default, neutral (best for print and docs), dark, forest, base (the only one that honors themeVariables fully).
• GitHub picks light/dark automatically; hard-coded fill colors can become unreadable in dark mode. Prefer classDef with both a fill and a contrasting color, or no fills.
• ELK layout (config: layout: elk) helps large flowcharts but needs a renderer with the ELK package; GitHub may not support it. Test in the target.

Rendering

npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.svg
npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -s 2 -b transparent
npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.pdf -f      # -f fits PDF to the diagram
npx -p @mermaid-js/mermaid-cli mmdc -i README.md -o README.out.md          # renders every mermaid block to SVG files

mmdc uses headless Chromium via Puppeteer; in CI/containers, pass a Puppeteer config (-p puppeteer.json with {"args": ["--no-sandbox"]}) only inside an isolated container. The live editor (mermaid.live) is fine for quick checks of non-sensitive diagrams; do not paste confidential architecture into third-party sites without the user’s agreement.

Gotchas

• Renderers differ in Mermaid version. GitHub, GitLab, Notion, Obsidian, and docs plugins each pin their own; new syntax may fail there even if mermaid.live renders it.
• A single syntax error blanks the whole diagram; error messages give the line — render after every major edit.
• Long labels make giant boxes; abbreviate and explain in surrounding text.
• Comments are %% at line start; // and # are not comments.
• Indentation is cosmetic in most types but significant in mindmap.

Verification

• mmdc renders without errors to SVG (or the target’s preview shows it).
• Diagram answers the stated question; every node and edge corresponds to something real in the code, schema, or spec.
• View the rendered output in both light and dark themes if it will live on GitHub.