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:

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:

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:

Below the library is a row of buttons:

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:

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:

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.