@unif/react-native-design 0.8.1 → 0.9.0

package/src/components/ui/Stepper/Stepper.tsx

@@ -1,13 +1,17 @@
 import React from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { useThemedStyles } from '../../../theme';
+import { fixed, pressedOpacity, useThemedStyles } from '../../../theme';
 import { createLogger } from '../../../utils/logger';
+import { childTestID } from '../../../utils/testID';
 import { makeStyles, sizingFor } from './styles';
 import type { StepperProps } from './types';
 
 const log = createLogger('Stepper');
 
+// [L-30] 模块级 Set 去重 —— step/min/max 告警只打一次,避免渲染阶段刷屏
+const _warned = new Set<string>();
+
 /**
  * 数字步进器 [−][ N ][+]。
  * 按钮自动夹到 min/max；越界的按钮透明度变 0.4。
@@ -28,11 +32,21 @@ export function Stepper({
   const styles = useThemedStyles(makeStyles);
   const dims = sizingFor(size);
 
-  if (Number.isFinite(step) && step <= 0) {
-    log.warn(`step 必须是正数，传入 ${step}，已 fallback 为 1`);
+  // [L-30] step 口径对齐:非有限数(NaN/Infinity)也告警,与 min>max 告警保持一致
+  // 模块级 Set 去重:每个异常组合只打一次告警,避免渲染阶段重复刷屏
+  if (!Number.isFinite(step) || step <= 0) {
+    const k = `step:${step}`;
+    if (!_warned.has(k)) {
+      _warned.add(k);
+      log.warn(`step 必须是有限正数，传入 ${step}，已 fallback 为 1`);
+    }
   }
   if (Number.isFinite(min) && Number.isFinite(max) && min > max) {
-    log.warn(`min(${min}) 不能大于 max(${max})，已按 min 渲染`);
+    const k = `minmax:${min}:${max}`;
+    if (!_warned.has(k)) {
+      _warned.add(k);
+      log.warn(`min(${min}) 不能大于 max(${max})，已按 min 渲染`);
+    }
   }
   const safeStep = Number.isFinite(step) && step > 0 ? step : 1;
   const safeMin = Number.isFinite(min) ? min : 0;
@@ -44,8 +58,15 @@ export function Stepper({
   const decDisabled = disabled || safeValue <= safeMin;
   const incDisabled = disabled || safeValue >= safeMax;
 
+  // [M-7] 按钮高 sm=28 / md=32 均低于 fixed.hitTarget=44;hitSlop 不越父边界,
+  // 须让容器一并扩展:wrap 加垂直 padding 把命中区撑到 44pt。
+  const wrapPaddingV = Math.max(0, Math.round((fixed.hitTarget - dims.h) / 2));
+
   return (
-    <View style={styles.wrap} testID={testID}>
+    <View
+      style={[styles.wrap, { paddingVertical: wrapPaddingV }]}
+      testID={testID}
+    >
       <Pressable
         onPress={() => onChange(Math.max(safeMin, safeValue - safeStep))}
         disabled={decDisabled}
@@ -53,21 +74,35 @@ export function Stepper({
         accessibilityLabel="减少"
         accessibilityState={{ disabled: decDisabled }}
         accessibilityHint={`当前值 ${safeValue}，减 ${safeStep}`}
-        testID={testID ? `${testID}-decrement` : undefined}
+        testID={childTestID(testID, 'decrement')}
         style={({ pressed }) => [
           styles.cell,
           styles.btnLeft,
           { width: dims.btn, height: dims.h },
-          { opacity: decDisabled ? 0.4 : pressed ? 0.7 : 1 },
+          { opacity: decDisabled ? 0.4 : pressed ? pressedOpacity : 1 },
         ]}
       >
         <Text style={styles.btnText}>−</Text>
       </Pressable>
+      {/* [L-29] adjustable 需配 accessible + accessibilityActions + onAccessibilityAction,
+          否则 iOS VoiceOver 宣读"可调节"但滑动手势无响应。*/}
       <View
+        accessible
         accessibilityRole="adjustable"
         accessibilityValue={{ min: safeMin, max: safeMax, now: safeValue }}
+        accessibilityActions={[
+          { name: 'increment', label: '增加' },
+          { name: 'decrement', label: '减少' },
+        ]}
+        onAccessibilityAction={(e) => {
+          if (e.nativeEvent.actionName === 'increment' && !incDisabled) {
+            onChange(Math.min(safeMax, safeValue + safeStep));
+          } else if (e.nativeEvent.actionName === 'decrement' && !decDisabled) {
+            onChange(Math.max(safeMin, safeValue - safeStep));
+          }
+        }}
         style={[styles.cell, { minWidth: dims.w, height: dims.h }]}
-        testID={testID ? `${testID}-value` : undefined}
+        testID={childTestID(testID, 'value')}
       >
         <Text style={[styles.valueText, { fontSize: dims.fs }]}>
           {safeValue}
@@ -80,12 +115,12 @@ export function Stepper({
         accessibilityLabel="增加"
         accessibilityState={{ disabled: incDisabled }}
         accessibilityHint={`当前值 ${safeValue}，加 ${safeStep}`}
-        testID={testID ? `${testID}-increment` : undefined}
+        testID={childTestID(testID, 'increment')}
         style={({ pressed }) => [
           styles.cell,
           styles.btnRight,
           { width: dims.btn, height: dims.h },
-          { opacity: incDisabled ? 0.4 : pressed ? 0.7 : 1 },
+          { opacity: incDisabled ? 0.4 : pressed ? pressedOpacity : 1 },
         ]}
       >
         <Text style={styles.btnText}>+</Text>

package/src/components/ui/Switch/Switch.tsx

@@ -9,17 +9,10 @@ import Animated, {
   useSharedValue,
   withTiming,
 } from 'react-native-reanimated';
-import { motion, r, useColors, useThemedStyles } from '../../../theme';
-import { INSET, makeStyles, THUMB, TRACK_W } from './styles';
+import { fixed, motion, r, useColors, useThemedStyles } from '../../../theme';
+import { makeStyles, THUMB_OFF_X, THUMB_ON_X, TRACK_H } from './styles';
 import type { SwitchProps } from './types';
 
-// ─── 动画派生常量(组件私有,非 style)─────────────────────────────────────
-// 把手 translateX 的 off / on 端点:左右各留 INSET 间距,
-// off = INSET(2),on = trackW - INSET - thumbW(32-2-16=14)。
-// 走 r() 保证多设备缩放跟 track / thumb 物理尺寸一致(否则非设计基准设备会错位)。
-const THUMB_OFF_X = r(INSET);
-const THUMB_ON_X = r(TRACK_W - INSET - THUMB);
-
 /**
  * 布尔切换。32×20 轨道 + 16×16 白色把手,200ms 缓动。
  *
@@ -66,7 +59,8 @@ export function Switch({
     <Pressable
       onPress={() => !disabled && onChange(!value)}
       disabled={disabled}
-      hitSlop={6}
+      // [M-7] 轨道高 r(20)≈20pt;补 (44-20)/2=12 到 fixed.hitTarget
+      hitSlop={Math.round((fixed.hitTarget - r(TRACK_H)) / 2)}
       style={disabled ? styles.pressableDisabled : styles.pressableEnabled}
       accessibilityRole="switch"
       accessibilityState={{ checked: value, disabled: !!disabled }}

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

@@ -1,16 +1,10 @@
 import React from 'react';
 import { Pressable } from 'react-native-gesture-handler';
 import { View } from 'react-native';
-import { motion, r, useColors, useThemedStyles } from '../../../theme';
-import { INSET, makeStyles, THUMB, TRACK_W } from './styles';
+import { motion, useColors, useThemedStyles } from '../../../theme';
+import { makeStyles, THUMB_OFF_X, THUMB_ON_X } from './styles';
 import type { SwitchProps } from './types';
 
-// ─── 动画派生常量(组件私有,非 style)─────────────────────────────────────
-// 把手 translateX 的 off / on 端点:左右各留 INSET 间距,
-// off = INSET(2),on = trackW - INSET - thumbW(32-2-16=14)。
-const THUMB_OFF_X = r(INSET);
-const THUMB_ON_X = r(TRACK_W - INSET - THUMB);
-
 /**
  * Web 端 Switch —— RN-Web 上 reanimated 4 + worklets 0.9.x 的 useAnimatedStyle
  * 链路会抛 `Object.keys(undefined)` TypeError(切换时打印,thumb 卡住),走 CSS

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

@@ -9,13 +9,21 @@ export const TRACK_H = 20;
 export const THUMB = 16;
 export const INSET = 2;
 
+/** [M-25] 把手 translateX 端点 —— 与 styles 同源导出,Switch.tsx / Switch.web.tsx 两端 import。
+ *  off = INSET(2),on = TRACK_W - INSET - THUMB(32-2-16=14)。走 r() 保证多设备缩放一致。 */
+export const THUMB_OFF_X = r(INSET);
+export const THUMB_ON_X = r(TRACK_W - INSET - THUMB);
+
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
     pressableEnabled: {
       opacity: 1,
+      // [L-37] alignSelf:'flex-start' 防止父容器拉伸把手区域(与 Chip [M-8] 同口径)
+      alignSelf: 'flex-start' as const,
     },
     pressableDisabled: {
       opacity: 0.5,
+      alignSelf: 'flex-start' as const,
     },
     track: {
       width: r(TRACK_W),
@@ -26,7 +34,8 @@ export const makeStyles = (c: ColorTokens) =>
     thumb: {
       width: r(THUMB),
       height: r(THUMB),
-      borderRadius: radius.md,
+      // [L-79] radius.pill —— sentinel 999 确保把手始终是真圆
+      borderRadius: radius.pill,
       backgroundColor: c.onPrimary,
     },
   });

package/src/components/ui/TabBar/TabBar.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { icon, useColors, useThemedStyles } from '../../../theme';
+import { pressedOpacity, r, useColors, useThemedStyles } from '../../../theme';
 import { childTestID } from '../../../utils/testID';
 import { Icon } from '../Icon';
 import { makeStyles } from './styles';
@@ -9,38 +9,46 @@ import type { TabBarProps } from './types';
 
 /**
  * 固定底部 tab bar —— App 主导航。
- * 高 50px，顶部一条细线边框。激活色：primary-300。
+ * 高 50px，顶部一条细线边框。激活色：primary。
  * 想留 home indicator 的安全区，请外面包一层 `<SafeAreaView edges={['bottom']}>`。
  */
 export function TabBar({
   active,
   onChange,
   items,
+  style,
   testID,
 }: TabBarProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
   return (
-    <View style={styles.bar} testID={testID}>
+    <View
+      style={[styles.bar, style]}
+      testID={testID}
+      accessibilityRole="tablist"
+    >
       {items.map((item) => {
         const on = item.id === active;
         const tint = on ? c.primary : c.foregroundSubtle;
         const itemTestID = childTestID(testID, item.id, item.testID);
+        // a11y label 包含角标数量,SR 用户知晓待处理条目数(如"消息,3条未读")
+        const a11yLabel =
+          item.badge != null ? `${item.label},${item.badge}条未读` : item.label;
         return (
           <Pressable
             key={item.id}
             onPress={() => onChange(item.id)}
             accessibilityRole="tab"
             accessibilityState={{ selected: on }}
-            accessibilityLabel={item.label}
+            accessibilityLabel={a11yLabel}
             testID={itemTestID}
             style={({ pressed }) => [
               styles.tab,
-              { opacity: pressed ? 0.7 : 1 },
+              { opacity: pressed ? pressedOpacity : 1 },
             ]}
           >
             <View>
-              <Icon name={item.icon} size={icon.sm} color={tint} />
+              <Icon name={item.icon} size={r(22)} color={tint} />
               {item.badge != null ? (
                 <View style={styles.badge}>
                   <Text style={styles.badgeText}>{item.badge}</Text>

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

@@ -1,9 +1,12 @@
 import { StyleSheet } from 'react-native';
 import type { ColorTokens } from '../../../theme';
-import { fixed, fw, r, radius, space, type as t } from '../../../theme';
+import { fixed, fw, r, type as t } from '../../../theme';
+import { badgeStyles } from '../shared/badgeStyles';
 
-export const makeStyles = (c: ColorTokens) =>
-  StyleSheet.create({
+export const makeStyles = (c: ColorTokens) => {
+  // TabBar 图标 22pt,角标上边缘偏移 r(-3):使圆心落在图标右上角
+  const badge = badgeStyles(c, r(-3));
+  return StyleSheet.create({
     bar: {
       height: fixed.tabbarH,
       flexDirection: 'row',
@@ -22,22 +25,7 @@ export const makeStyles = (c: ColorTokens) =>
       fontWeight: fw.medium,
       lineHeight: 12,
     },
-    badge: {
-      position: 'absolute',
-      top: r(-3),
-      right: r(-10),
-      minWidth: r(16),
-      height: r(16),
-      borderRadius: radius.md,
-      backgroundColor: c.error,
-      paddingHorizontal: space[1],
-      alignItems: 'center',
-      justifyContent: 'center',
-    },
-    badgeText: {
-      color: c.onError,
-      fontSize: t.nano,
-      fontWeight: fw.bold,
-      lineHeight: 12,
-    },
+    badge: badge.badge,
+    badgeText: badge.badgeText,
   });
+};

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

@@ -1,3 +1,4 @@
+import type { StyleProp, ViewStyle } from 'react-native';
 import type { IconName } from '../Icon';
 
 export type TabBarItem = {
@@ -14,6 +15,8 @@ export type TabBarProps = {
   active: string;
   onChange: (id: string) => void;
   items: TabBarItem[];
+  /** 容器附加样式(margin / position 等布局微调)。 */
+  style?: StyleProp<ViewStyle>;
   /** 容器 testID；item testID 自动派生为 `${testID}-${id}` */
   testID?: string;
 };

package/src/components/ui/Tabs/Tabs.tsx

@@ -1,11 +1,14 @@
 import React from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { useColors, useThemedStyles, fw } from '../../../theme';
+import { fw, pressedOpacity, useColors, useThemedStyles } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
 import { childTestID } from '../../../utils/testID';
 import { makeStyles } from './styles';
 import type { TabsProps } from './types';
 
+const log = createLogger('Tabs');
+
 /**
  * 页面级下划线 tabs。
  * 占满宽度，高 44px，激活项下方有 2px 主色下划线。
@@ -14,26 +17,42 @@ export function Tabs({
   value,
   onChange,
   items,
+  disabled: allDisabled = false,
+  style,
   testID,
 }: TabsProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
+  // items 长度守卫 —— types 注释承诺「≥2 项才有意义」,此处对违规使用方 dev warn。
+  // 不 return null:渲染空 tablist 比渲染单 tab 更符合 a11y 预期,且不破坏 hook 调用顺序。
+  if (items.length < 2) {
+    log.warn(`Tabs 至少需要 2 项，当前传入 ${items.length} 项`);
+  }
   return (
-    <View style={styles.under} testID={testID}>
+    <View
+      style={[styles.under, style]}
+      testID={testID}
+      accessibilityRole="tablist"
+    >
       {items.map((it) => {
         const on = it.id === value;
+        const itemDisabled = allDisabled || (it.disabled ?? false);
         const itemTestID = childTestID(testID, it.id, it.testID);
         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 || undefined,
+            }}
             accessibilityLabel={it.label}
             testID={itemTestID}
             style={({ pressed }) => [
               styles.underTab,
-              { opacity: pressed ? 0.7 : 1 },
+              { opacity: itemDisabled ? 0.4 : pressed ? pressedOpacity : 1 },
             ]}
           >
             <Text

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

@@ -1,6 +1,10 @@
 import { StyleSheet } from 'react-native';
 import type { ColorTokens } from '../../../theme';
-import { fixed, icon, r, type as t } from '../../../theme';
+import { fixed, r, type as t } from '../../../theme';
+
+// 下划线宽度固定 36pt —— 视觉上比 tab 文字稍宽、比整个 tab 格窄,
+// 刻意不用 icon.xl(语义是图标盒),此处是装饰性下划线,用具名常量自文档化。
+const UNDER_BAR_WIDTH = r(36);
 
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
@@ -23,7 +27,7 @@ export const makeStyles = (c: ColorTokens) =>
       position: 'absolute',
       bottom: 0,
       height: r(2),
-      width: icon.xl,
+      width: UNDER_BAR_WIDTH,
       backgroundColor: c.primary,
       borderRadius: r(1),
     },

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

@@ -1,8 +1,12 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
 export type TabItem = {
   /** 唯一 id，用作 key 跟选中标识 */
   id: string;
   /** 显示文本 */
   label: string;
+  /** 禁用该 tab —— disabled=true 时不可点击 + SR 报 disabled 状态 */
+  disabled?: boolean;
   /** 单 item testID（不传则自动用 `${tabsTestID}-${id}`） */
   testID?: string;
 };
@@ -12,8 +16,13 @@ export type TabsProps = {
   value: string;
   /** 切换 tab 回调 */
   onChange: (id: string) => void;
-  /** tab 列表（≥2 项才显示） */
+  /** tab 列表（≥2 项才显示）
+   *  @note 传入 < 2 项时组件仍渲染,但通常无意义;调用方应保证传入 ≥2 项。 */
   items: TabItem[];
+  /** 整体禁用 —— 所有 tab 不可点击(如异步加载数据期间) */
+  disabled?: boolean;
+  /** 容器附加样式(margin / position 等布局微调)。 */
+  style?: StyleProp<ViewStyle>;
   /** 容器 testID；item testID 自动派生为 `${testID}-${id}` */
   testID?: string;
 };

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

@@ -1,5 +1,12 @@
 import { StyleSheet } from 'react-native';
-import { fw, radius, type ColorTokens } from '../../../theme';
+import {
+  fw,
+  r,
+  radius,
+  space,
+  type as t,
+  type ColorTokens,
+} from '../../../theme';
 import type { TagSize, TagVariant } from './types';
 
 /** Tag 静态 base —— alignSelf 防 flex 父容器拉伸,radius 走 token。 */
@@ -24,16 +31,23 @@ export function sizingFor(size: TagSize): {
 } {
   switch (size) {
     case 'md':
-      return { h: 22, px: 8, fs: 12 };
+      return { h: r(22), px: space['3'], fs: t.xxs };
     case 'lg':
-      return { h: 26, px: 10, fs: 13 };
+      return { h: r(26), px: space['4'], fs: t.xs };
   }
 }
 
 /** Tag 颜色推导:variant → { bg, fg, border } 三色,全走 ColorTokens。
- *  签名 `(target, context)` 与 chat/Tool 的 tintFor / variantFor / labelFor 一致。 */
+ *  签名 `(variant, c)` 与 Button/Avatar 的 paletteFor 一致。
+ *  新增 variant 在 types.ts 加 union + 这里加 case。 */
 export function paletteFor(variant: TagVariant, c: ColorTokens) {
   switch (variant) {
+    case 'neutral':
+      return {
+        bg: c.surfaceContainerHigh,
+        fg: c.foregroundMuted,
+        border: undefined,
+      };
     case 'brand':
       return { bg: c.primaryContainer, fg: c.primary, border: undefined };
     case 'success':
@@ -48,11 +62,5 @@ export function paletteFor(variant: TagVariant, c: ColorTokens) {
         fg: c.foregroundMuted,
         border: c.outline,
       };
-    default:
-      return {
-        bg: c.surfaceContainerHigh,
-        fg: c.foregroundMuted,
-        border: undefined,
-      };
   }
 }

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

@@ -14,7 +14,7 @@ export type TagVariant =
   | 'info'
   | 'outline';
 
-/** Tag 尺寸：md=22 (h) / lg=26 (h) */
+/** Tag 尺寸：md=22 (h) / lg=26 (h)，均随设备宽度缩放 */
 export type TagSize = 'md' | 'lg';
 
 export type TagProps = {
@@ -26,7 +26,11 @@ export type TagProps = {
   size?: TagSize;
   /** 额外样式覆盖 */
   style?: StyleProp<ViewStyle>;
-  /** 文本 numberOfLines，默认 1（超长 ellipsis） */
+  /**
+   * 文本截断行数，默认 1（超长 ellipsis）。
+   * **警告：Tag 高度钉死（md=22 / lg=26），传 >1 时多余行溢出或被裁，
+   * 仅在同时自定义高度的场景才有意义。**
+   */
   numberOfLines?: number;
   /** E2E / 测试定位 */
   testID?: string;

package/src/components/ui/TextField/TextFieldBase.tsx

@@ -1,6 +1,7 @@
 import React, { type ComponentRef, forwardRef, useState } from 'react';
 import { Text, TextInput, View } from 'react-native';
-import { control, space, useColors, useThemedStyles } from '../../../theme';
+import { control, r, space, useColors, useThemedStyles } from '../../../theme';
+import { childTestID } from '../../../utils/testID';
 import { makeStyles } from './styles';
 import type { TextFieldBaseProps } from './types';
 
@@ -26,7 +27,8 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
     {
       multiline = false,
       height = control.lg,
-      minHeight = 96,
+      // [L-81] multiline minHeight 裸 96 → r(96),随设备缩放
+      minHeight = r(96),
       maxHeight,
       leading,
       trailing,
@@ -37,6 +39,7 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
       value,
       onFocus,
       onBlur,
+      onChangeText,
       testID,
       ...rest
     },
@@ -45,8 +48,15 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
     const c = useColors();
     const styles = useThemedStyles(makeStyles);
     const [focused, setFocused] = useState(false);
-    const filled = value != null && String(value).length > 0;
+    // [M-9] 内部镜像 state:非受控场景 value 不传,用 _mirror 做 hasValue 判断
+    const [_mirror, setMirror] = useState('');
+    // [M-9] filled 在受控 value 和内部镜像 state 之间取 hasValue,
+    // 保证非受控场景 filled 视觉态能正确响应用户输入,且受控用法行为不变
+    const filled =
+      value != null ? String(value).length > 0 : _mirror.length > 0;
     const isEditable = disabled ? false : editable;
+    // [L-31] editable=false(非 disabled)时也应进入 disabled a11y state
+    const isDisabledA11y = disabled || editable === false;
 
     // 视觉态优先级:error > focused > filled > idle。
     // active 三态(focus/filled/error)共享 wrapActive 白底,各自只覆 borderColor 差量。
@@ -79,6 +89,11 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
             {...rest}
             editable={isEditable}
             value={value}
+            onChangeText={(text) => {
+              // [M-9] 同步内部镜像,非受控场景 filled 视觉态依赖此 state
+              setMirror(text);
+              onChangeText?.(text);
+            }}
             multiline={multiline}
             onFocus={(e) => {
               setFocused(true);
@@ -97,12 +112,22 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
               },
             ]}
             placeholderTextColor={c.foregroundSubtle}
-            accessibilityState={disabled ? { disabled: true } : undefined}
-            testID={testID ? `${testID}-input` : undefined}
+            // [L-31] editable=false 并入 disabled a11y state,SR 能正确播报不可编辑
+            accessibilityState={isDisabledA11y ? { disabled: true } : undefined}
+            testID={childTestID(testID, 'input')}
           />
           {trailing != null ? <View>{trailing}</View> : null}
         </View>
-        {error ? <Text style={styles.errorMsg}>{error}</Text> : null}
+        {/* [L-31] error Text 补 accessibilityLiveRegion="polite" —— 错误出现时 SR 自动播报 */}
+        {error ? (
+          <Text
+            style={styles.errorMsg}
+            accessibilityLiveRegion="polite"
+            testID={childTestID(testID, 'error')}
+          >
+            {error}
+          </Text>
+        ) : null}
       </View>
     );
   }

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

@@ -15,7 +15,8 @@ export type TextareaProps = Omit<
   leading?: ReactNode;
   /** 可选的后置插槽（如字符计数器） */
   trailing?: ReactNode;
-  /** 错误信息 —— 容器进入错误态并在下方显示 */
+  /** 错误信息 —— 容器进入错误态并在下方显示。
+   *  空串 `""` / undefined 都不进 error 态(truthy 判定),与 TextFieldBase 保持一致。[L-96] */
   error?: string;
   /** 最小高度，默认 96（约 5 行） */
   minHeight?: number;

package/src/components/ui/Thumbnail/Thumbnail.tsx

@@ -1,9 +1,12 @@
 import React from 'react';
 import { Image, View } from 'react-native';
 import { useThemedStyles } from '../../../theme';
-import { makeStyles, sizingFor } from './styles';
+import { createLogger } from '../../../utils/logger';
+import { makeStyles, RING_EXTRA_RADIUS, sizingFor } from './styles';
 import type { ThumbnailProps } from './types';
 
+const log = createLogger('Thumbnail');
+
 /** 缩略图基础组件 —— 列表 / 卡片 / chat 行内通用 16:9.5 小图。
  *
  *  尺寸阶梯:sm / md(默认 113×67)/ lg,与 NewsList / NewsArea 历史一致。
@@ -26,7 +29,12 @@ export function Thumbnail({
   testID,
 }: ThumbnailProps): React.JSX.Element | null {
   const styles = useThemedStyles(makeStyles);
-  if (!uri && !source) return null;
+  if (!uri && !source) {
+    // [L-18] uri/source 均未传:一次性告警,返回 null 而非空白区域。
+    // types 注释已说明二选一语义;此 warn 用于开发期快速定位漏传。
+    log.warn('Thumbnail: uri 和 source 均未提供,组件将渲染为 null');
+    return null;
+  }
   const dim = sizingFor(size);
   const image = (
     <Image
@@ -42,7 +50,10 @@ export function Thumbnail({
   // ring 容器:borderRadius 比 image 大 (border + padding) 才能贴合包裹外圈
   return (
     <View
-      style={[styles.ring, { borderRadius: dim.borderRadius + 3 }]}
+      style={[
+        styles.ring,
+        { borderRadius: dim.borderRadius + RING_EXTRA_RADIUS },
+      ]}
       testID={testID}
     >
       {image}

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

@@ -2,6 +2,10 @@ import { StyleSheet } from 'react-native';
 import { r, type ColorTokens } from '../../../theme';
 import type { ThumbnailSize } from './types';
 
+/** [L-94] ring 圆角外展量:border(2) + padding(1) = 3pt,让外圈圆角贴合内圆角。
+ *  Thumbnail.tsx 侧用此常量替代魔数 `+ 3`。 */
+export const RING_EXTRA_RADIUS = r(2) + r(1); // border + padding
+
 /** Thumbnail 静态样式 ——
  *  - `base`:Image 占位色,加载中 / 失败时不至于空白
  *  - `ring`:`selected` 态的外圈品牌色描边,padding 抵消 ring 与 image 之间留 1pt gap */
@@ -11,9 +15,9 @@ export const makeStyles = (c: ColorTokens) =>
       backgroundColor: c.surfaceContainer,
     },
     ring: {
-      borderWidth: 2,
+      borderWidth: r(2),
       borderColor: c.primary,
-      padding: 1,
+      padding: r(1),
     },
   });