@unif/react-native-design 0.8.1 → 0.9.0

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,
+  };
+}

package/src/components/ui/StatusDot/StatusDot.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View } from 'react-native';
-import { useColors } from '../../../theme';
+import { r, useColors } from '../../../theme';
 import { Icon } from '../Icon';
 import { PulseDot } from '../Pulse';
 import { paletteFor, styles } from './styles';
@@ -10,14 +10,28 @@ import type { StatusDotProps } from './types';
  * 任务列表 / 推理链通用的状态圆点。
  * done = 绿底 + 白勾；active = 边框 + 内部 PulseDot；pending = 仅边框。
  */
+// status 派生默认 a11y label —— 不传时 SR 仍能播报状态语义。
+const DEFAULT_A11Y: Record<string, string> = {
+  pending: 'pending',
+  active: 'active',
+  done: 'done',
+};
+
 export function StatusDot({
   status,
-  size = 16,
+  size = r(16),
   tone = 'flat',
+  accessibilityLabel,
+  style,
   testID,
 }: StatusDotProps): React.JSX.Element {
   const c = useColors();
   const { bg, border } = paletteFor(status, tone, c);
+  // [L-14] 优先用 caller 传入值;空字符串表示由容器负责播报,不派生默认。
+  const a11yLabel =
+    accessibilityLabel !== undefined
+      ? accessibilityLabel || undefined
+      : DEFAULT_A11Y[status];
 
   return (
     <View
@@ -30,7 +44,10 @@ export function StatusDot({
           backgroundColor: bg,
           borderColor: border,
         },
+        style,
       ]}
+      accessible={!!a11yLabel}
+      accessibilityLabel={a11yLabel}
       testID={testID}
     >
       {status === 'done' ? (
@@ -41,7 +58,8 @@ export function StatusDot({
           strokeWidth={2.5}
         />
       ) : status === 'active' ? (
-        <PulseDot />
+        // [L-13] size 随外圈等比派生(系数 0.375 ≈ 6/16),视觉居中且不溢出。
+        <PulseDot size={Math.round(size * 0.375)} />
       ) : null}
     </View>
   );

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

@@ -16,7 +16,7 @@ export const styles = StyleSheet.create({
 });
 
 /** StatusDot 颜色推导:status × tone → { bg, border } 二色,全走 ColorTokens。
- *  签名 `(target, context, tokens)` 与 Tag/Tool 的 paletteFor 一致。
+ *  与 Tag/Button 的 paletteFor 同约定(状态入参 + ColorTokens → 配色对象),多一维 tone。
  *  `flat` = pending/active 底色透明；`soft` = pending 走 surface、active 走 primaryContainer。 */
 export function paletteFor(
   status: StatusDotStatus,

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

@@ -1,8 +1,10 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
 export type StatusDotStatus = 'pending' | 'active' | 'done';
 
 /**
  * `flat`：pending/active 底色透明（任务列表风格）。
- * `soft`：pending = bgCard、active = primary0，常用于推理链。
+ * `soft`：pending = surface、active = primaryContainer，常用于推理链。
  */
 export type StatusDotTone = 'flat' | 'soft';
 
@@ -10,6 +12,17 @@ export type StatusDotProps = {
   status: StatusDotStatus;
   size?: number;
   tone?: StatusDotTone;
+  /**
+   * [L-14] Screen Reader 朗读文本。
+   * 不传时按 status 派生默认值("pending" / "active" / "done")。
+   * 若状态语义已由父容器的 accessibilityLabel 覆盖,可传空字符串 "" 屏蔽默认值。
+   *
+   * 注:StatusDot 本身属于装饰性图标,状态语义通常由容器(列表行 / 任务项)负责播报;
+   * 对于需要独立播报的场景(独立状态指示器),请通过此 prop 传入有意义的描述。
+   */
+  accessibilityLabel?: string;
+  /** 容器附加样式(margin / position 等布局微调)。 */
+  style?: StyleProp<ViewStyle>;
   /** E2E / 测试定位 */
   testID?: string;
 };