pixelize-native-library 1.2.0 → 1.2.1

package/lib/module/modules/skeleton/MODULE.md

@@ -8,12 +8,12 @@ neutral fills. It takes no children and no interaction; it IS its own size, whic
 
 | File | Role |
 |------|------|
-| `Skeleton.tsx` | The component. Resolves size/colour/a11y, drives the `Animated` shimmer loop, `style` last. |
+| `Skeleton.tsx` | Translating highlight-band shimmer via Reanimated; `style` last. |
 | `Skeleton.variants.ts` | Pure resolvers (`resolveSkeletonSize`, `resolveSkeletonColors`, `resolveSkeletonAccessibility`) + the themed structural variant resolver `skeletonStructure`. No React. |
 | `index.ts` | Public surface: `Skeleton`, `SkeletonProps`, `SkeletonShape`. |
 | `__tests__/Skeleton.test.ts` | Pure: colour-role mapping + shimmer-visibility guard (all brands × modes), the size resolver, the a11y contract. |
 | `__tests__/Skeleton.render.test.tsx` | Render: shape scale, sizing, shimmer mounts/skips under reduced motion, decorative-vs-labelled a11y, consumer `style` applies last. |
-| `__tests__/Skeleton.motion.test.tsx` | Motion cost: the loop is handed to the native driver (`_startNativeLoop(-1)`), never restarted per iteration from JS; the pulse still fades both ways; both gates. |
+| `__tests__/Skeleton.motion.test.tsx` | Motion: linear `withRepeat` shimmer, stagger via `withDelay`, gated on reduce motion only. |
 
 ## Props
 
@@ -22,9 +22,10 @@ neutral fills. It takes no children and no interaction; it IS its own size, whic
 | `shape` | `rect \| circle \| text` | `rect` | Closed union — drives the corner radius only. |
 | `width` | `number` | per-shape fallback | dp. Component-owned sizing, **not** `LayoutStyle` — sizing is the point of this component. |
 | `height` | `number` | per-shape fallback | dp. `circle` mirrors whichever of `width`/`height` is given onto both axes (an unequal pair would render an ellipse). |
+| `staggerIndex` | `number` | `0` | Stagger sibling skeletons by `index × 100ms` (80–120ms band). |
 | `accessibilityLabel` | `string` | — | **Optional** — see Accessibility contract below. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
-| `testID` | `string` | — | The shimmer overlay (when mounted) also gets `${testID}-pulse`. |
+| `testID` | `string` | — | The shimmer band (when mounted) also gets `${testID}-shimmer`. |
 
 No `tone`/`color` prop: a skeleton has exactly one neutral appearance (`resolveSkeletonColors`),
 the same reasoning as `Avatar`'s and `Divider`'s colour resolvers — there is nothing for an app to
@@ -46,11 +47,10 @@ widen.
   `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"` natively.
 - **1.4.3 / 1.4.11** — N/A. A skeleton renders no text and draws no interactive boundary (same
   conclusion `Divider.test.ts` documents for its own decorative colour). What IS measured: `base`
-  and `pulse` must resolve to two genuinely different colours on every brand × mode, or the shimmer
+  and `highlight` must resolve to two genuinely different colours on every brand × mode, or the shimmer
   would be a silent no-op — asserted directly in `Skeleton.test.ts`.
-- **2.3.3 (reduced motion)** — `useReducedMotion()` gates the shimmer loop entirely. When true, the
-  `Animated` overlay is never mounted and the box renders as a static `bg.sunken` fill — never a
-  frame frozen mid-pulse.
+- **2.3.3 (reduced motion)** — `useReducedMotion()` gates the shimmer entirely. When true, only the
+  static neutral base (`palette.background[300]`) renders — no band, no pulse.
 - **Touch target (2.5.x)** — N/A. `Skeleton` has no `onPress`.
 
 ## Patterns copied from `Button`/`Avatar`
@@ -60,21 +60,9 @@ widen.
    overlay clips to it without recomputing the radius on that overlay too — safe here because,
    unlike `Button`, nothing needs to be drawn outside this box). Colour → resolved from role tokens
    (`resolveSkeletonColors`), applied inline.
-2. **Shimmer is one `Animated` opacity pulse over a static base fill** — the same "state layer over
-   a base" technique as `Button`'s press overlay: a `bg.sunken` box with an absolutely-positioned
-   overlay sibling whose opacity goes 0 → 1 → 0. That shape comes from ONE looped bare timing
-   driving a 0→1 value, interpolated `[0, 0.5, 1] → [0, 1, 0]` — **not** a looped
-   `Animated.sequence` of two timings. `Animated.loop` only takes RN's native path
-   (`_startNativeLoop`) when what it wraps reports `_isUsingNativeDriver()`, which
-   `Animated.sequence` returns `false` for unconditionally; a looped sequence therefore restarts
-   each leg from the JS thread, per row, exactly while the app is parsing the response those rows
-   are waiting on. `ProgressBar`'s sweep is the same bare-timing shape, for the same reason. The overlay colour is `base` composited with a
-   fixed-alpha `fg.default` (via `compositeOver`, same precedent as `Button`'s `PRESS_SCRIM_DARK`/
-   `LIGHT`) — **not** a second role lookup like `bg.raised`. Two arbitrary role rungs are not
-   guaranteed to differ enough to read as a shimmer: an earlier version used `bg.raised`, and a
-   contrast-ratio floor added to `Skeleton.test.ts` (`MIN_PULSE_CONTRAST`) caught that pair
-   collapsing to visually-indistinguishable on every brand × mode. Compositing a fixed-alpha overlay
-   makes the luminance delta a controlled constant instead of an incidental one.
+2. **Shimmer is a translating highlight band** — base = neutral ramp step 3 (`background[300]`),
+   highlight = step 5 (`background[500]`), band width 40%, linear 1400ms `withRepeat`, optional
+   `staggerIndex` delay. One `translateX` transform — no opacity pulse.
 3. **Pure, testable resolvers** in `Skeleton.variants.ts` (no React) so the colour, sizing, and a11y
    contracts are unit-tested against real palettes — never eyeballed.
 4. **Closed union only** (`shape`), `style: LayoutStyle` last and once, no `{...rest}`.
@@ -90,11 +78,17 @@ still stays layout-only, outermost, and last, for placement (margin, `alignSelf`
 
 ## Known gaps
 
-The pulse cadence changed with the native-loop fix: one cycle is now a single `deliberate` (500ms)
-instead of two (500ms up + 500ms down), and — because the easing now shapes the driver rather than
-each leg — the peak lands about a fifth of the way through the cycle instead of halfway. Restoring
-the old cadence exactly needs a `linear` easing key and a longer duration key in
-`core/motion/config.ts`; neither exists, and a component may not define its own timing.
+- No `staggerIndex` auto-assignment inside a list — the caller passes it per sibling when needed.
+
+## Why the shimmer duration is NOT a `MOTION_DURATION` key
+
+`SKELETON_SHIMMER_DURATION_MS` (1400ms) and `SKELETON_STAGGER_MS` (100ms) are bespoke constants,
+not `motion.duration("deliberate")` (500ms) like `TypingIndicator`'s dot pulse. Deliberate is the
+library's longest discrete key and is reserved for one-shot UI transitions ("onboarding and
+first-run emphasis only" per `core/motion/config.ts`); a shimmer is a continuous ambient loop, a
+different category, and industry-standard shimmer cadence sits at 1200–1600ms — forcing it onto a
+500ms transition would read as rushed and busy rather than a calm loading cue. The value is still
+gated by `useReducedMotion()` (WCAG 2.3.3), the same OS-level signal `useMotion()` itself reads.
 
 ## Performance
 
@@ -105,3 +99,5 @@ Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLA
 - Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
 - List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
 - `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.
+
+- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.

package/lib/module/modules/skeleton/Skeleton.js

@@ -1,79 +1,67 @@
 "use strict";
 
 /**
- * Skeleton — a loading placeholder box that shimmers while the real content it stands in for is
- * still on its way. It is its own size (`width`/`height` are component-owned props, not
- * `LayoutStyle` — sizing IS the point of this component) and has exactly one neutral appearance:
- * a resting `bg.sunken` fill cross-faded with a fixed-alpha `fg.default` overlay composited over it
- * (see `resolveSkeletonColors`), pulsing on an `Animated` opacity loop. Purely decorative by default
- * (see `Skeleton.variants.ts` →
- * `resolveSkeletonAccessibility`, the same "decorative unless labelled" contract as `Avatar`).
- *
- * The shimmer is gated on `motion.decorative`, so it runs on high-tier devices only. A skeleton is
- * usually rendered one-per-row across a whole loading list, and a per-row loop is the single most
- * expensive thing a placeholder can do — low/mid tiers and reduce-motion get the static fill. Even
- * on high tier the loop is shaped so it costs zero JS per iteration: see the effect below.
+ * Skeleton — a loading placeholder with a translating highlight-band shimmer over a neutral base.
  */
 
-import { memo, useEffect, useMemo, useRef } from "react";
-import { Animated, StyleSheet } from "react-native";
-import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { memo, useEffect, useMemo } from "react";
+import { StyleSheet } from "react-native";
+import Animated, { Easing, ReduceMotion, useAnimatedStyle, useSharedValue, withDelay, withRepeat, withTiming } from "react-native-reanimated";
+import { useReducedMotion } from "../../core/a11y/index.js";
 import { useTheme } from "../../theme/hooks.js";
-import { resolveSkeletonAccessibility, resolveSkeletonColors, resolveSkeletonSize, skeletonStructure } from "./Skeleton.variants.js";
+import { resolveSkeletonAccessibility, resolveSkeletonColors, resolveSkeletonSize, SKELETON_BAND_WIDTH_RATIO, SKELETON_SHIMMER_DURATION_MS, SKELETON_STAGGER_MS, skeletonStructure } from "./Skeleton.variants.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 export const Skeleton = /*#__PURE__*/memo(function Skeleton({
   shape = "rect",
   width,
   height,
+  staggerIndex = 0,
   accessibilityLabel,
   style,
   testID
 }) {
   const theme = useTheme();
-  const motion = useMotion();
-  const pulse = useAnimatedValue(0);
-  const loop = useRef(null);
+  const reducedMotion = useReducedMotion();
+  const translateX = useSharedValue(0);
   const size = resolveSkeletonSize(shape, width, height);
   const a11y = resolveSkeletonAccessibility({
     accessibilityLabel
   });
-  const colors = useMemo(() => resolveSkeletonColors(theme.colors), [theme.colors]);
-  const shimmer = motion.decorative;
+  const colors = useMemo(() => resolveSkeletonColors(theme.palette), [theme.palette]);
+  const shimmer = !reducedMotion;
+  const bandWidth = size.width * SKELETON_BAND_WIDTH_RATIO;
   useEffect(() => {
-    if (!shimmer) return undefined;
-    pulse.setValue(0);
-    // A BARE timing, never a sequence: `Animated.loop` only takes RN's `_startNativeLoop` path when
-    // what it wraps reports `_isUsingNativeDriver()`, and `Animated.sequence` returns false for that
-    // unconditionally — a looped sequence restarts each leg from the JS thread, per row, forever.
-    // The fade back out is the interpolation below, not a second leg (ProgressBar's sweep, same shape).
-    loop.current = Animated.loop(motion.timing(pulse, 1, {
-      duration: "deliberate"
-    }));
-    loop.current.start();
-    return () => {
-      loop.current?.stop();
-      loop.current = null;
-    };
-  }, [shimmer, motion, pulse]);
-
-  // The effect cleanup above already stops the loop, but only while `shimmer` stays true across the
-  // unmount — this guarantees it regardless of the order React tears the tree down in.
-  useEffect(() => () => loop.current?.stop(), []);
+    if (!shimmer || size.width <= 0) {
+      translateX.value = 0;
+      return undefined;
+    }
+    const travel = size.width + bandWidth;
+    const delay = staggerIndex * SKELETON_STAGGER_MS;
+    translateX.value = -bandWidth;
+    translateX.value = withDelay(delay, withRepeat(withTiming(travel, {
+      duration: SKELETON_SHIMMER_DURATION_MS,
+      easing: Easing.linear,
+      reduceMotion: ReduceMotion.System
+    }), -1, false));
+    return undefined;
+  }, [shimmer, size.width, bandWidth, staggerIndex, translateX]);
   const rootStyle = useMemo(() => [skeletonStructure(theme, {
     shape
   }), {
     width: size.width,
     height: size.height,
     backgroundColor: colors.base
-  }, style], [theme, shape, size.width, size.height, colors, style]);
-  const pulseOpacity = useMemo(() => pulse.interpolate({
-    inputRange: [0, 0.5, 1],
-    outputRange: [0, 1, 0]
-  }), [pulse]);
-  const pulseStyle = useMemo(() => [StyleSheet.absoluteFill, {
-    backgroundColor: colors.pulse,
-    opacity: pulseOpacity
-  }], [colors, pulseOpacity]);
+  }, style], [theme, shape, size.width, size.height, colors.base, style]);
+  const bandStyle = useAnimatedStyle(() => ({
+    transform: [{
+      translateX: translateX.value
+    }]
+  }));
+  const highlightStaticStyle = useMemo(() => ({
+    width: bandWidth,
+    height: size.height,
+    backgroundColor: colors.highlight
+  }), [bandWidth, size.height, colors.highlight]);
   return /*#__PURE__*/_jsx(Animated.View, {
     testID: testID,
     accessible: a11y.accessible,
@@ -83,10 +71,17 @@ export const Skeleton = /*#__PURE__*/memo(function Skeleton({
     "aria-hidden": a11y["aria-hidden"],
     style: rootStyle,
     children: shimmer && /*#__PURE__*/_jsx(Animated.View, {
-      testID: testID === undefined ? undefined : `${testID}-pulse`,
+      testID: testID === undefined ? undefined : `${testID}-shimmer`,
       pointerEvents: "none",
-      style: pulseStyle
+      style: [styles.band, highlightStaticStyle, bandStyle]
     })
   });
 });
+const styles = StyleSheet.create({
+  band: {
+    position: "absolute",
+    top: 0,
+    left: 0
+  }
+});
 //# sourceMappingURL=Skeleton.js.map

package/lib/module/modules/skeleton/Skeleton.variants.js

@@ -3,28 +3,8 @@
 /**
  * Skeleton's style + accessibility resolution — the pure functions the component (and its tests)
  * depend on, plus the themed structural variant resolver.
- *
- * The split every sibling module copies (see `Button.variants.ts` / `Avatar.variants.ts`):
- *  - STRUCTURE (the shape's corner radius) lives in the `createThemedVariants` resolver below —
- *    static per (brand, mode), registered once via `StyleSheet.create`.
- *  - SIZE is NOT theme-driven: a skeleton's whole job is standing in for a specific piece of
- *    content, so `width`/`height` are per-instance numbers the caller supplies (or a per-shape
- *    fallback), resolved by `resolveSkeletonSize` and applied inline — never a themed variant,
- *    since there is no closed set of values to register.
- *  - COLOUR is resolved from the theme's ROLE colours (`resolveSkeletonColors`), never a raw ramp,
- *    never a hardcoded hex. There is no `tone` prop to widen — a loading placeholder has exactly
- *    one neutral appearance (same reasoning as `resolveAvatarColors`). `pulse` is `base` composited
- *    with a fixed-alpha overlay (see `resolveSkeletonColors`), not a second role lookup — two
- *    arbitrary role rungs are not guaranteed to differ enough to read as a shimmer.
- *  - ACCESSIBILITY prop derivation is `resolveSkeletonAccessibility`, kept pure so the "decorative
- *    unless labelled" contract is unit-testable without rendering React Native (same shape as
- *    `resolveAvatarAccessibility`).
- *
- * Free of React and of any lucide import, so the WCAG + behaviour tests import it directly (mocking
- * only `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
  */
 
-import { compositeOver } from "../../theme/tokens/builders/color.js";
 import { createThemedVariants } from "../../core/style/index.js";
 /** Fallback dp size per shape, used whenever the caller gives neither `width` nor `height`. */
 export const SKELETON_DEFAULT_SIZE = {
@@ -42,12 +22,10 @@ export const SKELETON_DEFAULT_SIZE = {
   }
 };
 
-/**
- * Resolves the box's actual dp size. `circle` is the one shape that cannot take independent
- * width/height — an unequal pair would render an ellipse under the shared `radii.full` corner
- * radius, not a circle — so a single given dimension mirrors onto the other rather than the two
- * silently drifting apart.
- */
+// Ambient loop, not a one-shot transition — deliberately outside `MOTION_DURATION`; see MODULE.md.
+export const SKELETON_SHIMMER_DURATION_MS = 1400;
+export const SKELETON_BAND_WIDTH_RATIO = 0.4;
+export const SKELETON_STAGGER_MS = 100;
 export function resolveSkeletonSize(shape, width, height) {
   const fallback = SKELETON_DEFAULT_SIZE[shape];
   if (shape === "circle") {
@@ -62,45 +40,18 @@ export function resolveSkeletonSize(shape, width, height) {
     height: height ?? fallback.height
   };
 }
-// Fixed-alpha overlay composited onto `base` (Button's `PRESS_SCRIM_DARK`/`LIGHT` precedent for "I
-// need a guaranteed visible delta, not a role lookup"). `fg.default` is dark in light mode and light
-// in dark mode, so compositing it darkens/lightens `base` for free with no `if (dark)` branch. ~30%
-// alpha keeps the composited contrast ratio ≥ `MIN_PULSE_CONTRAST` (see `Skeleton.test.ts`) on every
-// brand × mode, with comfortable headroom above the floor.
-const PULSE_OVERLAY_ALPHA_HEX = "4d"; // 0x4d / 0xff ≈ 30%
-
-/**
- * Maps the placeholder onto role colours, then derives `pulse` as `base` composited with a small,
- * fixed-alpha overlay — never a second role lookup. A prior version returned `base: bg.sunken, pulse:
- * bg.raised`: two role rungs whose luminance gap is whatever the brand's ramp happens to produce, and
- * an independent re-measurement found that gap collapses to visually-indistinguishable on every
- * brand × mode — the shimmer was a silent no-op everywhere, not just on one theme. Compositing a
- * fixed-alpha overlay makes the luminance delta a controlled constant instead of an incidental one,
- * so it can't collapse regardless of how a brand's `bg.raised`/`bg.sunken` rungs happen to relate.
- */
-export function resolveSkeletonColors(colors) {
-  const base = colors.bg.sunken;
-  const pulse = compositeOver(`${colors.fg.default}${PULSE_OVERLAY_ALPHA_HEX}`, base);
+/** Neutral ramp step 3 (base) and step 5 (highlight band) on the gray ramp. */
+export function resolveSkeletonColors(palette) {
   return {
-    base,
-    pulse
+    base: palette.gray[300],
+    highlight: palette.gray[500]
   };
 }
-/**
- * Derives the accessibility surface once, purely, so the "decorative unless labelled" contract is
- * testable without a renderer (same shape as `resolveAvatarAccessibility`):
- *  - no label → the placeholder stands in for content that hasn't rendered yet and carries no
- *    meaning of its own, so it is hidden from assistive tech rather than read as a bare,
- *    unexplained box.
- *  - a label (e.g. `"Loading"`) → exposed as one `"progressbar"`-role element carrying it, with
- *    `busy: true` (WCAG 1.4.1 — the loading state is announced, not left to be inferred from a box
- *    appearing on screen).
- *
- * `aria-hidden` covers BOTH platforms in one prop: RN maps it onto `accessibilityElementsHidden`
- * (iOS) + `importantForAccessibility="no-hide-descendants"` (Android), and react-native-web forwards
- * it to the DOM — where those two native props reach nothing, so an unlabelled skeleton used to stay
- * fully exposed to a screen reader on web.
- */
+
+/** @deprecated Use palette-based resolver — kept for tests importing RoleColors. */
+export function resolveSkeletonColorsFromRoles(_colors, palette) {
+  return resolveSkeletonColors(palette);
+}
 export function resolveSkeletonAccessibility(input) {
   const hasLabel = input.accessibilityLabel !== undefined && input.accessibilityLabel.length > 0;
   return {
@@ -111,17 +62,6 @@ export function resolveSkeletonAccessibility(input) {
     "aria-hidden": hasLabel ? undefined : true
   };
 }
-
-/**
- * Structural styles only — the shape's corner radius, plus `overflow: "hidden"` so the animated
- * shimmer overlay (an absolutely-positioned sibling, see `Skeleton.tsx`) clips to it without each
- * shape recomputing the same radius on that overlay. No colour (state-driven, applied inline over
- * this), so this compiles once per theme identity via the `WeakMap`-cached themed resolver and
- * never rebuilds per render.
- *
- * Unlike `Button`, there is no focus ring here that needs to escape the bounds, so `overflow:
- * "hidden"` is safe — nothing else needs to be drawn outside this box.
- */
 export const skeletonStructure = createThemedVariants(theme => ({
   base: {
     overflow: "hidden"
@@ -129,10 +69,12 @@ export const skeletonStructure = createThemedVariants(theme => ({
   variants: {
     shape: {
       rect: {
-        borderRadius: theme.radii.base
+        borderRadius: theme.radii.md,
+        borderCurve: "continuous"
       },
       circle: {
-        borderRadius: theme.radii.full
+        borderRadius: theme.radii.full,
+        borderCurve: "continuous"
       },
       text: {
         borderRadius: theme.radii.sm

package/lib/module/modules/slider/MODULE.md

@@ -119,3 +119,5 @@ Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLA
 - Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
 - List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
 - `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.
+
+- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.

package/lib/module/modules/slider/Slider.js

@@ -192,7 +192,8 @@ export const Slider = /*#__PURE__*/memo(function Slider(props) {
       testID: testID === undefined ? undefined : `${testID}-focus-ring`,
       style: [styles.focusRing, {
         borderColor: theme.colors.border.focus,
-        borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+        borderRadius: theme.radii.md + FOCUS_RING_GAP + FOCUS_RING_WIDTH,
+        borderCurve: "continuous"
       }]
     }), /*#__PURE__*/_jsx(View, {
       pointerEvents: "none",

package/lib/module/modules/stage-progress/MODULE.md

@@ -7,7 +7,7 @@ Horizontal pipeline — `variant`: `pills` | `bar` | `stepper`. `value` is activ
 | File | Role |
 |------|------|
 | `StageProgress.variants.ts` | `resolveStageState` / `resolveActiveStageIndex`, the accessibility resolvers, `resolveStageProgressColors(RoleColors)`, and the structure resolvers. Plain, hook-free. |
-| `StageProgress.tsx` | Renders the row; picks the fill/text pair per stage state and wraps a pressable stage in `Pressable` only when it is interactive. |
+| `StageProgress.tsx` | Renders the row; picks the fill/text pair per stage state and wraps an interactive stage in the memoized `StagePressable` (scale/opacity via `usePressState` + `android_ripple`), same pattern as `Button`/`RadioGroup`. |
 
 ## Props
 
@@ -24,9 +24,11 @@ Horizontal pipeline — `variant`: `pills` | `bar` | `stepper`. `value` is activ
 - **`pills` / `stepper`** label each stage instead: `resolveStageAccessibilityLabel` appends the
   state — `", completed"` / `", current stage"` / `", not started"`. That suffix is the WCAG 1.4.1
   fix; fill colour is otherwise the only thing separating a completed stage from an upcoming one, and
-  there is no "completed" state to announce directly. `resolveStageAccessibilityState` supplies flat
-  `aria-selected` (active only) / `aria-disabled` — not `accessibilityState={{…}}`, which
-  react-native-web 0.21.2 drops entirely on web.
+  there is no "completed" state to announce directly. `resolveStageAccessibilityState` supplies
+  `aria-current="step"` (active only, WEB) + `accessibilityState={{ selected }}` (the NATIVE
+  fallback — React Native has no "current" concept) — not `aria-selected`, which is invalid ARIA on
+  `role="button"` and on a read-only stage's bare `View` alike (2026-08 sweep; mirrors `pagination`'s
+  `aria-current="page"` for "the page you're on", token `"step"` here instead).
 - **WCAG 2.4.7** — an interactive stage (`readOnly={false}`, not `disabled`) draws a `border.focus`
   ring (`${testID}-focus-ring-${stage.id}`) while focused. It is drawn **inside** the stage's
   bounds: `stageProgressRowStructure` clips to `overflow: "hidden"` and spaces stages one space step
@@ -50,10 +52,10 @@ no `Pressable`, and need no target.
 | `upcomingText` on `upcomingFill` (`fg.muted` / `bg.sunken`) | 6.45 |
 | `upcomingText` on `bg.canvas` (the `stepper` label under the circle) | 6.52 |
 
-`track` is `border.default` — a decorative pill/circle outline at 1.08–1.43 on the canvas, never
-escalated to `border.interactive` / `border.focus`. Bar-segment fills are deliberately quiet
-(`bg.sunken` at ~1.01–1.12 on the canvas); the state they encode is carried by the progressbar
-label, not by contrast.
+Pills and stepper circles carry no outline any more — `theme.elevation.sm` lifts them off the row
+instead (Wave 5 tonal restyle), the same "tone/depth, not a hairline" treatment `Card`'s elevated
+variant uses. Bar-segment fills are deliberately quiet (`bg.sunken` at ~1.01–1.12 on the canvas); the
+state they encode is carried by the progressbar label, not by contrast.
 
 ## Known gaps
 
@@ -62,3 +64,5 @@ label, not by contrast.
   cannot move outside the stage — the row clips — so a fix would be a token-level decision, not a
   change here.
 - There is no arrow-key path between stages: each interactive stage is its own tab stop.
+
+- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.