beautiful-mermaid徹底解説：Craft製TypeScriptで美しい図を瞬時に描画

この記事では開発者ドキュメントやAIチャットUIに組み込むMermaidレンダラとして、Craft社製のbeautiful-mermaidを掘り下げます。AI時代の自動化ツール全体像は AI自動化ツール｜ノーコードからコードまで2026年版の比較と選び方 をご覧ください。

1. beautiful-mermaidとは：AI時代に再設計されたMermaidレンダラ

beautiful-mermaidは、Craft社が自社のAIプロダクト「Craft Agents」のために再設計したMermaidレンダラで、GitHubで10,920スターを集めるMITライセンスのTypeScriptライブラリだ（2026-08-21実測。本記事初出時は9,041スター）。READMEには「Render Mermaid diagrams as beautiful SVGs or ASCII art」「Built for the AI era」と明記されており、LLMが生成したMermaidソースをリッチUIや端末で即座に描画する用途を主目的にしている。

公式のmermaid.jsは2014年から続く老舗だが、ブラウザDOMに依存し描画は非同期、テーマ調整にCSSクラスとの格闘が必要だった。beautiful-mermaidはこの3つを根本から覆すために、ゼロから書き起こされている。

開発元のCraft社はNotion風のドキュメントエディタ「Craft」を提供する企業で、AIアシスタント「Craft Agents」ではドキュメント上で対話的にダイアグラムを生成する機能がコア体験となっている。LLMが返したMermaidテキストを、フォントの読み込みや再描画フラッシュなしで即座に表示する必要があり、その要件から本ライブラリが生まれた。

1.1 公式版mermaid.jsの不満点

READMEの「Why We Built This」セクションでは、公式版に対する不満が4点列挙されている。第一に「美的感覚」だ。配色・余白・矢印の終端が、現代的なドキュメントツールが目指す洗練された見た目から離れているという主張だ。

第二は「複雑なテーマ調整」。色を変えるためにCSSクラスをひとつずつ書き換える必要があり、デザインシステムに統合しにくい。第三が「ターミナル出力の欠如」、第四が「依存の重さ」だ。

beautiful-mermaidは「2色のCSS変数で配色を派生」「ASCII出力標準対応」「DOM依存ゼロ」「ELK.jsだけを依存に持つ軽量実装」でこの4点に応えている。

1.2 リポジトリの規模感

GitHubスターは10,920件（2026-08-21実測。初出時は9,041件）、ライセンスはMIT、主要言語はTypeScriptだ。リポジトリ作成は2026-01-28、npm上ではbeautiful-mermaidとして配布され、最新はv1.1.3（2026-02-26公開）。mermaid-asciiのTypeScript移植部分が含まれるため、Goコードの読み解きと再実装が伴う相応の工数が投じられている。

2. なぜ「美しい」のか：2色から派生する配色設計

beautiful-mermaidの中核は「Two-Color Foundation」と呼ばれる配色設計だ。これがREADMEで最も丁寧に説明されているセクションでもある。

2.1 Mono Modeの仕組み

すべての図はbg（背景色）とfg（前景色）の2色を渡せば成立する。ノード塗り・ストローク・テキスト・矢印・グループヘッダの色は、CSS color-mix()を使って自動的に派生する。

READMEには派生ルールの表があり、たとえばノード塗りは「fgを3%だけbgに混ぜた色」、ノードのストロークは「fgを20%だけbgに混ぜた色」と決まっている。エッジラベルは40%、矢印ヘッドは85%といった具合に、要素ごとに混合比が固定されている。

この設計の意義は「2色決めれば終わる」点だ。デザイナーが時間を割いて10色をきめ細かく決める必要がなくなり、ダークモード・ライトモード・コーポレートカラーへの追従が劇的に楽になる。

2.2 Enriched Mode：必要な色だけ上書きする

Mono Modeで十分でない場合は、accent（強調色）・muted（くすんだ色）・line（エッジ色）・surface（ノード塗り）・border（ノードストローク）の5色をピンポイントで上書きできる。

import { renderMermaidSVG } from 'beautiful-mermaid'

const svg = renderMermaidSVG(diagram, {
  bg: '#1a1b26',
  fg: '#a9b1d6',
  line: '#3d59a1',
  accent: '#7aa2f7',
  muted: '#565f89',
  surface: '#292e42',
  border: '#3d59a1',
})

省略した色は自動的にcolor-mix()の派生値にフォールバックする。Tokyo Nightのような既製テーマを正確に再現したい時は全色指定、社内デザインシステムの基本色だけ反映したい時は2色だけ指定、と用途に応じて段階的に色数を増やせる。

2.3 CSS変数化によるライブテーマ切替

派生した配色はすべて<svg>要素のCSSカスタムプロパティとして埋め込まれる。--bgや--fgを書き換えるだけで、図全体の見た目が即座に切り替わる。再描画もJSの実行も不要だ。

Reactアプリでは、レンダリング時にvar(--background)のようなCSS変数参照を渡しておけば、ホストアプリのテーマカスケードがそのまま図にも届く。ダークモードトグルで全コンポーネントが切り替わるのと完全に同じ仕組みでMermaid図も連動する。

3. アーキテクチャ：DOM非依存の純粋関数として動く

beautiful-mermaidは公式版とまったく違うアーキテクチャを採用している。ELK.jsレイアウトとmermaid-asciiのTypeScript移植を土台に、純粋関数として図を生成する設計だ。

3.1 ELK.jsをFakeWorkerで同期実行

レイアウトエンジンとして採用しているELK.jsは、本来Web Workerでの非同期実行を前提とする実装だ。beautiful-mermaidは「FakeWorker」と呼ぶ独自のシムでこれを同期実行する仕組みを組み込んでいる。

これによりrenderMermaidSVG()は同期関数として動作する。Reactで言えばuseEffectを使わずにuseMemoの中だけで完結する。awaitもPromiseも不要だ。

＜悪い例＞ 公式版mermaid.jsは初期化が非同期で、ReactではuseEffect内でmermaid.render()をawaitし、描画完了までプレースホルダー表示が必要だった。

＜改善例＞ beautiful-mermaidはuseMemoの中で同期的にrenderMermaidSVGを呼び、SVG文字列をそのままdangerouslySetInnerHTMLに渡せる。フラッシュなし、ローディングUIなし。

3.2 mermaid-asciiのTS移植

ASCII出力はAlexander Grooff氏のGo製プロジェクトmermaid-asciiをTypeScriptに移植して実現している。READMEのAttributionセクションに明記されており、本家から移植したうえで、シーケンス図・クラス図・ER図のサポートとUnicode box-drawing文字、設定可能なpadding/spacingを追加した。

ターミナル環境でMermaidを表示できる実装は世界的にも珍しく、beautiful-mermaidが「AI era」を冠する根拠の一部にもなっている。CLIのAIアシスタント、SSH越しのログ表示、メール本文、Slackのcode block——リッチ表示できない場面でも、図の意図が伝わる。

3.3 純粋関数とテスト容易性

beautiful-mermaidはレンダリング処理が純粋関数として設計されている。グローバルステート・ブラウザAPI・ファイルシステムへの依存がなく、入力が同じなら常に同じ出力が返る。

これによりVitest・Jest・Bunのテストでexpect(renderMermaidSVG(code)).toMatchSnapshot()のようにスナップショットテストが書ける。CIで図のリグレッションテストを回す運用が現実的になる。

4. 対応6図種：何が描けて何が描けないか

beautiful-mermaidは公式版mermaidの全図種をカバーするわけではない。READMEのSupported Diagramsセクションに6種が明記されている。

4.1 移行可否の判断

エンジニアリングドキュメント、APIシーケンス、システム構成図、状態機械、DBスキーマが中心ならbeautiful-mermaidに今すぐ移行できる。逆にプロダクトロードマップ（Gantt）、ナレッジマップ（Mindmap）、git運用説明（Git Graph）を多用するチームは公式版を使い続ける必要がある。

ただしbeautiful-mermaidはバージョン2026.x時点で対応図種を増やしている最中で、今後Mindmapなどが追加される可能性は高い。Issueをウォッチしつつ、移行可能な記事から順次置き換える運用が現実的だ。

4.2 XY Chartの仕上がりが秀逸

XY Chart（棒・折れ線・混合グラフ）は公式版ではまだbeta扱いで、レイアウトが粗い。beautiful-mermaidはApple・Craft風のミニマルデザインに振っており、ドット格子背景・角丸バー・スプライン補間・落ち影・タッチで反応するツールチップを標準装備する。

const chart = renderMermaidSVG(`
xychart-beta
    title "Monthly Revenue"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Revenue ($K)" 0 --> 500
    bar [180, 250, 310, 280, 350, 420]
    line [200, 240, 290, 310, 360, 410]
`, { ...THEMES['tokyo-night'], interactive: true })

社内ダッシュボードのスパークラインや、note記事に貼り付ける数値グラフがこれ1つで完結する。Recharts/Visx/Plotly等の重量級ライブラリを引き込まずに済む点も評価できる。

5. React統合：useMemoで初回フラッシュゼロ

beautiful-mermaidの真価が最も効いてくるのはReact統合だ。READMEのReact Integrationセクションに掲載されているサンプルコードは、本ライブラリの設計思想を凝縮している。

import { renderMermaidSVG } from 'beautiful-mermaid'

function MermaidDiagram({ code }: { code: string }) {
  const { svg, error } = React.useMemo(() => {
    try {
      return {
        svg: renderMermaidSVG(code, {
          bg: 'var(--background)',
          fg: 'var(--foreground)',
          transparent: true,
        }),
        error: null,
      }
    } catch (err) {
      return { svg: null, error: err instanceof Error ? err : new Error(String(err)) }
    }
  }, [code])

  if (error) return <pre>{error.message}</pre>
  return <div dangerouslySetInnerHTML={{ __html: svg! }} />
}

5.1 初回フラッシュが消える3つの理由

第一に同期API。SVG文字列はuseMemoの評価中に確定するため、初回レンダリング時点で既にDOMに挿入できる。useEffect内の非同期描画とは違い、ローディングUIが必要ない。

第二にCSS変数。色をvar(--background)のように指定すれば、SVG内の<style>に固有色がハードコードされない。テーマ切替で再描画せずに済む。

第三にメモ化。codeプロップが変わったときだけ再評価されるため、親コンポーネントの不要な再描画でMermaidパースが走ることがない。ストリーミング応答で1文字ずつ表示される場合でも、codeが完全に揃ってからレンダリングする戦略が取れる。

5.2 Cloudflare WorkersでのSSR描画

DOM非依存設計の恩恵で、Cloudflare Workers・Vercel Edge・Deno Deploy・Bunのようなサーバーレス環境でもそのまま動作する。SSR時にbeautiful-mermaidでSVGを生成してHTMLに埋め込んでおけば、JSが完全ロードする前から図が表示される。

export default {
  async fetch(request: Request): Promise<Response> {
    const code = 'graph LR; A --> B --> C'
    const svg = renderMermaidSVG(code, { bg: '#fff', fg: '#222' })
    return new Response(`<!DOCTYPE html><html><body>${svg}</body></html>`, {
      headers: { 'content-type': 'text/html' },
    })
  },
}

公式版mermaid.jsはJSDOMをサーバーに持ち込む必要があったため、エッジ環境では実質動かなかった。beautiful-mermaidはこの制約を完全に取り払い、サーバー描画とクライアント描画を完全に統一できる。

6. Shikiテーマ互換：VS Codeテーマがそのまま使える

beautiful-mermaidはShiki（Markedで人気のコードハイライタ）との連携を公式に支援する。fromShikiTheme()関数1つで、Shikiが配布する数百のVS Codeテーマからダイアグラム配色を自動抽出できる。

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

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

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

fromShikiThemeはVS Codeのcolor token名から、ダイアグラムの役割への自動マッピングを行う。editor.backgroundはbgへ、editor.foregroundはfgへ、editorLineNumber.foregroundはlineへ、focusBorderまたはkeywordトークンはaccentへ、コメントトークンはmutedへ、というように、エディタの配色思想がそのまま図にも反映される。

6.1 ドキュメントとコードの配色を統一する

技術ブログやエンジニアリングドキュメントでは、シンタックスハイライトの配色と図の配色が揃っていると視覚的な統一感が出る。beautiful-mermaid + Shikiの組合せは、これを「同じテーマ名を指定するだけ」で達成する。

組み込みテーマは15種類で、Tokyo Night・Catppuccin・Nord・Dracula・Solarized・GitHubといった主要テーマがすべてカバーされている。

6.2 linkStyleによるエッジ単位の色制御

beautiful-mermaidは公式版と同じlinkStyle構文に対応する。エッジ単位の色制御をMermaidソース上から行える。

graph TD
  A --> B --> C
  linkStyle 0 stroke:#ff0000,stroke-width:2px
  linkStyle default stroke:#888888

エラーパス・代替パス・成功パスの色分けを、JSコードを書かずにMermaid内で完結できる。linkStyle 0,2 stroke:#f00のようなコンマ区切りで複数エッジへの一括適用も可能だ。strokeとstroke-widthがサポート対象だ。

7. ASCII出力：CLI/AIアシスタント向けの差別化機能

ASCII出力はbeautiful-mermaid独自の差別化ポイントだ。READMEの「ASCII Output」セクションに使い方が詳述されている。

import { renderMermaidASCII } from 'beautiful-mermaid'

const unicode = renderMermaidASCII(`graph LR; A --> B --> C`)
const ascii = renderMermaidASCII(`graph LR; A --> B --> C`, { useAscii: true })

Unicodeモードでは┌┐└┘│─►のbox-drawing文字を使い、ASCIIモードでは+|->`だけで完全に7ビットASCIIへフォールバックする。

7.1 ANSIカラー対応

colorModeオプションでnone・auto・ansi16・ansi256・truecolor・htmlの6段階を選べる。ターミナルがサポートする色深度に合わせて自動的に切り替えるautoがデフォルトだ。

CIログやSSH越しの画面で、ノードの種別を色で分けたい場合に効く。例えばbg・fg・accentを「黒・白・赤」に設定しておけば、エラーパスだけが赤く強調されたフロー図を、echoコマンドの出力として出せる。

7.2 設定可能なスペーシング

renderMermaidASCII(diagram, {
  useAscii: false,
  paddingX: 5,
  paddingY: 5,
  boxBorderPadding: 1,
})

paddingXはノード間の横方向スペース、paddingYは縦方向、boxBorderPaddingはノード内のテキスト余白だ。狭い端末では値を小さく、印刷物に出すなら大きく、と用途に合わせて調整できる。

7.3 XY ChartもASCII描画

棒グラフ・折れ線グラフもASCIIで描ける。Unicodeモードでは█ブロック・╭╮╰╯│─の組合せで階段状のラインを描画し、複数系列はANSIカラーで自動的に色分けされる。複数系列があれば凡例も自動表示される。

ターミナルで売上推移を見たい時に、わざわざブラウザを開く必要がなくなる。デプロイ完了Slackに、テキストのまま貼り付けたグラフを添える運用も現実的だ。

8. 競合との比較：Mermaid系レンダラの選択肢

Mermaid描画系のOSSをまとめて比較する。中心軸は「描画速度」「テーマ可変性」「ターミナル対応」「Reactフレンドリーさ」だ。

なお、ここで比べているのはいずれもMermaidソースを受け取って描くツールで、図そのものを作るツールではない。既存のインフラ定義から図を起こしたいなら Terravision：TerraformコードからAWSアーキテクチャ図を自動生成するOSSツール のように、入力がMermaidではなくHCLのツールが別に要る。

競合の★は初出時の表記より正確な値に置き換えた。mermaid-cli は「5,500以上」ではなく実測4,953、mermaid-isomorphic は「200以上」ではなく実測45で、いずれも初出時の記載が過大だった。beautiful-mermaid の 10,920★ は、この4つの中で公式 mermaid.js に次ぐ2位にあたる。

8.0 採用前に見るべき「更新が止まっている」事実

スター数だけを見て採用を決めると危ない状態になっている。2026-08-21時点の実測は次のとおりだ。

つまり 「利用者からの報告は届き続けているが、メンテナ側の反映が止まっている」 状態だ。放置されているIssueには実装上の具体的な不具合も含まれており、たとえば矢印の前に半角スペースが無い A-->B が単一ノード A-- としてパースされる（#140）、フローチャートのclass割り当てで末尾セミコロンを許容しない（#142）といった、LLM生成のMermaidソースを流し込む用途で踏みやすいパーサ側の報告が並ぶ。

本記事が評価する設計上の長所（同期描画・CSS変数テーマ・ASCII出力）は、コードが動く限り変わらない。ただし「未対応図種が今後増える」「報告済みバグが直る」ことは、現時点の実測からは期待できない。導入するなら、パーサの穴を自前でパッチできる前提か、mermaid.js へのフォールバック経路を持っておくのが現実的だ。

8.1 公式mermaid.jsとの使い分け

新規プロジェクトでドキュメントやAIチャットUIに組み込むなら、beautiful-mermaidが第一選択だ。同期描画・CSS変数テーマ・Edge対応という3点で公式版を上回る。

逆に既存のMermaid資産がガント・マインドマップ・Git Graphに大きく依存しているなら、すぐの移行は難しい。図種ごとに「対応していればbeautiful-mermaid、未対応は公式」と二段構えにする運用も可能だ。

8.2 mermaid-cliとの違い

mermaid-cliはPuppeteer経由でMermaidをPNG/SVG画像にバッチ変換するCLIだ。READMEや配布物の事前生成には向くが、ランタイムでの描画には重い。

beautiful-mermaidはWebアプリ・SSR・Edgeランタイムでのリアルタイム描画が主戦場で、cliとは役割が異なる。CIで画像を生成し、サイト上ではbeautiful-mermaidでインタラクティブに描く、というハイブリッド構成も実用的だ。

9. 実運用パターン：MarkdownレンダラーやAIチャットへの組み込み

beautiful-mermaidの典型的な組み込みパターンを3つ紹介する。

Markdownをそのまま資産として扱う構成——たとえば Go製軽量CMS「Foundry」、HackerNewsで話題。Markdownファイルをそのまま資産に のようなファイルベースCMS——では、ビルド時に画像を焼くのではなく、この remark プラグイン経路でリクエスト時にSVGを吐くほうが素直だ。同期APIなのでSSRでもawaitが要らない。

9.1 MDXとMarkdown-it統合

MDXユーザーは、Mermaidコードブロックを自動的にbeautiful-mermaid描画に置き換えるremarkプラグインを書ける。

import { visit } from 'unist-util-visit'
import { renderMermaidSVG } from 'beautiful-mermaid'

export function remarkBeautifulMermaid() {
  return (tree) => {
    visit(tree, 'code', (node) => {
      if (node.lang === 'mermaid') {
        const svg = renderMermaidSVG(node.value, {
          bg: 'var(--mermaid-bg)',
          fg: 'var(--mermaid-fg)',
        })
        node.type = 'html'
        node.value = svg
      }
    })
  }
}

Astro・Next.js・Vitepress・Nextra のいずれも、このプラグインを組み込むだけでMermaidの見た目が一気に揃う。

9.2 LLMストリーミング応答との連携

AIチャットUIでLLMがMermaidコードブロックをストリーミング出力する場合、ストリームが完了するまでパースしないほうがエラーが少ない。

function MermaidStream({ stream }: { stream: ReadableStream<string> }) {
  const [code, setCode] = useState('')
  const [isDone, setIsDone] = useState(false)

  useEffect(() => {
    const reader = stream.getReader()
    void (async () => {
      while (true) {
        const { value, done } = await reader.read()
        if (done) { setIsDone(true); break }
        setCode((c) => c + value)
      }
    })()
  }, [stream])

  return isDone ? <MermaidDiagram code={code} /> : <pre>{code}</pre>
}

ストリーミング中はテキストのまま流し、完了タイミングで描画に切り替える。完全同期APIなのでこの切替がスムーズに動く。

9.3 ダッシュボードの数値グラフ置換

社内ダッシュボードのスパークラインや進捗グラフを、Recharts・Chart.js・Plotlyからxychart-betaに置き換える運用も増えている。

const monthly = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']
const revenue = [180, 250, 310, 280, 350, 420]
const target  = [200, 240, 290, 320, 360, 410]

const svg = renderMermaidSVG(`
xychart-beta
    title "Monthly Revenue vs Target"
    x-axis [${monthly.join(', ')}]
    bar [${revenue.join(', ')}]
    line [${target.join(', ')}]
`, { ...THEMES['github-light'], interactive: true })

依存関係に重量級チャートライブラリを引き込まず、テキストテンプレートを組み立てるだけでチャートが完成する。バンドルサイズが100KB以上削減できるケースもある。

10. インストールと最初の1枚

最後にインストールから最初の図を出すまでをまとめる。

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

NodeとBunの両方をサポートし、TypeScript型定義が同梱されている。型をつけた最小コードは以下だ。

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

const svg: string = renderMermaidSVG(`
  graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
`, THEMES['tokyo-night'])

document.getElementById('chart')!.innerHTML = svg

renderMermaidSVGは文字列を返す純粋関数なので、テスト・スナップショット・スクリーンショット差分検査と相性がよい。

10.1 RenderOptionsの全パラメータ

主要オプションを表にまとめる。READMEのAPI Referenceから抜粋した。

thoroughnessを上げるとエッジ交差が減るが描画時間が伸びる。デフォルトの3で多くのケースは問題なく、複雑な大規模図でだけ5〜7に上げると良い。

10.2 ベストプラクティス

第一に、ReactではuseMemoを使う。第二に、色はCSS変数で渡してテーマ切替の再描画を避ける。第三に、ストリーミング応答中はパースを抑制し、完了後に描画する。第四に、サーバーサイドではEdgeランタイムにそのまま乗せる。

これらを守れば、AIチャット・ドキュメント・ダッシュボードのどこでも「美しい・速い・滑らか」なMermaid描画が手に入る。

まとめ

beautiful-mermaidは「Mermaidは速く美しく描けるべきだ」という主張を、コードで証明したライブラリだ。公式版が積み上げた16年の蓄積を尊重しつつ、AI時代の要件で再設計する勇気と覚悟が伝わる。

OSSドキュメンテーションの自動化については Tutorize：READMEから対話型チュートリアルを自動生成するOSS も合わせて読んでほしい。

参照ソース

• lukilabs/beautiful-mermaid — GitHub
• beautiful-mermaid — npm package
• AlexanderGrooff/mermaid-ascii — GitHub
• Mermaid公式 — mermaid.js.org