Semantic tokens

Updated: Sep 24, 2026

Choose semantic tokens by the role an element plays, not by a token’s current resolved value. For example, --uit-color-text-secondary means “supporting text,” not a particular gray. Role-based choices let the toolkit evolve while applications retain the intended hierarchy, contrast, and rhythm.

Use semantic tokens: Use the toolkit’s semantic tokens for colors, typography, spacing, corner radii, icon sizes, opacity, and elevation. Avoid hardcoded resolved values, including values that resemble plain white, black, transparent, or a familiar dimension.

Where tokens live

App loads the stylesheet that makes the complete --uit- custom-property namespace available on :root. The toolkit does not expose resolved color, spacing, or typography values through a JavaScript object. The CSS custom properties, uit-* utility classes, and component role enums form the public token surface.

TextAppearance is the only exported token-like object in this surface, and it contains class names rather than values. Two groups differ:

Motion is available only through exported constants and has no custom properties.
The radius scale is available both through custom properties and as CornerRadius, because shape providers are configured in TypeScript. See Corner radius.

Spacing

The --uit-spacing-* scale runs from smallest to largest:

--uit-spacing-2xs      --uit-spacing-xsmall   --uit-spacing-small
--uit-spacing-sm-med   --uit-spacing-medium   --uit-spacing-med-lg
--uit-spacing-large    --uit-spacing-xlarge   --uit-spacing-2xl
--uit-spacing-3xl      --uit-spacing-4xl      --uit-spacing-5xl

Use these tokens for gaps, padding, and margins between components. Spacing explains which step typically fits each relationship.

Corner radius

--uit-corner-radius-xxsmall   --uit-corner-radius-xsmall
--uit-corner-radius-small     --uit-corner-radius-medium
--uit-corner-radius-large     --uit-corner-radius-xlarge
--uit-corner-radius-2xlarge   --uit-corner-radius-3xlarge
--uit-corner-radius-full

Use --uit-corner-radius-full for a pill shape. See Corner radius for the complete scale and shape guidance.

Icon size

--uit-icon-2xs     --uit-icon-xsmall   --uit-icon-small
--uit-icon-medium  --uit-icon-large    --uit-icon-xlarge
--uit-icon-2xl

Use these tokens to size custom inline SVG artwork. Toolkit components size their own icons; see Icons.

Opacity and elevation

Token	Role
`--uit-enabled-opacity`	Opacity of an enabled control.
`--uit-disabled-opacity`	Opacity of a disabled control.
`--uit-elevation-default`	Shadow blur at rest.
`--uit-elevation-focused`	Shadow blur while targeted by focus.
`--uit-elevation-pressed`	Shadow blur while pressed.

Color

Choose a color token from the family that describes what it paints. Each family below uses the corresponding --uit-color- prefix in the stylesheet.

Family	Roles
Text	`--uit-color-text-primary`, `-secondary`, `-placeholder`, `-active-hover`, `-accent`, `-inverse`
Icon	`--uit-color-icon-primary`, `-secondary`, `-placeholder`, `-active-hover`, `-accent`, `-inverse`
Border	`--uit-color-border-primary`
Background	`--uit-color-background-window`, `-surface`, `-elevation1`, `-elevation2`, `-elevation3`, `-backface`, `-inset`, `-inset2`, `-flat`, `-shade`, `-track`, `-input-field`, `-input-field-primary`, `-message-inbound`, `-message-outbound`
Interactive	`--uit-color-interactive-stroke-idle`, `-stroke-targeted`, `-stroke-pressed`, `-stroke-highlight`, `-fill-pressed`, `-text-highlight`, `-text-edit`
Button	`--uit-color-button-primary-background`, `-secondary-background`, `-primary-targeted-background`, `-primary-targeted-highlight`, `-toggle-active-icon`, `-toggle-active-background`
Control	`--uit-color-control-idle`, `-active`, `-active-background`
Status	`--uit-color-persistent-action`, `-positive`, `-warning`, `-negative`, `-info`, `-active`, `-caution`, `-unread`, `-notification`, `-recording`, `-inactive`
Loading	`--uit-color-loading-content`, `--uit-color-loading-glimmer`
Container	`--uit-color-container-primary-`, `--uit-color-container-secondary-`, `--uit-color-container-message-inbound-`, `--uit-color-container-message-outbound-`, `--uit-color-container-glow`
Accent	`--uit-color-accent-red`, `-orange`, `-yellow`, `-olive`, `-green`, `-shamrock`, `-teal`, `-cyan`, `-blue`, `-indigo`, `-purple`, `-violet`, `-pink`, `-rose`, `-gray`

Two families are not direct customization surfaces. --uit-color-background-elevation3 is reserved within the elevation ramp, and the material system consumes the --uit-color-container-* roles. Use the material APIs to customize material paint instead.

Colors describes each role and when to choose it.

Typography

Apply a complete typography appearance rather than assembling individual font properties. Each appearance owns its family, size, weight, line height, and block metrics as one contract; the toolkit does not provide piecemeal font custom properties.

uit-text-numeral1  uit-text-numeral2  uit-text-display1
uit-text-heading1  uit-text-heading2
uit-text-body1     uit-text-body1-emphasized
uit-text-body2     uit-text-body2-emphasized
uit-text-label     uit-text-label-emphasized
uit-text-meta1     uit-text-meta1-emphasized
uit-text-meta2     uit-text-meta2-emphasized
uit-text-meta3

The exported TextAppearance object maps a constant to each class name:

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

<p className={TextAppearance.META2}>Updated moments ago</p>

See Typography for appearance roles and standard information stacks.

Motion

Motion values are exported constants rather than CSS custom properties. Build transitions from these constants to keep timing consistent:

import {
  AnimationDurations,
  Interpolators,
  createTransition,
} from '@wearables-ui-toolkit/mrbd';

const transition = createTransition(
  'opacity',
  AnimationDurations.CONTAINER_STATE_CHANGE,
  Interpolators.CONTAINER_SCALE,
);

SpringConfigs provides matching spring presets for useSpringAnimation. See Motion overview.

Component-anatomy variables are not tokens

Some stylesheet variables define the internal metrics of a single component. These variables belong to that component and are not public tokens. Do not read, override, or reuse them; changing component anatomy can misalign its visual geometry, focus bounds, and hit area.

Consume tokens in CSS

.summary-block {
  display: flex;
  flex-direction: column;
  gap: var(--uit-spacing-med-lg);
  padding: var(--uit-spacing-large);
  border-radius: var(--uit-corner-radius-medium);
}

.summary-block__meta {
  color: var(--uit-color-text-placeholder);
}

Consume tokens through component props

When a component exposes a semantic choice, prefer its enum to custom CSS. These enums intentionally accept a closed set of roles rather than raw color strings.

import { TextColor, TextStyle, TextView } from '@wearables-ui-toolkit/mrbd';

<TextView textStyle={TextStyle.BODY1}>Route updated</TextView>
<TextView textStyle={TextStyle.META2} textColor={TextColor.SECONDARY}>
  2 MINUTES AGO
</TextView>

Components that render icons, subtitles, or timestamps expose role-specific enums such as IconTintColor, SubtitleTextColor, and TimestampTextColor. These enums resolve to the same underlying color roles.

Apply the utility class to secondary foregrounds

Secondary text and icons use two pieces together: the secondary color role and a lighten blend that lifts the dimmed glyph from its material. A CSS custom property can substitute only one declaration, so the color variable alone cannot provide the blend.

TextView and other toolkit components apply both pieces when the secondary role is selected. For custom markup or inline SVG, apply the public utility class:

<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>

Blending does not inherit. Apply the utility to the element that paints the foreground, or to a wrapper when its entire subtree should blend. Custom SVG artwork must use currentColor for the icon utility to color it. Avoid applying the icon utility to full-color bitmap or brand artwork.

Recommended practices

Pick each token for its semantic role in the interface so its meaning remains stable when the theme evolves.
Keep raw values only for domain data and quantities defined by an external API.
Avoid choosing a token solely because its current appearance matches a mock.
Keep hardcoded values out of min(), max(), clamp(), grid tracks, and shadow syntax. Changing an arbitrary value to em or rem does not make it semantic.
Let layout respond to available space and intrinsic component sizes rather than a hardcoded viewport or device dimension.

See also:Theming, Theme API, Colors, Typography, Spacing.