Component authoring

• Prefer natural sizing from text and icons, with constraints supplied by the parent. Container, StaticContainer, and Surface default width and height to automatic sizing; set a dimension only when the design fixes it.
• Use semantic tokens for spacing, radii, typography, and color, such as var(--uit-spacing-large), so the component follows system-wide visual updates. Avoid literal values for these properties.
• Size relative to the container rather than the screen. Set min-inline-size: 0 and min-block-size: 0 on flex and grid children so long labels can shrink instead of overflowing.
• Keep one scroll container per axis. An internal scroller on the same axis as the route scroller creates competing focus-driven scrolling and unclear boundaries.

.stat-tile {
  display: grid;
  gap: var(--uit-spacing-xsmall);
  padding: var(--uit-spacing-medium);
  min-inline-size: 0;
}

import { useMemo, type ReactNode } from 'react';
import { Container, createDefaultContainerMaterial } from '@wearables-ui-toolkit/mrbd';

export function ShadowedTile({ children }: { children: ReactNode }) {
  const material = useMemo(
    () => createDefaultContainerMaterial({ withDropShadow: true }),
    [],
  );

  return <Container material={material}>{children}</Container>;
}

import { CornerRadius, RoundedRectangleShapeProvider } from '@wearables-ui-toolkit/mrbd';

const tileShape = new RoundedRectangleShapeProvider(CornerRadius.MEDIUM);

import { State } from '@wearables-ui-toolkit/mrbd';
import type { InteractionState } from '@wearables-ui-toolkit/mrbd';

function handleStateChange(_previous: InteractionState, next: InteractionState) {
  setShowsDetail(next.state === State.FOCUSED);
}

• Prefer disabling a control to unmounting it. disabled keeps the element focusable, preventing holes in directional navigation, and the toolkit applies aria-disabled and disabled opacity.
• Use the toolkit’s keyboard handling rather than adding another state machine. The base handles Enter, Space, long press, and directional input consistently.
• Put the component action on onActivate. It fires exactly once per activation and includes the originating keyboard or mouse event. onClick also fires for each real DOM click, including the click dispatched by keyboard activation, so using both handlers for the action invokes it twice.
• Keep partial-focus handoff and rubber-band feedback enabled by default. Narrow handoff with partialFocusSupportedAxis: PartialFocusSupportedAxis.XY is the default, X and Y restrict it to one axis, and None opts out. Set isRubberbandTranslationEnabled to false when the element itself cannot move. onPartialFocusHandoff and onInvalidFocusDirection let component visuals acknowledge these events; focus movement remains owned by the toolkit.
• Use Container’s visualStateOverride and materialTransition for driven previews, such as a gallery showing every state. They do not replace real interaction state in an application component.
• Override visualStateForInteractionStateFn or contentScaleForStateFn only for a component with a genuinely different state mapping, such as a control that omits its resting backdrop until focused.

• Extend the base props to preserve the standard DOM surface. Use Omit<ContainerProps, 'children'> for an interactive component built on Container, or UITCommonProps for a standalone component.
• Prefer semantic variants, expressed as named string-union cases, over open-ended styling hooks. For example, a size prop with three cases defines a stable API, while a styleOverrides object exposes implementation details.
• Accept and merge className and style so the application can position the component without replacing its own styles.
• Accept ref as a normal prop and forward it to the element callers expect to measure or focus.
• Keep measurement helpers, layout calculations, and internal state private. Export only the props interface and enums that callers need to name.
• Document every public prop with a doc comment because callers use the emitted TypeScript declarations as their API reference.

import {
  Container,
  CornerRadius,
  RoundedRectangleShapeProvider,
  TextColor,
  TextStyle,
  TextView,
} from '@wearables-ui-toolkit/mrbd';
import type { ContainerProps } from '@wearables-ui-toolkit/mrbd';
import type { Ref } from 'react';

const statTileShape = new RoundedRectangleShapeProvider(CornerRadius.MEDIUM);

export interface StatTileProps extends Omit<ContainerProps, 'children'> {
  /** Short caption describing the measurement. */
  label: string;
  /** Ref to the tile's root element. */
  ref?: Ref<HTMLDivElement>;
  /** Formatted value to display. */
  value: string;
}

export function StatTile({
  className = '',
  label,
  ref,
  value,
  ...containerProps
}: StatTileProps) {
  return (
    <Container
      {...containerProps}
      ref={ref}
      ariaLabel={`${label}: ${value}`}
      className={`stat-tile ${className}`}
      shapeProvider={statTileShape}
    >
      <TextView textStyle={TextStyle.NUMERAL2}>{value}</TextView>
      <TextView textStyle={TextStyle.META1} textColor={TextColor.SECONDARY}>
        {label}
      </TextView>
    </Container>
  );
}

• An accessible name when visible text does not name the control. Derive ariaLabel from the component’s semantic props when possible, as in the example above.
• The correct role for a control that is not a button, such as a switch, radio, slider, tab, or menu item.
• Every ARIA state required by that role, synchronized with component state.
• Text alternatives that distinguish meaningful icons and images from decorative content.
• A tooltip content description when using rich tooltipContent instead of tooltipText.

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

function useDetailTransition() {
  const prefersReducedMotion = usePrefersReducedMotion();
  return createTransition(
    'opacity',
    reducedMotionDuration(
      AnimationDurations.TEXT_OPACITY,
      prefersReducedMotion,
    ),
    Interpolators.TEXT_OPACITY,
  );
}

• Exercise default, focused, pressed, disabled, and every variant state.
• Move directional focus into and out of the component from all four directions, including a boundary that refuses movement.
• Check partial focus and handoff when the component participates in them.
• Check scroll boundaries inside a scroller. If the component opens an overlay, also verify dismissal and focus restoration.
• Confirm keyboard-only operation, an accessible name, and the correct role and state in the accessibility tree.
• Test reduced motion and a range of available widths and heights, including a space narrower than the content’s natural size.