Accessibility, performance, and validation

• Give every icon-only control an explicit accessible label because title is not always rendered.
• Name scrolling and paging containers. ScrollView and VerticalList render an unnamed role="region" landmark until the application passes an ariaLabel; Pager and SubNavigationPager otherwise use a generic name.
• Give Avatar meaningful alt text unless the image is decorative.
• Describe status indicators that communicate state. Built-in status types already add a description to the composed accessible name.
• Context menus, vertical menus, and tooltips must remain reachable and dismissible through directional navigation and Escape.
• Make the toolkit component the interaction target rather than wrapping it in another focusable element. A single target keeps focus behavior unambiguous.
• Custom menu items must be focusable and use role="menuitem" so arrow-key navigation can include them.
• Group related radio rows in a labeled container with role="radiogroup" so assistive technology communicates their relationship.

• Let components size themselves, and use their supported max-line behavior so longer strings do not break layouts.
• Keep toolkit text styles intact rather than globally compensating for text measurement differences.
• Apply typography with TextAppearance classes or TextView’s textStyle. Do not set individual font properties or custom letter spacing on toolkit text; the toolkit owns these values for legibility and consistency.
• The public text face is Noto Sans. App prefers a locally installed copy and otherwise loads it from the Google Fonts content delivery network at runtime, so no font package or bundled font files are required.
• Use sentence case for actions and labels unless a product name requires a different form.

• Keep object and callback props stable with useMemo and useCallback in large lists and animated surfaces to avoid unnecessary rendering.
• Avoid allocating new arrays or objects inline in list rows.
• Do not drive a frame-rate visual animation from React state. Use CSS transitions, or use useSpringAnimation and write to the DOM from onChange. Its callback is capped at 30 updates per second by default, pauses while the document is hidden, and snaps to the target under reduced motion.

• Memoize one material per host and reuse it. Creating an instance on every render restarts transitions and rebuilds per-layer caches.
• Reuse shape providers because the toolkit caches geometry by provider instance.
• Keep animated material layers mounted across state changes. The canvas host already pauses its animation loop when a continuously animated layer is not visible in the current state.
• Enable foregroundBlendsWithContent or backgroundBlendsWithBackdrop only when the blend needs live pixels because each option adds compositing surfaces.

• Split routes with createPreloadableLazyComponent and warm them through RoutePreloadProvider. The provider remains inert until it receives a preloadRoute handler. ReactRouterNavigationProvider mounts the provider and forwards its own preloadRoute. The toolkit queues requests, drains them on an idle callback, and defers them while directional input continues, preventing route warming from competing with scrolling or focus movement.
• Place preload targets on content the user is likely to reach next, such as a focused row, hovered link, or item entering the viewport. Use RoutePreloadTarget, useRoutePreloadTarget, or ReactRouterPreloadLink.
• Avoid application-level preloaders for unused materials or components because they consume resources without improving navigation.

• Size layouts from available space and let components use their intrinsic dimensions. This keeps the interface responsive across viewports.
• Keep one scroller per axis on each route. Nested same-axis scrollers make directional navigation ambiguous and increase scroll work.

• SVG masks and clip paths
• blend modes
• filters and backdrop effects
• font resolution and fallback
• animated SVG content
• large CSS or SVG layers
• portal coordinate spaces
• scroll and fading-edge compositing

• Prefer full-screen captures when negative-stacked or masked material layers are present, then crop to the exact component bounds. Element-clipped DevTools screenshots can misrepresent these layers.
• Treat anti-aliasing differences between desktop Chrome and the device WebView as rendering differences. Avoid changing component geometry to correct an aliasing-only discrepancy.
• Wait for images and fonts to load before evaluating pixels because device transport can delay asset delivery.
• Validate contrast and layering on hardware. The additive-light display draws content over the wearer’s view, so a design that reads against an opaque page background may not remain legible on the device.

1. Render the component on a representative route or page.
2. Match the state you intend to compare: default, focused, pressed, disabled, selected, loading, popup open, scroll position, route state, animation frame.
3. Capture the full screen for context.
4. Crop the exact component bounds.
5. Compare that crop against the design specification.
6. Record discrepancies in your validation notes.
7. Add a regression test for anything you fix.

• public API behavior and prop contracts
• focus eligibility, focus restoration, and directional navigation outcomes
• scroll-to-focused and fading-edge behavior
• portal placement and popup anchoring
• material configuration and layer ordering
• layout calculations
• which component owns an animation
• edge cases that previously regressed

• The app renders inside App, which loads the library stylesheet.
• Pages use Page for the header and content relationship.
• Toolkit components are used for toolkit anatomy instead of local reimplementations.
• No hardcoded colors, spacing, radii, typography values, or viewport dimensions — semantic CSS custom properties and the CornerRadius and TextAppearance scales only.
• No custom font settings on toolkit component text.
• No restyling of component internals, generated class names, or private DOM structure.
• Every interactive element has an accessible name; icon-only controls have an explicit label.
• Directional navigation reaches every control, and Tab still works.
• Invalid directional input scrolls or rubber-bands instead of doing nothing.
• Popups render through the app portal and stay anchored to their owner.
• Reduced motion is honored.
• The change renders acceptably in both desktop Chrome and the device WebView.
• Component-level visual evidence exists for anything visually sensitive.