Themes

A theme is a set of color tokens — the colors of lines, ports and labels in one place. It is written to CSS variables on the diagram, so a theme can be swapped at runtime and plain CSS can still override any token.

import { createVisualLinker, darkTheme } from '@macrulez/visual-linker-core'

const linker = createVisualLinker(el, { theme: darkTheme })

Tokens

Each token maps to one CSS variable. The values are those of lightTheme:

• line — --vl-line-color · #2e8b57. The color of every line at rest; markers, port outlines and label borders follow it unless set.
• lineHover — --vl-line-color-active · #2e8b57. The color of a line in the hover and highlight states.
• lineSelected — --vl-line-color-selected · #2e8b57. The color of a selected line; falls back to lineHover.
• selectedHalo — --vl-selected-color · #1f6feb. The glow around a selected line.
• focusRing — --vl-focus-color · #1f6feb. The glow around a line with keyboard focus.
• portFill — --vl-port-fill · #ffffff. The fill of the built-in port dot.
• portStroke — --vl-port-stroke-color · #2e8b57. The outline of the port dot.
• labelBackground — --vl-label-bg · #ffffff. The pill behind a label's text.
• labelBorder — --vl-label-border · #2e8b57. The outline of that pill.
• labelText — --vl-label-color · #1c1e2b. The text of a label.

A token that the theme leaves out writes nothing, so the built-in value, or a variable from your own CSS, stays in effect.

Built-in themes

lightTheme and darkTheme are included. darkTheme uses lighter lines (#6fcf97, #a8efc6 on hover, #8ab4ff when selected) and dark ports and labels (#1b1d2b) with light text (#e6e8f2).

Making a theme

defineTheme(overrides, base) returns a copy of base — lightTheme by default — with the tokens you give:

import { darkTheme, defineTheme } from '@macrulez/visual-linker-core'

const midnight = defineTheme(
  {
    line: '#8b9bff',
    lineHover: '#c4ccff',
    lineSelected: '#ffd479',
    portFill: '#14162a',
    portStroke: '#8b9bff',
  },
  darkTheme,
)

A theme is a plain object, so it can also be written by hand, or put together from your design tokens.

Switching themes

In the engine, change the theme field of the configuration. A key set to undefined removes its variable again:

linker.setConfig({ theme: lightTheme })
linker.setConfig({ theme: { line: undefined } })

In Vue and Nuxt, change the shared configuration once and every diagram on the page follows — see Shared Configuration.

Theme and other settings

A theme provides defaults. A value set for a group or an entity wins over it: lines.color beats line, a connection's style.color beats both. Markers, port outlines and label borders take their colors from the line color of the moment, theme included, so a theme change recolors them too.

Because a theme only writes CSS variables, the same tokens can be set from a stylesheet, for instance to follow prefers-color-scheme:

.diagram {
  --vl-line-color: #2e8b57;
}

@media (prefers-color-scheme: dark) {
  .diagram {
    --vl-line-color: #6fcf97;
  }
}

Tokens set by a theme in the configuration are written onto the diagram's own element and take precedence over variables inherited from your stylesheet. Marker colors are worked out by the engine from the configuration and the theme, not read back from CSS, so a marker follows a stylesheet-only color only if you also set that color in the theme.