@unif/react-native-design 0.8.2 → 0.10.0

package/src/components/ui/Pulse/usePulse.web.ts

@@ -1,57 +1,74 @@
 import { useEffect, useState } from 'react';
+import { usePrefersReducedMotion } from '../../../theme';
 import type { PulseOptions } from './types';
 
 /**
  * Web 端 usePulse —— RN-Web 上 reanimated 4 + worklets 0.9.x 的 useAnimatedStyle
  * 链路会抛 `Object.keys(undefined)` TypeError(animation frame 每帧打印),pulse 卡死
- * 在初始值。这里用 React state + setInterval + CSS 等价于在两个 opacity 之间循环,
- * 返回 RN style({ opacity }),保持 native API 兼容。
+ * 在初始值。
  *
  * native 端走 usePulse.ts(reanimated worklet) 不动。
  *
- * 注意:实现走 React state 而非 CSS transition——因为 RN style 不支持 transition,
- *  而 setInterval 切换 opacity 加上一个外层 div 的 CSS transition 视觉上等价
- *  (transition 由 ToastHost.web.tsx 那个模式接管,这里直接用 React 切值)。
+ * [M-19] 实现方案 —— CSS transition 降级(零 rAF JS 帧):
+ *   rnw 0.21 的 animationKeyframes 字段类型侧尚未稳定暴露;
+ *   且 <style> 注入在 Spinner.web.tsx 已有安全注释(不拼外部输入)——为保持
+ *   一致性,Pulse 侧不再注入第二处 <style> 标签,故采用 CSS transition 降级:
+ *
+ *   - 返回 { opacity, transition } 作为 RN style(RN-Web 把 transition 透传 DOM)
+ *   - setInterval 每隔 `duration` ms 在 from/to 两档切换 opacity ——
+ *     setState 频率从原来的 ~60fps 降到 1 次/duration ms(参 ToastHost.web.tsx)
+ *   - CSS transition 负责两档之间的视觉补间,JS 侧零插值
+ *   - reduce-motion:静止于 `to`(完全显示),骨架/圆点静态呈现
  */
 export function usePulse({
   from = 0.6,
   to = 1,
   duration = 700,
   delay = 0,
-}: PulseOptions = {}): { opacity: number } {
+}: PulseOptions = {}) {
+  const reduced = usePrefersReducedMotion();
   const [opacity, setOpacity] = useState(from);
 
   useEffect(() => {
-    let cancelled = false;
-    let direction: 'up' | 'down' = 'up';
-    let start = Date.now() + delay;
-    let raf: number | null = null;
-
-    const tick = () => {
-      if (cancelled) return;
-      const now = Date.now();
-      if (now < start) {
-        raf = requestAnimationFrame(tick);
-        return;
-      }
-      const elapsed = (now - start) % duration;
-      const t = elapsed / duration; // 0→1
-      const next =
-        direction === 'up' ? from + (to - from) * t : to - (to - from) * t;
-      setOpacity(next);
-      if (elapsed + 16 >= duration) {
-        direction = direction === 'up' ? 'down' : 'up';
-        start = now;
-      }
-      raf = requestAnimationFrame(tick);
+    // reduce-motion:不脉冲,直接停在完全显示(to),骨架/圆点静态呈现。
+    if (reduced) {
+      setOpacity(to);
+      return;
+    }
+
+    // CSS transition 模式:setInterval 只负责在 from/to 两档翻转(1 次/duration ms),
+    // 浏览器 CSS transition 负责补间 —— 与原方案 rAF 每帧 setState 相比
+    // setState 频率从 ~60fps 降到 1/(duration/1000) fps,无 JS 插值开销。
+    let timer: ReturnType<typeof setInterval> | null = null;
+    let current = from;
+
+    const start = () => {
+      timer = setInterval(() => {
+        current = current === from ? to : from;
+        setOpacity(current);
+      }, duration);
     };
-    raf = requestAnimationFrame(tick);
 
+    if (delay > 0) {
+      const delayTimer = setTimeout(start, delay);
+      return () => {
+        clearTimeout(delayTimer);
+        if (timer != null) clearInterval(timer);
+      };
+    }
+    start();
     return () => {
-      cancelled = true;
-      if (raf != null) cancelAnimationFrame(raf);
+      if (timer != null) clearInterval(timer);
     };
-  }, [from, to, duration, delay]);
+  }, [from, to, duration, delay, reduced]);
+
+  if (reduced) {
+    return { opacity: to } as any;
+  }
+
+  // RN-Web 把 transition 字段透传到 DOM style,实现 CSS 级平滑过渡。
+  // RN style typedef 无 transition 字段,cast any 绕过 TS strict
+  // (实际只在 web bundle 命中,DOM div 原样接受该字段)。
 
-  return { opacity };
+  return { opacity, transition: `opacity ${duration}ms ease-in-out` } as any;
 }

package/src/components/ui/Radio/Radio.tsx

@@ -1,8 +1,16 @@
 import React, { useContext } from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { useColors, useThemedStyles } from '../../../theme';
+import {
+  fixed,
+  pressedOpacity,
+  r,
+  space,
+  useColors,
+  useThemedStyles,
+} from '../../../theme';
 import { createLogger } from '../../../utils/logger';
+import { childTestID } from '../../../utils/testID';
 import { RadioContext } from './RadioContext';
 import { RadioGroup } from './RadioGroup';
 import { makeStyles } from './styles';
@@ -10,6 +18,9 @@ import type { RadioProps } from './types';
 
 const log = createLogger('Radio');
 
+// [L-30] 模块级 Set 去重 —— "must be inside Group" 只告警一次,避免 FlatList 滚动时刷屏
+const _warnedCtx = new Set<string>();
+
 /**
  * 单个 radio 选项。必须放在 `<Radio.Group>` 里使用。
  */
@@ -23,25 +34,37 @@ export function Radio({
   const styles = useThemedStyles(makeStyles);
   const ctx = useContext(RadioContext);
   if (!ctx) {
-    log.warn('<Radio> must be used inside <Radio.Group>');
+    // [L-30] 去重:同一 value 的 warn 只打一次,避免渲染阶段反复刷屏
+    const warnKey = `no-ctx:${String(value)}`;
+    if (!_warnedCtx.has(warnKey)) {
+      _warnedCtx.add(warnKey);
+      log.warn('<Radio> must be used inside <Radio.Group>');
+    }
     return <View />;
   }
   const checked = ctx.value === value;
-  const resolvedTestID =
-    testID ?? (ctx.groupTestID ? `${ctx.groupTestID}-${value}` : undefined);
+  // [L-92] 改用 childTestID:收口 parent+id 拼接逻辑,保持空串 override 回落拼接语义
+  const resolvedTestID = childTestID(ctx.groupTestID, value, testID);
+
+  // [M-7] row 含 paddingVertical space[2](上下各 ~6pt) → 行高 ≈ r(20) + 2×space[2] ≈ 32pt
+  // 补足到 fixed.hitTarget:slop = (44 - 32) / 2 = 6
+  const hitSlopV = Math.max(
+    0,
+    Math.round((fixed.hitTarget - (r(20) + 2 * space[2])) / 2)
+  );
 
   return (
     <Pressable
       onPress={() => !disabled && ctx.onChange(value)}
       disabled={disabled}
-      hitSlop={4}
+      hitSlop={hitSlopV}
       accessibilityRole="radio"
       accessibilityState={{ checked, disabled: !!disabled }}
       accessibilityLabel={label}
       testID={resolvedTestID}
       style={({ pressed }) => [
         styles.row,
-        { opacity: disabled ? 0.5 : pressed ? 0.7 : 1 },
+        { opacity: disabled ? 0.5 : pressed ? pressedOpacity : 1 },
       ]}
     >
       <View style={[styles.circle, checked && { borderColor: c.primary }]}>

package/src/components/ui/Radio/RadioGroup.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useMemo } from 'react';
 import { View } from 'react-native';
 import { useThemedStyles } from '../../../theme';
 import { RadioContext } from './RadioContext';
@@ -20,9 +20,16 @@ export function RadioGroup({
   testID,
 }: GroupProps): React.JSX.Element {
   const styles = useThemedStyles(makeStyles);
+  // [L-80b] useMemo 稳定 context value —— 避免每次渲染都产生新对象引用,
+  // 防止所有 Radio 子项因 context 变化而不必要 re-render。
+  const ctx = useMemo(
+    () => ({ value, onChange, groupTestID: testID }),
+    [value, onChange, testID]
+  );
   return (
-    <RadioContext.Provider value={{ value, onChange, groupTestID: testID }}>
-      <View style={styles.group} testID={testID}>
+    <RadioContext.Provider value={ctx}>
+      {/* [L-34] accessibilityRole="radiogroup" —— SR 宣读"单选按钮组" */}
+      <View style={styles.group} testID={testID} accessibilityRole="radiogroup">
         {children}
       </View>
     </RadioContext.Provider>

package/src/components/ui/Radio/styles.ts

@@ -6,17 +6,21 @@ export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
     group: {
       gap: space[1],
+      // [L-34] radiogroup 角色由 RadioGroup.tsx 容器 View 上设置
     },
     row: {
       flexDirection: 'row',
       alignItems: 'center',
+      // [L-37] alignSelf:'flex-start' 防止父容器拉伸(与 Chip [M-8] 同口径)
+      alignSelf: 'flex-start' as const,
       gap: space[4],
       paddingVertical: space[2],
     },
     circle: {
       width: r(20),
       height: r(20),
-      borderRadius: radius.lg,
+      // [L-79] radius.pill —— sentinel 999 确保任何尺寸下都是真圆
+      borderRadius: radius.pill,
       borderWidth: r(1.5),
       borderColor: c.outline,
       alignItems: 'center',
@@ -25,12 +29,15 @@ export const makeStyles = (c: ColorTokens) =>
     dot: {
       width: r(8),
       height: r(8),
-      borderRadius: radius.xs,
+      // [L-79] radius.pill —— 内圆点同理
+      borderRadius: radius.pill,
       backgroundColor: c.primary,
     },
     label: {
       fontSize: t.sm,
       color: c.foreground,
       fontWeight: fw.regular,
+      // flexShrink:长 label 在 row 内换行/截断,不溢出也不把同行控件挤没([M-10])
+      flexShrink: 1,
     },
   });

package/src/components/ui/Reveal/Reveal.web.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { View } from 'react-native';
-import { motion } from '../../../theme';
+import { motion, usePrefersReducedMotion } from '../../../theme';
 import type { RevealProps } from './types';
 
 /**
@@ -8,6 +8,15 @@ import type { RevealProps } from './types';
  * _updatePropsJS 里 Object.keys 抛 TypeError（layoutReanimation/web，渲染即每帧崩）,
  * 改用 React state + CSS transition 复刻入场淡入。退场在 web 省略（消费者卸载即移除）;
  * native 走 Reveal.tsx 的 reanimated 实现。
+ *
+ * **结构分叉说明（三层容器）**：
+ * - 外层 `<View style={style}>` —— 承接 RN StyleSheet 样式（flex/margin/padding 等），
+ *   与 native Reveal 保持相同的容器语义；
+ * - 中间 `<div style={animatedWebStyle}>` —— CSS opacity transition 动画层；
+ *   必须是真正的 DOM 元素才能触发 CSS transition（react-native-web 的 <View> 会先
+ *   inline 合并 style 再设 opacity，时序不稳定）；
+ * - 因此这里刻意不用 animationKeyframes（需要 @keyframes 注入 document），
+ *   而用 CSS transition + state 切换 opacity。
  */
 export function Reveal({
   children,
@@ -15,10 +24,16 @@ export function Reveal({
   duration = motion.base,
   testID,
 }: RevealProps): React.JSX.Element {
+  const reduced = usePrefersReducedMotion();
   const [visible, setVisible] = useState(false);
   const rafRef = useRef<number | null>(null);
 
   useEffect(() => {
+    // reduce-motion:跳过淡入,内容即时呈现(与 native FadeIn 在 ReduceMotion.System 下一致)。
+    if (reduced) {
+      setVisible(true);
+      return;
+    }
     let cancelled = false;
     // 双 RAF 过一帧 commit/paint，确保 CSS transition 有 opacity:0 起点（仿 ToastHost.web）。
     rafRef.current = requestAnimationFrame(() => {
@@ -31,11 +46,11 @@ export function Reveal({
       cancelled = true;
       if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
     };
-  }, []);
+  }, [reduced]);
 
   const animatedWebStyle: React.CSSProperties = {
     opacity: visible ? 1 : 0,
-    transition: `opacity ${duration}ms ease-out`,
+    transition: reduced ? undefined : `opacity ${duration}ms ease-out`,
   };
 
   return (

package/src/components/ui/Search/Search.tsx

@@ -1,7 +1,8 @@
 import React, { forwardRef } from 'react';
 import { Pressable } from 'react-native-gesture-handler';
 
-import { useColors } from '../../../theme';
+import { control, fixed, r, useColors } from '../../../theme';
+import { childTestID } from '../../../utils/testID';
 import { Icon } from '../Icon';
 import { Input } from '../Input';
 import type { TextInputRef } from '../TextField/TextFieldBase';
@@ -9,12 +10,12 @@ import type { SearchProps } from './types';
 
 /**
  * 搜索输入框 —— `<Input>` 的预设：前置搜索图标、清除按钮、
- * 高 36px、键盘 return 键为「搜索」。
+ * 高 control.md、键盘 return 键为「搜索」。
  *
  * Ref 透传到 Input 内部 TextInput，业务可调 `searchRef.current?.focus()`。
  */
 export const Search = forwardRef<TextInputRef, SearchProps>(function Search(
-  { onSubmit, placeholder = '搜索…', value, onChangeText, ...rest },
+  { onSubmit, placeholder = '搜索…', value, onChangeText, testID, ...rest },
   ref
 ): React.JSX.Element {
   const c = useColors();
@@ -26,22 +27,34 @@ export const Search = forwardRef<TextInputRef, SearchProps>(function Search(
       value={value}
       onChangeText={onChangeText}
       placeholder={placeholder}
-      height={36}
+      // [L-81] 高度裸 36 → control.md(r(36),随设备缩放)
+      height={control.md}
       returnKeyType="search"
       accessibilityRole="search"
-      onSubmitEditing={() => {
-        if (typeof value === 'string') onSubmit?.(value);
+      testID={testID}
+      onSubmitEditing={(e) => {
+        // [M-9] 改读 e.nativeEvent.text —— 不再依赖受控 value,非受控场景也能触发
+        const text = e.nativeEvent.text;
+        onSubmit?.(text);
       }}
-      leading={<Icon name="search" size={18} color={c.foregroundSubtle} />}
+      leading={<Icon name="search" size={r(18)} color={c.foregroundSubtle} />}
       trailing={
         filled ? (
           <Pressable
             onPress={() => onChangeText?.('')}
-            hitSlop={6}
+            // [M-7] 清除按钮 icon r(14)≈14pt;Input 高 control.md≈36pt 限制垂直扩展
+            // horizontal 走 (44-14)/2=15;vertical 走 (44-control.md)/2≈4
+            hitSlop={{
+              top: Math.round((fixed.hitTarget - control.md) / 2),
+              bottom: Math.round((fixed.hitTarget - control.md) / 2),
+              left: Math.round((fixed.hitTarget - r(14)) / 2),
+              right: Math.round((fixed.hitTarget - r(14)) / 2),
+            }}
             accessibilityRole="button"
             accessibilityLabel="清除"
+            testID={childTestID(testID, 'clear')}
           >
-            <Icon name="close" size={14} color={c.foregroundSubtle} />
+            <Icon name="close" size={r(14)} color={c.foregroundSubtle} />
           </Pressable>
         ) : null
       }

package/src/components/ui/Search/types.ts

@@ -1,8 +1,14 @@
 import type { TextInputProps } from 'react-native';
 
-export type SearchProps = Omit<TextInputProps, 'style'> & {
+// [L-36] Omit 扩 'multiline'/'numberOfLines' —— 搜索框固定单行,这两属性无意义
+export type SearchProps = Omit<
+  TextInputProps,
+  'style' | 'multiline' | 'numberOfLines'
+> & {
   /** 提交回调（按下 return 键时触发） */
   onSubmit?: (value: string) => void;
   /** 覆盖 placeholder（默认：搜索…） */
   placeholder?: string;
+  /** E2E / 测试定位 */
+  testID?: string;
 };

package/src/components/ui/Segmented/Segmented.tsx

@@ -16,6 +16,7 @@ export function Segmented({
   value,
   onChange,
   items,
+  disabled = false,
   testID,
 }: SegmentedProps): React.JSX.Element {
   const { colors: c, scheme, shadow } = useTheme();
@@ -24,16 +25,20 @@ export function Segmented({
   const activeShadow = scheme === 'dark' ? null : shadow.subtle;
 
   return (
-    <View style={styles.seg} testID={testID}>
+    // [L-34] accessibilityRole="tablist" —— SR 宣读"标签列表"
+    <View style={styles.seg} testID={testID} accessibilityRole="tablist">
       {items.map((it) => {
         const on = it.id === value;
         const itemTestID = childTestID(testID, it.id, it.testID);
+        // [L-82] item 禁用 = 整体 disabled OR 单项 it.disabled
+        const itemDisabled = disabled || !!it.disabled;
         return (
           <Pressable
             key={it.id}
-            onPress={() => onChange(it.id)}
+            onPress={() => !itemDisabled && onChange(it.id)}
+            disabled={itemDisabled}
             accessibilityRole="tab"
-            accessibilityState={{ selected: on }}
+            accessibilityState={{ selected: on, disabled: itemDisabled }}
             accessibilityLabel={it.label}
             testID={itemTestID}
             style={({ pressed }) => [

package/src/components/ui/Segmented/styles.ts

@@ -1,6 +1,6 @@
 import { StyleSheet } from 'react-native';
 import type { ColorTokens } from '../../../theme';
-import { control, r, radius, space, type as t } from '../../../theme';
+import { fixed, r, radius, space, type as t } from '../../../theme';
 
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
@@ -12,7 +12,9 @@ export const makeStyles = (c: ColorTokens) =>
       alignSelf: 'flex-start',
     },
     segItem: {
-      height: control.sm,
+      // [M-7] Segmented item 高原为 control.sm≈28pt < 44pt;
+      // hitSlop 不越父 seg 容器边界 → 改用 minHeight 直接对齐 fixed.hitTarget(44pt)
+      minHeight: fixed.hitTarget,
       paddingHorizontal: space[7],
       alignItems: 'center',
       justifyContent: 'center',

package/src/components/ui/Segmented/types.ts

@@ -5,6 +5,8 @@ export type SegmentedProps = {
   value: string;
   onChange: (id: string) => void;
   items: TabItem[];
+  /** [L-82] 整体禁用 —— 所有 item 不可点击,a11y state 同步 */
+  disabled?: boolean;
   /** 容器 testID；item testID 自动派生为 `${testID}-${id}` */
   testID?: string;
 };

package/src/components/ui/Skeleton/Skeleton.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import Animated from 'react-native-reanimated';
 import { usePulse } from '../Pulse';
-import { useColors } from '../../../theme';
+import { r, useColors } from '../../../theme';
 import type { SkeletonProps } from './types';
 
 /**
@@ -13,13 +13,14 @@ import type { SkeletonProps } from './types';
  * <Skeleton shape="circle" size={40} />        // 头像占位
  * ```
  *
- * `usePulse({ from: 0.5 })` 全局共享脉冲(Reanimated 4 worklet 驱动 opacity),
- * 区别于 chat `Shimmer`(沿 X 横扫高光,流式语义)。 */
+ * `usePulse({ from: 0.5 })` 每实例独立脉冲 —— native 端走 Reanimated 4 worklet,
+ * web 端走 CSS transition + setInterval(零 rAF JS 帧),opacity 在 0.5~1 循环。
+ * 区别于沿 X 横扫高光的流式 shimmer。 */
 export function Skeleton({
   shape = 'rect',
   width,
   height,
-  size = 40,
+  size = r(40),
   radius,
   style,
   testID,
@@ -35,14 +36,14 @@ export function Skeleton({
     if (shape === 'line') {
       return {
         width: width ?? '100%',
-        height: height ?? 11,
-        borderRadius: radius ?? 3,
+        height: height ?? r(11),
+        borderRadius: radius ?? r(3),
       };
     }
     return {
       width: width ?? '100%',
-      height: height ?? 80,
-      borderRadius: radius ?? 8,
+      height: height ?? r(80),
+      borderRadius: radius ?? r(8),
     };
   })();
 

package/src/components/ui/Spinner/Spinner.tsx

@@ -2,42 +2,42 @@ import { useEffect } from 'react';
 import Animated, {
   cancelAnimation,
   Easing,
+  ReduceMotion,
   useAnimatedStyle,
   useSharedValue,
   withRepeat,
   withTiming,
 } from 'react-native-reanimated';
-import { useColors } from '../../../theme';
-import { createLogger } from '../../../utils/logger';
+import { r, useColors } from '../../../theme';
+import { sanitizeSpinnerProps } from './shared';
 import type { SpinnerProps } from './types';
 
-const log = createLogger('Spinner');
-
 export function Spinner({
-  size = 18,
+  size = r(18),
   color,
-  thickness = 2,
+  thickness = r(2),
   style,
   testID,
 }: SpinnerProps) {
   const c = useColors();
   const angle = useSharedValue(0);
   const stroke = color ?? c.primary;
-  if (!Number.isFinite(size) || (size as number) < 8) {
-    log.warn(`size 应为 ≥8 的有限数，传入 ${size}，已钳到 8`);
-  }
-  if (Number.isFinite(thickness) && (thickness as number) <= 0) {
-    log.warn(`thickness 应为正数，传入 ${thickness}，已 fallback 为 2`);
-  }
-  const safeSize = Number.isFinite(size) && size > 8 ? size : 8;
-  const safeThickness =
-    Number.isFinite(thickness) && thickness > 0 ? thickness : 2;
+  const { safeSize, safeThickness } = sanitizeSpinnerProps(size, thickness);
 
   useEffect(() => {
+    // 加载指示属 essential motion(W3C):系统「减弱动态效果」下仍应旋转,否则会冻结成
+    // 与空闲/完成不可区分的静止圆环(形似卡死)。显式 ReduceMotion.Never 覆盖 reanimated
+    // 默认的 System —— 后者在 reduce-motion 下让 withTiming 跳端值、withRepeat 一轮即停。
     angle.value = withRepeat(
-      withTiming(360, { duration: 900, easing: Easing.linear }),
+      withTiming(360, {
+        duration: 900,
+        easing: Easing.linear,
+        reduceMotion: ReduceMotion.Never,
+      }),
       -1,
-      false
+      false,
+      undefined,
+      ReduceMotion.Never
     );
     return () => cancelAnimation(angle);
   }, [angle]);

package/src/components/ui/Spinner/Spinner.web.tsx

@@ -1,11 +1,9 @@
 import React, { useEffect, useRef } from 'react';
 import { View } from 'react-native';
-import { useColors } from '../../../theme';
-import { createLogger } from '../../../utils/logger';
+import { r, useColors } from '../../../theme';
+import { sanitizeSpinnerProps } from './shared';
 import type { SpinnerProps } from './types';
 
-const log = createLogger('Spinner');
-
 // React-Native-Web 上 reanimated 4 + worklets 0.9.x 的 useAnimatedStyle 链路在
 // web bundle 里跑会触发 `_updatePropsJS` 里 `Object.keys(updates)` 的 worklet
 // 回值打包 edge case(animation frame 每帧抛 TypeError),旋转停滞。
@@ -33,9 +31,9 @@ function ensureKeyframes() {
 }
 
 export function Spinner({
-  size = 18,
+  size = r(18),
   color,
-  thickness = 2,
+  thickness = r(2),
   style,
   testID,
 }: SpinnerProps): React.JSX.Element {
@@ -45,15 +43,7 @@ export function Spinner({
 
   const ref = useRef<any>(null);
   const stroke = color ?? c.primary;
-  if (!Number.isFinite(size) || (size as number) < 8) {
-    log.warn(`size 应为 ≥8 的有限数，传入 ${size}，已钳到 8`);
-  }
-  if (Number.isFinite(thickness) && (thickness as number) <= 0) {
-    log.warn(`thickness 应为正数，传入 ${thickness}，已 fallback 为 2`);
-  }
-  const safeSize = Number.isFinite(size) && size > 8 ? size : 8;
-  const safeThickness =
-    Number.isFinite(thickness) && thickness > 0 ? thickness : 2;
+  const { safeSize, safeThickness } = sanitizeSpinnerProps(size, thickness);
 
   // RN-Web 把 View 渲染成 div,我们用 ref 拿到底层 DOM 节点直接挂 CSS animation
   // (RN style 不支持 animation 字段;只能事后注入)。
@@ -61,6 +51,8 @@ export function Spinner({
     ensureKeyframes();
     const node = ref.current;
     if (node && node.style) {
+      // essential motion:加载指示在 prefers-reduced-motion 下仍应旋转(与 native 的
+      // ReduceMotion.Never 对齐),故意不加 @media (prefers-reduced-motion) 停转。
       node.style.animation = 'unif-spinner-spin 900ms linear infinite';
     }
   }, []);

package/src/components/ui/Spinner/shared.ts

@@ -0,0 +1,37 @@
+import { createLogger } from '../../../utils/logger';
+
+const log = createLogger('Spinner');
+
+/**
+ * [M-24][L-11] 入参防御逻辑抽到单一模块,native/web 两端 import 同一份:
+ *   - 去重 warn:同一异常值只告警一次(模块级 Set 记录),避免渲染路径每帧刷日志。
+ *   - size / thickness 两字段均覆盖非有限值告警(thickness 原缺失 isFinite 守卫)。
+ *   - 返回已钳制的安全值,调用方直接使用。
+ */
+
+const warnedKeys = new Set<string>();
+
+function warnOnce(key: string, msg: string) {
+  if (warnedKeys.has(key)) return;
+  warnedKeys.add(key);
+  log.warn(msg);
+}
+
+export function sanitizeSpinnerProps(
+  size: number,
+  thickness: number
+): { safeSize: number; safeThickness: number } {
+  if (!Number.isFinite(size) || size < 8) {
+    warnOnce(`size:${size}`, `size 应为 ≥8 的有限数，传入 ${size}，已钳到 8`);
+  }
+  if (!Number.isFinite(thickness) || thickness <= 0) {
+    warnOnce(
+      `thickness:${thickness}`,
+      `thickness 应为正有限数，传入 ${thickness}，已 fallback 为 2`
+    );
+  }
+  return {
+    safeSize: Number.isFinite(size) && size > 8 ? size : 8,
+    safeThickness: Number.isFinite(thickness) && thickness > 0 ? thickness : 2,
+  };
+}