Themes
Everything about how a Siren diagram looks comes from 42 CSS custom properties, the design tokens, all named --siren-*. One value for each of them is a theme. Changing the theme means neither editing the document nor writing code: you redeclare the tokens.
A theme covers the diagram only. The page background and the board’s control bar are not part of it; the control bar has its own --siren-board-* tokens.
Design tokens
The defaults below are Siren’s own, which is what the site shows in its light mode.
Colors
| Token | What it styles | Default |
|---|---|---|
--siren-node-fill |
The fill of nodes, classes, participants, states and other boxes | #f3efff |
--siren-node-stroke |
The outline of those boxes | #6d3fd6 |
--siren-node-text |
Text in the diagram | #1d1730 |
--siren-edge-stroke |
Edges, arrowheads and message lines | #6f6a84 |
--siren-highlight-color |
The accent of the outline and glow highlights |
#0d9488 |
--siren-label-link |
The text of a link in a label (<a href>) |
#0000ee |
--siren-label-mark-fill |
The background of marked text in a label (<mark>) |
#ff0 |
--siren-label-mark-text |
The text on that background | #000 |
--siren-edge-label-fill |
The background behind a connector’s label, so a line under it does not cross the text | rgb(255 255 255 / 0.8) |
--siren-subgraph-fill |
The fill of a flowchart subgraph’s frame, an ER subgraph’s frame and a composite state’s frame | none |
Text
| Token | What it styles | Default |
|---|---|---|
--siren-font-family |
The typeface | system-ui, sans-serif |
--siren-font-size |
Body text size | 14px |
--siren-title-font-size |
The diagram’s title |
18px |
--siren-label-font-size |
Secondary text: autonumbers, a block’s kind and condition | 12px |
Lines
| Token | What it styles | Default |
|---|---|---|
--siren-stroke-width |
Outlines and edges | 1.5 |
--siren-highlight-stroke-width |
The outline of an outline highlight |
3 |
--siren-edge-thick-stroke-width |
A thick edge (==>); twice the plain width by default |
calc(var(--siren-stroke-width) * 2) |
--siren-lifeline-dash |
The dash pattern of sequence-diagram lifelines | 4 4 |
--siren-edge-dash |
The dash pattern of a dotted edge (-.->) |
4 3 |
--siren-note-link-dash |
The dash pattern of a note’s connector | 4 4 |
Shapes
| Token | What it styles | Default |
|---|---|---|
--siren-node-border-radius |
The corners of rectangle and subroutine nodes; other shapes keep theirs | 6px |
--siren-box-fill-opacity |
How opaque a sequence-diagram box is |
0.35 |
Motion
| Token | What it styles | Default |
|---|---|---|
--siren-fade-duration |
How long a fade enter or exit takes |
600ms |
--siren-slide-duration |
How long a slide-* enter or exit takes |
500ms |
--siren-slide-distance |
How far a slide-* moves |
60px |
--siren-highlight-duration |
How long a highlight takes to apply |
300ms |
--siren-edge-march-dash |
The dash an animated edge (e1@{ animate: true }) marches |
9 5 |
--siren-edge-march-offset |
How far one march cycle moves the dash | 900 |
--siren-edge-march-fast-duration |
How long one cycle of a fast animated edge takes | 20s |
--siren-edge-march-slow-duration |
How long one cycle of a slow animated edge takes | 50s |
Gantt charts
A plain task’s bar is a node, so it takes --siren-node-fill and --siren-node-stroke, and its task labels, section titles and tick labels take --siren-node-text. These twelve paint what only a gantt chart draws.
| Token | What it styles | Default |
|---|---|---|
--siren-gantt-band-fill |
The row band behind the tasks of the first and third section, and every other section after them | #f7f4ff |
--siren-gantt-band-alt-fill |
The row band of the sections in between, alternating with the one above | #ffffff |
--siren-gantt-grid-stroke |
The vertical grid line at each tick of the axis | #e4e1ec |
--siren-gantt-active-fill |
The fill of an active task’s bar |
#ddd0ff |
--siren-gantt-active-stroke |
The outline of an active task’s bar |
#6d3fd6 |
--siren-gantt-done-fill |
The fill of a done task’s bar |
#e6e4ec |
--siren-gantt-done-stroke |
The outline of a done task’s bar |
#6f6a84 |
--siren-gantt-crit-fill |
The fill of a crit task’s bar |
#ffe0e6 |
--siren-gantt-crit-stroke |
The outline of a crit task’s bar, and of an active or done one that is also crit |
#d6336c |
--siren-gantt-today-stroke |
The line marking today | #d6336c |
--siren-gantt-exclude-fill |
The days excludes leaves out, such as weekends |
#eeecf3 |
--siren-gantt-vert-stroke |
A vert marker’s line and its label |
#4b3fa8 |
Styles
Every diagram the site draws is either under a Style or under a Custom theme. A Style is a look of the site’s own: it has a light set and a dark set that follow the light/dark switch in the site’s header, and each set is the 42 design tokens plus the site’s 36 category and role colors. A Style is locked: nobody can change it. The site has several Styles, each with its own colors, lines and motion; the default is Siren, the violet look this site has. A new visitor’s diagrams are under the Siren Style, and the home demo and the example pages always draw Siren. This page describes Siren and gives its values; the other Styles follow the same rules with values of their own.
A document may style its own targets with Mermaid’s style, classDef/class/:::name and linkStyle. Under a Style, the Style takes over these properties of the author’s: fill, stroke, color, stroke-width, stroke-dasharray, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-opacity, fill-opacity, opacity, font-weight, font-style, font-size, font-family, rx, ry, filter, text-decoration and letter-spacing; that list is fixed and cannot be adjusted. Each group of targets the author colored is repainted with the Style’s category and role colors, so the whole diagram is in the Style. Targets the author did not style are drawn from the tokens. A Custom theme does the same: it takes over the same list and repaints with its own category and role colors. A gantt chart’s todayMarker style is taken over too, but it forms no color group and is not repainted: the today line is always drawn in --siren-gantt-today-stroke.
How a Style keeps the author’s meaning
The author’s colors carry meaning: a classDef error block, three nodes painted the same amber. A Style keeps that meaning as color groups, and gives each group one color of its own:
- A named category is a
classDefthat supplies a fill or a stroke, together with the targets it colors. A class that only sets widths or weights forms no group. - An anonymous color group is every target whose color comes from
styleorlinkStyleand normalises to the same color:#f00,redandrgb(255,0,0)are one group. Grouping goes by fill, or by stroke when there is no fill. - A named category whose class name is in the role vocabulary gets its role automatically, matched case-insensitively: error (also
danger,fail,failure,critical), warning (warn,caution), success (ok,pass,done) and info (note,hint). A role is never read from a color: red is not error. - A group with a role takes that role color. Every other group takes the category color whose hue is nearest to the author’s (among the chosen Style’s category colors in the site’s current mode, so switching between light and dark assigns them again; with a Custom theme chosen, among its own category colors, whatever the mode); there are eight, and no two groups share one while one is free. Once all eight are taken, a group gets a derived color, a lighter or darker variant of the nearest category color, and the Diagram colors tab says that there are many categories.
In the Playground the Theme panel’s third tab, Diagram colors, lists the groups with their assigned color, under a Style and under a Custom theme alike: the chosen Style or Custom theme at the top, then two sections, Class (named categories) and Colored directly (anonymous color groups), one card per group, a group colored directly showing the author’s color beside the one it was given. There you can set or cancel a group’s role, merge two anonymous color groups and split them again, and clear color settings that no longer match anything in the diagram. Every confirmed change is written at once into the document’s frontmatter under the top-level siren: key, as one editor step (Ctrl+Z undoes it); nothing else in the document is touched. A document minus that key is still the same Mermaid.
siren:
groups:
- match: [stage]
role: info
Colors written inside a label’s own markup (<span style="color:…">, <font color>, a background-color) are not taken over: they are drawn as written under a Style and under a Custom theme alike.
Category and role colors
Besides the 42 design tokens, each set of a Style carries 8 category colors and 4 role colors, each as a fill, a stroke and a text color: 36 values, named --sirenchart-*. Each Style picks its own category colors, and their hues need not match another Style’s. The Siren Style’s light set is below; to see its dark set, switch this site to dark mode, add a Custom theme from the Siren Style in the Playground and download it: the theme file has it. Nobody edits a Style’s colors. Every Custom theme has 36 values of its own under the same names, one set that does not follow the site’s light/dark switch, and you adjust them color by color on the Custom tab. A Custom theme made on an earlier version of the site, before it had these colors, has each missing color filled in on its own: from the copy that older site kept among the theme’s tokens, if there is one, otherwise from the Siren Style’s light or dark set, whichever node fill is nearer its own (--siren-node-fill) in lightness, and the light set when its node fill is no color.
| Token | What it colors | Light default |
|---|---|---|
--sirenchart-category-1-fill |
Category 1 (red): fill | #fee2e2 |
--sirenchart-category-1-stroke |
Category 1 (red): stroke | #dc2626 |
--sirenchart-category-1-text |
Category 1 (red): text | #7f1d1d |
--sirenchart-category-2-fill |
Category 2 (orange): fill | #ffedd5 |
--sirenchart-category-2-stroke |
Category 2 (orange): stroke | #ea580c |
--sirenchart-category-2-text |
Category 2 (orange): text | #7c2d12 |
--sirenchart-category-3-fill |
Category 3 (yellow): fill | #fef9c3 |
--sirenchart-category-3-stroke |
Category 3 (yellow): stroke | #a16207 |
--sirenchart-category-3-text |
Category 3 (yellow): text | #713f12 |
--sirenchart-category-4-fill |
Category 4 (green): fill | #dcfce7 |
--sirenchart-category-4-stroke |
Category 4 (green): stroke | #15803d |
--sirenchart-category-4-text |
Category 4 (green): text | #14532d |
--sirenchart-category-5-fill |
Category 5 (teal): fill | #ccfbf1 |
--sirenchart-category-5-stroke |
Category 5 (teal): stroke | #0d9488 |
--sirenchart-category-5-text |
Category 5 (teal): text | #134e4a |
--sirenchart-category-6-fill |
Category 6 (sky): fill | #e0f2fe |
--sirenchart-category-6-stroke |
Category 6 (sky): stroke | #0284c7 |
--sirenchart-category-6-text |
Category 6 (sky): text | #0c4a6e |
--sirenchart-category-7-fill |
Category 7 (indigo): fill | #e0e7ff |
--sirenchart-category-7-stroke |
Category 7 (indigo): stroke | #4f46e5 |
--sirenchart-category-7-text |
Category 7 (indigo): text | #312e81 |
--sirenchart-category-8-fill |
Category 8 (pink): fill | #fce7f3 |
--sirenchart-category-8-stroke |
Category 8 (pink): stroke | #db2777 |
--sirenchart-category-8-text |
Category 8 (pink): text | #831843 |
--sirenchart-role-error-fill |
The error role: fill | #fecaca |
--sirenchart-role-error-stroke |
The error role: stroke | #b91c1c |
--sirenchart-role-error-text |
The error role: text | #450a0a |
--sirenchart-role-warning-fill |
The warning role: fill | #fde68a |
--sirenchart-role-warning-stroke |
The warning role: stroke | #b45309 |
--sirenchart-role-warning-text |
The warning role: text | #451a03 |
--sirenchart-role-success-fill |
The success role: fill | #bbf7d0 |
--sirenchart-role-success-stroke |
The success role: stroke | #15803d |
--sirenchart-role-success-text |
The success role: text | #052e16 |
--sirenchart-role-info-fill |
The info role: fill | #bfdbfe |
--sirenchart-role-info-stroke |
The info role: stroke | #1d4ed8 |
--sirenchart-role-info-text |
The info role: text | #172554 |
Siren’s categories are in hue order, red to pink, so a group’s nearest category is the one its own color looks most like. Siren core itself reads none of these: they are the site’s, used only when it repaints a diagram under a Style or a Custom theme.
Changing the theme in the Playground
The icon bar on the Playground’s left switches to Theme, which has three tabs. The button at the foot of the icon bar folds the left column down to the bar, giving the preview the whole width; any icon opens it again on its panel.
Library lists what you can choose, each with swatches of its five colors, in two sections:
- Styles: the site’s Styles, each with a line on how it looks. Every Style follows the site’s light or dark mode and is locked: it cannot be renamed, duplicated, downloaded or deleted, and its row has none of those buttons. A new visitor has Siren chosen.
- Your themes: your Custom themes, named and kept in this browser; the section shows once you have one. While one of them is chosen, switching the site between light and dark leaves the diagram alone; like a Style it takes over the document’s styling and repaints with its own category and role colors, and exporting from the Export panel uses it too.
Each Custom theme’s row ends with four icon buttons. They act on that row without choosing it first, and pressing one does not change which theme is chosen:
- Rename: the row becomes a name field; Enter or clicking elsewhere keeps the new name, Escape cancels.
- Duplicate: adds “X copy” right after it and chooses the copy.
- Download: saves that theme as a theme file; see the next section.
- Delete: in the warning color, after asking; deleting the theme in use takes the diagram back to the Siren Style.
Below the library is a row of buttons:
- New: start from the chosen Style’s set (Siren, the default, when none is chosen) for the site’s current mode (light or dark), its 42 tokens and its 36 category and role colors, as “My theme” (“My theme 2” if that is taken, and so on).
- Upload: pick a theme file and add it as a Custom theme; see the next section. It always works.
The Custom tab adjusts each token of the chosen Custom theme, its 42 tokens in six groups (colors, text, lines, shapes, motion, Gantt charts), then two more, Category colors and Role colors: one row per color, with fill, stroke and text swatches and a small node showing how it looks. The preview follows at once; “Start from light” and “Start from dark” begin it again (after asking), the tokens and the category and role colors together, from the Siren Style’s two sets. With a Style chosen, the tab only says that a Style cannot be changed, and Make one from it adds a Custom theme started from it.
The Diagram colors tab is the one described above under Styles: the color groups and what each was given. With a Custom theme chosen it lists them the same way, in that Custom theme’s own colors. There is no switch.
The Playground has no place to edit CSS directly. To write a theme in CSS, write a theme file and upload it: see the next section.
Theme files (.siren.css)
Press Download on a Custom theme’s row and it saves as a .siren.css file named after it (any of \ / : * ? " < > | in the name, which a file name cannot hold, becomes -). It is plain CSS: a comment at the top, then 78 declarations under :root, first the 42 --siren-* design tokens, then a section each for the category and the role colors. A theme made from the Siren Style’s light set and not yet changed downloads roughly as:
/* A note at the top: load after siren-core/theme.css; only the Siren Playground reads --sirenchart-* */
:root {
--siren-node-fill: #f3efff;
--siren-node-stroke: #6d3fd6;
/* …the rest */
/* Category colours */
--sirenchart-category-1-fill: #fee2e2;
/* …the rest */
/* Role colours */
--sirenchart-role-error-fill: #fecaca;
/* …the rest */
}
Upload such a file to the Playground and the library gains a Custom theme at the end, chosen for you, named after the file without its .siren.css or .css; if nothing is left, it is named “My theme” by the same rule as New. The name may repeat one already there, and nothing already there is replaced. The file is read like this:
- Only these 78 names are read: the 42
--siren-*design tokens and the 36--sirenchart-*category and role colors, under whatever selector or at-rule (such as@media) they sit; if one is declared more than once, the last one wins. Anything inside a comment does not count. - A token the file leaves out takes Siren’s default, except a gantt chart’s: those are worked out from the file’s own node fill, stroke and text and edge stroke, so a dark theme gets a dark gantt chart, legible wherever the theme’s own text color leaves room for it. An older Custom theme, saved before the site had a gantt chart, gets its gantt colors the same way. A category or role color it leaves out is filled in one by one, by the same rule as for an older Custom theme above: from the Siren Style’s light or dark set, whichever node fill is nearer the theme’s own (
--siren-node-fill) in lightness, and the light set when its node fill is no color. - Every other declaration is skipped and counted, including
--siren-board-*, unknown--siren-*or--sirenchart-*names and ordinary CSS properties, as is any declaration whose value containsurl(,expression(, a semicolon, a backslash or!important; so the gradients and patterns described below cannot come into the Playground through a theme file. You are told how many declarations were skipped. - A file with none of the 78 names in it shows an error and leaves the library as it was.
Using a theme on your own site
Declare the --siren-* tokens you want to change on :root after siren-core/theme.css is loaded and they take effect; the rest keep Siren’s defaults. You can also paste a theme file’s contents as they are; its --sirenchart-* colors do nothing outside this site, so you may delete them. Siren itself has one set of values and never switches to dark on its own; for a second theme (dark, high contrast, a projector), declare the tokens again under a selector of your own:
[data-theme="dark"] {
--siren-node-fill: #2a2144;
--siren-node-stroke: #b69cff;
--siren-node-text: #ece8f8;
--siren-edge-stroke: #8e88a3;
--siren-highlight-color: #2dd4bf;
--siren-label-link: #9cc7ff;
/* 80% white by default, a sticker on a dark canvas: the canvas at the same opacity instead */
--siren-edge-label-fill: rgb(20 17 29 / 0.8);
}
Siren’s twelve gantt tokens default to light colors only, so a dark theme declares the --siren-gantt-* tokens as well, or its gantt charts stay light. For a whole dark set ready to use, switch this site to dark mode, add a Custom theme from the Siren Style in the Playground and download it: the theme file has them all.
Declare the tokens on a container instead of :root and only the diagrams inside it change. See Theming in siren-core for the whole story. The --sirenchart-* colors do nothing there: a Style’s and a Custom theme’s colors are this site’s, not Siren’s.
Gradients and patterns
A color token is drawn as SVG paint, so besides a color it can hold url(#id), pointing at a <linearGradient>, <radialGradient> or <pattern> that your page defines in an <svg> of its own:
<svg width="0" height="0" aria-hidden="true">
<defs>
<linearGradient id="node-paint" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#fef3c7" />
<stop offset="1" stop-color="#fbcfe8" />
</linearGradient>
</defs>
</svg>
:root {
--siren-node-fill: url(#node-paint);
}
Every color token can hold one except --siren-highlight-color, which must stay a color: the glow wraps it in drop-shadow(), and a url() there makes the glow disappear without a word. A few more limits:
- A CSS gradient is not SVG paint:
--siren-node-fill: linear-gradient(…)paints black, and nothing reports it. - Give a gradient on lines (
--siren-edge-stroke, or--siren-node-strokewhere it strokes a straight line)gradientUnits="userSpaceOnUse"; with the default, a straight horizontal or vertical edge vanishes with its arrowhead. - The gradient lives on your page, not in the diagram’s
<svg>, so an SVG copied out on its own loses it.
See Gradients and patterns in siren-core for every limit.
Only colors in a label’s markup stay as written
On this site, whether a Style or a Custom theme is chosen, the listed properties in a document’s own style, classDef, class, linkStyle, :::name and a gantt chart’s todayMarker are taken over and every group the author colored is repainted (the today line is always drawn in --siren-gantt-today-stroke), as described above. Only colors written inside a label’s own markup (<span style="color:…">, <font color>, a background-color) are drawn as written.
With siren-core on your own site nothing is taken over: a document’s styling wins over the tokens, since the author named one element and the tokens speak for all of them. So a box the document fills with fill:#fdd keeps that color whatever the theme. For a look that should follow the theme, leave it to the tokens.