Theming

Both elements draw everything inside their shadow DOM, and read every colour, font and size from public --scxml-* custom properties. Set them on the elements, or on any ancestor, to make the elements match your app. Tokens you don't set fall back to the neutral default theme.

The default theme uses system fonts (nothing is downloaded) and one indigo accent. It follows the page's light or dark colour scheme.

Light	Dark

Light and dark#

The elements use the page's color-scheme. A page that declares color-scheme: light dark (or <meta name="color-scheme" content="light dark">) gets the dark theme when the OS is dark; a page that declares nothing gets the light one. To decide for the elements alone, set --scxml-color-scheme to light, dark or light dark:

scxml-view, scxml-explorer { --scxml-color-scheme: light dark; } /* follow the OS */

Your own token values can use light-dark() too, so one declaration covers both schemes.

Tokens#

The defaults are light / dark.

The elements don't load fonts. If a token names a web font, load it in your page.

Keep it readable#

The default theme meets WCAG AA. A theme should keep these pairs at the given contrast ratio; text needs 4.5:1, graphics 3:1:

The elements never use colour alone to show state: active states also get a marker and a name ("active") for screen readers.

Example: your design tokens#

Map your own design tokens onto the contract once, for both elements:

scxml-view,
scxml-explorer {
  --scxml-bg: var(--app-background);
  --scxml-surface: var(--app-card);
  --scxml-fg: var(--app-text);
  --scxml-fg-muted: var(--app-text-secondary);
  --scxml-accent: var(--brand);
  --scxml-accent-text: var(--brand-dark);
  --scxml-on-accent: white;
  --scxml-font-sans: "Inter", sans-serif;
  --scxml-radius: 8px;
}

The package ships one such mapping, for the Tinyactors design system. Import it where your bundler handles CSS, or link it:

import "@tinyactors/scxmljs/themes/tinyactors.css";

It's also a complete example to copy: see themes/tinyactors.css.

Parts#

For anything the tokens don't cover, style the elements' insides with ::part(). Every part and its modifiers are listed in the element references: <scxml-view> and <scxml-explorer>. Modifiers are added to the part name while they apply, so select them together:

scxml-view::part(state active) { box-shadow: 0 0 0 3px gold; }
scxml-view::part(transition fired) { transform: scale(1.1); }
scxml-explorer::part(card waiting) { outline: 2px dashed orange; }
scxml-explorer::part(tree-row match) { background: #ff05; }

Parts are public API: they're only renamed or removed in a release that says so in the changelog. The classes inside the shadow DOM, and the private --x-* custom properties, are not.