# Mermaid Conventions

> Conventions for creating consistent Mermaid diagrams including decision node layout, edge ordering, and flowchart direction rules.

- Skill: `vamseeachanta/mermaid-conventions-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vamseeachanta/mermaid-conventions-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamseeachanta/mermaid-conventions-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: vamseeachanta (https://skillmd.com/u/vamseeachanta)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamseeachanta/mermaid-conventions-2

---


# 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.

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

```mermaid
%% 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.

```mermaid
%% 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:
1. Inputs/sources first (e.g., "Users", "Engineer Laptops")
2. Processing/infrastructure middle (e.g., "Network", "Servers")
3. 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

## Sanitized Process Records

When converting chat-derived guidance into repo-maintained Mermaid artifacts, create a sanitized Markdown record rather than only returning the diagram in chat. Include frontmatter, a record log, one Mermaid block per process, a compact data-to-track table, assumptions/sensitivity notes, and an index/README link for discoverability. Avoid raw chat, personal identifiers, and high-sensitivity details; use role labels and concise operational summaries.

See `references/sanitized-process-flowchart-records.md` for the reusable record shape and template.

## 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