Mermaid Diagram Conventions Skill

Mermaid Diagram Conventions

Decision Node Layout (Flowcharts)

When creating mermaid flowcharts with decision nodes ({}), follow these rules for edge ordering:

Rule 1: Yes/positive path goes LEFT (list first)

The first edge from a decision node renders to the left in top-down (TD) flowcharts. Always list the positive/affirmative/happy-path edge first.

%% CORRECT: Yes listed first → renders left (prominent)
flowchart TD
    A{Ready?}
    A -- Yes --> B[Proceed]
    A -- No --> C[Wait]

%% WRONG: No listed first → renders left (confusing)
flowchart TD
    A{Ready?}
    A -- No --> C[Wait]
    A -- Yes --> B[Proceed]

Rule 2: Happy path stays in the main vertical flow

The positive/expected path should continue straight down the main trunk of the diagram. Error handling, fallbacks, and edge cases should branch off to the side.

%% CORRECT: Happy path flows straight down
flowchart TD
    A[Start] --> B{Valid?}
    B -- Yes --> C[Process]
    B -- No --> D[Show error]
    C --> E[Done]

Rule 3: Negative/discouraging behavior appears later in hierarchy

Place blocking, error, and "don't do this" paths lower in the visual hierarchy:

Positive outcomes are rendered first (visually prominent, left side)
Negative outcomes are rendered second (visually subordinate, right side)
Dead-ends and error states appear at the leaves, not near the root

Rule 4: Edge ordering determines position

In mermaid, the order you list edges from a node controls layout:

First edge → left (TD) or top (LR)
Second edge → right (TD) or bottom (LR)

Use this to control which path gets visual prominence.

Subgraph Ordering

List subgraphs in logical reading order:

Inputs/sources first (e.g., "Users", "Engineer Laptops")
Processing/infrastructure middle (e.g., "Network", "Servers")
Outputs/results last (e.g., "License Servers", "Results")

Connection Styles

Use connection styles to convey meaning:

--> solid arrow: active/primary connection
-.-> dotted arrow: blocked/inactive/secondary connection
-.- dotted line (no arrow): association/relationship (not a flow)
--- solid line (no arrow): strong association

PDF Rendering

When documents will be converted to PDF:

Mermaid blocks render via mermaid.ink API as PNG images
Keep diagrams simple enough to be readable at A4 scale
Use generate_pdfs.py in the admin directory to regenerate PDFs after mermaid changes
The script includes retry logic for mermaid.ink rate limits

Checklist

Before committing a mermaid diagram:

[ ] Yes/positive edges listed before No/negative edges at every decision node
[ ] Happy path flows straight down the main trunk
[ ] Error/blocking states branch to the side
[ ] Subgraphs in logical reading order
[ ] Connection styles match the relationship type
[ ] Diagram readable at A4 print size

Agent Skills: Mermaid Diagram Conventions

Install this agent skill to your local

Skill Files