Mermaid Theme Builder
Visual. Instant. Yours.
A free, open-source visual editor for Mermaid.js themes. Pick your colors, watch diagrams update live, and export production-ready CSS — no prompting, no guessing, no iteration cycles.
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.
Mermaid Theme Builder
Pick a color, see every diagram type update instantly. When it looks right, export. One round trip instead of five.
What the builder does
Live Diagram Preview
Every color change reflects instantly across multiple diagram types — flowchart, sequence, class, gantt, and more.
Full CSS Variable Export
One-click export of the complete Mermaid themeVariables block. Paste directly into your mermaid.initialize() config.
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.
Multiple Diagram Types
Preview your theme across the full range of Mermaid diagram types simultaneously, not just a single example.
Precise Color Picker
Not just a hex input — full HSL/RGB pickers let you dial in exact values with visual confirmation at every step.
Open Source, MIT License
Fork it, remix it, embed it. Full source on GitHub. Contributions welcome.
User Guide
Get from zero to a custom Mermaid theme in under five minutes.
-
01
Open the builder
Use the embedded tool above or open it in a full tab for maximum workspace. No login required.
-
02
Select a diagram type to preview
The panel shows multiple Mermaid diagram types. Pick the one most relevant to your use case as your primary reference.
-
03
Adjust base colors
Start with your primary background and node fill colors. Everything else cascades from these. Use the color pickers — HSL sliders give you the most control.
-
04
Refine edges, text, and accents
Dial in edge colors, label text colors, and cluster/subgraph backgrounds. Watch the preview update in real time.
-
05
Export your theme
Hit Export. You get a complete
mermaid.themeVariablesobject ready to drop into yourmermaid.initialize()call or mdx frontmatter. -
06
Paste and verify
Drop the exported variables into your project. If anything needs a tweak, return to the builder — your context is preserved in the URL.
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.ai?
No. This is an independent community contribution to the open-source Mermaid.js ecosystem. It has no relationship with Mermaid.ai or any commercial Mermaid product.
Does it cost anything?
Nothing. Free now, free always. No subscription, no freemium gate, no ads. MIT licensed.
Does it collect any data?
No. The tool is fully client-side. No analytics, no telemetry, no server communication. Your theme stays in your browser.
Which Mermaid.js versions does it support?
Tested against Mermaid.js v10 and v11. The themeVariables API has been stable across these versions.
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.
Why doesn't it support dark/light mode toggle in the builder itself?
It's V0.3 Public Alpha. Dark/light preview toggle is on the roadmap. For now, set your background color to match your target mode and the contrast preview is accurate.
Can I save and share my theme?
Not yet via a URL share feature, though it's planned. For now, export your themeVariables JSON and commit it to your project.
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³
The full write-up — what this is, how it came together, and what it means for the Mermaid.js community — is reserved for the V0.3 article. This page is the tool advertisement; the story is separate.
Article forthcoming. Watch github.com/OKHP3 for updates.