Interface: ThemeBundle

Defined in: Types.ts:256

A theme bundle packages a complete ThemeTokens (the base) with an optional semantic-only override for the alternate color mode.

• baseMode declares which mode the base theme represents.
• alternate remaps only semantic token references that differ in the opposite mode. Core token values stay immutable.

Why only two modes? prefers-color-scheme is binary (light / dark); that is the only axis ThemeBundle addresses. High-contrast, reduced-motion, and coarse-pointer are orthogonal CSS @media axes — they are handled by the dedicated blocks emitted by toCssVars and are not additional modes. Proposals to generalize to Record<ModeName, ModeOverride> conflate these independent axes and should be rejected.

When no alternate is provided, the theme is single-mode.

Example

const bundle: ThemeBundle = {
  baseMode: 'light',
  base: baseTheme,
  alternate: {
    semantic: {
      colors: {
        informational: { primary: { background: { default: '{core.colors.neutral.900}' } } },
      },
    },
  },
};

Properties

alternate?

optional alternate?: ModeOverride

Defined in: Types.ts:268

Semantic remapping overrides for the opposite mode. Only semantic references that differ need to be listed — core tokens are shared.

---

base

base: ThemeTokens

Defined in: Types.ts:263

Complete theme for the base mode.

---

baseMode

baseMode: "light" | "dark"

Defined in: Types.ts:261

Which color mode the base theme represents. Constrained to 'light' | 'dark' because prefers-color-scheme is binary.

---

meta?

optional meta?: ThemeBrief

Defined in: Types.ts:275

Machine-readable design brief (posture, density, accessibility target, …). Orthogonal to tokens — never serialized into DTCG/CSS. Optional so existing callers stay valid; carrying one lets FSL-DESIGN-001..003 be enforced.

See

ThemeBrief