Mermaid Studio

Mermaid Studio

Expert-level Mermaid diagram creation, validation, and multi-format rendering. Creates diagrams from descriptions or code analysis, validates syntax, and renders to SVG, PNG, or ASCII with professional theming.

Golden Rules — Elegant Diagrams by Default

Every diagram MUST follow these principles. They are not optional — they define the difference between a mediocre diagram and a gold-standard one.

Rule 1: Always Use an Init Directive for Professional Styling

NEVER create a diagram without an %%{init} directive or frontmatter config. The default Mermaid theme produces harsh black lines and generic colors. Always apply a curated palette.

For general diagrams (flowchart, sequence, state, class, ERD):

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#4f46e5', 'primaryTextColor': '#ffffff',
  'primaryBorderColor': '#3730a3', 'lineColor': '#94a3b8',
  'secondaryColor': '#10b981', 'tertiaryColor': '#f59e0b',
  'background': '#ffffff', 'mainBkg': '#f8fafc',
  'nodeBorder': '#cbd5e1', 'clusterBkg': '#f1f5f9',
  'clusterBorder': '#e2e8f0', 'titleColor': '#1e293b',
  'edgeLabelBackground': '#ffffff', 'textColor': '#334155'
}}}%%

⚠️ Font Warning: Do NOT set fontFamily in theme variables. The Mermaid default font (trebuchet ms, verdana, arial, sans-serif) works everywhere. Setting system-ui, Segoe UI, or -apple-system will render as Times New Roman in headless Chromium (used by mmdc).

For C4 diagrams — see the dedicated C4 styling section below.

For architecture-beta diagrams — see the dedicated AWS/Architecture section below.

Rule 2: Soft Lines, Never Harsh Black

The single biggest visual improvement is using lineColor: '#94a3b8' (slate-400) instead of the default black. This creates a modern, breathable diagram. For dark themes, use lineColor: '#64748b' (slate-500).

Rule 3: Limit Density — Breathe

• Maximum 15 nodes per diagram (not 20 — fewer is more elegant)
• Use subgraph or boundaries to create whitespace and visual grouping
• Prefer LR (left-right) for process flows — it reads more naturally
• Use invisible links (A ~~~ B) to add spacing when the layout is cramped

Rule 4: Meaningful Labels and Consistent Style

• Node IDs: camelCase (orderService, not s1 or os)
• Labels: short, clear natural language ([Order Service])
• Arrows: action verbs with protocol info ("Sends order via gRPC")
• Descriptions: one-line, role-focused ("Handles order lifecycle")

Rule 5: Color Harmony Over Color Variety

Use max 3-4 colors per diagram. Map colors to meaning:

• Blue tones (#4f46e5, #3b82f6) → primary systems, internal services
• Green tones (#10b981, #059669) → success states, data stores
• Amber tones (#f59e0b, #d97706) → external systems, warnings
• Slate tones (#64748b, #94a3b8) → lines, borders, secondary elements
• Red tones (#ef4444) → errors ONLY, never as decoration

Modes of Operation

This skill operates in three modes based on user intent:

Default to Full mode when intent is unclear.

Step 1: Understand the Request

Before writing any Mermaid code, determine:

1. What to diagram — system, flow, schema, architecture, code structure?
2. Which diagram type — use the Decision Matrix below
3. Output format — code only, SVG, PNG, or ASCII?
4. Theme preference — ask only if rendering; default to base theme with curated palette

Diagram Type Decision Matrix

If the user's description doesn't clearly map to one type, suggest 2-3 options with a brief rationale for each, then let them choose.

When to Load References

Load reference files ONLY when needed for the specific diagram type:

• C4 diagrams → Read references/c4-architecture.md BEFORE writing code
• AWS/Cloud architecture → Read references/aws-architecture.md BEFORE writing code
• Code-to-diagram → Read references/code-to-diagram.md BEFORE analyzing
• Theming/styling → Read references/themes.md when user requests custom themes
• Syntax errors → Read references/troubleshooting.md when validation fails
• Any diagram type details → Read references/diagram-types.md for comprehensive syntax

Step 2: Create the Diagram

2.1 — Write Mermaid Code

Follow these principles in order of priority:

1. Elegance first — every diagram must look professional with init directives and curated colors
2. Correctness — valid syntax that renders without errors
3. Clarity — meaningful labels, logical flow direction, clear relationships
4. Simplicity — under 15 nodes per diagram; split complex systems into multiple
5. Consistency — uniform naming (camelCase for IDs, descriptive labels in brackets)

2.2 — Structure Rules

%% Diagram: [Purpose] | Author: [auto] | Date: [auto]
%%{init: {'theme': 'base', 'themeVariables': { ... }}}%%
[diagramType]
    [content]

CRITICAL: The %%{init} directive MUST go on the very first non-comment line, BEFORE the diagram type declaration. Alternatively, use YAML frontmatter at the absolute start of the file.

Naming conventions:

• Node IDs: camelCase, descriptive (orderService, not s1)
• Labels: natural language in brackets ([Order Service])
• Relationships: action verbs ("Sends order to", "Reads from")

Layout best practices:

• TD (top-down) for hierarchical flows and processes
• LR (left-right) for timelines, pipelines, and sequential processes
• RL for right-to-left reading contexts
• Use subgraph to group related nodes; name subgraphs meaningfully
• Add direction inside subgraphs when needed for different flow

2.3 — Quick Reference Examples

Flowchart (with professional styling):

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#4f46e5', 'primaryTextColor': '#fff',
  'primaryBorderColor': '#3730a3', 'lineColor': '#94a3b8',
  'secondaryColor': '#10b981', 'tertiaryColor': '#f59e0b',
  'background': '#ffffff', 'mainBkg': '#f8fafc',
  'nodeBorder': '#cbd5e1', 'clusterBkg': '#f1f5f9',
  'clusterBorder': '#e2e8f0', 'titleColor': '#1e293b',
  'edgeLabelBackground': '#ffffff'
}}}%%
flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> End([End])

For sequence diagram and ERD styling examples, read references/themes.md.

C4 Context (with MANDATORY elegant styling):

C4Context
    title System Context — E-Commerce Platform

    Person(customer, "Customer", "Places orders online")
    System(platform, "E-Commerce Platform", "Handles orders and payments")
    System_Ext(payment, "Payment Gateway", "Processes transactions")
    System_Ext(email, "Email Service", "Sends notifications")

    Rel(customer, platform, "Uses", "HTTPS")
    Rel(platform, payment, "Processes payments", "API")
    Rel(platform, email, "Sends emails", "SMTP")

    UpdateRelStyle(customer, platform, $textColor="#475569", $lineColor="#94a3b8")
    UpdateRelStyle(platform, payment, $textColor="#475569", $lineColor="#94a3b8")
    UpdateRelStyle(platform, email, $textColor="#475569", $lineColor="#94a3b8")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Architecture (AWS with Iconify icons):

architecture-beta
    group vpc(logos:aws-vpc)[VPC]

    service api(logos:aws-api-gateway)[API Gateway] in vpc
    service lambda(logos:aws-lambda)[Lambda] in vpc
    service db(logos:aws-dynamodb)[DynamoDB] in vpc
    service s3(logos:aws-s3)[S3 Bucket]

    api:R --> L:lambda
    lambda:R --> L:db
    lambda:B --> T:s3

IMPORTANT: Architecture-beta diagrams with logos:* icons require icon pack registration. When rendering with the render script, use the --icons logos flag. If rendering in a markdown viewer that doesn't support icon packs, use the built-in icons (cloud, database, disk, server, internet) as fallback. Read references/aws-architecture.md for the complete icon catalog and rendering instructions.

For comprehensive syntax of ALL diagram types, read references/diagram-types.md.