Theme tokens

The widget loader exposes a single contract for visual customization: a flat set of --hw-* CSS custom properties. Every widget reads from these variables — recolor them once and every mounted widget picks up the new palette without touching the loader bundle.

This page lists every variable the loader writes, how it maps to the underlying token system, and how to override it at three different levels.

How overrides flow

The loader resolves theme tokens in this order, last write wins:

1. Built-in defaults — light or dark palette baked into the loader.
2. data-theme-vars — JSON-encoded --hw-* map on the script tag (set once when you paste the embed).
3. window.HatchedWidgets.remount({ themeVars }) — runtime overrides pushed from your host page after the embed has mounted. See the Runtime configuration guide for details.

Any key that does not begin with --hw- is dropped by the loader's style serializer, so you can't accidentally leak host-page CSS variables into the shadow DOM. Pass strings only; the loader does not parse JS values.

Try it

The playground writes overrides into a mock widget styled with the same tokens as the production loader. Adjust a token to see exactly which surface it controls, then copy the script tag at the bottom into your real embed.

<script
  src="https://cdn.hatched.live/widget.js"
  data-embed-token="EMBED_OR_SESSION_TOKEN"
  data-theme="light"
  data-theme-vars='{"--hw-accent":"#FF6B4A"}'
  defer
></script>

Reference

Surfaces

Borders

Text

Accent (primary brand color)

The accent ramp is what most tenants override first. Pick a brand hue for --hw-accent, derive a darker --hw-accent-strong for hover and a tinted --hw-accent-soft for chips/pills.

Semantic colors

Geometry

Typography

The loader ships Geist for body copy and Gluten for the playful display family by default. Override these to inherit the host site's fonts — the loader injects the fallback chain you provide; it does not bundle additional webfonts.

Other geometry primitives

Alias tokens (you don't need to set these)

A handful of widgets reference parallel token names that resolve to the canonical tokens above. You never have to set them — override the canonical token and the alias follows automatically. They exist only so older widget styles keep working; listing them here so nothing looks "missing".

Optional overrides (no loader default)

These tokens are not written by the loader's :host block, so they have no Light/Dark default of their own. They are only read as the first choice in a var() fallback chain — leave them unset and the listed fallback applies; set them with data-theme-vars (or remount) to take control of that one surface.

Setting tokens from the script tag

The simplest path: pass a data-theme-vars attribute on the loader script. The value is JSON, keys are CSS variable names, values are strings.

<script
  src="https://cdn.hatched.live/widget.js"
  data-embed-token="EMBED_OR_SESSION_TOKEN"
  data-theme="light"
  data-theme-vars='{"--hw-accent":"#5B5BFF","--hw-accent-strong":"#3F3FFF","--hw-accent-soft":"#E4E4FF","--hw-radius":"20px"}'
  defer
></script>

<div data-hatched-mount="buddy"></div>

Keys without the --hw- prefix are dropped on parse — there is no way to leak unrelated host-page variables.

Setting tokens at runtime

When the host application is an SPA and the embed has already mounted, push new tokens through the public API:

window.HatchedWidgets.remount({
  themeVars: {
    '--hw-accent': '#5B5BFF',
    '--hw-accent-strong': '#3F3FFF',
    '--hw-accent-soft': '#E4E4FF',
  },
});

remount() re-runs mount discovery and updates the in-memory config — already-mounted widgets receive the new tokens via their shadow-DOM style elements, no flicker.

Tips

• Light + dark with one accent ramp. Override --hw-accent, --hw-accent-strong, and --hw-accent-soft once with data-theme-vars and the loader keeps the rest of the palette in sync with data-theme.
• Densify a sidebar embed. Set --hw-density-scale: 0.85 to drop the vertical rhythm without rewriting every widget's spacing.
• Match host fonts. Override --hw-font-body and --hw-font-display with the host site's fallback chain. The loader does not load additional webfonts — the host page is responsible for serving them.
• Round buttons but square cards. Tokens are independent: pick --hw-button-radius: 9999px for pill buttons while keeping --hw-card-radius: 8px.

Companion docs

• Widget integration guide — how to paste the embed, choose a mode, and respond to events.
• Widget reference — every widget and the data-* attributes it accepts.
• @hatched/widgets-loader-types — IDE autocomplete for themeVars and window.HatchedWidgets.