Mermaid Diagrams

Mermaid Diagrams Skill

This skill provides:

• A conservative set of Mermaid templates that render on older renderers (VS Code/Markdown previewers, Git platforms) and remain clear to humans.
• Guidance on which diagram type to use for which situation.
• Compatibility tips and fallbacks when advanced Mermaid types are unavailable.

Compatibility Rules (Read First)

• Prefer graph LR/graph TB for flowcharts; some renderers fail on flowchart keyword.
• Quote labels containing spaces/special characters: A["Text (x|y) |"].
• Do not use literal \n inside labels - Mermaid does not interpret such line breaks. Use <br/> for line breaks.
• Advanced types like quadrantChart, sankey-beta, requirementDiagram, gitGraph may not be available. Use provided flowchart fallbacks.
• Code fences must start at column 0 with language mermaid.

ASCII/Unicode Sidecar (Human-Readable Raw Markdown)

To optimize for quick human scanning in raw Markdown and robust parsing by agents, always ship an ASCII/Unicode sidecar immediately below each Mermaid block.

Policy:

• MUST include a monospace, text-only diagram right under the Mermaid block using fenced code with language text.
• MUST keep Mermaid and sidecar in sync (same nodes/edges, same labels where feasible). If they diverge, treat Mermaid as the source of truth and update the sidecar.
• SHOULD limit width to ~80 columns for readability in diffs and terminals.
• SHOULD use simple line art characters (ASCII first; Unicode box-drawing optional when environment supports it).
• MAY add a one-line caption above the pair: Diagram: <name> (<type>).

Recommended primitives:

• Boxes: [Name], (Name), +-----+\n| N |\n+-----+
• Flows: -->, decisions as {cond?} lines, lists with -.
• Sequence (text-based): Actor -> Actor: message with indented lifelines.

Example (Flowchart):

graph LR
 A["Start"] --> B{Auth?}
 B -->|Yes| C["Dashboard"]
 B -->|No| D["Login"]

Diagram: Auth flow (flowchart)
 [Start] --> {Auth?}
 {Auth?} -- Yes --> [Dashboard]
 {Auth?} -- No --> [Login]

Example (Text-based Sequence):

sequenceDiagram
 participant U as User
 participant W as WebApp
 U->>W: Open
 W-->>U: OK

Diagram: Happy path (sequence)
 User -> WebApp : Open
 WebApp -> User : OK

Working Templates (Renderer-Compatible)

Flowchart

graph LR
 A["Start"] --> B{Auth?}
 B -->|Yes| C["Dashboard"]
 B -->|No| D["Login"]
 C --> E["Settings"]

Sequence

sequenceDiagram
 autonumber
 participant U as User
 participant W as WebApp
 participant API
 U->>W: Open
 W->>API: GET /status
 API-->>W: 200
 W-->>U: OK

Class

classDiagram
 class User {
 +String id
 +String name
 +login: bool
 }
 class Order {
 +String id
 +Decimal total
 +submit
 }
 User "1" o-- "*" Order

State (v2)

stateDiagram-v2
 [*] --> Idle
 Idle --> Loading : fetch
 Loading --> Ready : ok
 Loading --> Error : fail
 state Ready {
 [*] --> Viewing
 Viewing --> Editing : edit
 Editing --> Viewing : save
 }
 Error --> Idle : retry

ER (Entity-Relationship)

erDiagram
 USER ||--o{ ORDER : places
 ORDER ||--|{ ORDER_LINE : contains
 PRODUCT ||--o{ ORDER_LINE : referenced
 USER {
 string id
 string email
 }
 PRODUCT {
 string id
 string name
 float price
 }

Journey (User Journey)

journey
 title Checkout UX
 section Browse
 "See product": 5: User
 "Add to cart": 4: User
 section Payment
 "Enter card": 2: User
 "3DS confirm": 2: User
 section Result
 "Success page": 5: User

Gantt

gantt
 title Release Plan
 dateFormat YYYY-MM-DD
 section Dev
 Spec :done, des1, 2025-10-01,2025-10-05
 Impl :active, des2, 2025-10-06,2025-10-20
 Tests : des3, 2025-10-21, 7d
 section Release
 Freeze :milestone, m1, 2025-10-28, 0d
 Deploy :crit, des4, 2025-10-29, 1d

Pie (compatible syntax)

pie
 title Traffic by Source
 "Direct" : 35
 "Organic" : 45
 "Ads" : 20

Quadrant - flowchart fallback

graph TB
 Q1["Quick Wins<br/>High Impact - Low Effort<br/><br/>- Improve UX"]
 Q2["Major Projects<br/>High Impact - High Effort<br/><br/>- Rewrite Core"]
 Q3["Fill-ins<br/>Low Impact - Low Effort<br/><br/>- Docs polish"]
 Q4["Thankless<br/>Low Impact - High Effort<br/><br/>- Legacy migration"]

 Q1 --> Q2
 Q1 --> Q3
 Q2 --> Q4
 Q3 --> Q4

Requirement - flowchart fallback

graph LR
 R1["Requirement: PCI-DSS compliant"]
 T1["Test: PCI checklist"]
 SVC["Service"]

 SVC -- satisfies --> R1
 T1 -- verifies --> R1

Sankey - flowchart fallback (weights on edges)

graph LR
 Checkout["Checkout"] -->|100| PSP["PSP"]
 PSP -->|60| Settled["Settled"]
 PSP -->|40| Declined["Declined"]

Git graph - flowchart fallback (simple DAG)

graph LR
 A["init"] --> B["feat-A"]
 A --> C["fix-1"]
 B --> D["merge"]
 C --> D

When to Use Which Diagram

• Flowchart: General flows, decisions, and data movement in specs and PRDs.
• Sequence: Interactions over time between actors/services (APIs, requests, responses).
• Class: Domain models and static structure; useful for entity attributes and relations.
• State: Lifecycle of an entity/component (idle -> loading -> ready/error, nested states).
• ER: Database/logical data model with cardinalities.
• Journey: User experience across steps/sections (great for PRD acceptance flows).
• Gantt: Scheduling, releases, and dependencies by dates.
• Pie: Simple composition/ratios; prefer tables when precision matters.
• Quadrant (fallback): Prioritization matrix (Impact/Effort) without experimental chart support.
• Requirement (fallback): Traceability between requirements, tests, and system elements.
• Sankey (fallback): Convey relative volumes along a path when sankey is unavailable.
• Git graph (fallback): Small branch/merge DAGs when gitGraph is unavailable.

Troubleshooting

• If a diagram fails to render, try:

1. Replace flowchart with graph and simplify shapes.
2. Quote node texts.
3. Test in https://mermaid.live to isolate environment issues.
4. Fall back to the templates above for maximum compatibility.