@multiplatform.one/forms 7.34.3 → 7.35.0

package/src/Skeleton/index.tsx

@@ -1,10 +1,24 @@
+import { createContext, useContext, type ReactNode } from "react";
 import { radiusClassProps, sizeRecipeForToken, useResolvedKnobs } from "@multiplatform.one/theme";
 import type { GetProps } from "tamagui";
 import { View, styled, isWeb } from "tamagui";
+import { useTranslation } from "../shared/i18n";
+
+/**
+ * The one Skeleton. `@multiplatform.one/components` re-exports this module,
+ * so a loading Button, a field skeleton and a screen placeholder paint the
+ * same bone with the same motion.
+ *
+ * Motion: one keyframe (`mp-skeleton-pulse`), mounted once per document by
+ * the first bone. It runs only while the animation knob resolves a
+ * transition; `prefers-reduced-motion` resolves none (useResolvedKnobs), and
+ * the stylesheet's media query also stops a bone the server rendered pulsing.
+ */
 
 // ── Types ─────────────────────────────────────────────────────
 
 export type SkeletonVariant = "text" | "circular" | "rectangular" | "rounded";
+export type SkeletonTextSize = "body" | "display";
 
 export interface SkeletonProps extends Omit<GetProps<typeof SkeletonFrame>, "variant"> {
   variant?: SkeletonVariant;
@@ -14,6 +28,8 @@ export interface SkeletonProps extends Omit<GetProps<typeof SkeletonFrame>, "var
   height?: number | string;
   /** Whether to animate the skeleton */
   animate?: boolean;
+  /** Accessible name for a root loading region. Ignored on decorative bones. */
+  label?: string;
 }
 
 // ── Styled component ──────────────────────────────────────────
@@ -21,12 +37,14 @@ export interface SkeletonProps extends Omit<GetProps<typeof SkeletonFrame>, "var
 const SkeletonFrame = styled(View, {
   name: "Skeleton",
   backgroundColor: "$color5",
+  overflow: "hidden",
+  pointerEvents: "none",
+  flexShrink: 0,
 
   variants: {
     variant: {
       text: {
         borderRadius: "$2",
-        height: 16,
       },
       circular: {
         borderRadius: 1000,
@@ -48,34 +66,41 @@ const SkeletonFrame = styled(View, {
 // Size-knob geometry (spec: Skeleton block/text/circle scale with
 // `sizeToken`), DERIVED from the generated size recipe (LC-80): a text bone
 // is the token's recipe fontSize + 2px of line-box rounding (medium keeps
-// the previous 16px line), and a circle bone is the medallion one height
-// step above the control ramp (medium keeps the previous 40px circle).
-const SKELETON_SIZE_TOKENS = ["$3", "$4", "$5"] as const;
+// the previous 16px line), display is twice that, and a circle bone is the
+// medallion one height step above the control ramp.
+const SKELETON_SIZE_TOKENS = ["$3", "$4", "$true", "$5"] as const;
 const skeletonCircleTokenUp: Record<string, string> = { $3: "$4", $4: "$5", $5: "$6" };
 
-function skeletonTextHeight(sizeToken: string): number | undefined {
-  if (!(SKELETON_SIZE_TOKENS as readonly string[]).includes(sizeToken)) return undefined;
-  return sizeRecipeForToken(sizeToken).fontSize + 2;
+function skeletonTextHeight(sizeToken: string, textSize: SkeletonTextSize = "body"): number {
+  const known = (SKELETON_SIZE_TOKENS as readonly string[]).includes(sizeToken) ? sizeToken : "$4";
+  const body = sizeRecipeForToken(known).fontSize + 2;
+  return textSize === "display" ? body * 2 : body;
 }
 
 function skeletonCircleSize(sizeToken: string): number {
   return sizeRecipeForToken(skeletonCircleTokenUp[sizeToken] ?? "$5").height;
 }
-// SP-GAP: text-line gap follows the space knob; medium keeps $2.
-const skeletonGapMap: Record<string, string> = { small: "$1", medium: "$2", large: "$3" };
 
-// Self-contained pulse keyframes: the app root layout injects the same rule,
-// but Skeleton must not depend on a particular host (Storybook, tests, docs).
+// One keyframe, mounted once. The reduced-motion and forced-colors rules ride
+// the same sheet so a bone never pulses for a user who asked for stillness.
 const PULSE_STYLE_ID = "__mp-skeleton-pulse";
+const PULSE_ANIMATION = "mp-skeleton-pulse 1.5s ease-in-out infinite";
 function ensurePulseKeyframes() {
   if (!isWeb || typeof document === "undefined") return;
   if (document.getElementById(PULSE_STYLE_ID)) return;
   const style = document.createElement("style");
   style.id = PULSE_STYLE_ID;
-  style.textContent = "@keyframes skeleton-pulse{0%{opacity:1}50%{opacity:0.4}100%{opacity:1}}";
+  style.textContent = [
+    "@keyframes mp-skeleton-pulse{0%{opacity:1}50%{opacity:0.4}100%{opacity:1}}",
+    "@media (prefers-reduced-motion:reduce){.mp-skeleton-bone{animation:none!important}}",
+    "@media (forced-colors:active){.mp-skeleton-bone{outline:1px solid transparent;outline-offset:-1px}}",
+  ].join("");
   document.head.appendChild(style);
 }
 
+/** False inside a SkeletonText / SkeletonGroup: the region announces once. */
+const AnnounceCtx = createContext(true);
+
 // ── Skeleton Component ────────────────────────────────────────
 
 export function Skeleton({
@@ -84,42 +109,68 @@ export function Skeleton({
   height,
   animate = true,
   style,
+  label,
+  className,
   ...props
 }: SkeletonProps) {
-  const { knobProps } = useResolvedKnobs();
-  // Pulse only when animating is on AND the animation knob is not "none"
-  // (knobProps.transition resolves to undefined at animation:none).
-  const pulsing = animate && knobProps.transition !== undefined;
-  if (pulsing) ensurePulseKeyframes();
-
-  // Merge pulse last into `style` so a consumer style prop cannot kill the
-  // animation (LC-20: animation:none stops the pulse via the knob; otherwise
-  // it must run).
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ component: "Skeleton" });
+  const shouldAnnounce = useContext(AnnounceCtx);
+  // Pulse only when animating is on AND the animation knob resolves a
+  // transition (undefined at animation:none and under prefers-reduced-motion).
+  const pulsing = Boolean(animate && knobProps.motion.control.transition);
+  if (isWeb) ensurePulseKeyframes();
+
+  const decorative = props["aria-hidden"] === true || !shouldAnnounce;
+  // Corner smoothing is an R-SCALE arc: circular is R-PILL (a squircle would
+  // break 1:1) and rectangular is square by variant.
+  const smoothingClass =
+    variant === "text" || variant === "rounded" ? knobProps.borderRadius.className : undefined;
+  const boneClass = [
+    "mp-skeleton-bone",
+    pulsing ? "mp-skeleton-pulse" : "mp-skeleton-static",
+    smoothingClass,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  // Merge the pulse last into `style` so a consumer style cannot kill it
+  // (LC-20: animation:none stops the pulse via the knob; otherwise it runs).
   const mergedStyle =
-    isWeb && pulsing
-      ? { ...(style as object), animation: "skeleton-pulse 1.5s ease-in-out infinite" }
-      : style;
+    isWeb && pulsing ? { ...(style as object), animation: PULSE_ANIMATION } : style;
+
+  const textHeight = variant === "text" ? skeletonTextHeight(knobProps.sizeToken) : undefined;
+  const resolvedHeight = height ?? textHeight;
 
   return (
     <SkeletonFrame
       variant={variant}
       width={width}
-      // Text lines follow the size knob; explicit height ejects.
-      height={height ?? (variant === "text" ? skeletonTextHeight(knobProps.sizeToken) : undefined)}
-      // Radius only — a skeleton is a flat blob, it never draws the knob's border.
-      // Consumers that clamp (Checkbox/Radio/Switch) pass an explicit borderRadius
-      // which wins via ...props below.
-      // Text lines and rounded blocks ride DEFAULT (knobs-enumerated Part 2b,
-      // MPO-56): the token at every stop, the paint capping at h/2.
+      height={resolvedHeight}
+      // Radius only — a skeleton is a flat blob, it never draws the knob's
+      // border. Text lines and rounded blocks ride DEFAULT (MPO-56): the token
+      // at every stop. Consumers that clamp pass borderRadius via ...props.
       {...(variant === "rounded" || variant === "text"
         ? { borderRadius: knobProps.borderRadius.borderRadius }
         : undefined)}
-      // R-PILL (spec Skeleton "circle"): the circular variant stays 1:1 and
-      // round at every radius value, so it declares the class the
-      // `radius:none` sweep licenses it under (D-09 / LC-60).
+      // R-PILL (spec Skeleton "circle"): stays 1:1 and round at every radius.
       {...(variant === "circular" ? radiusClassProps("R-PILL", "SkeletonCircle") : undefined)}
       {...props}
+      {...(isWeb ? { className: boneClass } : undefined)}
       {...(mergedStyle ? { style: mergedStyle } : undefined)}
+      pointerEvents="none"
+      data-skeleton=""
+      data-skeleton-variant={variant}
+      data-animate={pulsing ? "true" : "false"}
+      data-width={width != null ? String(width) : undefined}
+      data-height={resolvedHeight != null ? String(resolvedHeight) : undefined}
+      aria-hidden={decorative ? true : undefined}
+      role={decorative ? undefined : "status"}
+      aria-busy={decorative ? undefined : true}
+      aria-live={decorative ? undefined : "polite"}
+      aria-label={decorative ? undefined : (label ?? t("Loading"))}
+      accessibilityElementsHidden={decorative}
     />
   );
 }
@@ -130,43 +181,111 @@ export function SkeletonText({
   lines = 1,
   gap: gapProp,
   lastLineWidth = "70%",
+  size: textSize = "body",
+  label,
+  width,
+  height,
+  animate,
+  style,
+  variant: _variant,
   ...props
 }: SkeletonProps & {
   lines?: number;
   gap?: string | number;
   lastLineWidth?: string | number;
+  size?: SkeletonTextSize;
 }) {
-  const { knobProps } = useResolvedKnobs();
-  const gap = gapProp ?? skeletonGapMap[knobProps.space] ?? "$2";
-  if (lines === 1) {
-    return <Skeleton variant="text" width={lastLineWidth} {...props} />;
-  }
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ component: "Skeleton" });
+  const shouldAnnounce = useContext(AnnounceCtx);
+  const count = Math.max(0, Math.floor(Number(lines) || 0));
+  const lineHeight = height ?? skeletonTextHeight(knobProps.sizeToken, textSize);
+  // SP-GAP: the text-line gap is the tight role (gapSm) at every size token.
+  const gap = gapProp ?? knobProps.gapSm.gap;
+  const decorative = !shouldAnnounce;
+
+  if (count === 0) return null;
 
   return (
-    <View gap={gap}>
-      {Array.from({ length: lines }).map((_, i) => (
-        <Skeleton
-          key={i}
-          variant="text"
-          width={i === lines - 1 ? lastLineWidth : "100%"}
-          {...props}
-        />
-      ))}
-    </View>
+    <AnnounceCtx.Provider value={false}>
+      <View
+        {...props}
+        width={width ?? "100%"}
+        gap={gap}
+        data-skeleton-text=""
+        data-lines={String(count)}
+        aria-hidden={decorative ? true : undefined}
+        role={decorative ? undefined : "status"}
+        aria-busy={decorative ? undefined : true}
+        aria-live={decorative ? undefined : "polite"}
+        aria-label={decorative ? undefined : (label ?? t("Loading"))}
+      >
+        {Array.from({ length: count }, (_, i) => (
+          <Skeleton
+            key={i}
+            variant="text"
+            animate={animate}
+            style={style}
+            height={lineHeight}
+            width={
+              count === 1 ? (width ?? lastLineWidth) : i === count - 1 ? lastLineWidth : "100%"
+            }
+          />
+        ))}
+      </View>
+    </AnnounceCtx.Provider>
   );
 }
 
 // ── Skeleton.Circle - for avatar placeholder ──────────────────
 
-export function SkeletonCircle({ size: sizeProp, ...props }: SkeletonProps & { size?: number }) {
-  const { knobProps } = useResolvedKnobs();
-  const size = sizeProp ?? skeletonCircleSize(knobProps.sizeToken);
-  return <Skeleton variant="circular" width={size} height={size} {...props} />;
+export function SkeletonCircle({
+  size: sizeProp,
+  label,
+  ...props
+}: SkeletonProps & { size?: number }) {
+  const { knobProps } = useResolvedKnobs({ component: "Skeleton" });
+  const diameter = Math.max(0, sizeProp ?? skeletonCircleSize(knobProps.sizeToken));
+  return (
+    <Skeleton
+      variant="circular"
+      label={label}
+      width={diameter}
+      height={diameter}
+      {...props}
+      data-diameter={String(diameter)}
+    />
+  );
+}
+
+// ── Skeleton.Group - one announcement for a composed placeholder ──
+
+export function SkeletonGroup({
+  children,
+  label,
+  ...props
+}: GetProps<typeof View> & { children?: ReactNode; label?: string }) {
+  const { t } = useTranslation();
+  return (
+    <AnnounceCtx.Provider value={false}>
+      <View
+        {...props}
+        role="status"
+        aria-busy={true}
+        aria-live="polite"
+        aria-label={label ?? t("Loading")}
+        data-skeleton-group=""
+      >
+        {children}
+      </View>
+    </AnnounceCtx.Provider>
+  );
 }
 
 // ── Attach sub-components ─────────────────────────────────────
 
 Skeleton.Text = SkeletonText;
 Skeleton.Circle = SkeletonCircle;
+Skeleton.Group = SkeletonGroup;
 
 export type SkeletonFrameProps = GetProps<typeof SkeletonFrame>;

package/src/Skeleton/skeletonStories.spec.tsx

@@ -1,7 +1,7 @@
 /**
  * Mounts every Forms/Skeleton story and asserts what it exists to show. The
  * theme hooks stay REAL: text-bone height comes from the size recipe and the
- * pulse gates on knobProps.transition, so a stub would measure neither.
+ * pulse gates on knobProps.motion.control.transition, so a stub would measure neither.
  *
  * Geometry is read off the CLASS, not `style`. Tamagui compiles width, height
  * and radius into atomic classes (`_w-240px`, `_w-7037` for 70%), and only the

package/src/Spinner/Spinner.spec.tsx

@@ -4,7 +4,7 @@
 
 import { cleanup } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { Preset } from "@multiplatform.one/theme";
+import { Preset, Surface } from "@multiplatform.one/theme";
 import { afterEach, describe, expect, it } from "vitest";
 import { Spinner } from "./index";
 
@@ -42,10 +42,10 @@ describe("Spinner", () => {
 
   it("maps explicit small/large onto the shared size-token scale", () => {
     const small = renderWithProviders(<Spinner size="small" />);
-    expect(status(small.container).getAttribute("data-size")).toBe("$1");
+    expect(status(small.container).getAttribute("data-size-token")).toBe("$1");
     cleanup();
     const large = renderWithProviders(<Spinner size="large" />);
-    expect(status(large.container).getAttribute("data-size")).toBe("$3");
+    expect(status(large.container).getAttribute("data-size-token")).toBe("$3");
   });
 
   it("publishes data-animation=none when the animation knob is none", () => {
@@ -64,17 +64,17 @@ describe("Spinner", () => {
 
   it("follows the size knob when size is omitted", () => {
     const small = renderWithProviders(
-      <Preset overrides={{ size: "small" }}>
+      <Surface size="$3">
         <Spinner />
-      </Preset>,
+      </Surface>,
     );
-    expect(status(small.container).getAttribute("data-size")).toBe("$3");
+    expect(status(small.container).getAttribute("data-size-token")).toBe("$3");
     cleanup();
     const large = renderWithProviders(
-      <Preset overrides={{ size: "large" }}>
+      <Surface size="$5">
         <Spinner />
-      </Preset>,
+      </Surface>,
     );
-    expect(status(large.container).getAttribute("data-size")).toBe("$5");
+    expect(status(large.container).getAttribute("data-size-token")).toBe("$5");
   });
 });

package/src/Spinner/Spinner.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useState } from "react";
-import { Preset } from "@multiplatform.one/theme";
+import { Preset, Surface } from "@multiplatform.one/theme";
 import { XStack, YStack, Paragraph } from "tamagui";
 import { Button } from "../Button";
 import { Spinner } from "./index";
@@ -41,22 +41,22 @@ export const Sizes: Story = {
       </XStack>
       <XStack gap="$6" alignItems="center">
         <YStack gap="$2" alignItems="center">
-          <Preset overrides={{ size: "small" }}>
+          <Surface size="$3">
             <Spinner />
-          </Preset>
-          <Paragraph size="$2">knob small</Paragraph>
+          </Surface>
+          <Paragraph size="$2">Surface $3</Paragraph>
         </YStack>
         <YStack gap="$2" alignItems="center">
-          <Preset overrides={{ size: "medium" }}>
+          <Surface size="$4">
             <Spinner />
-          </Preset>
-          <Paragraph size="$2">knob medium</Paragraph>
+          </Surface>
+          <Paragraph size="$2">Surface $4</Paragraph>
         </YStack>
         <YStack gap="$2" alignItems="center">
-          <Preset overrides={{ size: "large" }}>
+          <Surface size="$5">
             <Spinner />
-          </Preset>
-          <Paragraph size="$2">knob large</Paragraph>
+          </Surface>
+          <Paragraph size="$2">Surface $5</Paragraph>
         </YStack>
         <YStack gap="$2" alignItems="center">
           <Preset overrides={{ animation: "none" }}>

package/src/Spinner/index.native.tsx

@@ -28,7 +28,7 @@ export function Spinner({ size, color, ...props }: SpinnerProps) {
       sub.remove();
     };
   }, []);
-  const spinning = Boolean(knobProps.transition) && !reduceMotion;
+  const spinning = Boolean(knobProps.motion.control.transition) && !reduceMotion;
   const spin = useRef(new Animated.Value(0)).current;
 
   useEffect(() => {
@@ -65,7 +65,7 @@ export function Spinner({ size, color, ...props }: SpinnerProps) {
       aria-live="polite"
       aria-busy
       pointerEvents="none"
-      data-size={token}
+      data-size-token={token}
       data-animation={spinning ? "spin" : "none"}
       {...props}
     >

package/src/Spinner/index.tsx

@@ -7,8 +7,8 @@ import { spinnerSizePx, spinnerSizeToken, type SpinnerProps } from "./spinnerSiz
 export type { SpinnerProps, SpinnerSize } from "./spinnerSize";
 
 const MOTION_STYLE_ID = "mp1-spinner-motion";
-// A-CONTINUOUS period. Gated on `knobProps.transition` (LC-68); not sourced
-// from A-STATE durations (quick=100ms would strobe).
+// A-CONTINUOUS period. Gated on `knobProps.motion.control.transition` (LC-68); not sourced
+// from A-STATE durations (quick=150ms would strobe).
 const SPIN_PERIOD = "0.7s";
 
 function ensureMotionStyles() {
@@ -31,7 +31,7 @@ export function Spinner({ size, color, ...props }: SpinnerProps) {
   const token = spinnerSizeToken(size, knobProps.sizeToken);
   const px = spinnerSizePx(token);
   const stroke = useSpinnerStroke(color);
-  const animationsOff = !knobProps.transition;
+  const animationsOff = !knobProps.motion.control.transition;
   ensureMotionStyles();
   const { className: classNameProp, ...rest } = props as { className?: string };
   const className = ["mp1-spinner", animationsOff ? "mp1-spinner-static" : "", classNameProp]
@@ -46,7 +46,7 @@ export function Spinner({ size, color, ...props }: SpinnerProps) {
       aria-live="polite"
       aria-busy
       pointerEvents="none"
-      data-size={token}
+      data-size-token={token}
       data-animation={animationsOff ? "none" : "spin"}
       {...(isWeb ? { className } : undefined)}
       {...rest}

package/src/Spinner/spinnerSize.ts

@@ -12,7 +12,7 @@ export interface SpinnerProps {
 
 /**
  * Map the Tamagui binary size prop onto the shared size-token scale.
- * Unspecified size follows the size knob (`knobProps.sizeToken`) so one
+ * Unspecified size follows the size token (`knobProps.sizeToken`) so one
  * knob flip restyles the glyph (LC-18). Explicit small/large stay the
  * button-safe aliases ($1 / $3) used across the catalog.
  */

package/src/Wheel/Wheel.spec.tsx

@@ -54,7 +54,7 @@ describe("Wheel contrast contract", () => {
 });
 
 // ── LC-68 MOTION-RIDES-KNOB ───────────────────────────────────
-// Discrete snaps (keyboard) gate on knobProps.transition: undefined at
+// Discrete snaps (keyboard) gate on knobProps.motion.control.transition: undefined at
 // animation "none" (which also carries prefers-reduced-motion) means snap
 // duration 0 — the wheel JUMPS, no rAF tween. With motion on, the same snap
 // tweens across frames (positive control proving the probe measures motion,
@@ -120,7 +120,7 @@ describe("Wheel snaps ride the animation knob (LC-68)", () => {
     useFrameClock();
     const onChange = vi.fn();
     renderWithProviders(
-      // Default knobs: animation "quick" — knobProps.transition is defined.
+      // Default knobs: animation "quick" — knobProps.motion.control.transition is defined.
       <Wheel items={items} onChange={onChange} visibleItems={5} />,
     );
     const wrapper = screen.getByTestId("wheel-wrapper");
@@ -137,7 +137,7 @@ describe("Wheel snaps ride the animation knob (LC-68)", () => {
     expect(wheelSnapshot()).not.toBe(beforeFrames);
     expect(onChange).not.toHaveBeenCalled();
 
-    // Tween completes (quick ≈ 100ms) and commits exactly one change.
+    // Tween completes (quick = 150ms) and commits exactly one change.
     act(() => {
       vi.advanceTimersByTime(500);
     });

package/src/Wheel/Wheel.stories.tsx

@@ -136,7 +136,7 @@ export const LoopingAndBounded: Story = {
  */
 export const JoinedColumns: Story = {
   render: () => (
-    <XStack width={320}>
+    <XStack width={320} maxWidth="100%">
       <Wheel items={hours} value={9} loop flex={1} highlightEdges="start" aria-label="Hour" />
       <Wheel items={minutes} value={30} loop flex={1} highlightEdges="none" aria-label="Minute" />
       <Wheel items={periods} value="AM" flex={1} highlightEdges="end" aria-label="AM/PM" />

package/src/Wheel/index.tsx

@@ -1,7 +1,8 @@
+import { motionDurationMs } from "@multiplatform.one/theme";
 import type { CSSProperties, ReactNode } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { PanResponder, type GestureResponderEvent } from "react-native";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { sizeTokenStep, useResolvedKnobs } from "@multiplatform.one/theme";
 import type { GetProps, SizeTokens } from "tamagui";
 import { View, getTokens, isWeb, styled, Text } from "tamagui";
 import { t } from "../shared/t";
@@ -83,22 +84,10 @@ const perspectivePx = 400;
 const defaultColumnWidth = 88;
 
 /** Type scale for wheel numerals — iOS UIPickerView is ~21pt at default size. */
-const wheelFontBySize: Record<"small" | "medium" | "large", SizeTokens> = {
-  small: "$6",
-  medium: "$8",
-  large: "$9",
-};
-
-/** Durations for discrete snaps (mirrors theme animationConfig). */
-const transitionDurationsMs: Record<string, number> = {
-  bouncy: 200,
-  lazy: 600,
-  slow: 500,
-  medium: 250,
-  quick: 100,
-  tooltip: 400,
-  snappy: 80,
-  gentle: 450,
+const wheelFontByStep: Record<-1 | 0 | 1, SizeTokens> = {
+  [-1]: "$6",
+  0: "$8",
+  1: "$9",
 };
 
 // The interactive wrapper is a raw <div>, so the non-removable focus-visible
@@ -285,18 +274,17 @@ export function Wheel<T = string | number>({
   "aria-label": ariaLabel,
 }: WheelProps<T>) {
   const { knobProps } = useResolvedKnobs();
-  const sizeKnob = (knobProps.size as "small" | "medium" | "large") ?? "medium";
-  const size = sizeProp ?? wheelFontBySize[sizeKnob] ?? "$8";
+  const size = sizeProp ?? wheelFontByStep[sizeTokenStep(knobProps.sizeToken)];
   // Row geometry rides nestedControl (density-aware, 32px at medium — iOS
   // UIPickerView item extent). Explicit itemHeight ejects.
   const itemHeight = itemHeightProp ?? knobProps.nestedControl.px ?? 32;
   const columnWidth = widthProp ?? defaultColumnWidth;
   ensureWheelFocusStyles();
   // LC-25: discrete snaps (keyboard / controlled value) tween; drag stays 1:1.
-  // knobProps.transition is undefined at animation "none" (which also carries
+  // knobProps.motion.control.transition is undefined at animation "none" (which also carries
   // prefers-reduced-motion) — snaps must JUMP then, not fall back to a tween.
-  const motionTransition = knobProps.transition as string | undefined;
-  const snapDurationMs = motionTransition ? (transitionDurationsMs[motionTransition] ?? 100) : 0;
+  const motionTransition = knobProps.motion.control.transition as string | undefined;
+  const snapDurationMs = motionDurationMs(motionTransition);
   const containerRef = useRef<HTMLDivElement>(null);
   const [scrollOffset, setScrollOffset] = useState(0);
   const [selectedIndex, setSelectedIndex] = useState(0);

package/src/Wheel/wheelStories.spec.tsx

@@ -4,7 +4,7 @@
  * rather than in the gallery.
  *
  * The theme hooks stay REAL: Wheel reads knobProps.nestedControl.px for row
- * height and knobProps.transition for snap duration, and a stub that omits
+ * height and knobProps.motion.control.transition for snap duration, and a stub that omits
  * either changes the geometry these assertions measure.
  */
 import { cleanup } from "@testing-library/react";