Theming

Every diagram type is drawn by one design system. Colours come from a small set of CSS custom properties written on the <svg> element, and everything else is mixed from them inside the SVG's <style> block. On top of the colours, a style preset decides how things are painted (outlines, fills, containers, labels, markers), again for every diagram type at once.

15 themes ship in Themes.BuiltIn:

A diagram can pick a theme in its own source:

%%{init: {"theme": "tokyo-night"}}%%
flowchart LR
  A --> B

From code, copy the theme's values into RenderOptions. Copy the roles and the data palette too, or the diagram falls back to the zinc-light roles:

var t = Themes.BuiltIn["tokyo-night"];
var options = new RenderOptions
{
    Bg = t.Bg, Fg = t.Fg, Line = t.Line, Accent = t.Accent, Muted = t.Muted,
    DataPalette = t.DataPalette,
    Default = t.Default, Success = t.Success, Failure = t.Failure, Warning = t.Warning, Info = t.Info,
};

From the CLI: -t <name> (or --theme), and --list-themes prints the names.

Colours resolve in this order, each step overriding the previous one:

1. The diagram's %%{init}%% theme, or zinc-light when it names none (or an unknown theme).
2. Any colour set in RenderOptions.
3. The diagram's themeVariables: background, primaryTextColor, lineColor and primaryColor (the accent).

Strict styling drops the source theme and themeVariables, so only the host's colours apply. Every colour value is checked against an allowlist; an invalid value falls back to the previous step.

Three presets restyle all 24 diagram types, light and dark. They only change paint: layout, colours and font sizes are identical, so switching preset never moves a box.

var options = new RenderOptions
{
    Style     = DiagramStyle.Blueprint,
    Gradient  = true,
    Tint      = 1.0,
    Elevation = 1,
};

1. top-to-bottom fills; false = flat fills
2. 0.5–1.5: strength of every derived tint
3. 0 none, 1 boxes + containers, 2 adds an ambient shadow

The shadow colour is never a fixed value: it is mixed from the theme. On light pages it is the foreground at low strength; on dark pages it is the background deepened, so the shadow keeps the theme's own hue.

From the CLI: --style <quiet|blueprint|tonal>, --no-gradient, --tint <0.5-1.5>, --elevation <0|1|2>. The CLI rejects out-of-range values with an error.

The accent colour is the "look here" colour in every preset: terminals, decisions, notes, activation bars, the diagram title mark and similar highlights, plus the arrowheads in Blueprint. The full knob table and the rules renderers follow are in DESIGN.md.

derived values are computed with color-mix(in srgb, var(--fg) X%, var(--bg)), so they adapt when --fg and --bg change. You rarely need to set them.

Internally the renderer derives a fixed set of neutrals from these (secondary text at 72% of --fg, muted text 64%, soft rules 14%, strong rules 68%, …), chosen so text keeps at least 4.5:1 contrast and lines 3:1 in the built-in themes.

Every coloured element (a cluster of nodes, a container, a chart series, the accent, a role) is a colour family: one base colour from which every stage is mixed against --bg or --fg.

Tint multiplies every --bg-side ratio. Because each stage is a color-mix, a family re-themes with the page.

Pass any hex color or CSS color value via RenderOptions:

var options = new RenderOptions
{
    Bg      = "#0D1117",
    Fg      = "#E6EDF3",
    Accent  = "#58A6FF",
};

string svg = MermaidRenderer.RenderSvg(diagram, options);

1. dark background
2. light text
3. highlights

Options you leave unset come from the theme (zinc-light unless the diagram names one). On a dark Bg, also set the colour roles and DataPalette, or copy them from a dark built-in theme.

Five roles give boxes a meaning: Default (an ordinary box), Success, Failure, Warning and Info. Every shipped theme sets all five explicitly. The zinc themes use a cool slate Default (#64748b, #94a3b8 on zinc-dark) so the blue accent stands out; the other themes use their own palette's colours.

var options = new RenderOptions
{
    Default = "#4e79a7",
    Success = "#198038",
    Failure = "#da1e28",
    Warning = "#f1c21b",
    Info    = "#0f62fe",
};

The line colour follows the Default role: unless Line is set, connectors are drawn in the border colour of an ordinary box (Border when set), so lines and boxes read as one family.

In a diagram, give a node (or state) the class success, failure, warning or info:

An explicit style / classDef fill always wins. With strict styling the class must be on your allow-list.

Surface and Border are optional explicit overrides for ordinary boxes. Set them when you want a fixed fill and outline instead of the colours derived from the Default role. No built-in theme sets either one.

var options = new RenderOptions
{
    Surface = "#FEFCE8",
    Border  = "#A16207",
};

1. fill of ordinary boxes
2. their outline

They apply to every box painted in the Default colour family, the first cluster:

Surface is a solid fill in every style: it replaces the Quiet gradient, the Blueprint knock-out and the Tonal soft fill. Border keeps each style's outline width. Tonal draws no outlines, so Border changes no box there.

Other clusters, role classes (:::success …), decisions (accent), terminals and data stores (neutral), containers and charts keep their derived colours. Mindmap branches, timeline periods, journey sections and kanban columns start at the second cluster, so the overrides do not reach them.

Unless Line is set, connectors follow Border. This also replaces the line colour a built-in theme spells out. An explicit Line always wins. Terminals and data stores are mixed from the line colour, so they follow it as well.

Both are caller options: diagram source (%%{init}%%, classDef, style) never sets them, and unsafe values are ignored like any other colour option.

Flowchart, state, ER and class diagrams give each connected cluster of nodes one colour family. The first cluster takes the Default role; the rest take the data palette minus the hues of the Success, Failure and Warning roles, so an automatically coloured box never looks like a success or a failure. Containers (subgraphs, namespaces) take their own palette colour, never the colour of a member.

Shapes with a conventional meaning override the cluster colour: decisions ({} and state <<choice>>) take the accent, and terminals (([])) and data stores ([()]) take the neutral line family.

Pie, sankey, timeline, radar, gitgraph, mindmap, venn, journey, packet, xychart, and treemap use a categorical palette for series data. Override it with any array of CSS color strings:

var options = new RenderOptions
{
    DataPalette = ["#7FE0FF", "#D66FFF", "#B6D9FF", "#E19BFF", "#4A8CFF"]
};

When null, the theme's palette is used: 12 colours based on a Tableau palette, with a brightened variant on the dark themes.

Transparent defaults to true: the SVG has no background, so it inherits whatever is behind it. Set Transparent = false to fill the canvas with Bg:

var options = new RenderOptions { Transparent = false, Bg = "#FFFFFF" };

var options = new RenderOptions
{
    Font     = "Inter",
    MonoFont = "JetBrains Mono",
    FontSize = "0.9rem",
};

1. proportional text
2. ER types, class signatures, Blueprint captions
3. base size token --fs-m

Font defaults to Inter. MonoFont falls back to the system monospace stack when null. Font families must already be loaded in the host page: Mermaider does not embed web font @import rules in SVG output.

The type scale is derived from FontSize (default 1rem) via fixed ratios you can override:

Flowchart and state diagrams read three spacing options. Other diagram types use fixed spacing.

var options = new RenderOptions
{
    Padding      = 16,
    NodeSpacing  = 36,
    LayerSpacing = 40,
    RoundedEdges = true,
};

1. canvas padding in px (default 16)
2. gap between siblings in a layer (default 36)
3. gap between layers (default 40; state diagrams use at most 30)
4. rounded bends on edge paths (radius from the style preset)