Theme API

Use CSS custom properties to theme the toolkit. App loads the packaged stylesheet, which declares every --uit-* property at the document root for components to read. Override supported properties with ordinary CSS rules.

There is one theme. The toolkit has no light or dark mode and no mode switch; theming means re-pointing individual semantic roles.

There is no JavaScript theme object, no palette export, no useTheme hook, and no provider that carries design values. Only three theme identifiers are exported from the package:

import { TextAppearance } from '@wearables-ui-toolkit/mrbd';

<figcaption className={TextAppearance.META2}>Source</figcaption>

Everything else in the theme is either a CSS custom property or a closed component enum such as TextColor, TextStyle, IconTintColor, SurfaceCornerRadius, or CornerRadius. Component enums are values you pass to a component or a shape provider, not a general way to read design values in JavaScript.

The two exceptions that return a token reference rather than a token value are getIconTintCSSVariable and getTimestampTextCSSVariable, which resolve a tint enum to a var(--uit-…) string for custom content. They are documented on the Colors page.

The reset is deliberately scoped to the element App marks with data-app-root, and it carries no specificity weight, so it neither leaks into the surrounding document nor overrides component styles.

Tokens stay global on purpose: they are additive values that must resolve for any toolkit component, including overlays rendered through the floating portal root.

The opacity pair expresses the enabled and disabled states of content; use it rather than a literal opacity. The elevation trio is the shadow blur that corresponds to a surface’s resting, focused, and pressed states; use it rather than a literal blur.

The stylesheet additionally declares component-anatomy variables — minimum row heights, internal icon container sizes, divider thickness, scroll fading-edge lengths — that a single component uses for its own internal metrics. Those belong to that component: do not read them, override them, or reuse them to size your own content.

App paints its own root with var(--uit-color-background-window), but the document behind it is yours. Give html, body, and the mount root the same role so nothing shows through at the edges or during a route transition:

html,
body,
#root {
  height: 100%;
  background-color: var(--uit-color-background-window);
}

Override on [data-app-root] for the whole application:

[data-app-root] {
  --uit-color-text-accent: var(--app-color-accent);
  --uit-color-persistent-action: var(--app-color-action);
}

App forwards className and style to that same root element, so an override can also travel with the component tree instead of relying on the attribute selector:

import { App } from '@wearables-ui-toolkit/mrbd';

<App className="product-theme">{/* routes */}</App>

.product-theme {
  --uit-color-text-accent: var(--app-color-accent);
}

Override on a smaller ancestor for one intentional subtree:

.product-status {
  --uit-color-text-accent: var(--app-color-status-accent);
}

Custom properties inherit, so a subtree override reaches every toolkit component rendered inside that element. Portaled content is the exception worth knowing about: the tooltip an interactable shows is rendered into the floating portal root inside App rather than inside the element that owns it, so it picks up an override made on the App root but not one made on a deeper subtree. When an override has to reach a portaled surface, apply it on the App root — either through [data-app-root] or through the class you passed to App.

Source the values from your application’s own semantic tokens rather than writing literals into component CSS.

Supported overrides re-point semantic roles: foreground and background colors, interactive and persistent colors, spacing, corner radii, icon sizes, opacity, and elevation.

Overrides must not:

Secondary text and icons must use the utility classes. A color custom property substitutes a value into one declaration, so it cannot also apply the blend the secondary role requires.

For a different stateful paint — how a surface transitions between idle, targeted, and pressed — pass a ContainerMaterial to a material host instead of overriding colors. A token override and a material are not interchangeable.

Check the states users can reach: idle, targeted, pressed, disabled, selected, partial focus, and loading, plus any route transition or focus handoff on the screen. Colors that read well at idle often fail at the focused and pressed extremes, where the material gradient and glow dominate.

Theming, Semantic tokens, App, Materials overview.