Mermaid Diagram Skill

Create professional Mermaid diagrams with proper syntax, clear layout, and validated output.

Prerequisites

Required: Mermaid CLI - The mmdc command must be available:

npm install -g @mermaid-js/mermaid-cli

Optional: beautiful-mermaid - For enhanced theming and ASCII output:

cd skills/authoring-mermaid-diagrams/scripts && npm install

This enables 15 built-in themes (tokyo-night, dracula, github-dark, etc.) and text-based diagram rendering for terminals.

Workflow Overview

1. •Choose Diagram Type - Select the appropriate diagram type for your use case
2. •Write Diagram - Use idiomatic patterns and clear naming
3. •Validate Syntax - Run through mmdc to catch spec errors
4. •Render Output - Use beautiful-mermaid for final output (when available)
5. •Visual Review - Check the rendered output for layout issues
6. •Iterate - Refine based on feedback

Diagram Type Selection

For detailed syntax and examples of each type, see references/diagram-types.md.

Idiomatic Patterns

Use Self-Explanatory Node IDs

Good - IDs describe the node:

flowchart LR
    userInput[User Input] --> validation{Valid?}
    validation -->|Yes| processData[Process Data]
    validation -->|No| showError[Show Error]

Bad - Cryptic IDs:

flowchart LR
    A[User Input] --> B{Valid?}
    B -->|Yes| C[Process Data]
    B -->|No| D[Show Error]

Declare Nodes Before Connections

For complex diagrams, declare nodes first, then define connections:

flowchart TD
    %% Node declarations
    start[Start Process]
    validate{Validate Input}
    process[Process Data]
    error[Handle Error]
    done[Complete]

    %% Connections
    start --> validate
    validate -->|Valid| process
    validate -->|Invalid| error
    process --> done
    error --> validate

Use Subgraphs for Logical Grouping

flowchart LR
    subgraph Frontend
        ui[UI Layer]
        state[State Management]
    end

    subgraph Backend
        api[API Server]
        db[(Database)]
    end

    ui --> api
    state --> api
    api --> db

Direction Guidelines

Validation and Rendering Workflow

Step 1: Syntax Validation (mmdc)

Save your diagram to a .mmd file and validate syntax using mmdc:

uv run scripts/validate_mermaid.py diagram.mmd --renderer mmdc -o diagram.svg

The script will report syntax errors with line numbers. Always use mmdc for syntax validation as it is the authoritative Mermaid spec parser.

The validation script uses a default config (scripts/mermaid-config.json) that prevents text clipping by using arial font and increased padding. To use a custom config or disable it:

# Custom config
uv run scripts/validate_mermaid.py diagram.mmd --renderer mmdc -c my-config.json

# No config (use mmdc defaults)
uv run scripts/validate_mermaid.py diagram.mmd --renderer mmdc --no-config

Step 2: Render with beautiful-mermaid (Preferred)

After syntax validation passes, render the final output with beautiful-mermaid for better theming:

uv run scripts/validate_mermaid.py diagram.mmd --renderer beautiful --theme github-light -o diagram.svg

Renderer selection rules:

If beautiful-mermaid is not installed, skip this step and use the mmdc output from Step 1.

Step 3: Visual Quality Review

After syntax validation passes, review the rendered output for:

• • Readability: All text is legible, no overlapping labels
• • Edge Crossings: Minimized (try different direction if excessive)
• • Logical Grouping: Related nodes grouped in subgraphs where beneficial
• • Consistent Shapes: Same node shape for similar concepts
• • Flow Direction: Consistent and intuitive (usually LR for processes, TD for hierarchies)
• • Labels: Edge labels present where needed for clarity
• • Spacing: Nodes not too cramped or too spread out
• • Color Usage: Styling aids understanding, not just decoration

Step 4: Common Fixes

If the diagram renders but looks wrong:

Theming

beautiful-mermaid provides 15 built-in themes for professional diagram styling.

Available Themes

Using Themes

# List available themes
uv run scripts/validate_mermaid.py --list-themes

# Render with a specific theme
uv run scripts/validate_mermaid.py diagram.mmd --theme tokyo-night -o diagram.svg

# Custom colors (overrides theme)
uv run scripts/validate_mermaid.py diagram.mmd --bg "#1a1b26" --fg "#c0caf5" -o diagram.svg

Renderer Selection

Use a two-step approach for best results:

1. •Syntax validation: Always use --renderer mmdc (authoritative Mermaid parser)
2. •Final rendering: Use --renderer beautiful when available and supported

# Step 1: Validate syntax with mmdc
uv run scripts/validate_mermaid.py diagram.mmd --renderer mmdc -o diagram-validated.svg

# Step 2: Render final output with beautiful-mermaid
uv run scripts/validate_mermaid.py diagram.mmd --renderer beautiful --theme github-light -o diagram.svg

Note: For architecture diagrams, skip Step 2 as beautiful-mermaid does not support them.

For comprehensive theming documentation, see references/theming-guide.md.

ASCII Output

beautiful-mermaid can render diagrams as text for terminal environments.

Output Modes

Usage

# Unicode output (recommended)
uv run scripts/validate_mermaid.py diagram.mmd --unicode -o diagram.txt

# ASCII output
uv run scripts/validate_mermaid.py diagram.mmd --ascii -o diagram.txt

# With padding adjustments
uv run scripts/validate_mermaid.py diagram.mmd --unicode --padding-x 2 --padding-y 1 -o diagram.txt

Use Cases

• •Terminal-based documentation viewers
• •Log file embedding
• •Email/plain-text contexts
• •Accessibility (screen readers)
• •CI/CD pipeline output

Limitations

ASCII/Unicode output is only available for diagram types supported by beautiful-mermaid:

• •Flowcharts
• •Sequence diagrams
• •State diagrams
• •Class diagrams
• •ER diagrams

Architecture diagrams are not supported - use SVG output with mmdc instead.

Reference Files

• •references/diagram-types.md - Full syntax and examples for flowcharts, sequence, state, class, ER, and architecture diagrams
• •references/syntax-quick-ref.md - Node shapes, arrow types, styling classes, text formatting, and escape sequences
• •references/layout-patterns.md - Subgraph organization, nesting strategies, and direction optimization
• •references/common-issues.md - Parse errors, reserved words, text clipping fixes, and debugging steps
• •references/theming-guide.md - beautiful-mermaid themes, custom colors, and advanced styling

Example: Complete Workflow

Creating an authentication flow diagram:

1. •

   Choose type: Flowchart (it's a process with decisions)

2. •

   Write diagram:

flowchart TD
    subgraph Client
        request[Login Request]
        storeToken[Store Token]
        retry[Retry Login]
    end

    subgraph AuthServer["Auth Server"]
        validate{Valid Credentials?}
        generateToken[Generate JWT]
        logFailure[Log Failed Attempt]
    end

    request --> validate
    validate -->|Yes| generateToken
    validate -->|No| logFailure
    generateToken --> storeToken
    logFailure --> retry
    retry --> request

1. •Validate syntax (mmdc):

uv run scripts/validate_mermaid.py auth-flow.mmd --renderer mmdc -o auth-flow-check.svg

1. •Render with theme (beautiful-mermaid):

uv run scripts/validate_mermaid.py auth-flow.mmd --renderer beautiful --theme github-dark -o auth-flow.svg

1. •Generate ASCII for docs (optional):

uv run scripts/validate_mermaid.py auth-flow.mmd --renderer beautiful --unicode -o auth-flow.txt

1. •

   Review: Check the SVG output for readability

2. •

   Iterate: Adjust direction, add styling if needed