` happens to be on the current page. **A resolved promise does not mean the app was installed.** It means only that the install request was dispatched — accepted for launch, not confirmed as shown. The confirmation screen is not guaranteed to appear: the launched flow can still fail its own gate and finish immediately. And even when it does appear, the wearer may decline, with no callback telling you what they chose. Do not change your UI to an installed state on resolution, and do not count resolutions as installs. **Rejections** | Error | Cause | | ----- | ----- | | `DataError` | The `installUrl` could not be resolved, or is not `https:` or `http:`. | | `NotSupportedError` | Installation is not available on this device, or the URL was rejected. | | `AbortError` | The install request could not be dispatched. | Always catch. Rejection is a normal outcome, not a bug, because availability depends on the device. ### The `<install>` element An `<install>` element with an `installurl` or `href` attribute also triggers installation when activated: ```html <install installurl="https://example.com/myapp">Add to glasses</install> ``` Prefer `navigator.install()`. The element's failures are swallowed, so you cannot detect that installation was unavailable and cannot offer a fallback. `<install>` is also not a real element on other browsers, where it renders as an inert inline box and does nothing when clicked, so anything you put inside it needs to make sense as plain text. </gk> ### Build ## Overview Web Apps for Meta Ray-Ban Display glasses use standard web APIs. The easiest way to build Web Apps is with AI coding tools. Learn how to build optimized Meta Ray-Ban Display Web Apps by understanding: * How to Build with AI * Capabilities and Best Practices * Display * Input and navigation * Activation and continuous drag * Back navigation * Text composer * Sensors * Location * Local storage * Offline mode * App icons ## HTML metadata Add the following metadata to the `<head>` of your HTML file. This allows your web app to support upcoming discovery surfaces and enables us to message users when a website isn't compatible with Meta Ray-Ban Display glasses. ```html <head>  <meta name="description" content="Description of your web app">  <meta name="mrbd-web-app-capable" content="yes"> </head> ``` ## Capabilities Web Apps on Meta Ray-Ban Display glasses **support** these capabilities: | Capability | Description and guidance | | ---------- | ------------------------ | | Display | Additive waveguide overlay. Use dark backgrounds/light, high-contrast UI colors. Fixed 600x600px viewport. Avoid scrolling. | | Input | Directional navigation and activation from the touchpad or band translate into standard browser behavior. Optional continuous drag uses standard pointer events. The on-glasses composer provides text input. No mouse, touchscreen, or physical keyboard is available. All interactive elements must be focusable. | | Sensors (IMU) | Standard `DeviceMotionEvent` (accelerometer, gyroscope) and `DeviceOrientationEvent` (heading, tilt, roll) W3C APIs. Requires user permission. | | Location (GPS) | Standard `navigator.geolocation` W3C API. Location is fetched from the paired mobile device. Requires user permission. | | Local storage | Standard Web Storage APIs (`localStorage`, `sessionStorage`). Best for lightweight data (preferences, small caches). Use JSON for structured data. | | Offline mode | Standard Service Workers and Cache API. Save a copy of your app’s files directly on a device, so apps can load and render without a network request. | | App icons | Use Unicode symbols or high-resolution PNG favicons (>= 52x52 px) via `<link>` tags or Web App Manifest. SVGs are not supported. | Web Apps do **not yet support**: * Camera * Microphone * Notifications <gk project="wdp_manual_web_apps_docs_connect_26" markdown="block"> Web Apps on Meta Ray-Ban Display glasses also **support**: | Capability | Description and guidance | | ---------- | ------------------------ | | Text to speech | Standard `window.speechSynthesis` Web Speech API. Audio plays through the glasses speaker. One English voice; no permission prompt. `volume` is ignored and `boundary` events never fire. | </gk> ### Display The display is an additive waveguide that overlays rendered pixels onto the wearer's real-world view. This has a direct impact on how your app looks. * A pixel rendered as pure black is fully transparent, since it contributes zero light. * Bright, vivid colors are the most visible, because they add light on top of the real-world scene. #### Color and typography Because the display is additive, color choices matter more than on a conventional screen: * Use dark backgrounds, since they effectively disappear. Bright backgrounds cause glare and reduce readability. * Use light, high-contrast colors for UI elements like text and interactive components. Also, use bright colors for accents. * Use large, readable fonts: a minimum of 16 px for body text and 20-24 px for primary content. #### Viewport All content should render within a fixed 600 x 600 pixel viewport and avoid scrolling. Include the following viewport `meta` tag to lock the scale and prevent unexpected zooming: ```html  <meta name="viewport" content="width=600, height=600, initial-scale=1.0, user-scalable=no"> ``` Set `overflow: hidden` on the `<body>` element to ensure no content extends beyond the viewport boundary: ```css body { width: 600px; height: 600px; overflow: hidden; } ``` ### Input and navigation Meta Ray-Ban Display translates input from the touchpad and Meta Neural Band into directional navigation and activation. The glasses OS delivers those actions to your Web App as standard arrow key (`ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`) and `Enter` events. Since the Meta Ray-Ban Display glasses have no mouse, touchscreen, or physical keyboard, every interactive element in your Web App must support directional navigation and activation through standard web platform behavior. **JavaScript** ```javascript // — Input Constants — const DPAD = { UP: 'ArrowUp', DOWN: 'ArrowDown', LEFT: 'ArrowLeft', RIGHT: 'ArrowRight', SELECT: 'Enter', BACK: 'Escape', }; // — Focus Management — function moveFocus(direction) { var focusables = Array.from( document.querySelectorAll('.focusable:not([disabled]):not(.hidden)') ); if (!focusables.length) return; var idx = focusables.indexOf(document.activeElement); if (idx === -1) { focusables[0].focus(); return; } var next = (direction === 'up' || direction === 'left') ? (idx > 0 ? idx - 1 : focusables.length - 1) : (idx < focusables.length - 1 ? idx + 1 : 0); focusables[next].focus(); focusables[next].scrollIntoView({ block: 'nearest', behavior: 'smooth' }); } // — D-pad Listener — document.addEventListener('keydown', function(e) { switch (e.key) { case DPAD.UP: moveFocus('up'); break; case DPAD.DOWN: moveFocus('down'); break; case DPAD.LEFT: moveFocus('left'); break; case DPAD.RIGHT: moveFocus('right'); break; case DPAD.SELECT: if (document.activeElement.classList.contains('focusable')) { document.activeElement.click(); } break; case DPAD.BACK: history.back(); break; default: return; // don't preventDefault on unhandled keys } e.preventDefault(); }); ``` **HTML** ```html  <button class="focusable" data-action="settings">Settings</button> <button class="focusable" data-action="start">Start</button> ``` **CSS** ```css .focusable { transition: all 150ms ease; border: 2px solid transparent; min-height: 88px; /* glasses minimum tap target */ } .focusable:focus { outline: none; border-color: #00d4ff; box-shadow: 0 0 20px rgba(0, 212, 255, 0.4); } ``` ### Activation and continuous drag Meta Ray-Ban Display provides standard web events for activation and optional continuous drag. No special SDK is required. Two interaction modes are available to your Web App: * **Activation (always on):** Activating the focused element is equivalent to pressing Enter. It works on any focusable element, including buttons, links, and custom interactive controls. No opt-in is needed. * **Drag (opt-in):** Continuous arm movement provides positional input delivered as *pointer events*. Use it for sliders, drawing, panning, or any other interaction that needs smooth, continuous control. Opt in at the page level. | Interaction | Web event | Action | | --- | --- | --- | | Directional navigation | `ArrowUp` / `ArrowDown` / `ArrowLeft` / `ArrowRight` keydown | Move focus between elements | | Activation | `Enter` keydown | Activate focused element | | Continuous drag | `pointerdown` / `pointermove` / `pointerup` | Update a continuous position (opt-in) | #### Activation Activation fires `Enter` on the currently focused element (`document.activeElement`). It is **not** a positioned click, so there is no cursor or screen coordinate. Activation targets the element that currently has focus, so build your UI around focusable elements, not click targets. This means your app must: 1. Make interactive elements *focusable* (use `<button>`, `<a>`, or add `tabindex="0"`). 2. Make them *keyboard-activatable* (respond to `Enter` key or `click` events). 3. Provide a *visible focus indicator* so the wearer knows which element is selected. For most apps, activation works automatically if you build a standard accessible, focusable UI. ```html  <button data-focusable onclick="doAction()">Start</button> <a href="/next" data-focusable>Next Page</a>  <div tabindex="0" role="button" data-focusable onclick="doCustomAction()"> Custom Control </div> ``` Next, handle focus navigation with keyboard events. ```javascript var focusableElements = []; var focusIndex = 0; function updateFocusables() { focusableElements = Array.prototype.slice.call( document.querySelectorAll('[data-focusable]:not([disabled])') ); } function moveFocus(idx) { focusableElements.forEach(function(el) { el.classList.remove('focused'); }); focusIndex = Math.max(0, Math.min(idx, focusableElements.length - 1)); if (focusableElements[focusIndex]) { focusableElements[focusIndex].classList.add('focused'); focusableElements[focusIndex].focus(); } } // Keep `focusIndex` in sync if focus moves outside `moveFocus()` (for example, `programmatic .focus()`, native focus, or after `updateFocusables()`). document.addEventListener('focusin', function(e) { var idx = focusableElements.indexOf(e.target); if (idx !== -1) { focusableElements.forEach(function(el) { el.classList.remove('focused'); }); focusIndex = idx; e.target.classList.add('focused'); } }); document.addEventListener('keydown', function(e) { switch (e.key) { case 'ArrowUp': e.preventDefault(); moveFocus(focusIndex - 1); break; case 'ArrowDown': e.preventDefault(); moveFocus(focusIndex + 1); break; case 'Enter': e.preventDefault(); // Activation fires Enter on `document.activeElement`. // Activating `activeElement` (not a cached `focusIndex`) ensures the element the wearer sees as focused is the one that receives the click. if (document.activeElement && document.activeElement.matches('[data-focusable]')) { document.activeElement.click(); } break; case 'Backspace': e.preventDefault(); history.back(); break; case 'Escape': e.preventDefault(); history.back(); break; } }); // Initialize the focusable set once the DOM is ready and keep it in sync after any DOM updates that add or remove `data-focusable` elements document.addEventListener('DOMContentLoaded', function() { updateFocusables(); if (focusableElements.length) { moveFocus(0); } // The observer handles dynamic DOM changes automatically. Otherwise, call `updateFocusables()` directly from the code that mutates the DOM (for example, `container.appendChild(newItem); updateFocusables();`). var observer = new MutationObserver(function() { updateFocusables(); }); observer.observe(document.body, { childList: true, subtree: true }); }); ``` Provide a visible focus indicator. Since the code sample above toggles a `.focused` class and calls `.focus()`, you need to style both `:focus` and `.focused`. Without this CSS, the focus change has no visual effect. ```css /* Visible focus indicator — matches the earlier .focusable styles */ [data-focusable], .focusable { transition: all 150ms ease; border: 2px solid transparent; min-height: 88px; /* glasses minimum tap target */ } [data-focusable]:focus, [data-focusable].focused, .focusable:focus, .focusable.focused { outline: none; border-color: #00d4ff; box-shadow: 0 0 20px rgba(0, 212, 255, 0.4); } ``` You can use either convention: `class="focusable"` with `document.querySelectorAll('.focusable')`, or `data-focusable` with `document.querySelectorAll('[data-focusable]')`. Either way, keep the selector, the toggled class, and the CSS in sync, so the wearer always sees which element is focused. #### Drag (continuous input) When drag is enabled, the wearer can hold and move their arm to generate a continuous stream of positional data. This is delivered to your app as standard **pointer events** (`pointerdown`, `pointermove`, `pointerup`). Drag is *off* by default. The only interactions available without it are directional focus navigation and activation, meaning there is no free cursor or sliding motion unless you explicitly enable it. To enable drag, add `touch-action: none` to the `<body>` element in your initial stylesheet. ```css /* MUST be in your initial stylesheet, as it is not added dynamically via JavaScript */ body { touch-action: none; } ``` **Note:** `touch-action` is read on `<body>` only once at page load, so it must be in the corresponding CSS. It cannot be set on individual elements or included via JavaScript. Once drag is enabled, listen for pointer events to receive the continuous motion. ```javascript const slider = document.getElementById('slider'); let dragging = false; slider.addEventListener('pointerdown', function(e) { dragging = true; // Do not use requestPointerLock-- use standard pointer events instead slider.setPointerCapture(e.pointerId); }); slider.addEventListener('pointermove', function(e) { if (dragging) { // Use e.clientX and e.clientY for position updatePosition(e.clientX, e.clientY); } }); slider.addEventListener('pointerup', function() { dragging = false; }); ``` **Some drag use cases** - **Sliders:** Adjust volume, brightness, or any continuous value with arm movement - **Panning:** Navigate a map or large image by dragging in 2D - **Drawing:** Simple freehand drawing or annotation - **Games:** Control game elements with continuous positional input #### Considerations **Text input and activation** Activating a focused text input (such as `<input>` or `<textarea>`) opens the device text composer instead of dispatching a click to your page. **Verify on-device** The exact values in drag event fields (e.g., `movementX`, `movementY`, `clientX`, `clientY`) are generated device-side. Always **test on real glasses** by logging `pointermove` events before relying on specific coordinate behavior. Desktop emulation will not accurately represent the drag input. **Feature availability** Continuous drag relies on the band, which may not be available to every wearer. The APIs are always present (for example, pointer events exist in the browser), but drag input may not fire on some hardware. Always design your app to remain usable if drag events never arrive. Provide alternative directional navigation for critical actions. #### Best practices | Do | Don't | | --- | --- | | Use `<button>`, `<a>`, or `tabindex="0"` for activation targets | Rely on positioned click coordinates for activation | | Always show a visible focus indicator | Use hover-only styles for interactive elements | | Set `touch-action: none` on `<body>` in your initial stylesheet | Set `touch-action` per-element or via JavaScript at runtime | | Use `setPointerCapture()` for reliable drag tracking | Use `requestPointerLock()`, since it's not supported. | | Test drag behavior on real glasses hardware | Assume desktop pointer simulation matches device behavior | | Provide directional-navigation fallbacks for all critical actions | Make drag the only way to complete an essential task | | Call `e.preventDefault()` on all handled key events | Leave arrow key / Enter events unhandled (causes unexpected scrolling) | In addition to these best practices, verify the following before publishing your Web App with wearable input support: - Activation uses the currently focused element, so test every interactive control. - If using drag, test `pointermove` events directly on a device. - If using drag, the app still works through directional navigation and activation if drag events never fire. - All interactive elements are reachable from the home screen through directional navigation. ### Back navigation Back on Meta Ray-Ban Display glasses lets users move backward through a Web App's screens, panels, and other navigable states. For standard Web Apps, the native shell checks [`navigation.canGoBack`](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/canGoBack) when the user invokes Back. If a previous navigation entry is available, the shell calls `history.back()`. Otherwise, it shows the native system menu overlay. Use the standard web [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API) and [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to manage navigation. No custom SDK is required. Your Web App is responsible for rendering the destination state and restoring app-managed state, including focus, scroll offsets, and page/carousel positions. | User action | System behavior | | --- | --- | | Back with a previous history entry | Calls `history.back()`. | | Back with no previous history entry | Shows the native system menu overlay. | | Back while the native menu is visible | Exits the Web App. | The native transient UI is handled before web history. For example, when the native text-input UI is open, Back dismisses this UI before traversing the page's history. #### Navigation history limit The shell guards entries created with `history.pushState()` using a limit of **five** total navigation entries, including the initial document, so a typical Web App can have its root entry plus four deeper nav entries. Once `navigation.entries().length` reaches 5, subsequent `history.pushState()` calls replace the current entry instead of adding another entry. **Note:** This guard applies *only* to `history.pushState()`. It is not a universal cap on entries created through other navigation mechanisms. Design your Web App's `pushState()`-based navigation to stay within this five-entry limit. #### Adding and restoring navigation history Create a history entry when the user moves to a destination they would expect back navigation to reverse, such as a detail screen or a substantial panel. Seed the initial entry with `history.replaceState()`, save the current view state, and restore the destination from a `popstate` handler. ```javascript const HOME_STATE = {screen: 'home'}; // Give the initial document an explicit state without adding another entry. history.replaceState(HOME_STATE, ''); function saveCurrentViewState() { history.replaceState( { ...history.state, focusId: document.activeElement?.id ?? null, scrollX: window.scrollX, scrollY: window.scrollY, // Store any app-specific position here, such as a pager index. }, '', ); } function navigateTo(state) { saveCurrentViewState(); history.pushState(state, ''); renderScreen(state); } function openSettings() { navigateTo({screen: 'settings'}); } function openDetail(itemId) { navigateTo({screen: 'detail', id: itemId}); } window.addEventListener('popstate', (event) => { const state = event.state ?? HOME_STATE; renderScreen(state); // Restore state after the destination DOM has been rendered. requestAnimationFrame(() => { window.scrollTo(state.scrollX ?? 0, state.scrollY ?? 0); if (state.focusId) { document.getElementById(state.focusId)?.focus(); } // Restore app-specific state, such as a pager or carousel index, here. }); }); ``` You can handle traversal with the standard web Navigation API's `navigate` event instead of `popstate`. Use one coordinated traversal strategy so the destination isn't restored twice. When no previous history entry remains, the next Back action shows the native system menu. This is the expected app boundary, so don't add synthetic entries or push a new entry during Back handling to prevent the user from reaching it. #### Best practices | Do | Don't | | --- | --- | | Push an entry for a user-recognizable destination that Back should reverse. | Push entries for hover, focus changes, tooltips, or other transient UI. | | Seed the initial document with `history.replaceState()`. | Push a duplicate initial entry that creates an artificial Back step. | | Store serializable identifiers, offsets, and indexes in history state. | Store DOM elements or other non-serializable objects in history state. | | Restore the destination screen, focus, scroll, and component positions after traversal. | Assume an arbitrary SPA UI state will be restored automatically. | | Design for five total `pushState()` navigation history entries, *including* the root document. | Assume five additional screens can be pushed *after* the root entry. | | Allow history to drain until the native system menu is reached. | Push a new entry while handling Back or otherwise trap the user. | #### Troubleshooting | Issue | Potential cause | Solution | | --- | --- | --- | | Back opens the native system menu instead of the previous app screen. | The current screen did not add a history entry, or no previous entry remains. | Add an entry when navigating to a user-recognizable destination. | | Back traverses history, but the displayed screen does not change. | The `popstate` or Navigation API traversal handler does not render the destination state. | Read the destination state and render the corresponding screen. | | A newly opened screen cannot be reached again with Back. | The five-entry limit was reached, so `pushState()` likely replaced the current entry. | Keep the root plus deeper navigation within five total entries. | | The app cannot reach the native system menu. | A traversal handler pushes new entries or repeatedly prevents history from draining. | Never push while handling Back, and allow traversal to reach the initial entry. | | Focus, scroll, pager, or carousel position is lost. | The app did not save or restore that state, or restored it before rendering completed. | Store stable IDs and numeric positions, then restore them after rendering the destination. | ### Input: On-glasses composer for text Meta Ray-Ban Display glasses provide text input for Web Apps through an on-glasses composer, a systems-level handwriting and dictation panel that appears when users focus and activate a standard HTML text field. Since the glasses have no touchscreen or physical keyboard, users must use this composer to enter text into your app's search boxes, forms, notes fields, and name prompts. No special integration is required. When the user focuses and activates a text field, an **on-glasses composer panel** appears, allowing them to enter text via handwriting or voice dictation. The composed text is committed back to your field via standard DOM `input` and `change` events. **Note:** Text input requires glasses firmware **v127+** and Meta AI app **v272+**. #### Composer lifecycle ```mermaid flowchart TD A["User navigates\ndirectionally"] --> B["Text field\nreceives focus"] B --> C{"User activates\nthe field?"} C -->|No| D["Field stays focused.\nComposer does not open"] C -->|Yes| E["Composer panel opens\n(handwriting \+ voice)"] E --> F["User enters text"] F --> G["Text committed\nto field"] G --> H["'input' event fires\non your element"] H --> I{"More input\nneeded?"} I -->|Yes| F I -->|No| J["User navigates away.\nComposer closes"] J --> K["'change' event fires"] ``` The composer opens on focus and activation, *not* on focus alone. Programmatic calls to `.focus()` will not surface the composer, so user-initiated activation is required. #### Input types **Supported input types** The following HTML input types **can** open the composer. * `<input type="text">` * `<input type="search">` * `<input type="email">` * `<input type="url">` * `<input type="tel">` * `<input type="number">` * `<textarea>` * `contenteditable` elements **Unsupported input types** The following HTML input types **can not** open the composer. * `<input type="password">` * `<input type="date">` * `<input type="checkbox">` * `<input type="radio">` <gk project="wdp_manual_web_apps_docs_connect_26" markdown="block"> #### On-screen keyboard In addition to handwriting and dictation, the composer offers an on-screen QWERTY keyboard, which is part of the composer. Text arrives in your field the same way it does for handwriting and dictation, and your app needs no integration to support it. **Note:** The on-screen keyboard requires glasses firmware **v129+**. **Opening the keyboard** The keyboard is reached from the composer, not from your text field. Users focus and activate a text field to open the composer, then swipe down on the composer to raise the keyboard. Users on TalkBack can activate the chevron control on the composer instead of swiping. **Note:** There is no way for your app to open the keyboard directly, and the keyboard cannot be raised while the composer is in dictation mode. **Typing** The keyboard is a four-row grid with a letters layer and a numbers and symbols layer. Directional input moves focus from key to key, and activation selects the focused key. Up and down move to the key physically above or below the current one, so navigation follows cardinal directions even though rows may have different key counts. | Key | Behavior | | --- | -------- | | Shift | Latches caps lock on and off. It is not a one-shot shift, so it stays on until the user turns it off. | | Backspace | Deletes the selection, or the character before the caret when there is no selection. | | `123` / `ABC` | Switches between the letters layer and the numbers/symbols layer. Focus stays on the toggle key across the switch. | | Space | Inserts a space. | | Done | Collapses the keyboard and leaves the composer open with the typed text intact.* | *Swiping up while the focus is on the top row also collapses the keyboard. **Available characters** | Layer | Characters | | ----- | ---------- | | Letters | `a`–`z`, space | | Numbers and symbols | `0`–`9` `@` `#` `$` `%` `&` `*` `-` `+` `(` `)` `=` `/` `:` `;` `,` `.` `?` `!` | The keyboard cannot type apostrophes, quotation marks, underscores, backslashes, angle brackets, square brackets, braces, pipes, tildes, carets, or backticks. Avoid requiring these characters in values entered with the on-screen keyboard, especially email addresses and URLs. Password fields cannot open the composer. See [**Input types**](https://wearables.developer.meta.com/docs/develop/webapps/build#input-types) below. **Events your app receives** Typed characters go into the composer's own text buffer, not into your element, so your field remains unchanged while the user types. Text reaches your element only when the user confirms the composer, at which point `input` fires and then `change` fires, following the same process for handwriting and dictation. Your app receives the finished string in one update. Because the keyboard is a focus-driven overlay rather than an Android input method, no per-character key events reach the page. Do not rely on `keydown`, `keypress`, or `keyup` to observe typing, and do not implement per-keystroke behavior, like inline autocomplete that depends on them. Validate and react in your `input` handler instead. </gk> #### Text field implementation Add a standard HTML text field with a descriptive placeholder attribute. The placeholder text should help the user understand what to enter in the composer panel. **HTML** ```html  <input type="search" id="search" class="focusable" placeholder="Activate to write or speak" />  <textarea id="note" class="focusable" placeholder="Activate to write or speak" ></textarea> ``` **JavaScript** ```javascript // Read the composed text using standard event listeners in JavaScript. const note = document.getElementById('note'); //The composer commits text via the 'input' event note.addEventListener('input', () => { console.log('Current text:', note.value); }); // 'change' fires when the field loses focus after editing note.addEventListener('change', () => { console.log('Final text:', note.value); }); ``` #### Best practices | Do | Don't | | :---- | :---- | | Provide a clear, descriptive placeholder or aria-label | Leave fields without hints | | Use supported input types (`text`, `search`, `email`, `url`, `tel`, `number`) | Use `type="password"` (since the composer won't open) | | Listen for `input` events to read composed text | Listen for `keydown` events (since no physical keyboard exists) | | Provide a fallback if the composer is unavailable | Assume the composer will always be available | | Make fields focusable and reachable through directional navigation | Rely on mouse-click or touch to open fields | #### Known limitations * The `inputmode` and `enterkeyhint` attributes do **not** affect the composer behavior. The `type` attribute controls only whether the field is eligible. * On some firmware builds, the composer may be unavailable. Design your app to remain functional without it (for example, you can provide alternative navigation or pre-filled options). #### Complete example ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=600, height=600, initial-scale=1.0, user-scalable=no" /> <title>Search

; } ``` ```css .compass-needle { inline-size: var(--uit-spacing-xsmall); block-size: var(--uit-spacing-3xl); border-radius: var(--uit-corner-radius-full); background: var(--uit-color-icon-primary); transform-origin: bottom center; rotate: calc(var(--compass-heading, 0) * 1deg); } ``` `heading` can change every time a new reading arrives. Each `setTarget` reuses the spring's current position and velocity, so the needle never jumps and never restarts. ## API ### `useSpringAnimation(options)` Creates a spring controller that is stable for the lifetime of the component. Changing the config, the frame rate, or the callbacks reconfigures the existing controller in place — it does not create a new one and does not restart an animation that is already running. Because the controller identity never changes, it is safe to list in effect dependency arrays. The hook calls `onChange` once with the current value when it mounts, so the element you are driving is correct on first paint. ### `UseSpringAnimationOptions` | Field | Type | Default | Description | |---|---|---|---| | `config` | `SpringConfig` | — | Spring physics. Required. Validated when the controller is created and again whenever the values change. | | `initialValue` | `number` | — | Starting value. Required, and must be finite. Read only when the controller is created; to move the spring later, call `setTarget`. | | `onChange` | `(value: number) => void` | — | Required. Receives the initial value and every subsequent animated value. An imperative hot path: write to the DOM, a CSS custom property, a canvas, or another imperative sink. Calling a React state setter here reintroduces a render per frame. | | `onRest` | `(value: number) => void` | — | Called once after the spring reaches its target or snaps to it. A snap is silent when the value is already at the target. | | `frameRate` | `number` | `30` | Maximum number of value updates per second. Must be finite and positive. | The callbacks are read fresh on every render, so passing inline closures is fine and they always see current props. ### `SpringAnimationController` | Member | Signature | Description | |---|---|---| | `getValue` | `() => number` | The most recently emitted value. | | `isAnimating` | `() => boolean` | Whether a frame is currently scheduled. `false` once the spring has settled, and while it is paused or stopped. | | `setTarget` | `(targetValue: number) => void` | Retargets the spring, preserving its current velocity. Clears a previous `stop()`. Throws if the value is not finite. | | `stop` | `() => void` | Cancels scheduled frames, holds the current value, and clears velocity. The value stays held — including through config changes — until the next `setTarget`. | ### `SpringConfig` | Field | Type | Description | |---|---|---| | `stiffness` | `number` | Strength of the pull toward the target. Must be positive. Higher covers the distance faster. | | `damping` | `number` | Resistance to motion. Must be zero or greater. Lower relative to stiffness means more overshoot. | | `mass` | `number` | Inertia of the animated value. Must be positive. Higher makes the response heavier and slower. | `SpringConfig` also declares one optional field, `equilibriumMode`, which tunes how aggressively the spring is treated as settled. The four general-purpose presets below set it to its most aggressive value: fixed velocity and position thresholds, rather than the default's thresholds that scale with the values the spring moves between. Over a small range — an opacity, a normalized progress value — that cuts the imperceptible tail short; over a large range, such as an angle in degrees, the fixed position threshold is the stricter one, so the spring runs a little longer. The role-specific configurations omit the field and get the default. Configs you write should supply the three numeric fields and leave it out. ### `SpringConfigs` Named configurations. Prefer one of these over hand-tuned numbers so related motion across an application stays coherent. Four general-purpose presets, ordered from calmest to most energetic: | Preset | Character | |---|---| | `SOFT` | Gentle. The least overshoot of the four; good for large or ambient movement. | | `STANDARD` | The general-purpose choice. Clear overshoot, quick settle. | | `BOUNCY` | Pronounced overshoot at a moderate speed. Use it when the bounce itself is the message. | | `SNAPPY` | The same energetic character at much higher stiffness, so it covers the distance and settles fastest. | Six role-specific configurations, used by components and available when you are animating the same kind of thing: | Config | Role | |---|---| | `PROGRESS_VALUE` | Determinate progress values. Settles onto the target with a slight overshoot. | | `CONTAINER_SCALE_PRESS` | Content scale as a container enters the pressed state. Stiff and underdamped, so the scale passes the target and springs back. `Container` applies this itself. | | `CONTAINER_SCALE_RELEASE` | Content scale as a container leaves the pressed state. A little looser than the press spring. | | `PARTIAL_FOCUS_HANDOFF` | The partial-focus handoff between neighboring interactables as focus moves. Nearly critically damped, so the handoff reads as a lean rather than a bounce. | | `CHIP_LOADING_SWAP` | `Chip` swapping into and out of its loading presentation. | | `CONTROL_TILE_ICON_SWAP` | `ControlTile` swapping its icon. Looser damping, so the incoming icon settles with a visible bounce. | ## Behavior **Frame pacing.** Values are produced from animation frames but emitted at most `frameRate` times per second, so a display running faster than the spring's update rate does not multiply work. If a frame is delivered late, the step is clamped to a single interval, so a stalled tab or a dropped frame cannot make the spring jump ahead of where it should be. **Settling.** When velocity and remaining distance both fall below the config's thresholds, the value is set exactly to the target, `onChange` emits that exact value, and `onRest` fires once. After that `isAnimating()` is `false` and no frames are scheduled until the next `setTarget`. **Document visibility.** Springs pause while the document is hidden and resume when it becomes visible again. All controllers share a single visibility listener. **Unmounting.** The hook cancels any scheduled frame when the component unmounts, so there is nothing to clean up and no callback fires afterwards. **Reduced motion.** When the user prefers reduced motion, `setTarget` snaps straight to the target: `onChange` emits the target and `onRest` fires, with no frames scheduled. If the preference turns on while a spring is in flight, the spring snaps immediately. You do not need to branch on `usePrefersReducedMotion()` for a spring — see [reduced motion](/docs/develop/webapps/design/foundations/motion/overview/#reduced-motion). **Environments without animation frames.** If `requestAnimationFrame` is unavailable, the controller snaps to the target instead of failing. **Validation.** Invalid physics throws rather than silently producing `NaN` frames: `mass` and `stiffness` must be positive, `damping` must be zero or greater, `frameRate` must be finite and positive, and `initialValue` and every `setTarget` value must be finite. ## Recommended patterns - Use one controller per animated value and choose a named `SpringConfigs` member so related motion stays coherent. - Write the value into a transform, opacity, or CSS custom property from `onChange` to avoid per-frame React renders. - Call `setTarget` from an event handler or effect whenever the logical target changes, including while another animation is running. - Use `stop()` when an interaction takes manual control, then `setTarget` to hand the value back to the spring. ## Avoid - Write imperatively inside `onChange`; a React state setter there re-renders the subtree on every emitted frame. - Retarget the existing controller instead of recreating config values to restart an animation. - Let the toolkit components own properties they already animate, such as a container's focus or press scale. - Prefer an interpolated transition for a fixed, uninterruptible A-to-B change; it is cheaper and more predictable. ## Related resources [Motion](/docs/develop/webapps/design/foundations/motion/overview/), [Interpolated Motion](/docs/develop/webapps/design/foundations/motion/interpolated-motion/), [Second-order Motion](/docs/develop/webapps/design/foundations/motion/second-order-motion/), [Container](/docs/develop/webapps/design/components/foundation/container/), [Interactions](/docs/develop/webapps/design/components/foundation/interactions/) ### Second-order motion Derive second-order motion from the state that drives the primary motion. This keeps a following caption, anchored overlay, or focus-responsive list chrome in step with the element it depends on. Use the same progress value, state change, or scroll offset for both elements. Avoid measuring and repositioning the primary element every frame: layout reads in an animation loop force synchronous layout, and independent loops drift by at least one frame. ## Content that follows a material scale `Container` animates its content scale and its material's visual-state transition from a single timeline. An app-owned element that has to move with that change should join the same timeline rather than watching the container. `stateChangeAnimations` is that entry point. It is called with the state change that is about to run and returns animations to run alongside the container's own. They start together, they are driven by the same clock, and they are cancelled together when a new state change interrupts them. The context passed to the callback: | Field | Description | |---|---| | `prevInteraction` / `newInteraction` | The interaction state before and after the change. | | `animated` | Whether this change is animating at all. It is `false` when the user prefers reduced motion, while the page is entering, and during fast scrolling. | | `transition` | The `duration` and `interpolator` the container itself is using. Reuse the duration to stay in step. | | `containerSize` | The measured `width` and `height` of the container, so you do not have to measure it yourself. | Each returned animation: | Field | Type | Description | |---|---|---| | `duration` | `number` | Duration in milliseconds. Required. | | `onFrame` | `(elapsedMs: number, linearProgress: number) => void` | Required. Called per frame with the elapsed time and linear progress from zero to one. | | `startDelay` | `number` | Offset before this animation begins, while the rest of the transition is already running. | | `onStart` | `() => void` | Called when the transition starts. | | `onComplete` | `() => void` | Called when this animation finishes. | | `onCancel` | `() => void` | Called when the transition is interrupted. Restore a defined resting state here. | When `animated` is `false` the returned animations never run — no `onStart`, no `onFrame`, no `onComplete`. Apply the dependent element's end state directly from the callback so it lands with the container instead of being left behind. `transition.duration` is the timing of the container's material transition, and it is also the timing of the content scale for every state change except a press. A press-in or press-out drives the scale with a spring instead, run to the spring's own settle time, so on those changes reuse the duration to stay in step with the material rather than with the scale. ```tsx import {useMemo, useRef} from 'react'; import {Container, MaterialLibrary} from '@wearables-ui-toolkit/mrbd'; export function StatusTile({title, caption}: {title: string; caption: string}) { const material = useMemo(() => MaterialLibrary.default(), []); const captionRef = useRef(null); return ( [ { duration: transition.duration, onFrame: (_elapsedMs, linearProgress) => { captionRef.current?.style.setProperty( '--caption-reveal', String(linearProgress), ); }, }, ]} > {title} {caption} ); } ``` ```css .status-tile { display: flex; flex-direction: column; gap: var(--uit-spacing-xsmall); padding: var(--uit-spacing-medium); color: var(--uit-color-text-primary); } .status-tile-caption { opacity: var(--caption-reveal, 0); } ``` When frame accuracy is not required, `onScaleChange` is the lighter option. It reports the container's target content scale at each state change — at the boundary, not per frame — which is enough to update state that only needs to know where the container is heading. ## An overlay tracking its anchor Overlays render into the floating portal root, so they are positioned against their anchor rather than laid out with it. That makes anchoring an explicit decision. - `Tooltip` takes an `anchorRef` and positions itself. By default it positions against the anchor's unscaled box, so a tooltip does not drift while the anchor plays its focus or press scale. - `tracksAnchorScale` opts into the opposite: the overlay follows the anchor's live, animating box. Use it when the anchor's movement is large enough that a fixed position would visibly detach. `useTooltip` accepts the same option in its show options. - When the visual anchor is not the whole element — an icon inside a wide row, a badge in a corner — supply the geometry instead of nudging the overlay. `tooltipCenterPositionProvider` and `tooltipTargetRectProvider` on any interactable, and `centerPositionProvider` and `targetRectProvider` on `Tooltip`, receive the anchor element and return a point or a rectangle in the anchor's own coordinate space. - After a change that moves the anchor without animating it, call `refreshPosition()` from `useTooltip` once, at the boundary. Do not poll. ```tsx import {useCallback, useMemo, useRef} from 'react'; import {Container, MaterialLibrary, TooltipMode} from '@wearables-ui-toolkit/mrbd'; export function BadgedRow({ label, badge, badgeDescription, }: { label: string; badge: string; badgeDescription: string; }) { const material = useMemo(() => MaterialLibrary.default(), []); const badgeRef = useRef(null); const tooltipTargetRectProvider = useCallback((anchor: HTMLElement) => { const badgeElement = badgeRef.current; if (badgeElement == null) { return null; } const anchorRect = anchor.getBoundingClientRect(); const badgeRect = badgeElement.getBoundingClientRect(); return { left: badgeRect.left - anchorRect.left, top: badgeRect.top - anchorRect.top, right: badgeRect.right - anchorRect.left, bottom: badgeRect.bottom - anchorRect.top, width: badgeRect.width, height: badgeRect.height, }; }, []); return ( {label} {badge} ); } ``` The provider runs when the overlay positions itself, not on a loop, so the measurement cost is paid once per placement. ## List content responding to focus movement Focus movement already emits everything a dependent element needs. Subscribe to it rather than observing the DOM. | API | Where | What it reports | |---|---|---| | `onStateChange` | Any interactable | The previous and new interaction state, including focus and press. | | `onPartialFocusHandoff` | Any interactable | Focus moving between neighbors, so a component can render the handoff effect. | | `onInvalidFocusDirection` | Any interactable | Focus input that could not move in the requested direction. | | `partialFocusSupportedAxis` | Any interactable | Which axes carry partial-focus feedback: `XY`, `X`, `Y`, or `None`. | | `isRubberbandTranslationEnabled` | Any interactable | Whether rubber-band feedback translates the element, or only moves the material's origin. | | `onScroll` | `ScrollView` | The current scroll offset. | Prefer material-origin feedback to translating an element. Moving an element in a list moves its neighbors' apparent positions too, which is second-order motion nobody asked for. Scroll-derived chrome is the common case, and it should be expressed as state that a component then animates for you: {% raw %} ```tsx import {useState} from 'react'; import type {ReactNode} from 'react'; import {ScrollView, Vignette, VignetteEdge} from '@wearables-ui-toolkit/mrbd'; export function FadingList({children}: {children: ReactNode}) { const [scrollTop, setScrollTop] = useState(0); return (

{children} 0}} />

); } ``` {% endraw %} ```css .fading-list { position: relative; block-size: 100%; } ``` The scroll offset becomes a boolean, the boolean becomes an edge, and `Vignette` owns the fade. Nothing here animates opacity per scroll event. ## Keeping dependent motion stable - Keep one same-axis scroller per route. A dependent element that lives in a second scroller on the same axis will drift, because two scroll positions now describe its location. - Update dependent state at boundaries. The only place per-frame work belongs is inside the primary animation's own frame callback. - Give the dependent motion a defined resting state for every primary state, including interrupted ones. Handle `onCancel` as well as `onComplete`. - Keep overlays in the floating portal root so they share the application's coordinate space and theme. - Verify the relationship under rapid directional input, not just single steps. Second-order bugs show up when the primary motion is interrupted repeatedly. - Check it with reduced motion on. When the primary change snaps, the dependent element must snap with it and land in the right place. ## Recommended patterns - Join a container's transition with `stateChangeAnimations` when timing must match exactly, so both effects use one clock. - Derive dependent values from shared state such as progress, a state change, or a scroll offset. - Supply anchor geometry to overlays instead of correcting their position after placement. - Feed state to the component that owns the dependent visual and let it animate. ## Avoid - Derive from shared state instead of measuring a moving element every frame. - Join the primary animation's timeline rather than running a second loop. - Prefer in-place material feedback over translating a list element, which also moves its neighbors' apparent positions. - Use public callbacks and geometry providers rather than private DOM or generated class names. ## Related resources [Motion](/docs/develop/webapps/design/foundations/motion/overview/), [Spring Motion](/docs/develop/webapps/design/foundations/motion/spring-motion/), [Interpolated Motion](/docs/develop/webapps/design/foundations/motion/interpolated-motion/), [Container](/docs/develop/webapps/design/components/foundation/container/), [Interactable Base](/docs/develop/webapps/design/components/foundation/interactable-base/), [Scroll View](/docs/develop/webapps/design/components/foundation/scroll-view/), [Vignette](/docs/develop/webapps/design/components/foundation/vignette/), [Tooltip](/docs/develop/webapps/design/components/mrbd/tooltip/) ### Icons The toolkit provides an optional collection of icons designed for Meta Ray-Ban Display. Toolkit components accept icon data through `IconSource` slots and own each icon's size, alignment, spacing, and tint. ## Icon assets Install the icon collection from npm: ```sh npm install @wearables-ui-toolkit/icons ``` See the [`@wearables-ui-toolkit/icons` npm package](https://www.npmjs.com/package/@wearables-ui-toolkit/icons), or browse the [icons package on GitHub](https://github.com/facebook/meta-ray-ban-display-ui-toolkit-web/tree/main/packages/icons) to see the available assets and package source. The `@wearables-ui-toolkit/icons` package ships the public SVG icon set as a separate, optional dependency. Icon assets are not licensed under the Apache License 2.0. See the [Meta Wearables Developer Terms](https://wearables.developer.meta.com/terms/) and the package [license](https://github.com/facebook/meta-ray-ban-display-ui-toolkit-web/blob/main/packages/icons/LICENSE), which reproduces verbatim excerpts from Sections 2 and 10. The package provides: - tree-shakeable named exports, one per asset; - individual assets at `@wearables-ui-toolkit/icons/svg/.svg`; - `manifest.json` and `keyword-index.json` for searchable icon tools; and - an opt-in `browser` subpath for interfaces that select arbitrary manifest assets at runtime. Most icons include filled and outline variants, such as `airplaneFilled` and `airplaneOutline`. Import icons by name so the bundler can retain only the assets the application uses: ```tsx import {Button} from '@wearables-ui-toolkit/mrbd'; import {airplaneFilled} from '@wearables-ui-toolkit/icons';

; } ``` The controller is stable for the component's lifetime, throttles to its `frameRate` (thirty updates per second by default), stops scheduling frames while the document is hidden, and snaps straight to its target when the user prefers reduced motion. ## Animate transform and opacity `transform` and `opacity` are the two properties a browser can animate without recomputing layout. Everything else — `width`, `height`, `top`, `left`, `margin`, `padding` — relayouts the subtree on every frame, and on a toolkit surface it also invalidates the measured size the material geometry was generated from. Express timing with the exported motion constants rather than raw numbers: ```tsx import { AnimationDurations, Interpolators, createTransition, } from '@wearables-ui-toolkit/mrbd'; const style = { transition: createTransition( ['transform', 'opacity'], AnimationDurations.CONTAINER_STATE_CHANGE, Interpolators.CONTAINER_SCALE, ), }; ``` If a size really has to change, animate a `scale` transform over a fixed layout box, or let the component's own state transition handle it. ### Reduced motion Honor `prefers-reduced-motion: reduce` on both sides of the stack: pass JavaScript durations through `reducedMotionDuration`, and guard CSS transitions with the media query. `useSpringAnimation` already snaps instead of tweening. See [Accessibility](/docs/develop/webapps/design/foundations/utilities/accessibility/) for the full pattern. ## One same-axis scroller per route Use `ScrollView`, or `VerticalList` for a list, and give a route exactly one scroller per axis. Nested same-axis scrollers are not just a performance problem. Directional navigation hands unclaimed movement to the nearest scroll container, so two vertical scrollers inside one another compete for the same arrow key: focus sticks, the wrong region scrolls, or the outer region never reaches its end. Crossing axes is fine — a horizontal rail inside a vertical list is a supported composition, because each axis has exactly one owner. Long collections belong in the toolkit scroll infrastructure rather than a custom virtualized list. The scroller already coordinates scroll-to-focused behavior, fading edges, and directional handoff; a custom one has to reimplement all three. ## Keep props stable Every new object identity invalidates a memoized subtree. On a screen full of interactables, that is the difference between one component re-rendering and all of them. - Hoist icon data, style objects, and static arrays to module scope. - Wrap callbacks passed into list rows in `useCallback`, and derived objects in `useMemo`. - Create each `ContainerMaterial` and shape provider once with `useMemo` — one instance per mounted host. A material tracks the visual state it is animating between, and a shape provider caches the geometry it generated, so replacing either on every render throws both away. - Give list rows stable keys derived from the data, not the index, so a data update re-renders a row instead of remounting it. Remounting a focused row drops focus and restarts its state transition. - Do not build a new inline object for a prop that a component compares by identity. ## Clean up everything you start Anything created in an effect must be released by that effect's cleanup, or it keeps running after the route is gone. ```tsx import {useEffect} from 'react'; useEffect(() => { const timer = window.setInterval(tick, 1000); const controller = new AbortController(); window.addEventListener('resize', onResize, {signal: controller.signal}); return () => { window.clearInterval(timer); controller.abort(); }; }, [onResize, tick]); ``` - Clear every timer and interval, cancel every animation frame, disconnect every observer, and remove every listener. - Render portal content with `createPortal` so React unmounts it with the owning component. Never append nodes into the portal root imperatively — see [Floating Portals](/docs/develop/webapps/design/foundations/utilities/floating-portals/). - Call `clearPathCache()` only when tearing down a long-lived surface that generated many one-off geometries, not on a schedule. See [Smooth Corners](/docs/develop/webapps/design/foundations/utilities/smooth-corners/). ## Load routes lazily, warm them early Split each route into its own chunk and warm the chunk before the user commits to the navigation. ```tsx import {createPreloadableLazyComponent} from '@wearables-ui-toolkit/mrbd'; const SettingsRoute = createPreloadableLazyComponent( () => import('./SettingsRoute'), module => module.SettingsRoute, ); ``` `SettingsRoute.Component` renders the lazy route; `SettingsRoute.preload()` warms it. Wire the warming automatically by wrapping the app in `RoutePreloadProvider` and giving it a `preloadRoute` handler that maps a `preloadKey` to the matching `preload()` — without that handler preloading stays off — then marking entry points with `RoutePreloadTarget` (or `useRoutePreloadTarget` when you own the element) and its `preloadKey`. A target warms on focus, on pointer enter, and on visibility, and each of those triggers can be turned off individually. Warm only the routes a user is plausibly about to open; preloading everything just moves the cost earlier. ## Validation checklist Run this against the built app on the target runtime, not only in unit tests. 1. Type-check, format, lint, run your tests, and produce a production build. None of those prove behavior; they only clear the floor for the steps below. 2. Exercise every reachable interaction state: default, focused, pressed, disabled, selected, loading, and empty. 3. Navigate exclusively with directional input and the activation key. 4. Inspect initial focus, focus restoration, route history, and system Back. 5. Scroll to the exact beginning and end of every scroll region, and repeat the same direction rapidly at each end. 6. Capture each surface and each meaningful scroll state at representative viewport sizes, including a materially different one. 7. Wait for animations and web fonts to settle before comparing anything visually; a measurement taken mid-transition is not a bug. 8. Check for clipping, overflow, incorrect insets, doubled materials, unstable layout, and text or icon misalignment. 9. Validate custom themes and materials over the toolkit window background, where the additive display makes low-contrast pairings fail first. 10. Re-run the walkthrough with reduced motion enabled. 11. Confirm every toolkit import resolves to `@wearables-ui-toolkit/mrbd`, a documented per-component subpath, or the `react-router` subpath — nothing deeper. ### Profiling When something is slow, measure before changing anything: - Record a performance profile while reproducing the interaction and look for long tasks, forced reflow warnings, and layout thrash in the same frame. - Use the React profiler to find components re-rendering on every frame. A spring or scroll handler that re-renders React is the usual cause. - Check paint and layer counts before adding another animated layer; a full-size animated overlay is expensive even when it is transparent. ## Recommended patterns - Animate `transform` and `opacity` with `AnimationDurations` and `Interpolators` so the browser can composite consistent motion. - Let components measure and size themselves from available space. - Keep one scroller per axis per route so directional navigation has one owner. - Release timers, listeners, observers, frames, and portals on unmount. ## Avoid - Keep layout reads out of render, scroll handlers, and animation frames to prevent synchronous layout. - Use imperative frame callbacks instead of React state for frame-rate updates. - Keep focused regions, animated layers, and material hosts mounted while updating props; remounting drops focus and animation state. - Use one same-axis scroller per route rather than nesting competing scrollers. - Derive sizes from the available viewport, content, and semantic tokens. This keeps layouts responsive across supported viewports; avoid fixed device-resolution and private component-metric assumptions. - Complete the validation checklist instead of treating a successful build and tests as rendered-behavior evidence. ## Related resources [Accessibility](/docs/develop/webapps/design/foundations/utilities/accessibility/), [Smooth Corners](/docs/develop/webapps/design/foundations/utilities/smooth-corners/), [Floating Portals](/docs/develop/webapps/design/foundations/utilities/floating-portals/), [ScrollView](/docs/develop/webapps/design/components/foundation/scroll-view/), [Motion overview](/docs/develop/webapps/design/foundations/motion/overview/), [Route Navigation](/docs/develop/webapps/design/guides/route-navigation/) ### Floating portals Render floating surfaces through the shared portal root. Keeping overlays out of their anchor's inline DOM prevents ancestor overflow and stacking contexts from clipping them and keeps them above page content. Everything the toolkit floats resolves the same root: - Tooltips raised by an interactable's `tooltipText` or `tooltipContent`, which means every control built on `InteractableBase`. - The standalone `Tooltip` surface. - `ContextMenu` and `VerticalMenu`, which are anchored as focusable tooltip content on their trigger. - Toasts queued with `useToast` and rendered by `ToastContainer`. - The expanded text surface `Modal` opens when its subtitle is truncated. `App` creates that root for you: a full-size, pointer-transparent layer that is the last child of its content root, published through `FloatingPortalRootProvider`. Ordinary applications should let `App` own this API. ## Usage Use the provider only when you embed the toolkit inside a host that must own the overlay layer itself — for example a canvas that positions the app inside a larger document, where overlays have to be clipped to that region. Scope overlays to a subtree by rendering a provider around it and pointing the provider at an element inside that subtree. Hold the element in state rather than a ref so the subtree re-renders once the element exists. ```tsx import {useState, type ReactNode} from 'react'; import {FloatingPortalRootProvider} from '@wearables-ui-toolkit/mrbd'; import styles from './EmbeddedSurface.module.css'; export function EmbeddedSurface({children}: {children: ReactNode}) { const [portalRoot, setPortalRoot] = useState(null); return (

{children}

); } ``` ```css .surface { position: relative; overflow: hidden; border-radius: var(--uit-corner-radius-medium); background: var(--uit-color-background-window); } .overlayLayer { position: absolute; inset: 0; pointer-events: none; } ``` Keep the overlay element the last child of the region it covers so it paints over the content, give it `pointer-events: none` so it never intercepts input meant for the content below, and make the region a positioned ancestor so absolute coordinates resolve against it. Content outside the provider keeps using whatever root it resolves on its own, so two independent regions can each own their overlays. ## Props ### `FloatingPortalRootProvider` The full prop type is `FloatingPortalRootProviderProps`. Both props are required. | Prop | Type | Default | Description | |---|---|---|---| | `root` | `HTMLElement \| null` | — | Element floating content is portalled into. Required. `null` is a valid transient value while the element is still mounting, and suppresses floating content until it resolves. | | `children` | `ReactNode` | — | Subtree that uses this root. Required. | ## `useFloatingPortalRoot()` ```ts import {useFloatingPortalRoot} from '@wearables-ui-toolkit/mrbd'; const portalRoot: HTMLElement | null = useFloatingPortalRoot(); ``` Returns the element overlay content should render into. Resolution order: 1. The nearest `FloatingPortalRootProvider` value — including an explicit `null`, which is honored rather than falling through. 2. `document.body` when no provider is present. 3. `null` when there is no `document`, so server rendering is safe. Call it when you build a custom surface that must live in the same overlay layer as the toolkit popups, and render nothing until it resolves. ```tsx import {createPortal} from 'react-dom'; import {useFloatingPortalRoot} from '@wearables-ui-toolkit/mrbd'; import type {ReactNode} from 'react'; function Overlay({children}: {children: ReactNode}) { const portalRoot = useFloatingPortalRoot(); return portalRoot == null ? null : createPortal(children, portalRoot); } ``` ## Behavior - Portalled content stays inside the React tree, so context and React event bubbling keep working across the portal boundary. CSS custom properties are the exception — they cascade through the DOM, not the React tree. The design tokens are declared globally, so a portalled surface is themed correctly wherever its root lives, but a token override scoped to one subtree reaches portalled content only when the portal root sits inside that subtree. - A popup's position is measured from its anchor's viewport rectangle and then re-expressed relative to the portal root: fixed positioning when the root is `document.body`, and absolute positioning offset by the root's bounding rectangle otherwise. A scoped root and the document body therefore produce the same on-screen placement. - Placement is a preference, not a guarantee. The positioning system flips or clamps a surface to keep it inside the visible boundary, so never lay out content assuming a specific side. - Surfaces in the overlay layer are pointer-transparent themselves; only focusable popup content, such as a context menu or a focusable tooltip, takes pointer events back. That is why the layer as a whole can stay `pointer-events: none` without breaking the popups it hosts. - Overlay surfaces are dismissed by Escape and system Back before either reaches route navigation, and focus returns to the control that opened them. - Focus navigation treats a popup as its own scope: arrow keys move within the popup, and leaving it reports a dismissal reason instead of jumping into page content behind it. ## Recommended patterns - Let `App` own the portal root in ordinary applications so all overlays share one coordinate and theme context. - Create a root only when a host region must clip or own the overlay layer, and keep it pointer-transparent. - Read the root through `useFloatingPortalRoot` instead of querying the DOM. - Guard against `null` before portalling because the root can be unresolved or unavailable during server rendering. ## Avoid - Fix the underlying layout rather than portalling the toolkit popups into an arbitrary element to escape it. - Keep one overlay root per region instead of nesting a second root. - Treat DOM structure, generated class names, and stacking values as private implementation details. - The overlay layer must remain pointer-transparent; enabling pointer events on it swallows input meant for covered content. ## Related resources [App](/docs/develop/webapps/design/components/foundation/app/), [InteractableBase](/docs/develop/webapps/design/components/foundation/interactable-base/), [Tooltip](/docs/develop/webapps/design/components/mrbd/tooltip/), [ContextMenu](/docs/develop/webapps/design/components/mrbd/context-menu/), [VerticalMenu](/docs/develop/webapps/design/components/mrbd/vertical-menu/), [Toast](/docs/develop/webapps/design/components/mrbd/toast/), [Accessibility](/docs/develop/webapps/design/foundations/utilities/accessibility/) ### Smooth corners Use these utilities when custom geometry needs the same smooth corners as the toolkit. The toolkit corners are not circular arcs. A corner blends into the flat edge through cubic bezier segments so curvature changes continuously, which is why a toolkit surface reads as softer than the same radius applied with `border-radius`. These utilities produce that geometry as an SVG path string. Reach for them only when you are drawing custom geometry — a canvas layer, a clip path, a custom material shape. Components and materials already apply the correct shape, and a shape provider is the supported way to change a component's geometry. ## Signatures ```ts import { clearPathCache, generateSmoothRoundedRectPath, getCachedSmoothRoundedRectPath, type SmoothRoundedRectParams, } from '@wearables-ui-toolkit/mrbd'; ``` ```ts declare function generateSmoothRoundedRectPath( params: SmoothRoundedRectParams, ): string; declare function getCachedSmoothRoundedRectPath( params: SmoothRoundedRectParams, ): string; declare function clearPathCache(): void; ``` All three are pure with respect to the DOM: they take numbers and return a path string. Nothing is measured for you, so feed them a size you measured yourself. ### `getCachedSmoothRoundedRectPath(params)` Returns the path for `params`, reusing a previously generated string when the same parameters were requested before. This is the component entry point and the recommended default because it avoids recomputing stable geometry. ### `generateSmoothRoundedRectPath(params)` Identical geometry, recomputed on every call and never stored. Use it when the result is genuinely single-use and you do not want to occupy a cache slot. ### `clearPathCache()` Empties the shared cache. Call it only at a lifecycle boundary that makes the retained strings pointless — for example tearing down a long-lived surface that generated many one-off sizes. ### `SmoothRoundedRectParams` | Field | Type | Default | Description | |---|---|---|---| | `width` | `number` | — | Width of the rectangle. Required. | | `height` | `number` | — | Height of the rectangle. Required. | | `cornerRadius` | `number` | — | Corner radius, clamped to the range from zero through half the shorter side. Required. | | `x` | `number` | `0` | Left coordinate of the rectangle. | | `y` | `number` | `0` | Top coordinate of the rectangle. | | `smoothing` | `number` | `0.75` | How far the bezier transition extends past the circular arc endpoint along each edge, clamped to the range zero through one. Zero matches `border-radius` exactly, `0.75` is the toolkit standard, one is maximum smoothing. | All values are in the same coordinate space as the element you are drawing into, so pass the measured layout size rather than a token string. ## Usage ```tsx import {useLayoutEffect, useRef, useState, type ReactNode} from 'react'; import {getCachedSmoothRoundedRectPath} from '@wearables-ui-toolkit/mrbd'; import styles from './SmoothOutline.module.css'; function readLengthToken(element: HTMLElement, name: string): number { return Number.parseFloat(getComputedStyle(element).getPropertyValue(name)) || 0; } export function SmoothOutline({children}: {children: ReactNode}) { const hostRef = useRef(null); const [path, setPath] = useState(''); useLayoutEffect(() => { const host = hostRef.current; if (host == null) { return; } const observer = new ResizeObserver(() => { setPath( getCachedSmoothRoundedRectPath({ width: host.offsetWidth, height: host.offsetHeight, cornerRadius: readLengthToken(host, '--uit-corner-radius-large'), }), ); }); observer.observe(host); return () => observer.disconnect(); }, []); return (

{children}

); } ``` ```css .host { position: relative; padding: var(--uit-spacing-medium); } .outline { position: absolute; inset: 0; pointer-events: none; } ``` The returned string is a path `d` value, so the same result also drives `clip-path: path("…")` and `new Path2D(pathString)` on a canvas. ## Behavior The generator picks the geometrically correct construction for the inputs: | Input | Result | |---|---| | `cornerRadius` at or below zero | A plain rectangle, four straight edges. | | A square whose radius reaches half its side | A true circle, emitted as two semicircular arcs. | | A radius that reaches half the shorter side | A stadium: straight edges with pure circular ends. Smoothing is intentionally dropped, because a smoothed corner is undefined once there is no flat edge left to blend into. | | Anything else | The smoothed corner: three cubic segments per corner — into the arc, the arc, and out of it. | Inputs are clamped before the construction is chosen: a `cornerRadius` larger than half the shorter side is pulled down to exactly half, so it lands on the stadium case — or on the circle case when the rectangle is square — and a `smoothing` outside zero through one is pulled back into range. Smoothing is reduced per corner when the flat edge is too short to absorb it. The transition extends along an edge from the corners at both of its ends, so a short edge shortens both extensions, down to a plain circular arc when there is no room at all. Two surfaces built from the same radius and smoothing can therefore differ slightly when their proportions differ. ### When caching matters The cache key is the full parameter set — `x`, `y`, `width`, `height`, `cornerRadius`, and the resolved `smoothing`. Two calls hit the cache only when every one of those matches. Caching pays off when the same geometry is requested repeatedly: - Many elements share one size, such as every row in a list. - A component re-renders at a stable size, so each render asks for the same path. - A canvas material redraws the same shape across interaction states. Caching does nothing when the geometry changes every call. The cache holds a bounded number of entries and evicts the least recently used one, so animating a width or height not only misses on every frame but also pushes out entries that were being reused. Drive continuous motion with a transform on a path generated once, and regenerate only when the layout size actually settles on a new value. ## Recommended patterns - Use the cached generator and recompute only when measured size or radius changes, so stable geometry reuses its path. - Read radius from a `--uit-corner-radius-*` token rather than a numeric literal. - Use a shape provider when geometry belongs to a component or material. - Stabilize measured sizes before generating paths so subpixel jitter does not create a new cache entry per frame. ## Avoid - Generate a path when layout settles rather than on every animation frame. - Use the component or material that already draws a toolkit surface instead of approximating its path. - Use public shape APIs rather than applying paths over component internals. - Call `clearPathCache()` only at a lifecycle boundary. Calling it during render or on a timer discards work other surfaces still reuse. ## Related resources [Shape Providers](/docs/develop/webapps/design/foundations/materials/shape-providers/), [Custom Materials](/docs/develop/webapps/design/foundations/materials/custom-materials/), [Corner Radius](/docs/develop/webapps/design/foundations/theme/corner-radius/), [Performance and Validation](/docs/develop/webapps/design/foundations/utilities/performance-and-validation/) ### Overview Choose the semantic component that matches the interface's purpose. Semantic components own the expected layout, focus behavior, accessibility, material, and motion; use Foundation primitives only when no semantic component fits. This page helps you choose between components. For props and examples, follow the links to the individual component pages or browse the [Foundation overview](/docs/develop/webapps/design/foundations/overview/) and [Meta Ray-Ban Display component catalog](/docs/develop/webapps/design/components/mrbd/overview/). ## Choose a component ### Routes and navigation | You need | Use | | --- | --- | | The application shell, once at the root | [`App`](/docs/develop/webapps/design/components/foundation/app/) | | A route with a standard header | [`Page`](/docs/develop/webapps/design/components/mrbd/page/) | | A route with swipeable sibling sections | [`SubNavigationPager`](/docs/develop/webapps/design/components/mrbd/sub-navigation-pager/) | | Animated transitions between routes | [`PageTransition`](/docs/develop/webapps/design/components/foundation/page-transition/) | | A generic multi-page container within a route | [`Pager`](/docs/develop/webapps/design/components/foundation/pager/) | | Position within a pager or carousel | [`PaginationIndicator`](/docs/develop/webapps/design/components/mrbd/pagination-indicator/) | ### Content and collections | You need | Use | | --- | --- | | A vertical list of rows | [`VerticalList`](/docs/develop/webapps/design/components/foundation/vertical-list/) with [`ListItem`](/docs/develop/webapps/design/components/mrbd/list-item/) | | Another scrolling region | [`ScrollView`](/docs/develop/webapps/design/components/foundation/scroll-view/) | | Horizontal browsing between destinations | [`Carousel`](/docs/develop/webapps/design/components/foundation/carousel/) | | An activatable media or artwork block | [`Card`](/docs/develop/webapps/design/components/foundation/card/) | | A stacked set of cards | [`CardStack`](/docs/develop/webapps/design/components/foundation/card-stack/) | | Icon actions revealed by swiping a row | [`SwipeToReveal`](/docs/develop/webapps/design/components/mrbd/swipe-to-reveal/) | ### Actions and choices | You need | Use | | --- | --- | | One clear action | [`Button`](/docs/develop/webapps/design/components/mrbd/button/) | | Overflowing horizontal actions | [`ButtonRail`](/docs/develop/webapps/design/components/mrbd/button-rail/) | | A small set of actions that fits | [`ButtonGroup`](/docs/develop/webapps/design/components/mrbd/button-group/) | | A compact messaging reply | [`QuickReplyButton`](/docs/develop/webapps/design/components/mrbd/quick-reply-button/) | | Free-form text entry | [`InputTextView`](/docs/develop/webapps/design/components/mrbd/input-text-view/) | | A toggle, radio choice, or slider in a row | [`ListItem`](/docs/develop/webapps/design/components/mrbd/list-item/) with its built-in control | | A standalone adjustable value | [`SliderBar`](/docs/develop/webapps/design/components/mrbd/slider-bar/) or [`IsolatedControl`](/docs/develop/webapps/design/components/mrbd/isolated-control/) | | Media playback position | [`Scrubber`](/docs/develop/webapps/design/components/mrbd/scrubber/) | | A square control or launcher tile | [`ControlTile`](/docs/develop/webapps/design/components/mrbd/control-tile/) or [`AppControlTile`](/docs/develop/webapps/design/components/mrbd/app-control-tile/) | | Manifest-themed Web App identity | [`WebAppIcon`](/docs/develop/webapps/design/components/mrbd/web-app-icon/) | ### Feedback and overlays | You need | Use | | --- | --- | | Structured decision or informational content in a route | [`Modal`](/docs/develop/webapps/design/components/mrbd/modal/) | | Transient outcome feedback | [`Toast`](/docs/develop/webapps/design/components/mrbd/toast/) | | A hint attached to a focused element | Built-in tooltip props or [`Tooltip`](/docs/develop/webapps/design/components/mrbd/tooltip/) | | An anchored action menu | [`ContextMenu`](/docs/develop/webapps/design/components/mrbd/context-menu/) | | An anchored text-first menu | [`VerticalMenu`](/docs/develop/webapps/design/components/mrbd/vertical-menu/) | | Legibility over media | [`Scrim`](/docs/develop/webapps/design/components/mrbd/scrim/) or [`Vignette`](/docs/develop/webapps/design/components/foundation/vignette/) | ### Progress and status | You need | Use | | --- | --- | | Linear determinate progress | [`ProgressIndicator`](/docs/develop/webapps/design/components/mrbd/progress-indicator/) | | Circular determinate progress | [`ProgressRing`](/docs/develop/webapps/design/components/mrbd/progress-ring/) or [`CircularProgressBar`](/docs/develop/webapps/design/components/mrbd/circular-progress-bar/) | | Unknown-duration progress | [`IndeterminateLoader`](/docs/develop/webapps/design/components/mrbd/indeterminate-loader/) | | A loading skeleton | [`Shimmer`](/docs/develop/webapps/design/components/foundation/shimmer/) | | A system-style value overlay | [`VolumeIndicator`](/docs/develop/webapps/design/components/mrbd/volume-indicator/) or [`ZoomIndicator`](/docs/develop/webapps/design/components/mrbd/zoom-indicator/) | | A short input affordance | [`ActionHint`](/docs/develop/webapps/design/components/mrbd/action-hint/) | ### Identity, labels, and text | You need | Use | | --- | --- | | A person or entity image | [`Avatar`](/docs/develop/webapps/design/components/mrbd/avatar/) | | A minimal status label | [`Tag`](/docs/develop/webapps/design/components/mrbd/tag/) | | A richer label with metadata or an icon | [`Chip`](/docs/develop/webapps/design/components/mrbd/chip/) | | Body or heading text | [`TextView`](/docs/develop/webapps/design/components/foundation/text-view/) | | Text that crossfades when it changes | [`TextSwitcher`](/docs/develop/webapps/design/components/foundation/text-switcher/) | | Long text that must clamp and expand | [`ReadMoreTextView`](/docs/develop/webapps/design/components/mrbd/read-more-text-view/) | ## Common decisions ### `Page` or `SubNavigationPager`? Use [`Page`](/docs/develop/webapps/design/components/mrbd/page/) for a normal route with one content area. Use [`SubNavigationPager`](/docs/develop/webapps/design/components/mrbd/sub-navigation-pager/) when the route contains sibling sections that users move between. They are alternative route roots; do not combine them. ### `VerticalList` or `ScrollView`? Use [`VerticalList`](/docs/develop/webapps/design/components/foundation/vertical-list/) for a column of rows, usually [`ListItem`](/docs/develop/webapps/design/components/mrbd/list-item/) components. Use [`ScrollView`](/docs/develop/webapps/design/components/foundation/scroll-view/) for other scrolling content. Keep one same-axis scroll owner per route so focus and directional navigation remain predictable. ### `ButtonRail` or `ButtonGroup`? Use [`ButtonRail`](/docs/develop/webapps/design/components/mrbd/button-rail/) when actions can overflow, need horizontal scrolling, or form a bottom action surface. Use [`ButtonGroup`](/docs/develop/webapps/design/components/mrbd/button-group/) when a small set fits and should remain together, such as actions in a [`Modal`](/docs/develop/webapps/design/components/mrbd/modal/). ### Toast, tooltip, menu, or modal? - Use [`Toast`](/docs/develop/webapps/design/components/mrbd/toast/) for transient outcome feedback that requires no action. - Use [`Tooltip`](/docs/develop/webapps/design/components/mrbd/tooltip/) to explain a focused control. - Use [`ContextMenu`](/docs/develop/webapps/design/components/mrbd/context-menu/) or [`VerticalMenu`](/docs/develop/webapps/design/components/mrbd/vertical-menu/) for actions anchored to an element. - Use [`Modal`](/docs/develop/webapps/design/components/mrbd/modal/) for structured content within a route. It is an inline panel, not a blocking overlay; prefer a dedicated route for a blocking decision. ### Semantic component or Foundation primitive? Prefer the semantic component. If none fits, use [`Container`](/docs/develop/webapps/design/components/foundation/container/) for an interactable material surface, [`StaticContainer`](/docs/develop/webapps/design/components/foundation/static-container/) for a non-interactive one, or [`InteractableBase`](/docs/develop/webapps/design/components/foundation/interactable-base/) for interaction behavior without material. Do not recreate an existing component from generic elements or override its internal anatomy. ## Cross-component rules - Render exactly one [`App`](/docs/develop/webapps/design/components/foundation/app/) at the application root. It owns global focus, toast, and portal infrastructure. - Let [`Page`](/docs/develop/webapps/design/components/mrbd/page/) own the route header and its relationship to content. Do not place a standalone [`Header`](/docs/develop/webapps/design/components/mrbd/header/) in route content. - Use one scrolling owner per axis and route. Avoid nesting [`VerticalList`](/docs/develop/webapps/design/components/foundation/vertical-list/) inside [`ScrollView`](/docs/develop/webapps/design/components/foundation/scroll-view/). - Use component-provided icon slots and pass an `IconSource`; the host component owns icon size, placement, and tint. See [Icons](/docs/develop/webapps/design/foundations/utilities/icons/). - Render anchored surfaces through the portal infrastructure supplied by [`App`](/docs/develop/webapps/design/components/foundation/app/) so they remain aligned with their owners. - Keep component internals intact. Customize through documented props, semantic tokens, and supported composition points. ## Related guidance - [Application patterns](/docs/develop/webapps/design/guides/application-patterns/) - [Screen patterns](/docs/develop/webapps/design/guides/screen-patterns/) - [Navigation](/docs/develop/webapps/design/guides/navigation-and-focus/) - [Customization and composition](/docs/develop/webapps/design/guides/customization-and-composition/) - [Correct patterns](/docs/develop/webapps/design/guides/correct-patterns/) ### App Render exactly one `App` at the root of every toolkit application and wrap all application content with it. `App` registers the text font, scopes the stylesheet reset and base typography, establishes directional navigation and automatic initial focus, mounts the toast presenter, and creates the portal root for tooltips, menus, and other floating interface elements. Keeping these responsibilities in one root makes focus, platform-aware interaction feedback, and overlays consistent across the application. `App` fills its parent, so the host page must provide a box with a real size. Prefer layouts based on the available viewport rather than a fixed viewport size so content remains responsive. ## Usage Render `App` around the routed application. It loads the packaged stylesheet. ```tsx import { createRoot } from 'react-dom/client'; import { App } from '@wearables-ui-toolkit/mrbd'; import { AppRoutes } from './AppRoutes'; function Root() { return ( ); } createRoot(document.getElementById('root')!).render(); ``` `App` loads the packaged component styles, semantic token custom properties, and typography classes automatically. Give the host document a full-viewport box so `App` has space to fill, and use the window background role for the document: ```css html, body, #root { height: 100%; margin: 0; background-color: var(--uit-color-background-window); } ``` `App` already paints this background on its root. Applying it to the document as well prevents areas outside `App`, such as space exposed by overscroll, from showing the browser's default white. Use `className` or `style` on the outer root for an application-wide inset or background. `App` preserves its sizing unless your values override those properties: {% raw %} ```tsx ``` {% endraw %} `App` is also available from its component subpath: ```ts import { App } from '@wearables-ui-toolkit/mrbd/App'; ``` ## Props The complete prop type is `AppProps`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | — | Required application content. All content rendered with the toolkit must be inside `App`. | | `className` | `string` | — | Class applied to the outer root element. | | `style` | `CSSProperties` | — | Inline styles merged over the root's positioning and sizing styles. Values supplied by the application take precedence for the same property. | `App` accepts no other DOM props and does not forward a ref. ## What App provides - **Text font.** `App` registers Noto Sans in the regular, medium, and bold weights used by the design system. It checks for an installed copy first by registering local-only font faces ahead of the downloadable family. On its first mount, `App` appends the Google Fonts stylesheet link and preconnect hints; the browser fetches font files only when no local copy is installed. No font package is needed, and the toolkit registers no other family. - **Theme scope.** The root anchors the stylesheet's element reset and base typography. The box-sizing and margin and padding reset, text font stack, font smoothing, window background, and primary text colors apply within this subtree. The zero-specificity reset does not override component styles or affect the host document outside `App`. - **Platform profile.** `App` supplies the Meta Ray-Ban Display platform profile to its subtree. Components such as `Container` and `Surface` read this profile automatically when calculating their default content scale, so applications do not pass a platform value to individual components. - **Focus root.** `App` scopes the focus-navigation provider to its content and enables automatic initial focus. On mount, and when the focused element is removed, the toolkit focuses the top-left eligible interactable. The toolkit skips elements without a measured box and elements with [`initialFocusEligible={false}`](/docs/develop/webapps/design/components/foundation/interactable-base/). If nothing else has focus on mount, `App` focuses its content element to give directional navigation a starting point. - **Toast presenter.** `App` owns the toast container. Use the toast API to show a toast; mounting another presenter is unsupported because it can produce duplicate or inconsistent announcements. - **Floating portal root.** `App` provides an absolutely positioned overlay layer inside the content element. The layer sits above ordinary content and ignores pointer events while tooltips, context menus, vertical menus, and other floating interface elements render through it. Replacing this provider is unsupported because the toolkit owns consistent overlay placement and focus scope. - **Tooltip boundary.** `App` uses the content element as the boundary for anchored tooltips, keeping them within the application viewport. ## Behavior **Layout.** The outer root is relatively positioned and fills its parent in both axes. A nested content element fills the root and contains application content, the toast presenter, and the portal layer. The application can add padding or a background through `style`; values supplied there take precedence over the root's own styles for the same properties. **Font registration.** `App` inserts the font faces and stylesheet link into the document head once and leaves them in place. Registration is keyed to the injected stylesheet, so remounting `App`, or rendering more than one, does not duplicate them. During server rendering, when no document exists, `App` skips registration. **Focus.** The toolkit uses arrow keys for directional focus movement among interactables inside `App` and preserves native Tab traversal so keyboard and assistive-technology users are not trapped. `App` fixes the provider settings and exposes no tuning props. If an embedded host temporarily parks document focus on an unowned application ancestor, the toolkit restores the current interactable instead of clearing its visual focus state. Render a nested [`FocusNavigationProvider`](/docs/develop/webapps/design/components/foundation/focus-navigation-provider/) only when a subtree needs a different container or arrow-key-only traversal. **Rendering cost.** `App` is memoized and re-renders only when `children`, `className`, or `style` changes. Prefer keeping application state below `App` so updates do not recreate the root. **Scope.** `App` scopes each service it installs to its subtree. A nested `App` would create another focus root, toast presenter, and portal root, so this composition is unsupported. ## Accessibility - The application owns the document title, landmarks, and accessible names; `App` does not add roles, landmarks, or accessible names. - The content element is programmatically focusable but is not a tab stop. This preserves the first real control as the target of the first Tab press. - Floating interface elements render through a layer inside the content element, so overlays stay in the same accessibility subtree as their related content. ## Application responsibilities - Render one `App` at the top of the tree, above the router, so the toolkit has one consistent focus and overlay root. - Let `App` load the component styles, semantic tokens, and typography classes. - Give the mount element a real height so `App` can fill it responsively. - Let `App` own the platform profile, toasts, floating portals, and initial focus. ## Avoid - Avoid recreating only part of the application shell; use `App` so fonts, focus, toasts, and portals remain coordinated. - Do not nest `App`. Multiple roots are an unsupported composition and create competing focus, toast, and portal ownership. - Do not mount another toast presenter or floating-portal provider. `App` owns both services for its subtree. - Avoid loading a different text font or overriding the registered family. Noto Sans is the public toolkit text font and keeps typography consistent. - Prefer a dark window background for the additive-light display. A light page background emits light where the design expects transparency. - Avoid fixed device dimensions. Size the root from the available viewport so the layout stays responsive across Meta Ray-Ban Display environments. ## Related resources [Installation](/docs/develop/webapps/design/getting-started/installation/), [Page](/docs/develop/webapps/design/components/mrbd/page/), [Toast](/docs/develop/webapps/design/components/mrbd/toast/), [FocusNavigationProvider](/docs/develop/webapps/design/components/foundation/focus-navigation-provider/), [Floating portals](/docs/develop/webapps/design/foundations/utilities/floating-portals/), [Route navigation](/docs/develop/webapps/design/guides/route-navigation/) ### Card Use `Card` for image-forward or custom content that forms one destination. It builds on [Container](/docs/develop/webapps/design/components/foundation/container/) with the card material, a medium rounded shape, and optional top and bottom gradient scrims that keep overlaid text legible across varied imagery. Treat the whole card as one focus and press target. Descendants must not expose separate actions because nested targets create ambiguous focus and activation. For a standard row, prefer [ListItem](/docs/develop/webapps/design/components/mrbd/list-item/). `CardAboveScrim` and `CardBelowScrim` identify whether content paints above or below the scrim. ## Usage ```tsx import { Card, CardAboveScrim, CardBelowScrim, ScrimType, TextStyle, TextView, } from '@wearables-ui-toolkit/mrbd'; export function StoryCard({ story, onOpen }: StoryCardProps) { return (

{story.title}

); } ``` ```css .story-image { width: 100%; height: 100%; object-fit: cover; } ``` Let the card clip full-bleed media to its shape. Inset content that should not reach the edge with a spacing token: ```css .story-caption { padding: var(--uit-spacing-large); } ``` For a presentational card with no action, disable the interaction capabilities together: ```tsx import { Card, ScrimType } from '@wearables-ui-toolkit/mrbd'; ; ``` `Card`, both scrim layer components, and `ScrimType` are also available from the component subpath: ```ts import { Card, CardAboveScrim, CardBelowScrim, ScrimType, } from '@wearables-ui-toolkit/foundation/components/Card'; ``` ## Props The complete prop type is `CardProps`. It extends [Container](/docs/develop/webapps/design/components/foundation/container/) props, which extend [InteractableBase](/docs/develop/webapps/design/components/foundation/interactable-base/) props. The material, shape, interaction, and tooltip props documented on those pages are available to `Card`. The component forwards remaining props and a ref to the card root. ### Own props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | — | Card content. Children not wrapped in `CardAboveScrim` paint below the scrim. | | `topScrim` | `ScrimType` | `ScrimType.NONE` | Gradient scrim size measured from the top edge. | | `bottomScrim` | `ScrimType` | `ScrimType.NONE` | Gradient scrim size measured from the bottom edge. | ### Notable inherited props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `material` | `ContainerMaterial` | the card material | Material painted behind and in front of the content. | | `shapeProvider` | `ShapeProvider` | rounded rectangle at the `medium` corner radius | Geometry used for content clipping and every material path. | | `width` | `number \| string` | `'auto'` | CSS width. A number represents pixels. | | `height` | `number \| string` | `'auto'` | CSS height. A number also seeds the `FULL` scrim before measurement. | | `clipContent` | `boolean` | `true` | Clips the content subtree to the card shape. | | `interactive` | `boolean` | `true` | Default value for `focusable`, `pressable`, and `clickable`. | | `focusable` / `pressable` / `clickable` | `boolean` | value of `interactive` | Individual interaction capability switches. | | `disabled` | `boolean` | `false` | Blocks activation while keeping the card focusable. | | `onActivate` | `(event: InteractableActivationEvent) => void` | — | Card action. Fires once for each pointer or keyboard activation. | | `onClick` | `MouseEventHandler` | — | Raw DOM click handler for pointer and compatibility activation. | | `onStateChange` | `(prev: InteractionState, next: InteractionState) => void` | — | Called after the card applies an interaction state change. | | `ariaLabel` | `string` | — | Accessible name for the card. | | `tabIndex` | `number` | `0` | Tab index applied while the card is focusable. | | `contentScaleForStateFn` | `(state: State, containerSize: {width: number; height: number}) => number` | — | Replaces content scaling for each state. | | `visualStateOverride` | `VisualState` | — | Fixes the material's rendered visual state instead of deriving it from interaction. | | `className` | `string` | `''` | Class added to the card root. | | `style` | `CSSProperties` | — | Inline styles applied to the card root. | ### Scrim layer props `CardAboveScrim` and `CardBelowScrim` use the exported `CardScrimLayerProps` type. Both forward a ref to their wrapper `div`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | — | Content placed in the selected layer. | | `className` | `string` | `''` | Class added to the layer wrapper. | | `style` | `CSSProperties` | — | Inline styles applied to the layer wrapper. | ## Types and enums `ScrimType` - `NONE` — no scrim - `SMALL` — the shortest fixed gradient - `MEDIUM` — the middle fixed gradient - `TALL` — the tallest fixed gradient - `FULL` — a gradient spanning the card's measured height ## Behavior **Layering.** `Card` first paints children that are not wrapped in `CardAboveScrim`, then paints the scrim, and finally paints `CardAboveScrim` children. DOM order controls stacking within each group; the component adds no per-child offset. `CardBelowScrim` is optional and makes the default layer explicit. The above-scrim check requires an exact element-type match. Place `CardAboveScrim` directly under `Card`; wrapping it in another element, putting it in a fragment, or importing it from a duplicate package copy moves it into the below-scrim group. This direct composition is required for correct text layering. **Scrims.** `SMALL`, `MEDIUM`, and `TALL` use fixed gradient heights. `FULL` uses the measured card height, then a numeric `height` prop, then a built-in fallback height before the first measurement. Measurement stays live, so a `FULL` scrim follows responsive card resizing. Each gradient holds a three-quarter-opacity black band across the first fifth of its height from its edge, then fades to transparent at the opposite end. Top and bottom scrims can appear together in one decorative layer. When both values are `NONE`, `Card` renders no scrim layer. The gradient is black. Black emits no light on the additive-light display, so the scrim reduces emitted light instead of adding a tint. Its behavior does not change with the theme. Choose a scrim size for the area occupied by foreground content, not for the darkness of one image. Check legibility against the lightest and darkest real assets the application displays. **Material and focus.** The default card material keeps focus and press feedback visible over opaque content such as a photo. Let the component own this feedback rather than drawing another focus ring, which could create inconsistent focus cues. When another surface is needed, pass a `material` from the [material library](/docs/develop/webapps/design/foundations/materials/material-library/) and retain it with `useMemo`. Each mounted card must own a distinct material instance; mounting one material on two cards at the same time throws. **Interaction.** `Card` is focusable, pressable, and clickable by default because `interactive` defaults to `true`. The root is always a `div`. A clickable card receives a `button` role unless the caller provides another `role`. Use `interactive={false}` for a presentational card. Consider changing one of `focusable`, `pressable`, or `clickable` only when the interaction model needs a specific capability. **Shape.** The default shape is a rounded rectangle with the `medium` corner radius. A different `ShapeProvider` updates the content clip and every material fill and stroke path together. This keeps media aligned with custom geometry, such as a tail shape. **Sizing.** `Card` stacks content in a layer that fills the card, so content does not create an intrinsic card size. Set `width` and `height`, or let a parent grid cell or stretched flex item size the card. The component writes its size inline, so class-based `width` and `height` do not take effect; use the props or `style`. Prefer values derived from available space instead of a fixed Meta Ray-Ban Display size. Provide a numeric `height` when a `FULL` scrim must be correct on the first paint. ## Accessibility - An interactive card is one target. It must have an accessible name through `ariaLabel` or `aria-label` that describes the activation result. - Use `onActivate` for the card action so pointer and keyboard activation each invoke it exactly once. - When the card's name already describes the destination, mark decorative imagery with an empty `alt` and `aria-hidden="true"` so assistive technology does not announce redundant content. - The component marks its decorative scrim layer `aria-hidden`. - Use `interactive={false}` when the card has no action so it does not expose a `button` role or enter the tab order. ## Recommended practices - Place media and background content in `CardBelowScrim`, and place text or glyphs that depend on the scrim in `CardAboveScrim`. - Use a scrim whenever text overlays variable imagery so the text remains legible across assets. - Inset authored content with a spacing token and let the card clip full-bleed media. - Prefer real imagery whose subject matches the destination represented by the card. ## Avoid - Avoid nesting another rounded material surface, such as a container, static container, button, surface, chip, tag, or header, inside a card. Competing surfaces weaken hierarchy and can create unsupported interaction nesting. - Do not put separately focusable descendants inside an interactive card. The card must remain one unambiguous focus and activation target. - Place `CardAboveScrim` directly under `Card`; wrappers prevent the component from recognizing the above-scrim layer. - Avoid imitating photography with gradients or recreating a scrim with an overlay class. Use real media and the component-owned scrim for consistent additive-light display behavior. ## Related resources [CardStack](/docs/develop/webapps/design/components/foundation/card-stack/), [Container](/docs/develop/webapps/design/components/foundation/container/), [MediaWrapper](/docs/develop/webapps/design/components/foundation/media-wrapper/), [Vignette](/docs/develop/webapps/design/components/foundation/vignette/), [Scrim](/docs/develop/webapps/design/components/mrbd/scrim/), [Material library](/docs/develop/webapps/design/foundations/materials/material-library/), [Shape providers](/docs/develop/webapps/design/foundations/materials/shape-providers/) ### CardStack Use `CardStack` when one destination represents a related media collection, such as an album, gallery, or playlist. It presents one primary [Card](/docs/develop/webapps/design/components/foundation/card/) above as many as three background cards. `CardStack` owns the collection geometry. It normalizes card dimensions to the selected aspect ratio, calculates the bounds for fanned or scattered cards, positions every background card, and scales the group on focus. Background cards preview the collection and remain presentational rather than independent actions. ## Usage ```tsx import { AspectRatio, CardStack, ScrimType, StackType } from '@wearables-ui-toolkit/mrbd'; export function AlbumStack({ album, frame, onOpen }: AlbumStackProps) { return ( ({ src: preview.url, alt: '', }))} bottomScrim={ScrimType.MEDIUM} clickable height={frame.height} onActivate={onOpen} type={StackType.INTERACTIVE} width={frame.width} > ); } ``` ```css .album-cover { width: 100%; height: 100%; object-fit: cover; } ``` `width` and `height` are numeric and size the cards rather than the entire stack box. Derive both from a measured responsive frame when the cards need to fill that frame instead of hardcoding a Meta Ray-Ban Display size. Leave enough space between stacks for their expanded geometry: ```css .album-row { display: flex; gap: var(--uit-spacing-large); } ``` Background cards can render custom content instead of images. For a non-interactive collection visual, use the display arrangement and disable interaction: ```tsx import { CardStack, StackType } from '@wearables-ui-toolkit/mrbd'; }, { children: }, ]} maxWidth={rowWidth} > ; ``` `CardStack` and its enums are also available from the component subpath: ```ts import { AspectRatio, CardStack, StackType, } from '@wearables-ui-toolkit/foundation/components/CardStack'; ``` ## Props The complete prop type is `CardStackProps`. It extends [Card](/docs/develop/webapps/design/components/foundation/card/) props, except for `children`; those props extend [Container](/docs/develop/webapps/design/components/foundation/container/) and [InteractableBase](/docs/develop/webapps/design/components/foundation/interactable-base/) props. The component forwards a ref to the stack root. ### Own props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | — | Content of the primary card. | | `type` | `StackType` | `StackType.INTERACTIVE` | Stack layout and interaction model. | | `aspectRatio` | `AspectRatio` | `AspectRatio.PORTRAIT` | Aspect ratio applied to every card in the stack. | | `backgroundCards` | `BackgroundCardConfig[]` | `[]` | Preview cards behind the primary card. | | `topScrim` | `ScrimType` | `ScrimType.NONE` | Top gradient scrim on the primary card. | | `bottomScrim` | `ScrimType` | `ScrimType.NONE` | Bottom gradient scrim on the primary card. | | `width` | `number` | — | Requested card width in pixels. It bounds the cards, not the whole stack. When omitted, a built-in seed width applies and also caps the cards. | | `height` | `number` | — | Requested card height in pixels. When omitted, a built-in seed height applies and also caps the cards. | | `maxWidth` | `number` | — | Upper bound in pixels for the measured stack width. | | `maxHeight` | `number` | — | Upper bound in pixels for the measured stack height. | ### Notable inherited props `CardStack` forwards these props to the primary card unless noted. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `shapeProvider` | `ShapeProvider` | rounded rectangle at the `medium` corner radius | Geometry shared by primary and background cards. It also defines the corner pivot for the interactive fan. | | `material` | `ContainerMaterial` | the card material | Primary-card material. Background cards always use the card material. | | `interactive` | `boolean` | `true` | Default value for `focusable`, `pressable`, and `clickable` on the primary card. | | `disabled` | `boolean` | `false` | Blocks activation of the primary card. | | `onActivate` | `(event: InteractableActivationEvent) => void` | — | Action for the stack destination. | | `onStateChange` | `(prev: InteractionState, next: InteractionState) => void` | — | Called when the primary card's interaction state changes. The stack drives its scale from the same event. | | `ariaLabel` | `string` | — | Accessible name for the stack destination. | | `tabIndex` | `number` | `0` | Tab index of the primary card. A `DISPLAY` stack forces it to `-1`. | | `className` | `string` | `''` | Class added to the stack root. | | `style` | `CSSProperties` | — | Inline styles applied to the stack root after measured size and focus scale. | ## Types and enums `StackType` - `INTERACTIVE` — the primary card owns interaction, and as many as two background cards fan from a corner pivot when it receives focus - `DISPLAY` — a static scattered arrangement without focus animation, with as many as three background cards `AspectRatio` - `SQUARE` — 1:1 - `PORTRAIT` — 3:4 `BackgroundCardConfig` - `src?: string` — image source for the background card - `alt?: string` — image alt text, with an empty string as the default - `children?: ReactNode` — custom content rendered instead of the image ## Behavior **Card count limits.** An `INTERACTIVE` stack supports at most two background cards, and a `DISPLAY` stack supports at most three. Exceeding the applicable limit is a misuse. Development builds throw so the issue is visible immediately; production builds drop extra cards and log a console warning rather than crashing the screen. A stack without background cards is supported and renders as one card. **Sizing.** `width` and `height` bound each card rather than the entire stack. `CardStack` finds the largest card with the selected aspect ratio that fits those bounds, calculates the space needed by the fanned or scattered arrangement, and then derives the individual card size from those bounds. If either dimension is omitted, the component uses a seed value. As a result, `width` alone grows cards only as far as the seed height allows; provide both dimensions when the stack must fill measured space. `maxWidth` and `maxHeight` constrain the stack box and shrink the complete arrangement to fit. Rotated and translated background cards make the box wider than one card, and a `DISPLAY` stack is also taller. The application owns the surrounding layout and should reserve this additional space to prevent clipping. **Interaction.** In an `INTERACTIVE` stack, the primary card is the only focus target. Its background cards rotate farther from their shared corner pivot on focus, while focus and press scale the whole group on the same motion curve as a container state change. In a `DISPLAY` stack, the primary card's tab index is forced to `-1` and no focus animation runs. The default interaction props still apply, so use `interactive={false}` when the stack is presentational. Background cards always have a `presentation` role and never enter the focus order. **Content scale.** Individual card dimensions remain fixed during interaction. `CardStack` pins their content scale, so a `contentScaleForStateFn` passed to the stack does not reach the cards. The stack root applies the focus breathing once, which keeps the fanned geometry aligned. **Background content.** A background card renders `children` when provided; otherwise, it renders the image from `src` scaled to cover the card. Without either value, it renders empty. Scrims apply only to the primary card. **Prop routing.** `CardStack` applies `className`, `style`, and `data-uit-*` attributes to the stack root and forwards every other inherited prop to the primary card. The component owns the primary card's `style`, rendered size, and content scale, so callers cannot set those values through the stack. Use `width`, `height`, `maxWidth`, and `maxHeight` to shape the arrangement. **Display tilt.** A `DISPLAY` stack tilts the primary card slightly even without background cards so it still reads as a stack. The stack box does not clip its rotated corners. Leave clearance around the box so nearby content does not collide with them. ## Accessibility - The stack represents one destination. It must have an accessible name through `ariaLabel` that describes the collection rather than one image. - Background previews are decorative. Keep their `alt` empty, which is also the default, to avoid redundant announcements. - A `DISPLAY` stack is not keyboard reachable. Do not add activation semantics or present it as a tap target. Use `interactive={false}` so its primary card does not expose an unreachable `button` role. - Do not place separately focusable content inside the primary card. The stack must remain one focus and activation target. ## Recommended practices - Give adjacent stacks enough space for focus expansion so their cards remain visible and distinct. - Prefer a vertical layout when side-by-side stacks would expand beyond the viewport. - Derive `width` and `height` from a measured frame. Use `maxWidth` or `maxHeight` when the row must remain within a known bound. - Keep each preview visually consistent with the collection opened by the stack. ## Avoid - Do not exceed two background cards for an `INTERACTIVE` stack or three for a `DISPLAY` stack. These are the component's supported runtime limits. - Do not make background cards independently focusable or clickable. The stack is one destination, and the primary card owns interaction. - Avoid positioning background cards with `style` or custom CSS. `CardStack` owns their geometry to keep focus animation and responsive sizing consistent. - Prefer [Card](/docs/develop/webapps/design/components/foundation/card/) for a single media item; a stack communicates that one destination contains a collection. ## Related resources [Card](/docs/develop/webapps/design/components/foundation/card/), [Carousel](/docs/develop/webapps/design/components/foundation/carousel/), [Container](/docs/develop/webapps/design/components/foundation/container/), [Shape providers](/docs/develop/webapps/design/foundations/materials/shape-providers/), [Material library](/docs/develop/webapps/design/foundations/materials/material-library/) ### Carousel Use `Carousel` for a horizontal sequence that centers the focused item. Each child becomes one item in a focusable slot. `Carousel` owns scrolling, centering, edge spacing for the first and last items, horizontal fades, and the optional dot or text position indicator. This ownership keeps focus and visible position synchronized. Items can contain cards, containers, media, or custom compositions. Prefer [Pager](/docs/develop/webapps/design/components/foundation/pager/) when every destination occupies a whole page. ## Usage ```tsx import { Card, Carousel, PaginationMode, TextStyle, TextView, } from '@wearables-ui-toolkit/mrbd'; export function ConditionsCarousel({ days }: { days: Forecast[] }) { return ( reportVisibleDay(days[index])} > {days.map(day => ( {day.label} {day.summary} ))} ); } ``` To control the carousel from another part of the screen, keep a ref to its imperative handle: ```tsx import { useRef } from 'react'; import { Button, Carousel } from '@wearables-ui-toolkit/mrbd'; import type { CarouselHandle } from '@wearables-ui-toolkit/mrbd'; export function CaptureStrip({ captures }: { captures: Capture[] }) { const carouselRef = useRef(null); return ( <> {captures.map(capture => ( ))}

Messages