Design Tokens

Headless Design Tokens; covers CSS cascade layers, CSS custom properties, semantic feedback tones.

API

setThemeTokens

Override theme tokens on one element's subtree.

function setThemeTokens( element: ElementCSSInlineStyle, overrides: ThemeTokenOverrides, ): () => void

themeCascadeLayerOrder

Cascade layers shipped by the package, in ascending priority order.

const themeCascadeLayerOrder

themePresetAttribute

Attribute whose space-separated values opt a subtree into presets.

const themePresetAttribute

themeDensityAttribute

Attribute that retunes the density factor for a subtree.

const themeDensityAttribute

themePresets

Presets shipped in @layer vize.preset, ordered from least to most opinionated.

const themePresets: readonly ThemePresetName[]

themeDensityScales

Density factors mirrored from the data-vize-density scopes in theme.css.

const themeDensityScales: Readonly<Record<ThemeDensityScale, string>>

themeScopeStorageKeys

Storage keys read by createThemeBootstrapScript.

const themeScopeStorageKeys: Readonly<Record<ThemeScopeStorageKeyName, string>>

themeScopeAttributes

Normalize theme scope options into renderable attributes.

function themeScopeAttributes( scope: ThemeScopeOptions = {}, ): Readonly<ThemeScopeAttributes>

applyThemeScope

Apply theme scope attributes to one element and return a restorer. This is the imperative counterpart to rendering themeScopeAttributes in Vue. Only provided attributes are touched; unrelated consumer attributes and nested scopes remain owned by the application.

function applyThemeScope(element: Element, scope: ThemeScopeOptions): () => void

createThemeBootstrapScript

Create a small inline script that applies persisted theme attributes before paint. The script validates stored values against this package's published preset and density lists, falls back to server-rendered defaults when storage is empty or blocked, and otherwise does nothing on non-browser runtimes.

function createThemeBootstrapScript(options: ThemeBootstrapOptions = {}): string

themeTokenPackNames

Independent token packs that can be composed with any preset.

const themeTokenPackNames: readonly ThemeTokenPackName[]

themeTokens

Semantic token contract mirrored from theme.css. The packaged stylesheet is the source of truth; this mirror exists so JavaScript consumers can read the same headless defaults the CSS ships with. Preset values are deliberately not mirrored: presets are opt-in cascade, not API.

const themeTokens: Readonly<Record<ThemeTokenName, string>>

themeTokenProperty

Custom-property name (--vize-ui-*) for one theme token.

function themeTokenProperty(name: ThemeTokenName): string

themeTokenVar

var() reference to one theme token for imperative style composition.

function themeTokenVar(name: ThemeTokenName): string

themeTokensForPack

Tokens in one independent token pack, derived from the shared token mirror.

function themeTokensForPack(pack: ThemeTokenPackName): readonly ThemeTokenName[]

Behavior

Normative contract for the theme family (@vizejs/ui/theme): the semantic design-token contract, the package-wide cascade-layer order, and the opt-in presets. The stylesheet contract is proven on the packaged dist/style.css and the CSS-only dist/theme.css / dist/theme-preset-*.css entrypoints (the pack pipeline lowers src/families/foundations/theme/theme.css and the preset files src/families/foundations/theme/theme-preset-headless.css, src/families/foundations/theme/theme-preset-atelier.css, src/families/foundations/theme/theme-preset-midnight.css, src/families/foundations/theme/theme-preset-paper.css, src/families/foundations/theme/theme-preset-play.css, src/families/foundations/theme/theme-preset-signal.css, and src/families/foundations/theme/theme-preset-high-contrast.css to the declared browser floor; see style-pipeline.behavior.md) in src/families/foundations/theme/theme-stylesheet.test.ts; runtime rows are proven by the named test in src/families/foundations/theme/theme.test.ts or src/families/foundations/theme/theme-ssr.test.ts; compile-only assertions live in src/families/foundations/theme/theme.types.test-d.ts.

Cascade-layer order and specificity budget

• The package ships exactly four cascade layers, in ascending priority: vize.tokens (semantic defaults) < vize.ui (behavior-critical component styles) < vize.preset (opt-in visual presets) < vize.policy (accessibility stand-downs such as forced colors). src/families/foundations/theme/theme.css declares the order once; packaged CSS concatenates in src/index.ts module order, so the theme export stays directly after field-wiring and the statement leads dist/style.css.
• Specificity budget: every rule in every vize layer sits on a :where() selector at specificity (0,0,0) — pseudo-elements keep only their intrinsic element specificity. Consumer CSS outside the vize layers always wins, and consumer @layer rules win by declaring their layers later.

Extension contract

• Every token is a --vize-ui-* custom property defined at zero specificity: a consumer rule outside the layers — or a setThemeTokens override on an ancestor — replaces any role for a whole subtree without forking components. --vize-ui-focus-ring-color resolves through --vize-ui-color-accent, and space/size tokens resolve through --vize-ui-density, so one override retunes a whole phase.
• Feedback tones are color tokens: --vize-ui-color-neutral, --vize-ui-color-info, --vize-ui-color-success, --vize-ui-color-warning, --vize-ui-color-danger, and each *-contrast pairing. Headless defaults stay system-palette aligned, while presets make the tones visually distinct for badge, alert, status, and future feedback chrome.
• data-vize-theme holds space-separated preset names and is inert without the shipped preset CSS; headless is an explicit no-visual-opinion preset for persisted theme choice, atelier is the Vize brand default, midnight is the dark-first application preset, paper is the editorial preset for content-forward surfaces, play is the expressive consumer-product preset, signal is the dense data/tooling preset, and high-contrast is the legibility-first preset with heavy boundaries and flat elevation. When multiple presets are present, package source order resolves ties, so later shipped presets win. Every opinionated preset must assign every semantic color role with a scheme-aware value, plus every elevation role, so a new preset cannot accidentally ship a partial visual surface. data-vize-density accepts compact and comfortable. Both scope by inheritance, so nesting attributes nests themes.
• Consumers that want manual CSS loading can import @vizejs/ui/theme.css for the semantic token and policy layers, then one or more @vizejs/ui/theme-preset-*.css files for visual presets. The public ThemeTokenStylesheetSpecifier and ThemePresetStylesheetSpecifier types mirror those package subpaths for typed integration code without adding runtime weight.
• SSR bootstrapping is CSS-only and flash-free by construction: server-render the attribute (typically on <html>), and preset light-dark() values follow the user's scheme with no runtime script. For persisted user choices, @vizejs/ui/theme-scope creates an optional inline bootstrap script that validates stored values before first paint, falls back to server-rendered defaults, and imports no CSS.
• themeTokensForPack() exposes color, typography, space, size, radius, border, elevation, opacity, z-index, focus, and density packs from the single token mirror. The package does not publish a second runtime token graph for packs, so every new token must remain covered by the gap/overlap test. Motion tokens stay in the motion family (motion.behavior.md).