Performance and validation

• Layout reads such as getBoundingClientRect(), offsetWidth, scrollTop, and getComputedStyle() must stay out of scroll handlers, animation frames, and render because they can force synchronous layout.
• Batch any measurement you genuinely need into one pass, then write in a separate pass.
• Prefer ResizeObserver and IntersectionObserver over polling. Observers deliver measurements the browser has already computed.
• Share one observer across many elements instead of creating one per row.

import {useEffect, useRef} from 'react';
import {SpringConfigs, useSpringAnimation} from '@wearables-ui-toolkit/mrbd';
import styles from './ProgressFill.module.css';

export function ProgressFill({progress}: {progress: number}) {
  const fillRef = useRef<HTMLDivElement>(null);
  const spring = useSpringAnimation({
    config: SpringConfigs.PROGRESS_VALUE,
    initialValue: progress,
    onChange: value => {
      fillRef.current?.style.setProperty('--fill', String(value));
    },
  });

  useEffect(() => {
    spring.setTarget(progress);
  }, [progress, spring]);

  return <div ref={fillRef} className={styles.fill} />;
}

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

const style = {
  transition: createTransition(
    ['transform', 'opacity'],
    AnimationDurations.CONTAINER_STATE_CHANGE,
    Interpolators.CONTAINER_SCALE,
  ),
};

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

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.
• Call clearPathCache() only when tearing down a long-lived surface that generated many one-off geometries, not on a schedule. See Smooth Corners.

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

const SettingsRoute = createPreloadableLazyComponent(
  () => import('./SettingsRoute'),
  module => module.SettingsRoute,
);

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.

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

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

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