mermaid

name	mermaid
description	Must read guide on creating clear, well-designed mermaid diagrams — includes design principles, diagram type selection, and syntax reference for all 18 diagram types

Mermaid Skill

Use this skill to design, write, and validate Mermaid diagrams. Covers design principles for clear visual explanation, a decision guide for choosing diagram types, and a syntax reference for all 18 Mermaid diagram types. Validation uses the official Mermaid CLI.

Arguments

When this skill is invoked, the user may provide a file path and name as an argument:

@skills/mermaid/skill.md <filename.mmd>

Examples: vue-architecture.mmd, docs/auth-flow.mmd, db-schema.mmd

• If a filename is provided, use it exactly as given.
• If no filename is provided, derive a descriptive kebab-case name from the diagram's subject (e.g. user-auth-flow.mmd, payment-sequence.mmd, order-er-diagram.mmd). Place it in the project root.
• Never reuse a generic name like diagram.mmd. Every diagram gets its own descriptively named file.

Prerequisites

• Node.js + npm (for npx).
• First run downloads a headless Chromium via Puppeteer. If Chromium is missing, set PUPPETEER_EXECUTABLE_PATH.

Tool

Validate a diagram

The validate script lives inside the skill directory. Use the path relative to the skill, not the working directory:

skills/mermaid/tools/validate.sh <filename.mmd> [output.svg]

• Parses and renders the Mermaid source.
• Non-zero exit = invalid Mermaid syntax.
• Prints an ASCII preview using beautiful-mermaid (best-effort; not all diagram types are supported).
• If output.svg is omitted, the SVG is rendered to a temp file and discarded.

Workflow (short)

1. Choose a descriptive filename for the diagram (from the argument or derived from the subject). Use kebab-case with .mmd extension.
2. Write the Mermaid source to that file in the project root (or the path given).
3. Run skills/mermaid/tools/validate.sh <filename.mmd>.
4. Fix any errors shown by the CLI.
5. Always show the ASCII preview output to the user. The tool prints an ASCII rendering of the diagram — display it in your response so the user can see the result without opening another tool.
6. Quality check before finishing. Review the diagram against this checklist:
   • Title or header present (e.g. title, ---\ntitle:, or a top-level label)
   • 5–15 nodes. If more, split into separate diagrams.
   • Every edge has a label (what flows, what triggers, what relationship)
   • Labels are concrete and specific — no vague "data", "process", or "info"
   • Colors/styles encode meaning or are absent — no decorative styling
   • Diagram type matches the question being answered (see Choosing the Right Diagram Type below)
7. Once it validates and passes the quality check, if the diagram will live in Markdown, copy the Mermaid block into the target Markdown file.

---

Design Principles

Scope and Focus

• One concept per diagram. A diagram should answer one question. "How does auth work?" is one diagram. "How does the whole system work?" is five diagrams.
• 5–15 nodes is the sweet spot. Fewer than 5 and you probably don't need a diagram. More than 15 and readers get lost — split it up.
• Title everything. Every diagram needs a title or prominent top-level label. Without one, readers have to reverse-engineer what they're looking at.
• Scope to your audience. A diagram for a new teammate shows different detail than one for a principal engineer. Match the abstraction level to who's reading it.

Labels and Naming

• Be concrete and specific. "User submits order" beats "data". "POST /api/orders" beats "request". If a label could apply to anything, it's too vague.
• Verb-first edge labels. Edges describe actions or relationships: "sends auth token", "triggers rebuild", "contains". Noun-only labels ("data", "response") leave the reader guessing.
• No orphan abbreviations. If you use an abbreviation, define it in the node text: DB["PostgreSQL Database"], not just DB.
• Meaningful node IDs. Use IDs that read naturally in the source: authService, orderDB, not A, B, C. This also makes the .mmd file self-documenting.

Visual Clarity

• Maximize the data-ink ratio. Every visual element should convey information. If a color, line, or shape doesn't encode meaning, remove it.
• Relationships matter more than node decoration. Spend effort on edge labels and flow direction, not on styling individual boxes.
• Direction encodes meaning. Top-down (TD) implies hierarchy or time flow. Left-right (LR) implies a pipeline or data flow. Choose direction intentionally.
• Use subgraphs to reduce clutter. Group related nodes into named subgraphs. This creates visual hierarchy and lets readers zoom in mentally.
• Show dynamics, not just structure. Where possible, show what triggers transitions, what messages flow, what changes state — not just which boxes connect.

Common Mistakes to Avoid

• The mega-diagram. Cramming an entire system into one diagram. If you need to scroll, you need to split.
• The decoration trap. Adding colors, thick borders, and gradients "to make it look nice." If the colors don't encode meaning (like status or category), they're noise.
• The abstraction mismatch. Mixing high-level architecture with implementation details. Don't show "Kubernetes Pod" next to "User clicks button" in the same diagram.
• Unlabeled edges. An arrow without a label says "these are related somehow." That's almost never enough information.

---

Choosing the Right Diagram Type

Question you're answering	Diagram type
How does this process work?	Flowchart
What messages pass between services?	Sequence Diagram
What are the parts and relationships?	Class / ER Diagram
What states can this be in?	State Diagram
What's the system architecture?	Architecture / Block
When did things happen?	Timeline / Gantt
How do quantities flow or distribute?	Sankey / Pie
How do options compare on two axes?	Quadrant Chart
What's the branching strategy?	Git Graph
What tasks are in what stage?	Kanban

Rule of thumb: Flowcharts and sequence diagrams cover 80% of needs. Start there unless the question clearly calls for something else.

---

Syntax Reference

Detailed syntax for every Mermaid diagram type. See Design Principles above for guidance on what makes a diagram effective, and Choosing the Right Diagram Type to pick the right one.

General Syntax Tips

Multi-line labels: \n does not work in Mermaid. Use markdown strings with backticks and real newlines:

flowchart TD
    A["`Line 1
Line 2
Line 3`"]

Markdown strings also support bold (**text**) and italic (*text*) formatting inside the backticks.

1. Flowchart

Use for: Process flows, decision trees, workflows, algorithms.

flowchart TD
    A[Start] --> B{Decision?}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Directions: TB/TD (top-down), BT, LR, RL

Node shapes: A[rect] A(rounded) A([stadium]) A[[subroutine]] A[(cylinder)] A((circle)) A{diamond} A{{hexagon}} A[/parallelogram/] A[/trapezoid\] A(((double circle)))

Links: --> arrow, --- open, -.-> dotted, ==> thick, ~~~ invisible, <--> bidirectional. Add text: -->|text| or -- text -->

Subgraphs: subgraph id[title] ... end

Styling: style A fill:#f9f,stroke:#333 or classDef cls fill:#f9f; A:::cls

2. Sequence Diagram

Use for: API calls, service interactions, request/response flows, protocol sequences.

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello
    B-->>A: Hi back
    A->>B: How are you?
    B-->>A: Great!

Participants: participant, actor. Stereotypes (JSON config): boundary, control, entity, database, collections, queue

Arrows: ->> solid+arrowhead, -->> dotted+arrowhead, -x cross end, -) async open arrow, <<->> bidirectional

Activations: activate A / deactivate A or shorthand A->>+B: msg / B-->>-A: reply

Notes: Note right of A: text or Note over A,B: text

Control flow:

• loop text ... end
• alt text ... else ... end
• opt text ... end
• par [Action 1] ... and [Action 2] ... end
• critical [text] ... option [text] ... end
• break [text] ... end

Grouping: box color Title ... end

Background highlight: rect rgb(0,255,0) ... end

3. Class Diagram

Use for: OOP class structures, inheritance hierarchies, domain models.

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal : +isMammal() bool
    Duck : +swim()
    Fish : +canEat() bool

Members: Bracket syntax Class { +method() returnType; -field type }. Visibility: + public, - private, # protected, ~ internal. Classifiers: * abstract, $ static.

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

Cardinality: ClassA "1" --> "*" ClassB

Annotations: <<Interface>>, <<Abstract>>, <<Enumeration>>, <<Service>>

Generics: List~int~

Namespaces: namespace Name { class A { } }

Notes: note "text" or note for ClassName "text"

4. State Diagram

Use for: Finite state machines, lifecycle states, object state transitions.

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : submit
    Processing --> Done : complete
    Processing --> Error : fail
    Error --> Idle : retry
    Done --> [*]

States: stateName, stateName : Description, state "Description" as s1

Start/End: [*] --> First, Last --> [*]

Composite: state CompositeState { InnerA --> InnerB }

Choice: state decision <<choice>>

Fork/Join: state fork <<fork>>, state join <<join>>

Notes: note right of State : text ... end note

Concurrency: state Parallel { A --> B -- C --> D } (use -- separator)

Direction: direction LR (or RL, TB, BT)

5. Entity Relationship Diagram

Use for: Database schemas, data models, table relationships.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    PRODUCT ||--o{ LINE-ITEM : "is in"

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

Line style: -- identifying (solid), .. non-identifying (dashed)

Attributes:

ENTITY {
    string name PK
    int age
    string email UK "user email"
}

Key types: PK, FK, UK

6. Gantt Chart

Use for: Project schedules, task timelines, sprint planning.

gantt
    title Project Plan
    dateFormat YYYY-MM-DD
    section Phase 1
    Task A           :a1, 2024-01-01, 30d
    Task B           :after a1, 20d
    section Phase 2
    Task C           :2024-02-15, 12d
    Milestone        :milestone, m1, 2024-03-01, 0d

Task format: Task name :tags, id, start, end/duration. Tags: done, active, crit, milestone

Dependencies: after taskId, until taskId

Date config: dateFormat YYYY-MM-DD, axisFormat %Y-%m-%d

Excludes: excludes weekends or specific dates

7. Pie Chart

Use for: Proportions, distributions, market share.

pie showData title Browser Market Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 4
    "Other"  : 12

Syntax: pie [showData] [title text] then "label" : value per line. Values must be positive numbers.

8. Git Graph

Use for: Branch strategies, release flows, git workflows.

gitGraph
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit tag:"v1.0"

Commands: commit, branch name, checkout name, merge name, cherry-pick id:"commitId"

Commit options: id: "abc", tag: "v1.0", type: NORMAL|REVERSE|HIGHLIGHT

9. Mindmap

Use for: Brainstorming, topic hierarchies, concept maps.

mindmap
    root((Central Idea))
        Topic A
            Subtopic 1
            Subtopic 2
        Topic B
            Subtopic 3

Hierarchy: Indentation defines parent-child relationships.

Shapes: [square], (rounded), ((circle)), )cloud(, {{hexagon}}, ))bang(( or plain text.

Icons: ::icon(fa fa-book) after node text.

Classes: :::className after node text.

10. Timeline

Use for: Historical events, release histories, roadmaps.

timeline
    title Project Milestones
    section 2024 Q1
        January : Kickoff : Team formed
        March   : MVP released
    section 2024 Q2
        June    : Public launch

Syntax: time period : event1 : event2 or stack events on separate lines with : event.

Sections: section Title groups subsequent entries.

11. User Journey

Use for: UX flows, customer experience mapping, satisfaction scoring.

journey
    title User Purchase Flow
    section Browse
        Visit site: 5: User
        Search product: 3: User
    section Checkout
        Add to cart: 5: User
        Enter payment: 2: User, System
        Confirm order: 4: User, System

Syntax: Task name: score: actor1, actor2. Score is 1-5 (1=bad, 5=great).

Sections: Group tasks into phases.

12. Quadrant Chart

Use for: Priority matrices, competitive analysis, effort-vs-impact plots.

quadrantChart
    title Feature Priority
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First
    quadrant-2 Plan
    quadrant-3 Eliminate
    quadrant-4 Delegate
    Feature A: [0.8, 0.9]
    Feature B: [0.2, 0.7]
    Feature C: [0.6, 0.3]

Points: Label: [x, y] where x,y are 0-1. Optional: radius: 12, color: #ff3300

13. Sankey Diagram

Use for: Flow quantities, energy/resource distribution, budget allocation.

sankey
    Source A,Target X,100
    Source A,Target Y,50
    Source B,Target Y,80
    Source B,Target Z,30

Syntax: CSV format source,target,value. Wrap commas in quotes: "A, Inc",B,100

Config: linkColor: source|target|gradient|#hex, nodeAlignment: justify|center|left|right

14. XY Chart (Bar/Line)

Use for: Data trends, comparisons, statistics.

xychart
    title "Monthly Sales"
    x-axis "Month" [Jan, Feb, Mar, Apr, May]
    y-axis "Revenue" 0 --> 500
    bar [120, 200, 150, 300, 450]
    line [100, 180, 160, 280, 420]

Orientation: xychart horizontal for horizontal layout.

X-axis: categorical ["a", "b"] or numeric min --> max. Y-axis: numeric only.

Data: bar [values] and/or line [values].

15. Block Diagram

Use for: System architecture layouts, infrastructure diagrams, component arrangements.

block-beta
    columns 3
    A["Frontend"] B["API"] C["Database"]
    D["Cache"]:2 E["Queue"]
    A --> B --> C
    B --> D

Columns: columns N sets grid width. Blocks span columns with :N.

Shapes: Same as flowchart: [rect], (rounded), ((circle)), {diamond}, [(cylinder)], etc.

Links: -->, --- with optional text.

Nesting: Blocks can contain other blocks for composite layouts.

Space: Use space or space:N to insert empty cells.

16. Packet Diagram

Use for: Network protocol headers, binary data formats, memory layouts.

packet-beta
    0-15: "Source Port"
    16-31: "Destination Port"
    32-63: "Sequence Number"
    64-95: "Acknowledgment Number"

Syntax: start-end: "Field name" for ranges, or +N: "Field name" for N-bit auto-positioned fields.

17. Architecture Diagram

Use for: Cloud infrastructure, CI/CD pipelines, service topology.

architecture-beta
    group api(cloud)[API Layer]

    service db(database)[PostgreSQL] in api
    service server(server)[App Server] in api
    service client(internet)[Client]

    client:R --> L:server
    server:R --> L:db

Groups: group id(icon)[Title] — containers for services. Nest with in parentId.

Services: service id(icon)[Title] — individual nodes. Nest with in groupId.

Edges: serviceA:direction --> direction:serviceB. Directions: T, B, L, R.

Junctions: junction id — four-way connection points.

Icons: Built-in: cloud, database, disk, internet, server. Custom via iconify: "logos:aws"

18. Kanban Board

Use for: Task boards, workflow stages, agile boards.

kanban
    todo[To Do]
        task1[Design mockups]
        task2[Write specs]
    inprog[In Progress]
        task3[Build API]
    done[Done]
        task4[Setup repo]

Columns: id[Title] at root level.

Tasks: id[Description] indented under a column.

Metadata: @{ assigned: "Alice", ticket: "PROJ-123", priority: "High" } after task.

Config: ticketBaseUrl in YAML frontmatter creates clickable ticket links.