mermaid-diagrams

Use this skill for any Mermaid work in technical writing.

When to use it

• Writing or editing Mermaid in README.md, design docs, RFCs, ADRs, runbooks, or onboarding notes
• Turning prose architecture into a diagram
• Choosing between flowchart, sequence, state, ER, timeline, or gantt
• Adding semantic colors, subgraphs, lanes, and grouping
• Validating Mermaid before shipping docs

Default workflow

1. Identify the doc's purpose: overview, interaction, lifecycle, data model, rollout plan, or chronology.
2. Pick the simplest diagram type that communicates that purpose.
3. Draft the smallest correct diagram first.
4. Add semantic grouping with subgraphs / boxes / sections.
5. Add a restrained color palette only after the structure is correct.
6. Validate the exact file you changed.
7. If validation is unavailable, keep syntax conservative and call out that rendering was not verified locally.

Diagram chooser

• flowchart / graph — architecture overview, process flow, request pipeline, ownership boundaries
• sequenceDiagram — time-ordered service interactions or control flow
• stateDiagram-v2 — lifecycle/state machine
• classDiagram — domain model, interfaces, component relationships
• erDiagram — tables/entities and cardinality
• timeline — chronology or milestone history
• gantt — execution plan, migration plan, rollout schedule
• mindmap — scope decomposition or brainstorming
• journey — end-user workflow scoring
• gitGraph — release flow or branch strategy

Semantic color guidance

Prefer one consistent palette across the document:

• users / external actors: blue
• authoring or control plane: purple
• runtime / compute / workers: green
• networking / edge / ingress: orange
• data stores / queues / persistence: red
• storage / artifacts / object stores: yellow
• observability / policy / meta systems: gray
• success states: green
• warning / pending states: amber
• failure states: red

Use reusable styles instead of one-off colors wherever possible.

Flowchart pattern

flowchart LR
  subgraph Clients["Clients"]
    U["Developer"]
  end

  subgraph Control["Control plane"]
    API["Docs API"]
    WF["RFC workflow"]
  end

  subgraph Data["Persistence"]
    DB[("Metadata DB")]
  end

  U --> API --> WF --> DB

  classDef actor fill:#E0F2FE,stroke:#0369A1,color:#0C4A6E;
  classDef control fill:#F5F3FF,stroke:#7C3AED,color:#4C1D95;
  classDef data fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D;

  class U actor;
  class API,WF control;
  class DB data;

Sequence pattern

sequenceDiagram
  box rgba(224, 242, 254, 0.45) User
    actor Author as RFC author
  end
  box rgba(245, 243, 255, 0.55) Control plane
    participant Docs as Docs service
    participant Review as Review workflow
  end
  box rgba(220, 252, 231, 0.55) Runtime
    participant Store as Content store
  end

  Author->>Docs: Submit draft
  Docs->>Review: Start review
  Review->>Store: Persist version
  Store-->>Review: Saved
  Review-->>Docs: Review requested
  Docs-->>Author: Show status

Mermaid gotchas

• Every Mermaid block starts with a diagram type declaration.
• Prefer quoted labels when they contain punctuation.
• Avoid lowercase end as an unquoted label.
• In flowcharts, linkStyle indexes edges by declaration order.
• Keep the first draft minimal, then style.
• Validate after edits because small typos can break the whole diagram.

Validation

Always validate Mermaid if mmdc is available.

Run the bundled validator from the skill directory:

node ./scripts/validate-mermaid.js path/to/file.md
node ./scripts/validate-mermaid.js path/to/diagram.mmd
node ./scripts/validate-mermaid.js docs/
node ./scripts/validate-mermaid.js --self-test-styles

The validator:

• extracts Mermaid fences from Markdown and MDX
• validates standalone .mmd and .mermaid files
• reports failing block numbers and approximate source lines
• can self-test styled flowchart, sequence, class, state, and ER examples

Optional scaffolding helper

Use the template generator when you want a fast, styled starting point:

node ./scripts/new-mermaid-template.js flowchart
node ./scripts/new-mermaid-template.js sequence --title "RFC review lifecycle"

Finishing rule

Before finalizing Mermaid changes:

1. save the file
2. validate the changed file(s)
3. fix any parse issues
4. re-run validation
5. only then return the final diagram or patch

References

Read these as needed:

• references/diagram-types.md — small working examples for major Mermaid diagram types; use the deeper per-type docs only when a flowchart, ER, or gantt diagram gets complex
• references/flowchart-keywords.md — flowchart / graph keywords, edge operators, subgraphs, shapes, and gotchas
• references/er-keywords.md — ER relationship syntax, cardinality markers, attributes, keys, and layout
• references/gantt-keywords.md — gantt task metadata, dates, dependencies, sections, tags, and exclusions
• references/rfc-diagram-patterns.md — doc/RFC-friendly patterns with colors, groups, and recommended use cases
• references/official-sources.md — official Mermaid docs and validation notes