A Live Mermaid Theme Playground: mermaid.design

I use Mermaid a lot — flowcharts in design docs, sequence diagrams in READMEs, the odd ER diagram. Diagrams-as-code is a great deal: versionable, diffable, no dragging boxes around a canvas. What was never great is how the result looks.

The built-in themes are functional, but the colors feel dated. Mermaid does have a real theming system — set theme: 'base' and override whatever you like in themeVariables. The problem is the workflow: edit a frontmatter block, re-render, squint at the output, guess which of the 70-odd variables actually paints the thing you dislike, repeat.

My breaking point was a sequence diagram. I changed primaryColor and the actor boxes changed color along with it — turns out those belong to actorBkg. Ten minutes per color, most of it guessing, because a variable's name tells you almost nothing about what it paints.

What I wanted was simple: tweak a variable, see what it does. Immediately.

So I built mermaid.design — Mermaid code on the left, a live preview in the middle, and the whole theme system editable on the right. Every change re-renders the diagram in place. The feedback loop went from minutes to seconds.

That's the pitch. Here are the parts that actually save time.

The gallery: every diagram type at a glance

The annoying thing about theme variables is that the same variable behaves differently across diagram types. The gallery page renders all 84 templates — flowcharts, sequence, class, state, ER and more — live with your current theme. Change a variable, scroll the gallery, and the effect on every diagram type is right there. No more switching diagram types back and forth to check. That's the time it saves.

Theme variables: defaults and inheritance on the surface

Every one of the 73 variables shows its default from the mermaid base theme. Variables you haven't set get an AUTO badge showing the value mermaid derives at render time — and where that value comes from:

• mainBkg follows primaryColor
• primaryBorderColor is a border color computed from primaryColor
• secondaryTextColor is the inverse of secondaryColor (for contrast)
• actorBkg follows mainBkg — which explains the trap from earlier: changing primaryColor moved my actor boxes because there's an inheritance chain primaryColor → mainBkg → actorBkg

Once you see the chain, recoloring stops being guesswork.

Presets: official, designer, and more to come

21 presets, one click to apply: the 11 official mermaid themes (default, neutral, dark, forest, base, plus the v12 redux and neo families) and 10 designer presets I tuned by hand. Each shows a live mini preview — and the collection keeps growing.

Generate: one primary color, a whole palette

Pick a single primary seed color and the generator ramps lightness in HSL space around its hue — an 8-step scale — to derive a complete palette, dark-mode variant included. The fastest way to make a diagram match your brand.

Render config: beyond colors

Colors are only half of it. Mermaid has 438 render-affecting config fields, grouped by diagram type into 34 groups. A few examples:

• Global: fontFamily, fontSize, wrap (auto text wrapping), look (classic or handDrawn)
• Flowchart: flowchart.curve (edge curve style), flowchart.nodeSpacing / flowchart.rankSpacing (node/rank spacing), flowchart.diagramPadding
• Sequence: sequence.actorMargin, sequence.messageMargin, sequence.showSequenceNumbers (message numbering), sequence.mirrorActors
• Pie: pie.textPosition, pie.donutHole, pie.legendPosition

The group matching your current diagram type opens automatically.

ASCII mode: diagrams as text

The same diagram can render as ASCII art — one click to copy, ready for code comments, commit messages, or plain-text docs. It currently supports five diagram types: flowchart, sequence, class, state, and ER. The charset can be Unicode box-drawing or plain ASCII.

Wrapping up

The motivation behind mermaid.design was simple: the official theme colors are hard to love, hand-tuning themeVariables is slow, and I wanted a place where every change shows its effect immediately. Today it has live-editable theme variables with visible defaults and inheritance, a gallery that shows every diagram type at once, official and designer presets, a generator that turns one primary color into a full palette, 438 render-config fields, and an ASCII mode that turns diagrams into text.