Colors

Updated: Sep 24, 2026
Choose each toolkit color by its semantic role: dominant content, supporting content, emphasis, status, or surface. Roles stay stable even when their resolved values change. The additive-light display makes this more important than on an ordinary screen — content is drawn as light over the world, so contrast comes from the role system rather than from a page background you control.
All roles are CSS custom properties in the --uit-color- namespace, declared at the document root by the library stylesheet. No palette object, color constant, or resolved color value is exported from JavaScript: read a role with var() from CSS, or select one through a component’s color enum.

Foreground roles

TokenRole
--uit-color-text-primary
Dominant text.
--uit-color-text-secondary
Supporting text. Requires the secondary utility class — see below.
--uit-color-text-placeholder
Placeholder or not-yet-entered text.
--uit-color-text-active-hover
Text in an active or hovered state.
--uit-color-text-accent
Emphasized or actionable text.
--uit-color-text-inverse
Text on an inverted foreground, such as a filled toggle.
--uit-color-icon-primary
Dominant icon glyphs.
--uit-color-icon-secondary
Supporting icon glyphs. Requires the secondary utility class.
--uit-color-icon-placeholder
Placeholder icon glyphs.
--uit-color-icon-active-hover
Icon glyphs in an active or hovered state.
--uit-color-icon-accent
Emphasized or actionable icon glyphs.
--uit-color-icon-inverse
Icon glyphs on an inverted surface.
--uit-color-border-primary
Hairline separation between regions.

Background roles

TokenRole
--uit-color-background-window
The document and application window. Keep the page on this role.
--uit-color-background-surface
The base surface a component sits on.
--uit-color-background-elevation1
First raised level.
--uit-color-background-elevation2
Second raised level.
--uit-color-background-elevation3
Third raised level.
--uit-color-background-backface
The reverse face of a card or stacked surface.
--uit-color-background-inset
Recessed area within a surface.
--uit-color-background-inset2
Lighter recessed area.
--uit-color-background-flat
Fully transparent background for a surface that should not paint.
--uit-color-background-shade
Shade drawn over content, such as behind an overlay.
--uit-color-background-message-inbound
Received-message bubble.
--uit-color-background-message-outbound
Sent-message bubble.
--uit-color-background-input-field
Text entry field.
--uit-color-background-input-field-primary
Emphasized text entry field.
--uit-color-background-track
Track behind a slider or progress fill.

Interactive and control roles

TokenRole
--uit-color-interactive-stroke-highlight
Highlight stroke on an interactive surface.
--uit-color-interactive-stroke-targeted
Stroke while the surface is targeted by focus.
--uit-color-interactive-stroke-pressed
Stroke while the surface is pressed.
--uit-color-interactive-stroke-idle
Stroke at rest.
--uit-color-interactive-fill-pressed
Fill applied on press.
--uit-color-interactive-text-highlight
Selection highlight behind text.
--uit-color-interactive-text-edit
Editing affordance behind text.
--uit-color-control-idle
Control fill at rest, such as a slider or thumb.
--uit-color-control-active
Control fill when active.
--uit-color-control-active-background
Background behind an active control.
--uit-color-button-primary-background
Primary button surface.
--uit-color-button-secondary-background
Secondary button surface.
--uit-color-button-primary-targeted-background
Primary button surface while targeted.
--uit-color-button-primary-targeted-highlight
Highlight on a targeted primary button.
--uit-color-button-ai-response-background
Surface for an assistant response button.
--uit-color-button-toggle-active-icon
Glyph on an active toggle.
--uit-color-button-toggle-active-background
Surface of an active toggle.

Status roles

Use persistent roles only for their documented meaning. This is required so status remains consistent and is not reduced to decoration.
TokenRole
--uit-color-persistent-action
Actionable emphasis.
--uit-color-persistent-positive
Success or confirmation.
--uit-color-persistent-warning
Warning.
--uit-color-persistent-negative
Error or destructive outcome.
--uit-color-persistent-info
Informational status.
--uit-color-persistent-active
Currently active state.
--uit-color-persistent-caution
Caution, between warning and negative.
--uit-color-persistent-unread
Unread marker.
--uit-color-persistent-notification
Notification marker.
--uit-color-persistent-recording
Recording in progress.
--uit-color-persistent-inactive
Explicitly inactive or unavailable.

Loading roles

TokenRole
--uit-color-loading-content
The placeholder body of a shimmer skeleton.
--uit-color-loading-glimmer
The travelling highlight that sweeps across it.

Container ramp roles

The --uit-color-container-* roles are the color ramp the material system paints interactive surfaces from. A ramp is an idle fill plus four focused gradient steps, from the bright core of the focus origin out to the dark extent, plus a glow tint for the focus stroke.
RampTokens
Primary
--uit-color-container-primary-idle and --uit-color-container-primary-target-step1 through -step4
Secondary
--uit-color-container-secondary-idle and --uit-color-container-secondary-target-step1 through -step4
Glow
--uit-color-container-glow
Inbound message
--uit-color-container-message-inbound-target-step1 through -step4, and --uit-color-container-message-inbound-glow
Outbound message
--uit-color-container-message-outbound-target-step1 through -step4, and --uit-color-container-message-outbound-glow
The message ramps take their idle fill from --uit-color-background-message-inbound and --uit-color-background-message-outbound.
These roles belong to the material system. To change how a surface is painted across its states, pass a ContainerMaterial to a material host instead of reading or overriding these directly. MaterialLibrary.themedPrimary(theme) takes a complete ramp — an idle fill, four gradient steps, and a glow tint — and recolors the standard material stack from it, which is the supported way to give a surface a ramp of its own. See Materials overview and Material library.

Accent roles

The --uit-color-accent-* family covers red, orange, yellow, olive, green, shamrock, teal, cyan, blue, indigo, purple, violet, pink, rose, and gray. Use accents for categorical distinction between items. Use the matching persistent role for status so the meaning stays consistent.

Choosing a color from a component

Where a component exposes a color choice, it exposes a closed enum of roles, not a color string. This keeps per-instance raw colors out of the API.
import { TextColor, TextView } from '@wearables-ui-toolkit/mrbd';

<TextView textColor={TextColor.ACCENT}>Connected</TextView>
EnumMembers
TextColor
PRIMARY, SECONDARY, PLACEHOLDER, ACTIVE_HOVER, ACCENT
IconTintColor
PRIMARY, SECONDARY, ACCENT, ON_CHECKED, ACTION, POSITIVE, WARNING, NEGATIVE, INFO
SubtitleTextColor
PRIMARY, SECONDARY, POSITIVE, WARNING, NEGATIVE, INFO
TimestampTextColor
PRIMARY, SECONDARY, ACCENT
IconTintColor deliberately mixes families: PRIMARY, SECONDARY, and ACCENT resolve to the matching --uit-color-icon-* roles, ON_CHECKED resolves to --uit-color-button-primary-background — the glyph color for an icon sitting on a filled or checked control — and ACTION, POSITIVE, WARNING, NEGATIVE, and INFO resolve to the matching persistent status roles. TimestampTextColor resolves to --uit-color-text-primary, --uit-color-text-secondary, and --uit-color-text-accent.

Resolving a tint for your own content

When custom content has to sit beside a toolkit component and carry the same tint, resolve it rather than re-deriving it. Two pairs of resolver functions are exported; each returns a var(--uit-…) reference and the mix-blend-mode the role requires, which is 'lighten' for the secondary role and undefined otherwise.
import {
  IconTintColor,
  getIconTintBlendMode,
  getIconTintCSSVariable,
} from '@wearables-ui-toolkit/mrbd';

function StatusGlyph({ tint }: { tint: IconTintColor }) {
  return (
    <svg
      aria-hidden="true"
      style={{ color: getIconTintCSSVariable(tint), mixBlendMode: getIconTintBlendMode(tint) }}
    >
      {/* Paths paint with currentColor. */}
    </svg>
  );
}
getTimestampTextCSSVariable and getTimestampTextBlendMode do the same for TimestampTextColor. There is no equivalent resolver for TextColor — use TextView, or the appearance class plus the secondary utility class below.

The secondary foreground contract

Secondary foregrounds are the one case where the color role is not enough. A dimmed glyph over a material needs a lighten blend to stay legible, and a CSS custom property cannot add a second declaration. So the secondary role ships as a utility class that supplies both parts:
<p className="uit-text-body2 uit-color-text-secondary">Supporting details</p>
<svg className="uit-color-icon-secondary" aria-hidden="true">
  {/* Paths paint with currentColor. */}
</svg>
Components apply this automatically when you select TextColor.SECONDARY, IconTintColor.SECONDARY, or the equivalent role on a component enum. The blend is rendering behavior, not a customizable design token.
Blending does not inherit, so apply the utility to the element that paints the foreground, or to a wrapper whose whole rendered subtree should blend.
  • Choose a role by meaning and let the theme resolve its value, so themes can change without changing content semantics.
  • Keep the page on the window background and add legibility with Panel, StaticContainer, Surface, or a card scrim.
  • Pair color with an icon, label, or shape. State must not rely on color alone.
  • Paint monochrome icon artwork from currentColor so semantic tints apply.

Avoid

  • Use semantic tokens instead of hardcoded colors, including white, black, and transparent.
  • Choose a token for its role rather than its current resemblance to a mock.
  • Keep persistent status roles for status, not decoration.
  • Preserve the original colors of photographic and brand artwork.
  • Customize through public props and tokens rather than component internals; secondary color variables also require their utility class.
Semantic tokens, Theme API, Typography, Materials overview, Material library.