Mermaid Theme Builder
Visual governance for AI-generated Mermaid diagrams.
Paste Mermaid, detect the family, apply a reusable theme, preview live, and export renderer-aware code or prompt scaffolds. Browser-only. No login. No backend. No data collection.
The Missing Layer
Every prompt is a fresh roll of the dice
When ChatGPT, Claude, Copilot, or Gemini generate Mermaid diagrams, each prompt produces different colors, inconsistent styling, and no memory of what worked before.
Default styling = brand disconnection
Mermaid's default theme makes every AI-generated diagram look generic — no relationship to your brand system, your document style, or each other.
Not all diagram types style the same way
Flowcharts, sequence diagrams, and class diagrams each expose different styling surfaces. What works for one may break another — and AI tools don't know the difference.
3–5 follow-up prompts just to fix styling
Users routinely spend more time correcting colors, fixing syntax errors from hallucinated theme variables, and chasing consistency than on actual diagram content.
v0.5.0 — Shipped May 2026
A governance workbench, not a diagram editor
- ◆A visual workbench for defining and enforcing Mermaid diagram themes
- ◆A renderer-aware export tool — flags what breaks in GitHub, GitLab, Obsidian, Notion, Confluence
- ◆A brand palette enforcer — presets for OverKill Hill P³, Glee-fully, and AskJamie, plus four utility palettes (Ocean Depth, Forest Sage, Slate Ember, Violet Mist)
- ◆A prompt scaffold generator — AI tools stay on-brand from the first generation
- ◆A SKILL.md-packaged agent skill for headless diagram-governance workflows
- ◆An open-source community contribution to the Mermaid.js ecosystem. MIT licensed. Free always.
- —Not Mermaid — it does not generate, parse, or render Mermaid syntax itself
- —Not a diagram editor — it governs style, not structure
- —Not a Mermaid syntax generator — you bring the code
- —Not a BPMN engine — it applies visual themes, not structural process semantics
- —Not affiliated with Mermaid.ai, Mermaid Chart, or any commercial Mermaid product
- —Not a replacement for Mermaid.js — a governance layer on top of it
- —Not a SaaS, not a subscription, not a freemium gate
- —Not collecting any data — 100% client-side, no server, no analytics
What you get here that you don't get from prompting an LLM
Prompting an LLM
Generates CSS variable blobs you paste and re-prompt until something looks right. No live preview, no iteration feedback, result varies by model. No renderer awareness — you find out what breaks when you paste it.
Mermaid Theme Builder
Pick a color, see every diagram type update instantly. Export as a themeVariables block, a Markdown style bootstrap, or a renderer-aware prompt scaffold. AI tools stay on-brand from the first generation — not the sixth.
Who uses Mermaid Theme Builder
Enterprise Architects
Need repeatable visual standards across hundreds of diagrams. One governed theme applies consistently — no manual re-styling after every AI generation.
AI Power Users
Generate 10+ diagrams per week through LLMs. Prompt scaffolds keep every output on-brand from generation one — no follow-up style cycles.
Documentation Teams
Maintain visual consistency across technical docs at scale. Export a shared theme once, apply it everywhere — GitHub, Confluence, Notion, Obsidian.
Product Managers
Create stakeholder-ready architecture diagrams that look intentional, not auto-generated. Clean presentation styling without manual CSS work.
Developers
Document systems with consistent styling baked in. Drop a themeVariables block into your mermaid.initialize() call and every diagram inherits the contract.
Six community pain points MTB addresses
These aren't invented problems — they come from GitHub issues, Stack Overflow threads, community forums, and AI tool feedback. MTB doesn't fix Mermaid core behavior. It helps users avoid, detect, or route around known styling and renderer pitfalls.
Custom colors and styles
Users ask how to customize Mermaid node, link, and diagram colors — without re-prompting an AI or editing raw CSS. Theme Builder provides a visual workflow and exportable theme contract.
Branded consistency
Users want Mermaid diagrams to match a consistent visual language across documents, posts, repos, and deliverables. A reusable palette applied once stays consistent across every diagram it touches.
Renderer parity
Mermaid behaves differently across GitHub, GitLab, Obsidian, Notion, Confluence, Mermaid Live, and other renderers. Theme Builder surfaces renderer-specific warnings before you paste — not after.
Export fidelity
Some workflows preview one appearance and export another. Theme Builder preserves the theme contract in source-level Mermaid and Markdown — not just in image export behavior.
Diagram-family limits
Not every Mermaid family supports the same styling mechanisms. Theme Builder warns when classDef, linkStyle, themeVariables, or typography controls are limited for a given family.
AI-generated Mermaid drift
AI tools may generate diagrams that render in one place but fail or look different somewhere else. Prompt scaffolds instruct the AI before generation — preventing renderer-fragile output rather than patching it.
What shipped in v0.4 and v0.5
Renderer Intelligence
Moved from capability notes to active renderer profiles. The workbench now selects export rules based on your target renderer — not just flags what might fail.
Look API Support
Mermaid v11.15.0 look API — Classic, Neo, and Hand-Drawn modes — with per-renderer warnings where support is inconsistent. Shipped in v0.4; hardened in v0.5.
Reference Capability Registry
27+ diagram-family capability matrix covering renderer × family × version combinations. Was implicit in v0.3; now a dedicated Reference tab.
SKILL.md Agent Packaging
Governance logic is being extracted into a machine-readable SKILL.md for Claude Code, Cursor, GitHub Copilot, and VS Code. Not in v0.3.
Multi-Diagram Splitting
Paste compound Mermaid blocks and the tool splits, themes, and exports each diagram independently. Not available in v0.3.
Shareable URL State
Your full theme configuration is encoded in the URL. Bookmark it, share it, or return to it later. v0.3 had no persistent state between sessions.
Vitest 4 Test Suite
Export integrity, themeVariable completeness, and renderer profile accuracy verified by Vitest 4. Every export claim is now testable. v0.3 had no test suite.
Hypothesis Validated
Built against a validated research hypothesis — not shipped on a hunch.
98 sources analyzed
GitHub issues, Stack Overflow threads, enterprise documentation, and community forums — all pointing to the same gap in the Mermaid ecosystem.
Pain is real and documented
Users across every major LLM tool report the same struggle: Mermaid theming is inconsistent, renderer-dependent, and invisible to AI generation workflows.
No existing tool fills the gap
No tool combines theme governance + LLM scaffolding + renderer-awareness in a single, free, browser-based workbench. This is the gap MTB fills.
Genuine ecosystem gap confirmed
The product fills a documented gap at the intersection of diagram-as-code and AI generation — not an incremental improvement on an existing tool category.
What it's built on
React 19 + Vite 8
Modern component architecture with fast dev iteration. No framework lock-in — the governance logic is extractable independent of the React layer.
Tailwind CSS v4
Utility-first styling with OKH Forge UI System v0.1.0 design tokens. Consistent visual language across the workbench's controls, previews, and export panels.
Mermaid.js 11.15.0
Pinned to a specific version for reproducible rendering. The Look API, 27+ diagram families, and full themeVariables coverage — all at a known, tested baseline.
TypeScript 6.0.3 (strict)
Strict mode throughout. Renderer profile types, diagram family unions, and export format contracts are all type-safe — not inferred at runtime.
Playwright e2e Tests
End-to-end test coverage for export integrity, renderer profiles, and diagram family classification. Every claimed behavior is a passing test, not a documented assumption.
PWA-Ready (Offline Capable)
Service worker and web app manifest are both present in the source repo. The workbench runs without a network connection after the first visit. Installable, works offline after first load.
What the builder does
Live Diagram Preview
Every color change reflects instantly across multiple diagram types — flowchart, sequence, class, Gantt, and more. What you see is what you get.
Diagram Family Detection
Automatically identifies your diagram type and applies family-appropriate transformations. Not all Mermaid families behave the same — the tool knows the difference.
Multi-Format Export
Export as a complete themeVariables block, a Markdown style bootstrap you paste before any diagram, or a model-specific LLM prompt scaffold.
Prompt Scaffold Generator
Generates LLM-ready prompt prefixes with your theme embedded. AI tools produce on-brand Mermaid on the first try — no follow-up styling cycles needed.
Renderer Capability Notes
Flags which styling choices work in GitHub, GitLab, Notion, Obsidian, and other renderers — so you know what breaks before you paste and find out.
Brand Palette Presets
Ships with seven built-in palettes: four utility (Ocean Depth, Forest Sage, Slate Ember, Violet Mist) and three brand (OverKill Hill P³, Glee-fully, AskJamie). Start from a working preset or build your own.
Precise Color Controls
Full HSL/RGB pickers with live swatch previews. Dial in exact values with visual confirmation at every step — not just a hex input box.
Browser-Only — No Server
Runs 100% client-side. No login, no account, no data leaves your machine. Close the tab and nothing is stored anywhere.
Pan / Zoom Canvas
Navigate complex diagrams without losing context. Pan and zoom the preview canvas — useful for dense flowcharts and class diagrams that don't fit the initial viewport.
SKILL.md Package
The governance logic is being packaged as a machine-readable agent skill. AI tools and coding assistants can apply brand palettes and renderer profiles without opening the visual app.
Open Source, MIT License
Fork it, remix it, embed it. Full source on GitHub. Contributions welcome.
Look API — Classic, Neo, Hand-Drawn
Supports Mermaid v11.15.0 look API. Switch between Classic, Neo, and Hand-Drawn rendering modes — with renderer warnings where support is inconsistent across platforms.
Reference Tab — 27+ Family Registry
A built-in capability registry covering 27+ diagram families. Documents which features are supported per renderer, per family, per Mermaid version — the reference stays open alongside your workspace.
Multi-Diagram Splitting
Paste compound or multi-block Mermaid code and the tool splits it into individual diagrams, applies your theme to each, and exports them independently. No manual untangling.
Vitest 4 Test Suite
Export integrity, theme-variable completeness, and renderer-profile accuracy are verified by a Vitest 4 test suite. Every export claim is testable against its target renderer — not just described.
How it fits the ecosystem
Mermaid.js
The open-source diagram rendering engine. Mermaid Theme Builder is a governance layer that wraps and extends the Mermaid.js themeVariables system. No affiliation — an independent ecosystem contribution built on top of the same open library.
Mermaid.ai
A commercial AI-first diagram generation platform. Completely separate — no affiliation, no integration, no dependency. MTB works with the open Mermaid.js library directly. The distinction matters: Mermaid.js is the open standard; Mermaid.ai is a commercial product built on it.
BPMN for Mermaid
The structural sibling. BPMN for Mermaid extends Mermaid syntax toward BPMN-aligned diagram patterns. MTB is the styling and governance layer; BPMN for Mermaid is the structural extension layer. They are complementary — style what BPMN for Mermaid produces. See the project →
SKILL.md / Agent Workflows
MTB is being packaged as a reusable agent skill. The SKILL.md format exposes its governance logic — palette definitions, renderer profiles, prompt scaffold patterns — as a machine-readable workflow that AI agents and coding assistants can consume without the visual UI.
Support taxonomy — not all families are equal
Mermaid.js does not treat all diagram types with equal stability or renderer support. MTB reflects this — it does not imply uniform support across all families.
These families have the most consistent support across Mermaid.js versions and hosted renderers (GitHub, GitLab, Obsidian, Confluence). Safe for production use in most contexts.
These families exist in recent Mermaid.js releases but are marked beta or have inconsistent renderer support. Hosted renderers (GitHub, Confluence, Notion) may not support them yet. Verify before deploying.
The Mermaid %%{init:…}%% directive and CSS-level overrides work in browser Mermaid.js but are stripped or ignored by many hosted renderers. MTB flags known breakpoints — the export profiles are built around this constraint.
Brand-specific scaffolding patterns that apply OKH conventions to standard diagram families. Not extensions of Mermaid syntax — conventions applied on top of valid Mermaid.
Structural diagram patterns from the sibling BPMN for Mermaid project. These extend Mermaid toward BPMN-aligned semantics. MTB can style BPMN-for-Mermaid outputs — they share the same theming contract. See BPMN for Mermaid →
Why renderer-aware output matters
Mermaid.js can render a diagram that GitHub Markdown, Notion, or Obsidian cannot. The same themeVariables object that works perfectly in a browser may fail silently — or break layout — in a hosted renderer.
- The
%%{init:…}%%directive is stripped by most hosted renderers — it only works in browser Mermaid.js. - Custom CSS overrides work in the browser but are ignored by GitHub, GitLab, and Confluence.
- The Look API (Classic/Neo/Hand-Drawn) is Mermaid.js 11.x — hosted renderers pin older versions and may not support it.
- Beta diagram families (sankey, kanban, block) exist in the library but are not supported by most hosted renderers yet.
- Mermaid.js version pinning varies by host — the same code behaves differently in GitHub vs. Obsidian vs. Confluence.
MTB tracks known renderer compatibility and flags styling choices that break in common deployment targets. The export profiles are built around these constraints. You find out before you paste, not after.
For AI-generated diagrams this matters even more. An AI tool generating Mermaid has no renderer context — it produces valid Mermaid.js that may be useless in the target environment. A renderer-aware prompt scaffold closes that gap before generation begins.
SKILL.md — headless diagram governance
What the SKILL.md package does
Mermaid Theme Builder is being packaged as a reusable agent skill — a machine-readable SKILL.md that exposes the tool's governance logic in a format AI agents and coding assistants can consume directly, without opening the visual app.
The skill covers:
- Palette definition and brand token mapping
- Renderer profile selection — GitHub, GitLab, Obsidian, Notion, Confluence
- Mermaid
themeVariablesassembly for a target renderer - Prompt scaffold generation with embedded palette and renderer constraints
- Diagram family classification and renderer-safe export rules
Intended for: AI coding assistants, local agent workflows, CI/CD diagram validation pipelines, and headless diagram-governance scripts that need to apply consistent brand and renderer rules without human review at each step.
Install in your AI coding assistant
Once the SKILL.md is published, drop it into your agent's skill directory. The file is self-contained — no dependencies beyond the Mermaid.js spec.
Claude Code
# .claude/skills/mermaid-theme-builder.md # Point Claude Code at the published SKILL.md raw URL or local copy curl -o .claude/skills/mermaid-theme-builder.md \ https://raw.githubusercontent.com/OKHP3/mermaid-theme-builder/main/skills/okhp3-mermaid-theme-builder/SKILL.md
Cursor
# .cursor/rules/mermaid-theme-builder.mdc # Copy skills/okhp3-mermaid-theme-builder/SKILL.md from the cloned repo # or reference via @mermaid-theme-builder in Cursor chat
GitHub Copilot
# .github/copilot-instructions.md # Append contents of skills/okhp3-mermaid-theme-builder/SKILL.md under a "Mermaid Diagram Governance" heading # Copilot picks up repo-level instructions automatically in VS Code
VS Code (any agent via workspace context)
# .vscode/mermaid-theme-builder.md (add to workspace context) # Copy skills/okhp3-mermaid-theme-builder/SKILL.md from the cloned repo # Reference in any chat-mode prompt: "Apply the Mermaid Theme Builder # governance rules for [renderer] before generating diagram code."
Desktop-first. Mobile companion mode.
This is an honest description, not an apology. The workbench is a power tool — the full experience is designed for a desktop viewport with room for controls, preview, and output side by side.
Full power-user experience
- Full color picker suite — HSL, RGB, hex
- Live multi-diagram preview across families
- Pan / zoom canvas for complex diagrams
- All export formats — themeVariables, Markdown, prompt scaffold
- Renderer profile selection and compatibility flags
- Dense diagram inspection at full fidelity
Useful subset, honestly scoped
- Browse palette presets and examples
- Copy prompt scaffolds for pasting into AI tools
- Check renderer-safe export output
- Light diagram preview at smaller scale
- Review renderer compatibility notes
Heavy code editing and dense diagram inspection remain desktop-first. Mobile hardening is on the v0.6.x validation sprint roadmap.
Where the build is going
-
✓
V0.1 — Foundation Shipped
Paste, detect, palette, preview, export. Four utility palettes. Prompt scaffold modal. GitHub Pages deploy.
-
✓
V0.2 — Brand System Shipped
OverKill Hill P³, Glee-fully, and AskJamie brand palettes. Family-specific theming overlays. Extract mode.
-
✓
V0.3 — Architecture Hardening Shipped
React 19 + Vite + TypeScript monorepo. Compose tab. 5-tier typography hierarchy.
-
✓
V0.4 — Renderer Intelligence Shipped
7 renderer profiles with parity matrix. Look API (Classic, Neo, Hand-Drawn). Dark/light/system preview. 26+ example files. Diff view.
-
✓
v0.5.0 — Baseline Shipped
Forge UI System, pan/zoom canvas, renderer-aware export, brand palette presets, Look API (Classic/Neo/Hand-Drawn), multi-diagram splitting, shareable URL state, Reference tab with 27+ family registry.
-
▶
v0.5.x — SKILL.md Hardening Active
Extract governance logic into a portable SKILL.md agent skill for Claude Code, Cursor, GitHub Copilot, and VS Code. Vitest 4 test suite hardening. Renderer profile verification fixtures.
-
○
v0.6.x — Native Capability + Ko-fi Artifacts Planned
Native renderer capability checking. Ko-fi artifact packaging for purchasable theme packs and brand kits. Mobile hardening sprint.
-
○
v0.7.x — Session Persistence + Multi-Diagram Canvas Planned
Local storage persistence for sessions across browser restarts. Multi-diagram canvas — manage, compare, and export multiple themed diagrams in one workspace.
-
○
v0.8.x — Collaboration + Governance Hardening Planned
Shareable governance profiles. Team-level palette enforcement. Governance audit log — tracks which themes were applied to which diagrams, when, and by which export format.
-
○
v1.0 — Production Release Planned
Stable API surface, production-grade test coverage, full documentation, and formal governance contract for downstream consumers (BPMN for Mermaid, SKILL.md, Ko-fi artifacts).
User Guide
Get from zero to a custom Mermaid theme in under five minutes.
-
01
Paste your Mermaid code or start from examples
Use the embedded tool above or open it in a full tab. No login required. Start from an example diagram or paste your own Mermaid code.
-
02
Select a theme or compose custom colors
Pick from built-in palettes (Ocean Depth, Forest Sage, Slate Ember, Violet Mist) or build custom colors with HSL pickers. Every change previews instantly across diagram families.
-
03
Preview with instant rendering
Watch your theme apply across multiple Mermaid diagram types simultaneously. Pan and zoom the canvas for complex diagrams.
-
04
Export styled code, Markdown docs, or AI prompts
Export a complete
themeVariablesblock, a Markdown style bootstrap, or a renderer-aware prompt scaffold — your context is preserved in the URL for future sessions. -
05
Use prompt scaffolds in ChatGPT, Claude, or Copilot
Paste the generated prompt scaffold before your next diagram request. AI tools produce on-brand Mermaid from the first generation — no follow-up styling cycles needed.
Tier 2 users: Follow steps 1–5. Total time: ~3 minutes.
Palette Reference
All Mermaid themeVariables touched by the builder, and what they control.
| Variable | Effect |
|---|---|
| primaryColor | Main node fill color — the dominant hue in your diagram. |
| primaryTextColor | Text inside primary-colored nodes. Ensure contrast. |
| primaryBorderColor | Border/stroke of primary nodes. |
| secondaryColor | Secondary node fill — used for alternate node types. |
| secondaryTextColor | Text inside secondary nodes. |
| secondaryBorderColor | Border of secondary nodes. |
| tertiaryColor | Tertiary fill — subgraphs, clusters, grouping elements. |
| tertiaryTextColor | Text inside tertiary elements. |
| tertiaryBorderColor | Border of tertiary elements. |
| background | Canvas/diagram background. Usually the page's background color. |
| mainBkg | Default background for most node types. |
| nodeBorder | Default border for all node types. |
| clusterBkg | Subgraph/cluster fill color. |
| clusterBorder | Subgraph/cluster border. |
| lineColor | Arrow and edge line color. |
| edgeLabelBackground | Background of inline edge labels. |
| fontFamily | Font family applied to all diagram text. |
| fontSize | Base font size — default 16px. |
| labelBackground | Background of standalone labels. |
| labelTextColor | Color of standalone label text. |
| titleColor | Diagram title text color. |
The builder exports these as a complete themeVariables object. Pass them to mermaid.initialize({ theme: 'base', themeVariables: {...} }).
FAQ
Is this affiliated with Mermaid, Mermaid Chart, or Mermaid.ai?
No. Mermaid Theme Builder is an independent community contribution to the open-source Mermaid.js ecosystem. It has no affiliation with Mermaid Chart (mermaidchart.com), Mermaid.ai, or any commercial Mermaid product. It is built on top of the open-source Mermaid.js library.
Is it free?
Yes. Free now, free always. No subscription, no freemium gate, no ads. MIT licensed.
Does it send my diagrams anywhere?
No. All transforms run locally in the browser. No analytics, no telemetry, no server communication. Your theme and diagrams stay in your browser.
Which Mermaid.js versions does it support?
Mermaid v11.15.0 is the current reviewed target. The tool also surfaces known renderer breakpoints — the same code that works in the browser may fail silently in GitHub, Notion, or Confluence. The workbench flags those conflicts before you paste.
Can I use the exported theme with Docusaurus, VitePress, or GitHub?
Yes. The exported themeVariables object is standard Mermaid config — it works anywhere Mermaid.js is used. Check your platform's docs on how to pass themeVariables.
Does it support dark/light mode preview toggle?
Yes — dark/light preview toggle shipped in v0.4.x. Set your target mode in the preview panel and the live preview reflects it. The contrast preview is accurate for any background you choose.
Can I save and share my theme?
Yes. Theme state is encoded in the URL, so you can bookmark or share your current configuration directly. For permanent storage, export your themeVariables JSON and commit it to your project.
Does it work on mobile?
Companion mode only. On mobile you can browse palette presets and examples, copy prompt scaffolds, check renderer-safe export output, and review compatibility notes. The full workbench is desktop-first. Mobile hardening is on the v0.6.x roadmap.
What is SKILL.md and can I use it without the visual app?
SKILL.md is a machine-readable agent skill — a file you drop into Claude Code, Cursor, GitHub Copilot, or VS Code that exposes the builder's governance logic without opening the visual app. The agent can apply brand palettes, select renderer profiles, and generate prompt scaffolds in headless workflows. The SKILL.md is under active development as part of the v0.5.x sprint.
What is the relationship between Mermaid Theme Builder and BPMN for Mermaid?
They are sibling projects from OKH P³. BPMN for Mermaid extends Mermaid syntax toward BPMN-aligned structural patterns. Mermaid Theme Builder is the styling and governance layer. They are complementary — use MTB to govern the visual output of what BPMN for Mermaid produces. See BPMN for Mermaid →
How do I contribute or file a bug?
Open an issue or PR on GitHub. Community feedback is actively used to shape the roadmap.
This tool started as a personal itch. I kept running into the same friction: needing a custom Mermaid theme, describing what I wanted in a prompt, getting CSS, pasting it, noticing something was off, re-prompting. The feedback loop was slow and imprecise.
So I built the direct-manipulation version. Pick a color. See the change. Move on.
It's useful to me and probably useful to someone else in the Mermaid.js community. That's why it's here.
Not a startup. Not a SaaS pivot in progress. A tool I built, made free, and put on GitHub.
— OverKill Hill P³
v0.5.0 is the current live state. The Forge UI System is in, pan/zoom is live, and the Look API (Classic/Neo/Hand-Drawn) shipped with full renderer compatibility notes. The Reference tab carries 27+ diagram family entries. Every export format is renderer-profiled — you get a GitHub-safe export if you target GitHub, a browser export if you target browser Mermaid.js.
The active sprint is v0.5.x SKILL.md Hardening. The governance logic that powers the visual app is being extracted into a machine-readable
SKILL.md— the same palette definitions, renderer profiles, and prompt scaffold patterns, in a format Claude Code, Cursor, Copilot, and VS Code can consume directly without opening the browser tool.The v0.6.x sprint follows: native renderer capability checking, Ko-fi artifact packaging, and mobile hardening. The goal is that every export claim is verifiable against its target renderer — not just described.
— May 2026 · OverKill Hill P³