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

For worked examples organized by PM task, see

references/pm-use-cases.md

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

references/TEMPLATE.md

references/EXAMPLE.md

references/diagram-catalog.md

references/pm-use-cases.md

references/syntax-guide.md