Mermaid Diagram Style Guide

For AI agents: Read this file for all core styling rules. Then use the diagram selection table to pick the right type and follow its link — each type has its own file with a production-quality exemplar, tips, and a copy-paste template.

For humans: This guide + the linked diagram files ensure every Mermaid diagram in your repo is accessible, professional, and renders cleanly in GitHub light and dark modes. Reference it from your AGENTS.md or contributing guide.

Target platform: GitHub Markdown (Issues, PRs, Discussions, Wikis, .md files) Design goal: Minimal professional styling that renders beautifully in both GitHub light and dark modes, is accessible to screen readers, and communicates clearly with zero visual noise.

---

Quick Start for Agents

1. Pick the diagram type → Selection table
2. Open that type's file → Copy the template, fill in your content
3. Apply styling from this file → Emoji from approved set, colors from approved palette
4. Add accessibility → accTitle + accDescr (or italic Markdown paragraph for unsupported types)
5. Verify → Renders in light mode, dark mode, and screen reader

---

Core Principles

---

Accessibility Requirements

Every diagram MUST include both accTitle and accDescr:

accTitle: Short Name 3-8 Words
accDescr: One or two sentences explaining what this diagram shows and what insight the reader gains from it

• accTitle — 3–8 words, plain text, names the diagram
• accDescr — 1–2 sentences on a single line (GitHub limitation), explains purpose and key structure

Diagram types that do NOT support accTitle/accDescr: Mindmap, Timeline, Quadrant, Sankey, XY Chart, Block, Kanban, Packet, Architecture, Radar, Treemap. For these, place a descriptive italic Markdown paragraph directly above the code block as the accessible description.

ZenUML note: ZenUML requires an external plugin and may not render on GitHub. Prefer standard sequenceDiagram syntax.

---

Theme Configuration

✅ Do: No theme directive (GitHub auto-detects)

flowchart LR
    accTitle: Secure API Request Flow
    accDescr: Three-step API request from authentication through processing to response

    auth[🔐 Authenticate] --> process[⚙️ Process request] --> respond[📤 Return response]

❌ Don't: Inline styles or custom themes

%% BAD — breaks dark mode
style A fill:#e8f5e9
%%{init: {'theme':'base'}}%%

---

Approved Emoji Set

One emoji per node, at the start of the label. Same emoji = same meaning across all diagrams in a project.

Systems & Infrastructure

Processes & Actions

People & Roles

Status & Outcomes

Information & Data

Domain-Specific

Emoji Rules

1. Place at start: [🔐 Authenticate] not [Authenticate 🔐]
2. Max one per node — never stack
3. Consistency is mandatory — same emoji = same concept across all diagrams
4. Not every node needs one — use on key nodes that benefit from visual distinction
5. No decorative emoji: 🎉 💯 🔥 🎊 💥 ✨ — they add noise, not meaning

---

GitHub-Compatible Color Classes

Use only when you genuinely need color-coding (multi-actor diagrams, severity levels). Prefer shapes + emoji first.

Approved palette (tested in both GitHub light and dark modes):

Live preview — all 7 classes rendered:

flowchart LR
    accTitle: Color Palette Preview
    accDescr: Visual reference showing all seven approved classDef color classes side by side

    primary[🔵 Primary] ~~~ success[✅ Success] ~~~ warning[⚠️ Warning] ~~~ danger[❌ Danger]
    neutral[ℹ️ Neutral] ~~~ accent[🟣 Accent] ~~~ warm[🟠 Warm]

    classDef primary fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef success fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef warning fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef danger fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
    classDef neutral fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
    classDef accent fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
    classDef warm fill:#ffedd5,stroke:#ea580c,stroke-width:2px,color:#7c2d12

    class primary primary
    class success success
    class warning warning
    class danger danger
    class neutral neutral
    class accent accent
    class warm warm

Rules:

1. Always include color: (text color) — dark-mode backgrounds can hide default text
2. Use classDef + class — never inline style directives
3. Max 3–4 color classes per diagram
4. Never rely on color alone — always pair with emoji, shape, or label text

---

Node Naming & Labels

| Rule | ✅ Good | ❌ Bad | | --------------------- | -------------------------- | ----------------------------------- | --- | ----- | ----------------------------- | --- | | snake_case IDs | run_tests, deploy_prod | A, B, node1 | | IDs match labels | open_pr → "Open PR" | x → "Open PR" | | Specific names | check_unit_tests | check | | Verbs for actions | run_lint, deploy_app | linter, deployment | | Nouns for states | review_state, error | reviewing, erroring | | 3–6 word labels | [📥 Fetch raw data] | [Raw data is fetched from source] | | Active voice | [🧪 Run tests] | [Tests are run] | | Sentence case | [Start pipeline] | [Start Pipeline] | | Edge labels 1–4 words | --> | All green | |---> | All tests passed successfully | |

---

Node Shapes

Use shapes consistently to convey node type without color:

---

Bold Text

Use **bold** on one key term per node — the word the reader's eye should land on first.

• ✅ [🚀 **Gradual** rollout] — highlights the distinguishing word
• ❌ [**Gradual** **Rollout** **Process**] — everything bold = nothing bold
• Max 1–2 bold terms per node. Never bold entire labels.

---

Subgraphs

Subgraphs are the primary tool for organizing complex diagrams. They create visual groupings that help readers parse structure at a glance.

subgraph name ["📋 Descriptive Title"]
    node1 --> node2
end

Subgraph rules:

• Quoted titles with emoji: ["🔍 Code Quality"]
• Group by stage, domain, team, or layer — whatever creates the clearest mental model
• 2–6 nodes per subgraph is ideal; up to 8 if tightly related
• Subgraphs can connect to each other via edges between their internal nodes
• One level of nesting is acceptable when it genuinely clarifies hierarchy (e.g., a "Backend" subgraph containing "API" and "Workers" subgraphs). Avoid deeper nesting.
• Give every subgraph a meaningful ID and title — subgraph deploy ["🚀 Deployment"] not subgraph sg3

Connecting subgraphs — choose the right level of detail:

Use subgraph-to-subgraph edges when the audience needs the high-level flow and internal details would be noise:

subgraph build ["📦 Build"]
    compile --> package
end
subgraph deploy ["🚀 Deploy"]
    stage --> prod
end
build --> deploy

Use internal-node-to-internal-node edges when the audience needs to see exactly which step hands off to which:

subgraph build ["📦 Build"]
    compile --> package
end
subgraph deploy ["🚀 Deploy"]
    stage --> prod
end
package --> stage

Pick based on your audience:

---