beautiful-mermaid is an open-source library designed to render Mermaid diagrams as aesthetically pleasing SVGs or ASCII art. Developed by Craft, it addresses limitations of the default Mermaid renderer, such as aesthetics, complex theming, lack of terminal output, and heavy dependencies, particularly for use in AI-assisted programming environments and CLI tools.

The library offers dual output capabilities: SVG for rich user interfaces and ASCII/Unicode for terminal environments, providing ultra-fast rendering (over 100 diagrams in under 500ms) with zero DOM dependencies, making it suitable for various platforms. It supports five core diagram types: Flowcharts, State Diagrams, Sequence Diagrams, Class Diagrams, and ER Diagrams.

The core methodology of beautiful-mermaid revolves around a sophisticated yet flexible theming system. It is built on a "Two-Color Foundation" in what is termed "Mono Mode." In this mode, only two fundamental colors are required: bg (background) and fg (foreground). All other diagram element colors are automatically derived from these two using CSS's color-mix() function. For instance:

• Text: fg at 100%
• Secondary text: fg at 60% mixed into bg
• Edge labels: fg at 40% mixed into bg
• Connectors: fg at 30% mixed into bg
• Arrow heads: fg at 50% mixed into bg
• Node fill: fg at 3% mixed into bg
• Node stroke: fg at 20% mixed into bg

For richer themes, an "Enriched Mode" allows users to provide optional override colors for specific diagram roles. These enrichment colors include line (edge/connector), accent (arrow heads, highlights), muted (secondary text, labels), surface (node fill), and border (node stroke). If an enrichment color is not provided, the system gracefully falls back to the color-mix() derivation from bg and fg.

A key architectural feature of the theming system is its reliance on CSS custom properties (CSS variables). All colors are exposed as CSS variables on the SVG element (e.g., --bg, --fg). This enables dynamic, live theme switching without requiring re-rendering of the SVG; simply updating the CSS variables on the SVG element will instantly update the diagram's appearance. The library ships with 15 built-in themes, which can be accessed via THEMES object, or users can define custom themes by providing bg, fg, and optional enrichment colors.

For advanced theming, beautiful-mermaid offers full compatibility with Shiki, a syntax highlighter built on VS Code themes. The fromShikiTheme() function allows direct extraction of diagram colors from any Shiki theme object. This function intelligently maps VS Code editor theme properties to diagram roles:

• editor.background $\rightarrow$ bg
• editor.foreground $\rightarrow$ fg
• editorLineNumber.foreground $\rightarrow$ line
• focusBorder / keyword token $\rightarrow$ accent
• comment token $\rightarrow$ muted
• editor.selectionBackground $\rightarrow$ surface
• editorWidget.border $\rightarrow$ border

The library provides two primary rendering functions:

1. renderMermaid(text, options?): An asynchronous function that takes Mermaid source code and optional RenderOptions (including bg, fg, and enrichment colors, font, transparent background) to produce an SVG string.
2. renderMermaidAscii(text, options?): A synchronous function that renders Mermaid source code to ASCII or Unicode text. This engine is based on mermaid-ascii by Alexander Grooff, ported from Go to TypeScript and extended with support for Sequence, Class, and ER diagrams, Unicode box-drawing characters, and configurable spacing. AsciiRenderOptions include useAscii (boolean, true for pure ASCII, false for Unicode), paddingX, paddingY (horizontal/vertical node spacing), and boxBorderPadding (inner padding within node boxes).

The library is distributed via npm, bun, and pnpm, and also available for browser environments via CDN script tags, exposing renderMermaid, renderMermaidAscii, THEMES, DEFAULTS, and fromShikiTheme on the global beautifulMermaid object.