szoloth/skills/beautiful-mermaid

Beautiful Mermaid Skill

Render Mermaid diagrams as beautiful SVGs or ASCII art. Ultra-fast, fully themeable, zero DOM dependencies.

Triggers

Use this skill when:

• Creating any diagram, flowchart, or visualization
• Explaining architecture, workflows, or data flows visually
• User asks to "draw", "diagram", "visualize", or "show me" a process
• Documenting system designs, state machines, or entity relationships
• Adding diagrams to documentation, PRDs, or technical specs
• Need ASCII diagrams for terminal, CLI, or plain-text output
• Want themed or styled diagram output
• Mentions Mermaid, flowchart, sequence diagram, class diagram, ER diagram, state diagram

Installation

npm install beautiful-mermaid
# or
bun add beautiful-mermaid
# or
pnpm add beautiful-mermaid

Dependencies: Only @dagrejs/dagre for layout. No DOM required.

Quick Start

SVG Output

import { renderMermaid } from 'beautiful-mermaid'

const svg = await renderMermaid(`
  graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
`)

ASCII Output

import { renderMermaidAscii } from 'beautiful-mermaid'

const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)

// Output:
// ┌───┐     ┌───┐     ┌───┐
// │   │     │   │     │   │
// │ A │────►│ B │────►│ C │
// │   │     │   │     │   │
// └───┘     └───┘     └───┘

Supported Diagram Types

| Type | Header | Features | |------|--------|----------| | Flowchart | graph TD/LR/BT/RL | All directions, subgraphs, shapes | | State | stateDiagram-v2 | States, transitions, nested states | | Sequence | sequenceDiagram | Participants, messages, notes | | Class | classDiagram | Classes, methods, relationships | | ER | erDiagram | Entities, relationships, cardinality |

Theming System

The theming system is the heart of beautiful-mermaid. It uses CSS custom properties for instant theme switching.

Two-Color Foundation (Mono Mode)

Every diagram needs just two colors: bg (background) and fg (foreground):

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',  // Background
  fg: '#a9b1d6',  // Foreground
})

All other elements are automatically derived using color-mix():

| Element | Derivation | |---------|------------| | Text | --fg at 100% | | Secondary text | --fg at 60% into --bg | | Edge labels | --fg at 40% into --bg | | Connectors | --fg at 30% into --bg | | Arrow heads | --fg at 50% into --bg | | Node fill | --fg at 3% into --bg | | Node stroke | --fg at 20% into --bg |

Enriched Mode

For richer themes, provide optional enrichment colors:

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',
  fg: '#a9b1d6',
  // Optional enrichment:
  line: '#3d59a1',    // Edge/connector color
  accent: '#7aa2f7',  // Arrow heads, highlights
  muted: '#565f89',   // Secondary text, labels
  surface: '#292e42', // Node fill tint
  border: '#3d59a1',  // Node stroke
})

Live Theme Switching

Colors are CSS custom properties - switch themes instantly without re-rendering:

// In the browser, update the SVG's CSS variables
svgElement.style.setProperty('--bg', '#282a36')
svgElement.style.setProperty('--fg', '#f8f8f2')
// The entire diagram updates immediately

Built-in Themes (15 total)

import { renderMermaid, THEMES } from 'beautiful-mermaid'

const svg = await renderMermaid(diagram, THEMES['tokyo-night'])

Available themes:

• zinc-light, zinc-dark
• tokyo-night, tokyo-night-storm, tokyo-night-light
• catppuccin-mocha, catppuccin-latte
• nord, nord-light
• dracula
• github-light, github-dark
• solarized-light, solarized-dark
• one-dark

Custom Theme: samzoloth

Based on samzoloth.com - warm cream background with sage green accents:

const SAMZOLOTH = {
  bg: '#FAF9F6',      // Warm cream background
  fg: '#18181B',      // Near-black text (darker for contrast)
  accent: '#4A6741',  // Sage green (metric highlights)
  line: '#4A6741',    // Sage green for edges too
  muted: '#71717A',   // Zinc-500 for secondary text
  surface: '#FFFFFF', // White card surfaces
  border: '#D4D4D8',  // Zinc-300 for borders
}

// Usage
const svg = await renderMermaid(diagram, SAMZOLOTH)

Color reference from the site:

• Background: #FAF9F6 (warm cream)
• Heading text: #18181B (zinc-900)
• Accent metrics: #4A6741 (sage green - "60 seconds", "30 Days")
• Body text: #3F3F46 (zinc-700)
• Muted text: #71717A (zinc-500)

Shiki Theme Compatibility

Use any VS Code theme directly via Shiki:

import { getSingletonHighlighter } from 'shiki'
import { renderMermaid, fromShikiTheme } from 'beautiful-mermaid'

const highlighter = await getSingletonHighlighter({
  themes: ['vitesse-dark', 'rose-pine']
})

const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark'))
const svg = await renderMermaid(diagram, colors)

API Reference

renderMermaid(text, options?): Promise<string>

Render Mermaid diagram to SVG. Auto-detects diagram type.

RenderOptions:

| Option | Type | Default | Description | |--------|------|---------|-------------| | bg | string | #FFFFFF | Background color | | fg | string | #27272A | Foreground color | | line | string? | — | Edge/connector color | | accent | string? | — | Arrow heads, highlights | | muted | string? | — | Secondary text, labels | | surface | string? | — | Node fill tint | | border | string? | — | Node stroke color | | font | string | Inter | Font family | | transparent | boolean | false | Transparent background |

renderMermaidAscii(text, options?): string

Render Mermaid diagram to ASCII/Unicode text. Synchronous.

AsciiRenderOptions:

| Option | Type | Default | Description | |--------|------|---------|-------------| | useAscii | boolean | false | Use ASCII instead of Unicode | | paddingX | number | 5 | Horizontal node spacing | | paddingY | number | 5 | Vertical node spacing | | boxBorderPadding | number | 1 | Inner box padding |

fromShikiTheme(theme): DiagramColors

Extract diagram colors from a Shiki theme object.

THEMES: Record<string, DiagramColors>

Object containing all 15 built-in themes.

DEFAULTS: { bg: string, fg: string }

Default colors (#FFFFFF / #27272A).

Usage Examples

Flowchart with Custom Theme

const svg = await renderMermaid(`
  graph TD
    A[User Request] --> B{Valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
    C --> E[Response]
    D --> E
`, THEMES['dracula'])

Sequence Diagram

const svg = await renderMermaid(`
  sequenceDiagram
    Alice->>Bob: Hello Bob!
    Bob-->>Alice: Hi Alice!
    Alice->>Bob: How are you?
    Bob-->>Alice: Great, thanks!
`, { bg: '#0d1117', fg: '#e6edf3', accent: '#4493f8' })

Class Diagram

const svg = await renderMermaid(`
  classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal: +int age
    Animal: +String gender
    Animal: +isMammal() bool
    Duck: +String beakColor
    Duck: +swim()
    Duck: +quack()
`)

ER Diagram

const svg = await renderMermaid(`
  erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "is in"
`)

ASCII for Terminal Output

// Unicode mode (default) - prettier box drawing
const unicode = renderMermaidAscii(`graph LR; A --> B`)

// Pure ASCII mode - maximum compatibility
const ascii = renderMermaidAscii(`graph LR; A --> B`, { useAscii: true })

// ASCII output:
// +---+     +---+
// |   |     |   |
// | A |---->| B |
// |   |     |   |
// +---+     +---+

Transparent Background

const svg = await renderMermaid(diagram, {
  ...THEMES['tokyo-night'],
  transparent: true
})

Integration Patterns

React Component

For React integration, parse the SVG string and insert safely:

import { renderMermaid, THEMES, ThemeName } from 'beautiful-mermaid'
import { useState, useEffect, useRef } from 'react'
import DOMPurify from 'dompurify'

interface MermaidDiagramProps {
  code: string
  theme?: ThemeName
}

function MermaidDiagram({ code, theme = 'github-light' }: MermaidDiagramProps) {
  const containerRef = useRef<HTMLDivElement>(null)
  
  useEffect(() => {
    async function render() {
      const svgString = await renderMermaid(code, THEMES[theme])
      if (containerRef.current) {
        // Use DOMPurify to sanitize SVG before DOM insertion
        const sanitized = DOMPurify.sanitize(svgString, { USE_PROFILES: { svg: true } })
        const parser = new DOMParser()
        const doc = parser.parseFromString(sanitized, 'image/svg+xml')
        const svgElement = doc.documentElement
        containerRef.current.replaceChildren(svgElement)
      }
    }
    render()
  }, [code, theme])
  
  return <div ref={containerRef} />
}

CLI Tool

import { renderMermaidAscii } from 'beautiful-mermaid'

const diagram = `
graph LR
  A[Input] --> B[Process] --> C[Output]
`

console.log(renderMermaidAscii(diagram))

Server-Side Rendering

import { renderMermaid, THEMES } from 'beautiful-mermaid'
import { writeFileSync } from 'fs'

async function generateDiagram(code: string, outputPath: string) {
  const svg = await renderMermaid(code, THEMES['zinc-dark'])
  writeFileSync(outputPath, svg)
}

Browser Script Tag

<script type="module">
  import { renderMermaid, THEMES } from 'beautiful-mermaid'
  
  const svg = await renderMermaid('graph TD; A --> B', THEMES['dracula'])
  // Insert into DOM using your framework's safe methods
</script>

Performance

• Ultra-fast: Renders 100+ diagrams in under 500ms
• Zero DOM: Pure TypeScript, works in Node.js, Bun, Deno, browser
• Small bundle: Only dagre as dependency
• Synchronous ASCII: No async overhead for terminal output

Architecture Notes

The library uses a modular pipeline:

1. Parser: Converts Mermaid text to AST (detects diagram type)
2. Layout: Uses dagre for graph layout (async)
3. Renderer: Generates SVG with CSS custom properties
4. Theme: Derives all colors from --bg and --fg via color-mix()

ASCII rendering follows a similar pipeline but uses A* pathfinding for edges and grid-based layout.

Credits

ASCII rendering engine based on mermaid-ascii by Alexander Grooff (ported from Go to TypeScript).

References

• GitHub Repository
• Live Demo
• Mermaid Documentation