Draw Mermaid Diagram

Draw Mermaid Diagram

General-purpose guidance for drawing and validating Mermaid diagrams. For AWS / cloud architecture diagrams, switch to draw-infra-diagram.

When to use which diagram type

If you're not sure: a flowchart with action nodes is rarely wrong. Sequence is for ordered communication; state is for "what state can the thing be in." ER is for data models, not behavior.

Authoring workflow

1. Draft in a standalone .mmd file. Easier to validate than a fenced block inside Markdown.
2. Write the diagram.
3. Validate: ${CLAUDE_SKILL_ROOT}/tools/validate.sh diagram.mmd
4. Once it validates, copy the contents into the target Markdown file as a fenced ```mermaid block.

The validator catches syntax errors before they surface as a broken render in the published doc. See Validation below.

Syntax cheatsheets

Flowchart

flowchart TD
    Start([Start]) --> Decide{Has account?}
    Decide -->|Yes| Login[Login]
    Decide -->|No| Signup[Signup]
    Login --> Dashboard[Dashboard]
    Signup --> Dashboard

Direction: TD (top-down), BT, LR, RL. Edge styles: --> solid, -.-> dotted, ==> thick. Node shapes are documented under "shape vocabulary" in the Mermaid docs.

Sequence

sequenceDiagram
    participant User
    participant Browser
    participant API
    participant DB
    User->>Browser: Click "Sign in"
    Browser->>API: POST /auth/login
    API->>DB: SELECT user WHERE email=?
    DB-->>API: user row
    API-->>Browser: 200 + session cookie
    Browser-->>User: Dashboard

->> solid arrow, -->> dashed (response), -> open arrow, --) async. Note over A,B: text for annotations. loop, alt/else, opt, par for control flow.

State

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted: submit
    Submitted --> Approved: approve
    Submitted --> Rejected: reject
    Approved --> [*]
    Rejected --> Draft: revise

[*] is the start/end pseudo-state. Use state X { ... } for nested composite states.

Class

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +String breed
        +bark() void
    }
    Animal <|-- Dog

Relationships: <|-- inheritance, *-- composition, o-- aggregation, --> association, ..> dependency.

ER

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    USER {
        uuid id PK
        string email
        timestamp created_at
    }
    ORDER {
        uuid id PK
        uuid user_id FK
        decimal total
    }

Cardinality: || exactly one, }o zero or many, }| one or many, o| zero or one. Mirrored on the other side of the relation.

Gantt

gantt
    title Release schedule
    dateFormat YYYY-MM-DD
    section Backend
    API rewrite      :a1, 2026-01-01, 14d
    Migration        :after a1, 7d
    section Frontend
    Component refresh:2026-01-08, 21d

Validation

${CLAUDE_SKILL_ROOT}/tools/validate.sh diagram.mmd

The script invokes npx -y @mermaid-js/mermaid-cli to parse and render the diagram. Non-zero exit means invalid syntax. When supported by the diagram type, it also prints an ASCII preview via beautiful-mermaid.

First-run gotcha: the Mermaid CLI uses Puppeteer, which downloads a headless Chromium on first invocation. This is slow (~100MB, one-time). On systems where that download fails (CI sandboxes, restricted networks), set PUPPETEER_EXECUTABLE_PATH to point at an existing Chrome/Chromium binary.

Optional second arg writes the rendered SVG to disk:

${CLAUDE_SKILL_ROOT}/tools/validate.sh diagram.mmd /tmp/diagram.svg

Without it, the SVG goes to a temp file and is cleaned up on exit.

Layout gotchas

• Linear chains in subgraphs sometimes render horizontally even with flowchart TD. Force vertical with direction TB inside the subgraph.
• Long labels truncate in some renderers. Keep node and subgraph labels short — push detail into the prose around the diagram.
• HTML in labels requires the label be quoted: id("text<br/>more text"). Unquoted labels can't contain <, >, (, ), or ,.
• Reserved words. end, class, style, linkStyle are keywords. If a node id collides, prefix it (n_end instead of end).

Anti-patterns

• Picking the wrong diagram type. A flowchart of "states" is usually really a state diagram; force-fitting it loses the implicit time semantics. A sequence diagram of "components" is usually a class or component diagram.
• All-rectangle flowcharts. Mermaid's shape vocabulary is a free communication channel — use rounded boxes for processes, diamonds for decisions, stadiums for start/end, cylinders for data stores.
• Skipping validation. Markdown renderers fail Mermaid blocks silently in some setups; the doc looks fine in preview but breaks on the deployed site. Always validate.

Reference

• Mermaid full syntax: https://mermaid.js.org/syntax/
• Mermaid CLI: https://github.com/mermaid-js/mermaid-cli
• Live editor (for ad-hoc tweaks): https://mermaid.live/

Related skills

• draw-infra-diagram — AWS / cloud architecture specialist. Curated shape and color vocabulary, region-tinted subgraphs, debugging-oriented document structure. Builds on this skill.

Adapted from

• mitsuhiko/agent-stuff — tools/validate.sh