product-on-purpose/utility-mermaid-diagrams

<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->

Mermaid Diagrams

Create effective, syntactically valid mermaid diagrams for product documents.

When to Use

• Creating mermaid diagrams for PRDs, specs, roadmaps, or stakeholder presentations
• Choosing which of 15 diagram types fits a specific communication need
• Debugging mermaid code that won't render or renders incorrectly
• Reviewing diagrams for clarity, accuracy, and accessibility

When NOT to Use

• Exporting diagrams to image files (PNG/SVG) - that's a rendering tool concern
• Using non-mermaid diagramming tools (Figma, Lucidchart, draw.io)
• Creating purely decorative visuals with no informational purpose

The Cardinal Rule

Don't diagram what a list can say.

Diagrams earn their place when they reveal relationships, branching, or flow that prose flattens. Before creating any diagram, ask:

Does this show branching, relationships, or flow that a list or table would flatten?

• Yes → proceed with a diagram
• No → use a numbered list, bullet list, or table instead

A 5-step linear process is a list. A 5-step process with two decision points and a retry loop is a diagram.

Diagram Selection Guide

| I need to show... | Use | Also consider | |-------------------|-----|---------------| | A decision or approval process | Flowchart | State | | Multi-service or multi-party interactions | Sequence | Flowchart | | Feature lifecycle or status transitions | State | Flowchart | | Work stages or pipeline status | Kanban | State | | Release or sprint timeline with dependencies | Gantt | Timeline | | Version history or chronological milestones | Timeline | Gantt | | 2D prioritization (effort/impact, risk/value) | Quadrant | - | | Allocation breakdown or composition | Pie | Treemap | | Problem decomposition or brainstorming | Mindmap | - | | Domain models or data relationships | ER | Class | | API or object contracts | Class | ER | | System topology or infrastructure | Architecture | Flowchart | | Flow quantities or budget allocation | Sankey | Pie | | Hierarchical proportional data | Treemap | Pie | | Trends or time-series metrics | XY-Chart | - |

For worked examples organized by PM task, see references/pm-use-cases.md. For full syntax and options per type, see references/diagram-catalog.md.

Syntax Validity Principles

Six rules that prevent most rendering failures:

1. Quote labels - Any label containing spaces, parentheses, brackets, colons, commas, or reserved words must be quoted with double quotes
2. Escape special characters - Characters with mermaid or markdown meaning (>, <, - at line start, #) need escaping or quoting
3. Declare before referencing - Define a node before using it in an edge; referencing an undeclared node causes silent failures in some types
4. Respect limits - Each diagram type has a maximum node/participant count beyond which readability collapses (see references/diagram-catalog.md for per-type limits)
5. Comment your intent - Use %% comments to document non-obvious choices (why this layout direction, why this grouping)
6. Test before shipping - Paste into a mermaid renderer (mermaid.live, VS Code preview, or your target environment) and verify it renders correctly

For the complete syntax reference, see references/syntax-guide.md.

Instructions

1. Identify what you're communicating - What relationship, flow, hierarchy, or proportion needs to be visible? Who is the audience?
2. Apply the cardinal rule - Confirm a diagram adds value over a list or table
3. Select a diagram type - Use the selection guide above, browse references/pm-use-cases.md by task, or browse references/diagram-catalog.md by type
4. Plan the diagram - Fill out the planning worksheet in references/TEMPLATE.md: purpose, audience, node inventory, type rationale
5. Write the mermaid code - Follow references/syntax-guide.md rules; start with the minimal syntax example from references/diagram-catalog.md and expand
6. Validate - Run through the quality checklist below
7. Embed - Place the validated mermaid code block in your document

Output Contract

• Planning artifact: A completed diagram planning worksheet (references/TEMPLATE.md)
• Final output: A syntactically valid mermaid code block embedded in the target document
• Quality gate: All items in the quality checklist pass

Quality Checklist

• [ ] Diagram renders without error in target environment
• [ ] Cardinal rule satisfied - a list or table would not communicate this more clearly
• [ ] No linear sequences without branching, relationships, or hierarchy
• [ ] All labels with spaces or special characters are properly quoted
• [ ] Special characters escaped where needed
• [ ] Node/participant count within type-specific limits
• [ ] Colors are accessible (WCAG AA 3:1 contrast minimum, black text on light backgrounds)
• [ ] Color is never the sole differentiator - shapes and labels also distinguish elements
• [ ] Diagram has a descriptive title or surrounding prose context
• [ ] %% comments document any non-obvious layout or grouping choices

References

| File | Purpose | |------|---------| | references/TEMPLATE.md | Diagram planning worksheet - fill out before writing mermaid code | | references/EXAMPLE.md | Worked example: PM creating 4 diagrams for a product launch | | references/diagram-catalog.md | All 15 diagram types: syntax, PM examples, limits, pitfalls | | references/pm-use-cases.md | PM task → diagram type mapping with mini worked examples | | references/syntax-guide.md | Complete syntax validity rules, escaping, styling, and validation checklist |