Modal

import { Button, ButtonGroup, Modal, Page } from '@wearables-ui-toolkit/mrbd';

export function PermissionScreen({ onAllow, onDismiss }: PermissionScreenProps) {
  return (
    <Page>
      <Modal
        title="Allow notifications?"
        subtitle="Notifications keep playback controls available while you are in another app."
        icon={notificationsIcon}
        buttons={
          <ButtonGroup>
            <Button title="Not now" onActivate={onDismiss} />
            <Button title="Allow" onActivate={onAllow} />
          </ButtonGroup>
        }
      />
    </Page>
  );
}

import {
  Button,
  ButtonGroup,
  Modal,
  ModalBannerSize,
  ModalBannerTag,
} from '@wearables-ui-toolkit/mrbd';

<Modal
  title="Live translation"
  subtitle="Translate what you hear, in the moment."
  bannerSrc="/media/translation-banner.webp"
  bannerAlt="Two people talking with translated captions between them"
  bannerSize={ModalBannerSize.TALLER}
  bannerTag={ModalBannerTag.BETA}
  buttons={
    <ButtonGroup>
      <Button title="Try it" onActivate={startTranslation} />
    </ButtonGroup>
  }
/>;

import { IconTintColor, Modal, type ModalListItem } from '@wearables-ui-toolkit/mrbd';

const capabilities: ModalListItem[] = [
  { icon: cameraIcon, description: 'Capture photos and video' },
  { icon: micIcon, description: 'Record audio' },
  { icon: lockIcon, description: 'Stored on device', iconColor: IconTintColor.POSITIVE },
];

<Modal title="What this app can do" listItems={capabilities} />;

import { Modal, ModalContentMode } from '@wearables-ui-toolkit/mrbd';

<Modal title="Hold to talk" contentMode={ModalContentMode.TITLE_ONLY} />;

import { Carousel, Modal } from '@wearables-ui-toolkit/mrbd';

<Carousel onItemCentered={setStep}>
  <Modal isCarouselItem title="Look up" subtitle="Wake the display with a glance." />
  <Modal isCarouselItem title="Swipe" subtitle="Move between cards with the trackpad." />
</Carousel>;

• One leading treatment. Banner, logo, avatar, and icon are mutually exclusive and resolve in that order: bannerSrc wins, then logoSrc, then avatarSrc or avatarPrimaryContent, then icon. Supplying several is not an error — the lower-priority ones simply do not render.
• Content modes.TITLE_ONLY suppresses the whole leading area, the subtitle, and the list, and switches the title to the emphasized body appearance. The standard mode reserves a single-line minimum height for the title so stacked modals stay visually aligned.
• Subtitle or list, not both. The subtitle renders only when it is a non-empty string, the mode is standard, and there are no list items. Supplying listItems always wins.
• Banner tag. The tag renders only when a banner is present and bannerTag is not NONE, over a gradient scrim pinned to the bottom of the banner.
• Long subtitle. The subtitle is clamped to four lines. When the text overflows, the modal shows a “Read more” affordance, becomes focusable, and becomes clickable; clicking it opens a full-screen overflow surface containing the complete subtitle, which closes on Escape. That surface is rendered into the app’s floating portal root, so it covers the route rather than the modal’s own box. Overflow is measured with a resize observer and re-measured when the subtitle changes.
• Focus. The modal is not a focus stop by default. It becomes focusable when isCarouselItem is set or when the subtitle overflows. Press feedback is disabled, so a focusable modal never enters the pressed state. The controls inside buttons are the real focus stops, and focus navigation moves between them like any other controls on the route.
• Not an overlay. No backdrop, no focus trap, no role="dialog", and no aria-modal. Escape is left unhandled so the surrounding route can act on it — the one exception is while the read-more surface is open, where Escape closes that surface and goes no further.
• Sizing. The modal fills the width it is given and grows to fit its content. All internal spacing comes from spacing tokens, so the layout adapts to the space the route allocates.
• Clipping. Content clipping is off, which lets inset media such as the banner draw its own rounded corners against the panel’s smooth corners.

• The panel’s accessible name defaults to the visible title, subtitle, and banner tag joined with commas. Pass aria-label to replace it when the visible copy does not read well out of context.
• The complete leading area — icon, banner, logo, and avatar — is marked decorative and hidden from assistive technology. The corresponding *Alt values do not contribute to the modal’s accessible name, so repeat any meaning carried by the media in the title, subtitle, or list.
• The “Read more” affordance is decorative. The overflow surface it opens is a real dialog: it takes role="dialog", aria-modal="true", is labelled with the complete subtitle, receives focus when it opens, and closes on Escape.
• The modal itself claims no dialog semantics. When separate presentation infrastructure overlays it, that presenter owns any dialog semantics, focus entry, focus containment, and returning focus to whatever opened it. A dedicated decision route owns its own focus entry and return navigation.
• Every control in buttons supplies its own accessible name. Keep those labels explicit (“Delete photo”, not “OK”).
• Handle system Back on the route with useBackNavigation (see Navigation and Focus) rather than adding an in-app back button to the modal.

• Give the modal a title, and choose either subtitle or listItems.
• Choose exactly one leading treatment so its precedence never becomes visible.
• Put actions in buttons as a ButtonGroup so they share the group’s alignment and focus handling.
• Put any meaning conveyed by the leading media into visible modal copy because the leading area is decorative in the accessibility tree.
• Set isCarouselItem on every modal used as a Carousel item.
• Tint list icons with a semantic IconTintColor case when the glyph carries status meaning.

• Avoid treating Modal as an overlay presenter. It paints no scrim, does not trap focus, and ignores Escape and system Back, so a dedicated route or separate presenter must own those behaviors.
• Choose subtitle or listItems; when both are supplied, both do not appear.
• Choose one of bannerSrc, logoSrc, avatarSrc, and icon for the leading treatment.
• Preserve the modal’s material and clipping behavior, and avoid nested rounded surfaces that compete with its panel.
• Keep listItems informational and place interactive controls in buttons.
• Use Toast for brief confirmation of an action that already succeeded.