pixelize-native-library 1.2.0 → 1.3.0

package/lib/module/modules/select/Select.js

@@ -5,18 +5,23 @@
  */
 
 import { memo, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
-import { Animated, Modal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import { Modal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Reanimated, { useAnimatedStyle } from "react-native-reanimated";
 import { focusItemProps, useDismissOnEscape, useFocusTrap, useRovingKeys, useSpaceActivation } from "../../core/a11y/keyboard";
 import { Icon } from "../../core/icon/index.js";
 import { VirtualList } from "../../core/list/index.js";
-import { useMotion, usePressMotion, useReveal } from "../../core/motion/index.js";
+import { renderNodeSlot } from "../../core/slot/index.js";
+import { MOTION_TRANSFORM, useMotion, useAnimatedValue, usePressMotion, useReveal } from "../../core/motion/index.js";
+import { elevation, floatingBackground, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { rippleColor } from "../../theme/platform/stateLayer.native.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
+import { withAlpha } from "../../core/gradient/index.js";
 import { useTheme } from "../../theme/hooks.js";
-import { ModalPortalContext } from "../modal/ModalPortalContext.js";
-import { renderWebPortal } from "../modal/renderWebPortal";
-import { resolveSelectAccessibility, resolveSelectRowColors, resolveSelectTriggerColors, SELECT_LISTBOX_ROLE, SELECT_ROW_ICON_SIZE, SELECT_ROW_MIN_HEIGHT, SELECT_SIZES, selectOverlayStructure, selectRowLeadingStructure, selectRowStructure, selectSheetStructure, selectTriggerStructure, selectTriggerValueStructure } from "./Select.variants.js";
+import { ModalPortalContext, renderWebPortal } from "../../core/overlay/index.js";
+import { resolveSelectAccessibility, resolveSelectOptionLabelColor, resolveSelectRowColors, resolveSelectTriggerColors, SELECT_LISTBOX_ROLE, SELECT_OPTION_ROLE, SELECT_ROW_ICON_SIZE, SELECT_ROW_MIN_HEIGHT, SELECT_SIZES, selectOverlayStructure, selectRowLeadingStructure, selectRowStructure, selectSheetStructure, selectTriggerStructure, selectTriggerValueStructure } from "./Select.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const ICON_STROKE = 2;
-const BACKDROP_SCRIM = "#00000099";
+const BACKDROP_SCRIM = withAlpha("#000000", MOTION_TRANSFORM.scrimOpacity);
 const SelectOptionRow = /*#__PURE__*/memo(function SelectOptionRow({
   option,
   selected,
@@ -29,6 +34,10 @@ const SelectOptionRow = /*#__PURE__*/memo(function SelectOptionRow({
   const motion = useMotion();
   const press = usePressMotion();
   const handlePress = useCallback(() => onSelect(option), [onSelect, option]);
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(theme.mode),
+    borderless: false
+  } : undefined, [theme.mode]);
   const rowRef = useRef(null);
   const active = tabIndex === 0;
 
@@ -39,21 +48,20 @@ const SelectOptionRow = /*#__PURE__*/memo(function SelectOptionRow({
     rowRef.current?.focus();
   }, [active]);
 
-  // `menuitem` is not `button`, so RNW never presses on Space — see `core/a11y/keyboard.web.ts`.
+  // `option` is not `button`, so RNW never presses on Space — see `core/a11y/keyboard.web.ts`.
   useSpaceActivation(rowRef, handlePress);
-  const checkOpacity = useRef(new Animated.Value(selected ? 1 : 0)).current;
+  const checkOpacity = useAnimatedValue(selected ? 1 : 0);
   const skipFirst = useRef(true);
   const running = useRef(null);
   useEffect(() => {
     running.current?.stop();
-    // A row scrolled into view already-selected must snap, never fade.
     if (skipFirst.current) {
       skipFirst.current = false;
-      checkOpacity.setValue(selected ? 1 : 0);
+      checkOpacity.value = selected ? 1 : 0;
       return;
     }
     if (!motion.enabled) {
-      checkOpacity.setValue(selected ? 1 : 0);
+      checkOpacity.value = selected ? 1 : 0;
       return;
     }
     running.current = motion.timing(checkOpacity, selected ? 1 : 0, {
@@ -63,6 +71,9 @@ const SelectOptionRow = /*#__PURE__*/memo(function SelectOptionRow({
     return () => running.current?.stop();
   }, [selected, motion, checkOpacity]);
   useEffect(() => () => running.current?.stop(), []);
+  const checkStyle = useAnimatedStyle(() => ({
+    opacity: checkOpacity.value
+  }));
   const rowStructure = useMemo(() => selectRowStructure(theme), [theme]);
   const leadingStructure = useMemo(() => selectRowLeadingStructure(theme), [theme]);
   const rowStyle = useCallback(({
@@ -73,33 +84,32 @@ const SelectOptionRow = /*#__PURE__*/memo(function SelectOptionRow({
   const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
     flex: 1,
     fontSize: theme.fontSizes.md,
-    color: rowColors.text
-  }], [theme, rowColors]);
+    color: resolveSelectOptionLabelColor(theme.colors, option.tone, option.customColors)
+  }], [theme, option.tone, option.customColors]);
   return /*#__PURE__*/_jsx(Pressable, {
     ref: rowRef,
     testID: testID ? `${testID}-option-${option.value}` : undefined,
-    accessibilityRole: "menuitem",
+    accessibilityRole: SELECT_OPTION_ROLE,
     "aria-selected": selected,
     tabIndex: tabIndex,
     onPress: handlePress,
     onPressIn: press.onPressIn,
     onPressOut: press.onPressOut,
+    android_ripple: androidRipple,
     style: rowStyle,
-    children: /*#__PURE__*/_jsxs(Animated.View, {
+    children: /*#__PURE__*/_jsxs(Reanimated.View, {
       testID: testID ? `${testID}-option-${option.value}-content` : undefined,
       style: [rowStructure, press.style],
       children: [option.leading !== undefined && /*#__PURE__*/_jsx(View, {
         style: leadingStructure,
-        children: option.leading
+        children: renderNodeSlot(option.leading, labelStyle)
       }), /*#__PURE__*/_jsx(Text, {
         numberOfLines: 1,
         style: labelStyle,
         children: option.label
-      }), selected && /*#__PURE__*/_jsx(Animated.View, {
+      }), selected && /*#__PURE__*/_jsx(Reanimated.View, {
         testID: testID ? `${testID}-option-${option.value}-check` : undefined,
-        style: {
-          opacity: checkOpacity
-        },
+        style: checkStyle,
         children: /*#__PURE__*/_jsx(Icon, {
           name: "check",
           size: SELECT_ROW_ICON_SIZE,
@@ -116,6 +126,8 @@ export const Select = /*#__PURE__*/memo(function Select({
   onValueChange,
   placeholder,
   label,
+  status = "default",
+  errorText,
   disabled = false,
   size = "md",
   containerStyle,
@@ -156,7 +168,7 @@ export const Select = /*#__PURE__*/memo(function Select({
   const typeaheadLabels = useMemo(() => options.map(option => option.label), [options]);
 
   // Keyboard (web only — every hook below is a no-op on native, see `core/a11y/keyboard.ts`).
-  // No `onActivate`: RNW already presses a `menuitem` on Enter, and each row's own
+  // No `onActivate`: RNW already presses on Enter regardless of role, and each row's own
   // `useSpaceActivation` owns Space — passing it here would select twice.
   useDismissOnEscape(open, closeMenu);
   useFocusTrap(sheetRef, open);
@@ -183,14 +195,29 @@ export const Select = /*#__PURE__*/memo(function Select({
   const triggerStyle = useMemo(() => [selectTriggerStructure(theme, {
     size
   }), {
-    backgroundColor: triggerColors.background,
-    borderColor: triggerColors.border
-  }, disabled && styles.dimmed], [theme, size, triggerColors, disabled]);
+    backgroundColor: focused || open ? withAlpha(theme.colors.accent.solid, 0.04) : triggerColors.background,
+    borderColor: status === "error" ? theme.colors.status.danger.solid : triggerColors.border,
+    borderWidth: focused || open || status === "error" ? 2 : theme.borderWidths.thin,
+    overflow: "hidden"
+  }, disabled && styles.dimmed], [theme, size, triggerColors, disabled, focused, open, status]);
   const valueStructure = useMemo(() => selectTriggerValueStructure(theme), [theme]);
   const overlayStructure = useMemo(() => selectOverlayStructure(theme), [theme]);
-  const sheetStyle = useMemo(() => [selectSheetStructure(theme), {
-    backgroundColor: theme.colors.bg.surface
-  }], [theme]);
+  const floatingStyle = useMemo(() => {
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.md);
+    void theme.elevatedSurfaces;
+    return {
+      backgroundColor: floatingBackground(theme, "md"),
+      ...floatingSurfaceStyle(theme, "md")
+    };
+  }, [theme]);
+  const sheetStyle = useMemo(() => [selectSheetStructure(theme), floatingStyle, {
+    overflow: "hidden"
+  }], [theme, floatingStyle]);
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(theme.mode),
+    borderless: false
+  } : undefined, [theme.mode]);
   const fieldLabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
     fontSize: theme.fontSizes.sm,
     color: theme.colors.fg.muted,
@@ -209,9 +236,10 @@ export const Select = /*#__PURE__*/memo(function Select({
       style: styles.backdrop,
       onPress: closeMenu
     }), /*#__PURE__*/_jsx(View, {
-      style: overlayStructure,
-      pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsx(Animated.View, {
+      style: [overlayStructure, {
+        pointerEvents: 'box-none'
+      }],
+      children: /*#__PURE__*/_jsx(Reanimated.View, {
         ref: sheetRef,
         style: [sheetStyle, reveal.style],
         children: /*#__PURE__*/_jsx(VirtualList, {
@@ -225,12 +253,15 @@ export const Select = /*#__PURE__*/memo(function Select({
     })]
   }) : null;
   const menu = Platform.OS === "web" && portalContainer != null ? open ? renderWebPortal(/*#__PURE__*/_jsx(View, {
-    style: StyleSheet.absoluteFill,
-    pointerEvents: "box-none",
+    style: [StyleSheet.absoluteFill, {
+      pointerEvents: 'box-none'
+    }],
     children: sheet
   }), portalContainer) : null : /*#__PURE__*/_jsx(Modal, {
     visible: open,
     transparent: true,
+    statusBarTranslucent: true,
+    navigationBarTranslucent: true,
     animationType: "none",
     onRequestClose: closeMenu,
     children: sheet
@@ -245,16 +276,18 @@ export const Select = /*#__PURE__*/memo(function Select({
       accessibilityRole: a11y.accessibilityRole,
       accessibilityLabel: accessibleName,
       "aria-disabled": a11y["aria-disabled"],
+      "aria-invalid": status === "error" ? true : undefined,
       "aria-expanded": a11y["aria-expanded"],
       disabled: a11y.disabled,
       onPress: openMenu,
       onFocus: handleFocus,
       onBlur: handleBlur,
       hitSlop: spec.hitSlop,
+      android_ripple: androidRipple,
       style: triggerStyle,
       children: [/*#__PURE__*/_jsxs(View, {
         style: valueStructure,
-        children: [selectedOption?.leading, /*#__PURE__*/_jsx(Text, {
+        children: [renderNodeSlot(selectedOption?.leading, valueTextStyle), /*#__PURE__*/_jsx(Text, {
           numberOfLines: 1,
           style: valueTextStyle,
           children: displayText
@@ -265,7 +298,14 @@ export const Select = /*#__PURE__*/memo(function Select({
         color: triggerColors.icon,
         strokeWidth: ICON_STROKE
       })]
-    }), menu]
+    }), status === "error" && errorText ? /*#__PURE__*/_jsx(Text, {
+      style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+        fontSize: theme.fontSizes.xs,
+        color: theme.colors.status.danger.solid,
+        marginTop: theme.space[1]
+      }],
+      children: errorText
+    }) : null, menu]
   });
 });
 const styles = StyleSheet.create({

package/lib/module/modules/select/Select.variants.js

@@ -13,6 +13,7 @@
  * directly (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
  */
 
+import { MIN_TOUCH_TARGET, slopFor } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants } from "../../core/style/index.js";
 /**
  * The option list's container role. RN 0.86's role unions have no `listbox` — both `Role` and
@@ -22,32 +23,38 @@ import { createThemedVariants } from "../../core/style/index.js";
  */
 export const SELECT_LISTBOX_ROLE = "listbox";
 
-/** Same touch-target floor as Button (44dp — Apple HIG minimum, WCAG 2.5.5 AAA). */
-export const MIN_TOUCH_TARGET = 44;
-const slopFor = height => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - height) / 2));
+/**
+ * Each option row's role. `aria-selected` is only valid ARIA on `option`/`row`/`tab`/`gridcell`/
+ * `treeitem` — the row sits inside a `SELECT_LISTBOX_ROLE` container, so `option` is the
+ * textbook-correct pairing (2026-08 sweep fixed the row from the invalid `menuitem`+`aria-selected`
+ * combination). Same type gap as `SELECT_LISTBOX_ROLE`: RN 0.86's `AccessibilityRole` union has no
+ * `option` either.
+ */
+export const SELECT_OPTION_ROLE = "option";
+export { MIN_TOUCH_TARGET, slopFor };
 export const SELECT_SIZES = {
   sm: {
-    height: 32,
+    height: 44,
     fontSize: 14,
     iconSize: 16,
-    hitSlop: slopFor(32)
+    hitSlop: slopFor(44)
   },
   md: {
-    height: 40,
+    height: 52,
     fontSize: 16,
     iconSize: 18,
-    hitSlop: slopFor(40)
+    hitSlop: slopFor(52)
   },
   lg: {
-    height: 48,
+    height: 56,
     fontSize: 18,
     iconSize: 20,
-    hitSlop: slopFor(48)
+    hitSlop: slopFor(56)
   }
 };
 
 /** Minimum height for an option row — a list item is still an interactive target (WCAG 2.5.8). */
-export const SELECT_ROW_MIN_HEIGHT = 44;
+export const SELECT_ROW_MIN_HEIGHT = 48;
 
 /** The "check" glyph beside the active row. Fixed — independent of the trigger's own `size`. */
 export const SELECT_ROW_ICON_SIZE = 18;
@@ -60,7 +67,7 @@ export const SELECT_ROW_ICON_SIZE = 18;
 export function resolveSelectTriggerColors(colors, focused) {
   return {
     background: colors.bg.surface,
-    border: focused ? colors.border.focus : colors.border.interactive,
+    border: focused ? colors.accent.solid : colors.border.interactive,
     text: colors.fg.default,
     placeholder: colors.fg.muted,
     icon: colors.fg.muted
@@ -74,6 +81,20 @@ export function resolveSelectRowColors(colors) {
     pressedRow: colors.bg.sunken
   };
 }
+export function resolveSelectOptionLabelColor(colors, tone, customColors) {
+  if (tone === undefined) {
+    return colors.fg.default;
+  }
+  if (tone === "custom") {
+    if (!customColors) {
+      throw new Error('SelectOption tone="custom" requires customColors={{ bg, fg }}.');
+    }
+    return customColors.fg;
+  }
+  if (tone === "accent") return colors.accent.text;
+  if (tone === "neutral") return colors.fg.default;
+  return colors.status[tone].text;
+}
 /**
  * Derives the trigger's accessibility surface once, purely: `expanded` tracks whether the option
  * list is showing (WCAG 4.1.2 — a collapsible control must expose its expanded/collapsed state),
@@ -99,7 +120,8 @@ export const selectTriggerStructure = createThemedVariants(theme => ({
     alignItems: "center",
     justifyContent: "space-between",
     columnGap: theme.space[2],
-    borderRadius: theme.radii.base,
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     borderWidth: theme.borderWidths.thin
   },
   variants: {
@@ -143,12 +165,13 @@ export const selectOverlayStructure = createThemedVariants(theme => ({
     paddingHorizontal: theme.space[6]
   }
 }));
+
+// No vertical padding — rows must tile edge-to-edge so the sheet's own fill never shows through.
 export const selectSheetStructure = createThemedVariants(theme => ({
   base: {
-    borderRadius: theme.radii.base,
-    paddingVertical: theme.space[2],
-    maxHeight: 320,
-    ...theme.elevation.lg
+    borderRadius: theme.radii.lg,
+    borderCurve: "continuous",
+    maxHeight: 320
   }
 }));
 export const selectRowStructure = createThemedVariants(theme => ({

package/lib/module/modules/select/SelectProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=SelectProps.js.map

package/lib/module/modules/setting-row/MODULE.md

@@ -0,0 +1,8 @@
+# setting-row/ — a settings line with a title and a trailing control
+
+Settings line: title + optional description left, arbitrary `control` right.
+
+## Exports
+
+- `SettingRow` — `title` (required), `description`, `control` (required `ReactNode`, trailing
+  edge), `isDanger` (danger ink for destructive zones), `style` (layout-only, last), `testID`

package/lib/module/modules/setting-row/SettingRow.js

@@ -0,0 +1,50 @@
+"use strict";
+
+import { memo, useMemo } from "react";
+import { View } from "react-native";
+import { renderNodeSlot } from "../../core/slot/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { Text } from "../text/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const SettingRow = /*#__PURE__*/memo(function SettingRow({
+  title,
+  description,
+  control,
+  isDanger = false,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const rowStyle = useMemo(() => ({
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: theme.space[3],
+    paddingVertical: theme.space[3],
+    minHeight: 56
+  }), [theme]);
+  const controlSlotStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.md,
+    color: theme.colors.fg.default
+  }], [theme]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [rowStyle, style],
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: {
+        flex: 1,
+        gap: theme.space[1]
+      },
+      children: [/*#__PURE__*/_jsx(Text, {
+        variant: "body-sm",
+        color: isDanger ? "danger" : "default",
+        children: title
+      }), description ? /*#__PURE__*/_jsx(Text, {
+        variant: "caption",
+        color: "muted",
+        children: description
+      }) : null]
+    }), renderNodeSlot(control, controlSlotStyle)]
+  });
+});
+//# sourceMappingURL=SettingRow.js.map

package/lib/module/modules/setting-row/SettingRowProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=SettingRowProps.js.map

package/lib/module/modules/setting-row/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { SettingRow } from "./SettingRow.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/settings-section/MODULE.md

@@ -0,0 +1,7 @@
+# settings-section/ — a grouped settings block with an optional title
+
+Grouped settings block with optional section title. Compose with `setting-row`.
+
+## Exports
+
+- `SettingsSection` — `title` (optional), `children` (required), `style` (layout-only, last), `testID`

package/lib/module/modules/settings-section/SettingsSection.js

@@ -0,0 +1,37 @@
+"use strict";
+
+import { memo, useMemo } from "react";
+import { View } from "react-native";
+import { renderNodeSlot } from "../../core/slot/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { Text } from "../text/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const SettingsSection = /*#__PURE__*/memo(function SettingsSection({
+  title,
+  children,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const sectionStyle = useMemo(() => ({
+    gap: theme.space[1],
+    marginBottom: theme.space[4]
+  }), [theme]);
+  const childrenSlotStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    color: theme.colors.fg.default,
+    fontSize: theme.fontSizes.md
+  }], [theme]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [sectionStyle, style],
+    children: [title ? /*#__PURE__*/_jsx(Text, {
+      variant: "overline",
+      color: "muted",
+      style: {
+        marginBottom: theme.space[2]
+      },
+      children: title
+    }) : null, renderNodeSlot(children, childrenSlotStyle)]
+  });
+});
+//# sourceMappingURL=SettingsSection.js.map

package/lib/module/modules/settings-section/SettingsSectionProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=SettingsSectionProps.js.map

package/lib/module/modules/settings-section/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { SettingsSection } from "./SettingsSection.js";
+//# sourceMappingURL=index.js.map

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,11 +22,13 @@ 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`),
+No `tone`/`color` prop: a skeleton has exactly one neutral appearance (`resolveSkeletonColors` from
+`bg.sunken` / `bg.skeletonShimmer` roles; shimmer band via `core/gradient/ShimmerGradientFill`),
 the same reasoning as `Avatar`'s and `Divider`'s colour resolvers — there is nothing for an app to
 widen.
 
@@ -46,11 +48,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 +61,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 +79,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 +100,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.