Mermaid Diagrams

Background knowledge for producing clean, readable, print-ready Mermaid diagrams. This skill provides the craft -- the visualize skill provides the workflow.

Scope: Mermaid is the engine for all non-mind-map diagram types. Mind maps auto-route to Markmap via the visualize skill. Users can override to Mermaid for mind maps if they prefer themed presets over Markmap's visual quality.

Curated visual identity: All diagrams use one of three preset configs. Each preset pairs a theme, look mode, and layout engine. See default-theme.md for the full specification.

Quick Start

Minimal correct diagram (Classic preset, the default):

flowchart LR
    classDef primary fill:#0072B2,color:#fff,stroke:#005a8c,stroke-width:2px
    classDef success fill:#009E73,color:#fff,stroke:#006B4F,stroke-width:2px
    classDef warning fill:#E69F00,color:#000,stroke:#B37A00,stroke-width:2px

    A[Input]:::primary --> B{Valid?}:::warning
    B -->|Yes| C[Process]:::primary
    B -->|No| D[Error]:::warning
    C --> E[Done]:::success

Export with Classic preset (default):

bunx @mermaid-js/mermaid-cli -i input.mmd -o output.svg \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white

Core Principles

Non-negotiable rules for every diagram:

1. Max 15 nodes per diagram. Split into multiple diagrams if larger.
2. Max 3 shapes per diagram. More shapes become visual noise.
3. Use classDef, not inline styles. Keeps diagrams consistent and maintainable.
4. Use a preset config via -c flag for all visualize-skill output. Never put %%{init:}%% directives in generated diagrams -- the config file handles theming. Three presets: default-theme.json (Classic), sketch-theme.json (Sketch), blueprint-theme.json (Blueprint).

Diagram Type Selection

Pick the right diagram for the job. Default to the simplest type that communicates the idea.

Decision heuristic: If you're unsure, start with flowchart TD. It handles 70% of use cases. Upgrade to a specialized type only when the data demands it.

Core Styling Principles

1. Readability first

• Max 15 nodes per diagram. Split into multiple diagrams if larger.
• Max 3-5 main branches for mind maps.
• Keep node labels under 30 characters. Use abbreviations + a legend if needed.
• Prefer <br/> over backtick markdown-string syntax for line breaks -- backtick labels cause dagre layout cramping with 10+ nodes.
• Max 2 lines per node label. Move detail to edge labels, legends, or index.md.
• One concept per node. Never combine two ideas.

2. Direction matters

3. Grouping with subgraphs

Use subgraph to visually cluster related nodes. Label every subgraph. Keep nesting to 2 levels max -- deeper nesting kills readability at print scale.

subgraph "API Layer"
    A[REST Controller] --> B[Service]
    B --> C[Repository]
end

4. Edge labels

Label every edge that isn't self-explanatory. Use -->|label| syntax. Keep labels to 1-3 words.

Theme Configuration

Init directive

Place at the top of any diagram to configure theme and variables:

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A --> B

Built-in themes

Use base with default-theme.json for all visualize skill output. The neutral theme silently ignores themeVariables (GitHub #4264), so base is the only option for custom palettes.

Custom theme variables

Override specific colors via themeVariables in the init directive:

%%{init: {'theme': 'base', 'themeVariables': {
    'primaryColor': '#4a90d9',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#2c5f8a',
    'lineColor': '#333333',
    'secondaryColor': '#f0f4f8',
    'tertiaryColor': '#e8e8e8',
    'fontSize': '16px'
}}}%%

Important: Mermaid only recognizes hex colors (#4a90d9), not color names (blue).

Node Shapes

Flowcharts support many shapes. Use them semantically:

Rule of thumb: Use max 3 different shapes per diagram. More than that and the visual language becomes noise.

Print-Safe Color Palette

When color is needed on print diagrams, use this accessible palette. Based on the Wong palette (Nature Methods, 2011) -- the standard for colorblind-safe scientific visualization. All colors maintain WCAG AA contrast against white.

The full classDef block is in default-theme.md. Apply with ::::

classDef primary fill:#0072B2,color:#fff,stroke:#005a8c
classDef secondary fill:#009E73,color:#fff,stroke:#007a5a
classDef accent fill:#E69F00,color:#000,stroke:#b87d00

A[Start]:::primary --> B{Check}:::accent
B -->|Pass| C[Done]:::secondary

Font Sizing for Print

These minimums ensure readability at 1-2 meters viewing distance on A3/A2 paper:

Set via init directive:

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '16px'}}}%%

Export with mmdc CLI

The @mermaid-js/mermaid-cli (mmdc) is the primary export path. Use with -c <preset>-theme.json for the curated visual identity. The MCP server's export_diagram_formats produces placeholder files -- do not use it for export.

Basic export

bunx @mermaid-js/mermaid-cli -i input.mmd -o output.svg \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white

Key flags

Print-ready export

# A4 landscape SVG (default)
bunx @mermaid-js/mermaid-cli -i input.mmd -o diagram.svg \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white -w 3508 -H 2480

# A3 landscape SVG (wall poster)
bunx @mermaid-js/mermaid-cli -i input.mmd -o diagram.svg \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white -w 4961 -H 3508

# PDF for direct printing (add --pdfFit)
bunx @mermaid-js/mermaid-cli -i input.mmd -o diagram.pdf \
  -c "$CLAUDE_PLUGIN_ROOT/skills/mermaid-diagrams/references/default-theme.json" \
  -b white -w 3508 -H 2480 --pdfFit

A4 landscape = 3508 x 2480px at 300 DPI. A3 landscape = 4961 x 3508px.

Quality Checklist

Verify before finalizing any diagram:

• Max 15 nodes
• Labels under 30 characters
• Node labels max 2 lines, using <br/> (not backtick syntax)
• Max 3 different shapes
• All non-obvious edges labeled
• Subgraph nesting max 2 levels
• Font size >= 14pt for nodes
• Color + shape together (not color alone)
• No %%{init:}%% in visualize-skill output

Anti-Patterns

Done When

The diagram is complete when every item in the Quality Checklist above passes and the exported file (SVG/PDF/PNG) renders correctly at the target paper size.

Reference Files

For comprehensive details, see:

• default-theme.md - Curated visual identity, preset classDef blocks, type detection, export commands
• default-theme.json - Classic preset config (pass via -c)
• sketch-theme.json - Sketch preset config (hand-drawn, warm tones)
• blueprint-theme.json - Blueprint preset config (monochrome, ELK layout)
• syntax-reference.md - Full syntax for all diagram types
• styling-patterns.md - Themes, classDef, custom variables
• print-optimization.md - Paper sizes, mmdc CLI, export recipes
• config-engineering.md - Config tuning, layout workarounds, known Mermaid bugs