# Mermaid Diagrams > Practical guide for creating human-readable and agent-parseable diagrams using Mermaid. Includes conservative, renderer-compatible templates and when-to-use guidance. - Skill: `whiner9/mermaid-diagrams` (Agent Skill) - Install (CLI): `npx skillmds@latest add whiner9/mermaid-diagrams` - Raw SKILL.md: https://api.skillmd.com/api/skills/whiner9/mermaid-diagrams/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: whiner9 (https://skillmd.com/u/whiner9) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/whiner9/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 `
` 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: ()`. 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): ```mermaid graph LR A["Start"] --> B{Auth?} B -->|Yes| C["Dashboard"] B -->|No| D["Login"] ``` ```text Diagram: Auth flow (flowchart) [Start] --> {Auth?} {Auth?} -- Yes --> [Dashboard] {Auth?} -- No --> [Login] ``` Example (Text-based Sequence): ```mermaid sequenceDiagram participant U as User participant W as WebApp U->>W: Open W-->>U: OK ``` ```text Diagram: Happy path (sequence) User -> WebApp : Open WebApp -> User : OK ``` ## Working Templates (Renderer-Compatible) ### Flowchart ```mermaid graph LR A["Start"] --> B{Auth?} B -->|Yes| C["Dashboard"] B -->|No| D["Login"] C --> E["Settings"] ``` ### Sequence ```mermaid 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 ```mermaid classDiagram class User { +String id +String name +login: bool } class Order { +String id +Decimal total +submit } User "1" o-- "*" Order ``` ### State (v2) ```mermaid 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) ```mermaid 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) ```mermaid 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 ```mermaid 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) ```mermaid pie title Traffic by Source "Direct" : 35 "Organic" : 45 "Ads" : 20 ``` ### Quadrant — flowchart fallback ```mermaid graph TB Q1["Quick Wins
High Impact - Low Effort

- Improve UX"] Q2["Major Projects
High Impact - High Effort

- Rewrite Core"] Q3["Fill-ins
Low Impact - Low Effort

- Docs polish"] Q4["Thankless
Low Impact - High Effort

- Legacy migration"] Q1 --> Q2 Q1 --> Q3 Q2 --> Q4 Q3 --> Q4 ``` ### Requirement — flowchart fallback ```mermaid 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) ```mermaid graph LR Checkout["Checkout"] -->|100| PSP["PSP"] PSP -->|60| Settled["Settled"] PSP -->|40| Declined["Declined"] ``` ### Git graph — flowchart fallback (simple DAG) ```mermaid 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.