@unif/react-native-design 0.8.1 → 0.9.0

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

@@ -1,5 +1,5 @@
 import { StyleSheet } from 'react-native';
-import { avatar, fw, type ColorTokens } from '../../../theme';
+import { avatar, fw, rf, type ColorTokens } from '../../../theme';
 import type { AvatarSize, AvatarVariant } from './types';
 
 /** Avatar 静态 base —— 圆形容器(borderRadius / 尺寸由 sizingFor 派生)。 */
@@ -24,19 +24,19 @@ export const styles = StyleSheet.create({
 export function sizingFor(size: AvatarSize): { box: number; fs: number } {
   switch (size) {
     case 'xs':
-      return { box: avatar.xs, fs: 10 };
+      return { box: avatar.xs, fs: rf(10) };
     case 'sm':
-      return { box: avatar.sm, fs: 12 };
+      return { box: avatar.sm, fs: rf(12) };
     case 'md':
-      return { box: avatar.md, fs: 13 };
+      return { box: avatar.md, fs: rf(13) };
     case 'lg':
-      return { box: avatar.lg, fs: 15 };
+      return { box: avatar.lg, fs: rf(15) };
     case 'xl':
-      return { box: avatar.xl, fs: 20 };
+      return { box: avatar.xl, fs: rf(20) };
   }
 }
 
-/** Avatar 配色推导:4 种 variant → { bg, fg }。签名与 Tag/Tool 的 paletteFor 一致。 */
+/** Avatar 配色推导:4 种 variant → { bg, fg }。签名与 Tag/Button 的 paletteFor 一致。 */
 export function paletteFor(
   variant: AvatarVariant,
   c: ColorTokens

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

@@ -1,4 +1,4 @@
-import type { ImageSourcePropType } from 'react-native';
+import type { ImageSourcePropType, StyleProp, ViewStyle } from 'react-native';
 
 /** 头像尺寸（对应 avatar.xs..xl）：xs=18 / sm=28 / md=32 / lg=40 / xl=56 */
 export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
@@ -27,6 +27,8 @@ export type AvatarProps = {
    * 提供时优先渲染 image；onError 触发后自动 fallback 到 label。
    */
   source?: ImageSourcePropType;
+  /** 容器附加样式(margin / position 等布局微调)。 */
+  style?: StyleProp<ViewStyle>;
   /** E2E / 测试定位 */
   testID?: string;
 };

package/src/components/ui/BlurLayer/BlurLayer.tsx

@@ -9,7 +9,7 @@ import type { BlurLayerProps } from './types';
  *  blurType 跟 scheme 自动切(亮 'light' / 暗 'dark',避免暗色奶白雾)。
  *
  *  - `'soft'` 玻璃数据条 / 小区域
- *  - `'strong'` 焦点引导 backdrop(BottomSheet blur 模式) */
+ *  - `'strong'` 焦点引导 backdrop(sheet 类浮层) */
 export function BlurLayer({
   intensity,
   tint,
@@ -32,6 +32,9 @@ export function BlurLayer({
         style={StyleSheet.absoluteFill}
         blurType={blurType}
         blurAmount={blurTokens[intensity]}
+        // iOS「降低透明度」开启时 BlurView 用纯色替换模糊;库默认 #FFFFFF 在暗色 scheme
+        // 下整面刺眼白底。传随 scheme 的 surface 色,与下方 tint 层视觉一致([M-6])。
+        reducedTransparencyFallbackColor={c.surface}
       />
       <View
         style={[

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

@@ -22,7 +22,13 @@ export function BlurLayer({
   const blurAmount = blurTokens[intensity];
   const defaultTint =
     intensity === 'strong' ? c.sheetBackdrop : c.glassTintLight;
-  // RN style typedef 不识别 web-only 属性,cast 绕过 TS;RN-Web 浏览器侧原样输出
+  // RN style typedef 不识别 web-only 属性,cast 绕过 TS;RN-Web 浏览器侧原样输出。
+  // [L-15] saturate(180%):苹果 HIG 玻璃效果的标准值,增强模糊后的颜色鲜艳度,
+  //   与 macOS / iOS 系统 vibrancy 视觉一致;降低会让玻璃面板显得灰暗脱色。
+  // [L-15] opacity:0.96(暗色):暗色 scheme 下 backdrop-filter 在 Chromium 中
+  //   opacity=1 时存在渲染 artifact(模糊层与底层内容边界锯齿),降到 0.96 消除;
+  //   亮色 scheme 不受影响故保持 1。native 端 BlurLayer.tsx 用双层 View 实现,
+  //   语义等价(tint 层覆盖 BlurView),无需此 opacity 补丁。
   const webBlurStyle = {
     backdropFilter: `blur(${blurAmount}px) saturate(180%)`,
     WebkitBackdropFilter: `blur(${blurAmount}px) saturate(180%)`,

package/src/components/ui/Button/Button.tsx

@@ -7,7 +7,7 @@ import { makeStyles } from './styles';
 import type { ButtonProps } from './types';
 
 /**
- * 6 variant × 3 size 文本按钮。
+ * 7 variant × 3 size 文本按钮。
  * 内部组合 ButtonBase + content(label + 可选 leftIcon / rightIcon),
  * ButtonBase 接管 chrome(sizing / palette / disabled / loading / a11y)。
  *
@@ -48,6 +48,7 @@ export function Button({
           ) : null}
           <Text
             style={[styles.label, { color: palette.fg, fontSize: sizing.fs }]}
+            numberOfLines={1}
           >
             {label}
           </Text>

package/src/components/ui/Button/ButtonBase.tsx

@@ -6,7 +6,12 @@ import {
   type ViewStyle,
 } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { useColors, useThemedStyles } from '../../../theme';
+import {
+  fixed,
+  pressedOpacity,
+  useColors,
+  useThemedStyles,
+} from '../../../theme';
 import { makeStyles, paletteFor, sizingFor } from './styles';
 import type {
   ButtonBaseRenderContext,
@@ -61,6 +66,24 @@ export function ButtonBase({
   const isText = variant === 'text';
   const isInteractive = !disabled && !loading;
 
+  // [M-7] 触控目标补偿:hitSlop 向外扩展命中区域到 fixed.hitTarget(44pt)。
+  // 公式:vertical slop = max(0, (hitTarget - h) / 2);square 时同补 horizontal。
+  // text variant height=undefined(仅行内文字高 ~18pt),无法从 sizing.h 推算,
+  // 保守固定补到 44pt 等效(top+bottom ≈ 13pt each)。
+  // ⚠ hitSlop 不越父边界;相邻可按压元素建议间距 ≥ 2×slop 以防重叠裁决。
+  const hitSlop = useMemo(() => {
+    if (isText) {
+      // text 无 chrome,仅靠行高无法可靠获取实际高度,固定补至 44pt
+      const v = Math.round((fixed.hitTarget - 18) / 2);
+      return { top: v, bottom: v, left: 0, right: 0 };
+    }
+    const v = Math.max(0, Math.round((fixed.hitTarget - sizing.h) / 2));
+    if (square) {
+      return { top: v, bottom: v, left: v, right: v };
+    }
+    return { top: v, bottom: v, left: 0, right: 0 };
+  }, [isText, sizing.h, square]);
+
   return (
     <Pressable
       accessibilityRole={accessibilityRole}
@@ -69,6 +92,7 @@ export function ButtonBase({
       accessibilityHint={accessibilityHint}
       disabled={!isInteractive}
       onPress={onPress}
+      hitSlop={hitSlop}
       testID={testID}
       style={({ pressed }) => [
         styles.base,
@@ -82,7 +106,7 @@ export function ButtonBase({
           backgroundColor: palette.bg,
           borderColor: palette.border ?? 'transparent',
           borderWidth: palette.border ? 1 : 0,
-          opacity: disabled ? 0.5 : pressed ? 0.7 : 1,
+          opacity: disabled ? 0.5 : pressed ? pressedOpacity : 1,
           alignSelf: block ? 'stretch' : 'flex-start',
           // 非 block 用 undefined 而非硬编码 0:Yoga 的 resolveFlexGrow 里显式 flexGrow
           // 优先级高于 flex 简写,写死 0 会让调用方 style={{ flex: 1 }} 失效(按钮撑不开 /

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

@@ -33,35 +33,37 @@ export const makeStyles = (_c: ColorTokens) =>
  *  h 走 control.<size>,br 走 radius.<size>,gap / px 走 space[].
  *  新增 size 在 types.ts 加 union + 这里加 case。 */
 export function sizingFor(size: ButtonSize): ButtonSizing {
-  if (size === 'lg') {
-    return {
-      h: control.lg,
-      px: r(18),
-      fs: t.body,
-      br: radius.lg,
-      gap: space['2'],
-    };
-  }
-  if (size === 'sm') {
-    return {
-      h: control.sm,
-      px: space['4'],
-      fs: t.xxs,
-      br: radius.sm,
-      gap: space['1'],
-    };
+  switch (size) {
+    case 'lg':
+      return {
+        h: control.lg,
+        px: r(18),
+        fs: t.body,
+        br: radius.lg,
+        gap: space['2'],
+      };
+    case 'sm':
+      return {
+        h: control.sm,
+        px: space['4'],
+        fs: t.xxs,
+        br: radius.sm,
+        gap: space['1'],
+      };
+    case 'md':
+      return {
+        h: control.md,
+        px: space['6'],
+        fs: t.sm,
+        br: radius.md,
+        gap: space['2'],
+      };
   }
-  return {
-    h: control.md,
-    px: space['6'],
-    fs: t.sm,
-    br: radius.md,
-    gap: space['2'],
-  };
 }
 
 /** Button 配色推导:7 种 variant → { bg, fg, border }。签名与 Tag/Avatar 的 paletteFor 一致。
- *  text / ghost / neutral 共用 'transparent' 底,差异在 fg。 */
+ *  text / ghost / neutral 共用 'transparent' 底;ghost↔text palette 字节级同一,
+ *  差异在几何:text variant 在 ButtonBase 撕除高度与内边距。 */
 export function paletteFor(
   variant: ButtonVariant,
   c: ColorTokens

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

@@ -25,7 +25,7 @@ export type ButtonVariant =
   | 'text';
 
 export type ButtonProps = {
-  /** 按钮文案；icon-only 场景请用其他组件（Pressable + Icon） */
+  /** 按钮文案；icon-only 场景请用 IconButton */
   label: string;
   /** 点击回调；disabled / loading 时不触发 */
   onPress?: () => void;

package/src/components/ui/Card/Card.tsx

@@ -17,23 +17,33 @@ export function Card({
 }: CardProps): React.JSX.Element {
   const styles = useThemedStyles(makeStyles);
   const shadow = useShadow();
+  const br = borderRadius ?? radius.xl;
 
+  // 双层:外层持底色 + 阴影 + 圆角(无 overflow,阴影不被裁);内层持 overflow hidden
+  // 按圆角裁内容 + padding + 可选边框。[H-4] iOS 上 overflow 与阴影同层会裁掉阴影。
   return (
     <View
       testID={testID}
       style={[
         styles.base,
-        { borderRadius: borderRadius ?? radius.xl },
-        !bare && { padding: padding ?? space[6] },
+        { borderRadius: br },
         variantToStyle(variant, shadow, styles),
-        borderColor != null && {
-          borderColor,
-          borderWidth: borderWidth ?? 2,
-        },
         style,
       ]}
     >
-      {children}
+      <View
+        style={[
+          styles.clip,
+          { borderRadius: br },
+          !bare && { padding: padding ?? space[6] },
+          borderColor != null && {
+            borderColor,
+            borderWidth: borderWidth ?? 2,
+          },
+        ]}
+      >
+        {children}
+      </View>
     </View>
   );
 }

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

@@ -4,8 +4,13 @@ import type { CardVariant } from './types';
 
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
+    // 外层:底色 + 阴影(iOS 阴影需不透明背景才投影)。overflow hidden 不放这层 ——
+    // 否则 iOS 会把 View 自己的卡片阴影一起裁掉([H-4])。
     base: {
       backgroundColor: c.surface,
+    },
+    // 内层:overflow hidden 按圆角裁剪内容(如贴边媒体),不影响外层阴影。
+    clip: {
       overflow: 'hidden',
     },
     flat: {},

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

@@ -3,7 +3,7 @@ import type { StyleProp, ViewStyle } from 'react-native';
 
 /**
  * Card **视觉变体**（控制装饰，跟 `bare` 是正交维度）：
- * - `default`：白底 + 阴影 + 边框（标准卡片）
+ * - `default`：白底 + 阴影（标准卡片;默认无边框,传 `borderColor` 才显示边框）
  * - `plain`：仅白底（无阴影无边框，承载更轻量，如 chat 气泡内嵌组件）
  * - `flat`：**deprecated** — 等价于 `plain`，新代码请用 `plain`。
  */
@@ -16,11 +16,11 @@ export type CardProps = {
   variant?: CardVariant;
   /** 自定义内边距（覆盖默认 padding） */
   padding?: number;
-  /** 自定义圆角（覆盖默认 radius.md） */
+  /** 自定义圆角（覆盖默认 radius.xl） */
   borderRadius?: number;
-  /** 自定义边框色（覆盖默认 c.outline；仅 default/flat 有边框） */
+  /** 边框色 —— 传入即显示边框（任何 variant 生效;默认无边框） */
   borderColor?: string;
-  /** 自定义边框宽度（覆盖默认 1；仅 default/flat 有边框） */
+  /** 边框宽度（默认 2;仅在传了 borderColor 时生效） */
   borderWidth?: number;
   /**
    * 「裸壳」模式：把 padding 设为 0，children 紧贴 Card 边缘渲染。

package/src/components/ui/Carousel/Carousel.tsx

@@ -6,7 +6,7 @@ import ReanimatedCarousel, {
 import { useSharedValue } from 'react-native-reanimated';
 import { space, useThemedStyles } from '../../../theme';
 import { makeCarouselStyles } from './styles';
-import type { CarouselProps } from './types';
+import type { CarouselProps, ICarouselInstance } from './types';
 
 /** Carousel —— 包装 `react-native-reanimated-carousel@5.0.0-beta.5`。
  *
@@ -16,21 +16,28 @@ import type { CarouselProps } from './types';
  *  用 Pagination.Custom 而非 Basic:Basic 的 activeDot 用 translateX 推进
  *  内层 fill,外壳宽度等于 dotStyle.width,activeDotStyle.width 只影响内层,
  *  做不出"active 4 → 12 长条"。Custom 自己 interpolate width/height/bg。
+ *
+ *  forwardRef 透传 ICarouselInstance —— 解锁 a11y 暂停(ref.current.scrollTo)
+ *  以及宿主页面的命令式 scrollTo / prev / next。
  */
 // T 约束 object —— `Pagination.Basic<T extends {}>` 需要 object
-export function Carousel<T extends object>({
-  items,
-  renderItem,
-  height,
-  itemWidth,
-  autoPlay,
-  showIndicator = true,
-  indicatorPosition = 'bottom',
-  onPressItem,
-  getAccessibilityLabel,
-  style,
-  testID,
-}: CarouselProps<T>): React.JSX.Element {
+function CarouselInner<T extends object>(
+  {
+    items,
+    renderItem,
+    height,
+    itemWidth,
+    autoPlay,
+    loop = true,
+    showIndicator = true,
+    indicatorPosition = 'bottom',
+    onPressItem,
+    getAccessibilityLabel,
+    style,
+    testID,
+  }: CarouselProps<T>,
+  ref: React.Ref<ICarouselInstance>
+): React.JSX.Element {
   const { width: screenWidth } = useWindowDimensions();
   const width = itemWidth ?? screenWidth;
   const styles = useThemedStyles(makeCarouselStyles);
@@ -54,14 +61,24 @@ export function Carousel<T extends object>({
         // v5 把 width / height prop deprecate,迁到 style
         style={{ width, height }}
         data={data}
-        loop
+        loop={loop}
         autoPlay={!!autoPlay}
         autoPlayInterval={autoPlay}
         onProgressChange={progress}
+        ref={ref}
         renderItem={({ item, index }) => (
+          // RN Pressable 而非 RNGH Pressable:Carousel 的 GestureDetector 已挂在
+          // ReanimatedCarousel 内部,外层再套 RNGH Pressable 会产生手势冲突;
+          // 用 RN 原生 Pressable 让库自己的拖拽手势优先,tap 仍正常触发。
           <Pressable
             onPress={() => onPressItem?.(item, index)}
             style={{ width, height }}
+            // [L-92] 恒产出兜底:testID 缺失时用 'carousel' 前缀而非 undefined。
+            // 与 childTestID「父缺失返 undefined」语义不同,不替换为 childTestID。
+            // 原因:renderItem 须向 ReanimatedCarousel 提供稳定可预期的子项 testID
+            // 用于 E2E 定位,哪怕调用方未传 testID 也能用 carousel-item-0 等定位;
+            // 副作用:同屏两个未传 testID 的 Carousel 会碰撞 carousel-item-N。
+            // 建议:多 Carousel 场景请务必传 testID 以避免碰撞。
             testID={`${testID ?? 'carousel'}-item-${index}`}
             // 只在真正可点时声明 button 语义,纯展示型不标 button 避免读屏器误导
             {...(onPressItem
@@ -78,6 +95,9 @@ export function Carousel<T extends object>({
         )}
       />
       {showIndicator && items.length > 1 ? (
+        // importantForAccessibility="no" —— dots 仅视觉辅助,SR 不需要读出
+        // 每个 dot 的状态(已由 accessibilityRole=tab / accessibilityState.selected 表达
+        // 的场景另论,这里 Pagination.Custom 无内置 a11y 语义,对 SR 隐藏比误读更优)。
         <Pagination.Custom<T>
           progress={progress}
           data={data}
@@ -88,8 +108,17 @@ export function Carousel<T extends object>({
               ? styles.dotsWrapOverlay
               : styles.dotsWrapBottom
           }
+          // @ts-expect-error — importantForAccessibility 是 RN View prop,
+          // Pagination.Custom containerStyle 走 ViewStyle 但 TS 类型未收录该 prop
+          importantForAccessibility="no-hide-descendants"
+          accessibilityElementsHidden={true}
         />
       ) : null}
     </View>
   );
 }
+
+// forwardRef 不支持泛型函数组件直接推断 T,需要手动标注 + 类型断言
+export const Carousel = React.forwardRef(CarouselInner) as <T extends object>(
+  props: CarouselProps<T> & { ref?: React.Ref<ICarouselInstance> }
+) => React.JSX.Element;

package/src/components/ui/Carousel/index.ts

@@ -1,2 +1,2 @@
 export { Carousel } from './Carousel';
-export type { CarouselProps } from './types';
+export type { CarouselProps, ICarouselInstance } from './types';

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

@@ -1,6 +1,9 @@
+import type { ICarouselInstance } from 'react-native-reanimated-carousel';
 import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 
+export type { ICarouselInstance };
+
 /** Indicator 位置策略:
  *  - 'bottom'(默认):指示器独立行,跟 Carousel 下方;容器高度 = height + 16
  *  - 'overlay-bottom-right':指示器 absolute 浮在 Carousel 右下角,不占额外高度 */
@@ -19,6 +22,8 @@ export type CarouselProps<T> = {
   itemWidth?: number;
   /** autoPlay 间隔 ms,undefined / 0 不自动 */
   autoPlay?: number;
+  /** 是否循环播放,默认 true。传 false 时首尾不循环,可配合 a11y 暂停控制。 */
+  loop?: boolean;
   /** 是否显示底部 dot indicator,默认 true */
   showIndicator?: boolean;
   /** indicator 位置策略,默认 'bottom' */

package/src/components/ui/Cell/Cell.tsx

@@ -1,13 +1,22 @@
 import React from 'react';
 import { type StyleProp, Text, type TextStyle, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { useColors, useThemedStyles } from '../../../theme';
+import { pressedOpacity, r, useColors, useThemedStyles } from '../../../theme';
 import { Icon } from '../Icon';
 import { useListVariant } from './context';
 import { Leading } from './Leading';
 import { makeStyles } from './styles';
 import type { CellProps } from './types';
 
+/** extra 是否包含可交互控件(Switch/Stepper/Checkbox 等 ReactNode)。
+ *  用于决定 Pressable 外壳是否关闭 accessible —— 若外壳 accessible=true 且 extra 也是
+ *  独立 accessible 控件,SR 会产生「双播报 + 控件被遮挡无法直接激活」的体验缺陷。
+ *  规则:extra 是 ReactNode(非 string / null / undefined)时判定为「可能含控件」。
+ *  使用方若明确 extra 是纯展示 ReactNode,可通过 accessibilityHint='none' 绕过(暂不加 prop)。*/
+function extraHasInteractiveNode(extra: CellProps['extra']): boolean {
+  return extra != null && typeof extra !== 'string';
+}
+
 function renderSlot(
   value: React.ReactNode,
   textStyle: StyleProp<TextStyle>,
@@ -77,7 +86,7 @@ export function Cell({
       {arrow && !danger ? (
         <Icon
           name="chevron-right"
-          size={flush ? 18 : 20}
+          size={r(flush ? 18 : 20)}
           color={c.foregroundSubtle}
           style={flush ? styles.chevronFlush : undefined}
         />
@@ -86,19 +95,32 @@ export function Cell({
   );
 
   if (onPress) {
+    // 若 extra 含交互控件(Switch/Stepper 等),外壳 Pressable 关闭 accessible,
+    // 让 SR 直接穿透读取控件本身,避免双播报和控件被遮挡无法激活的体验缺陷。
+    const hasInteractiveExtra = extraHasInteractiveNode(extra);
+
+    // 默认 a11y label:title + desc 拼接,给 SR 用户同时听到主副信息。
+    // 有 accessibilityLabel 显式覆盖时走 prop,否则组合 title+desc。
+    const defaultLabel =
+      typeof title === 'string'
+        ? typeof desc === 'string' && desc
+          ? `${title},${desc}`
+          : title
+        : undefined;
+
     return (
       <Pressable
         onPress={onPress}
         disabled={disabled}
         accessibilityRole="button"
-        accessibilityLabel={
-          accessibilityLabel ?? (typeof title === 'string' ? title : undefined)
-        }
+        accessibilityLabel={accessibilityLabel ?? defaultLabel}
         accessibilityHint={accessibilityHint}
         accessibilityState={disabled ? { disabled: true } : undefined}
+        // extra 含控件时外壳不作为独立 a11y 元素,让 SR 穿透到 extra 控件
+        accessible={hasInteractiveExtra ? false : undefined}
         testID={testID}
         style={({ pressed }) => [
-          { opacity: disabled ? 0.5 : pressed ? 0.7 : 1 },
+          { opacity: disabled ? 0.5 : pressed ? pressedOpacity : 1 },
         ]}
       >
         {inner}

package/src/components/ui/Cell/Leading.tsx

@@ -41,7 +41,7 @@ export function Leading({
         >
           <Icon
             name={slot as IconName}
-            size={16}
+            size={r(16)}
             color={danger ? c.error : c.primary}
           />
         </View>
@@ -50,7 +50,7 @@ export function Leading({
     return (
       <Icon
         name={slot as IconName}
-        size={22}
+        size={r(22)}
         color={danger ? c.error : c.foregroundMuted}
       />
     );

package/src/components/ui/Cell/List.tsx

@@ -24,14 +24,20 @@ export function List({
     return (
       <ListVariantContext.Provider value="flush">
         <View style={[styles.listFlush, style]} testID={testID}>
-          {items.map((child, i) => (
-            <React.Fragment key={i}>
-              {i > 0 && divider === 'full' ? (
-                <View style={styles.separator} />
-              ) : null}
-              {child}
-            </React.Fragment>
-          ))}
+          {items.map((child, i) => {
+            // 优先使用 caller 传入的 key(React.Children.toArray 已将 key 注入 child)，
+            // 回退到索引确保 reconciler 稳定 —— 避免 caller key 丢失导致不必要重挂载。
+            const key =
+              React.isValidElement(child) && child.key != null ? child.key : i;
+            return (
+              <React.Fragment key={key}>
+                {i > 0 && divider === 'full' ? (
+                  <View style={styles.separator} />
+                ) : null}
+                {child}
+              </React.Fragment>
+            );
+          })}
         </View>
       </ListVariantContext.Provider>
     );

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

@@ -1,7 +1,9 @@
 import { StyleSheet } from 'react-native';
 import {
+  fixed,
   fw,
   r,
+  rf,
   radius,
   space,
   type as t,
@@ -26,7 +28,8 @@ export const makeStyles = (c: ColorTokens) =>
       gap: space[4],
       paddingHorizontal: r(11),
       paddingVertical: r(11),
-      minHeight: 0,
+      // [M-7] flush 可按压行高约 39pt < iOS HIG 44pt;用 minHeight 撑到 fixed.hitTarget
+      minHeight: fixed.hitTarget,
     },
     cellFlushWithDesc: {
       paddingVertical: r(9),
@@ -43,10 +46,10 @@ export const makeStyles = (c: ColorTokens) =>
       lineHeight: t.body * 1.3,
     },
     titleFlush: {
-      fontSize: r(13),
+      fontSize: rf(13),
       fontWeight: fw.medium,
       letterSpacing: -0.1,
-      lineHeight: r(13) * 1.3,
+      lineHeight: rf(13) * 1.3,
       color: c.foreground,
     },
     desc: {
@@ -55,7 +58,7 @@ export const makeStyles = (c: ColorTokens) =>
       lineHeight: t.xs * 1.4,
     },
     descFlush: {
-      fontSize: r(11),
+      fontSize: rf(11),
       color: c.foregroundMuted,
       opacity: 0.55,
       marginTop: r(1),
@@ -65,7 +68,7 @@ export const makeStyles = (c: ColorTokens) =>
       color: c.foregroundSubtle,
     },
     extraFlush: {
-      fontSize: r(11),
+      fontSize: rf(11),
       color: c.foregroundMuted,
       opacity: 0.55,
     },

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

@@ -9,7 +9,10 @@ export type CellProps = {
   titleLines?: number;
   /** 副标题；string 自动 numberOfLines=2，传 ReactNode 完全自定义 */
   desc?: ReactNode;
-  /** 右侧 slot —— 字符串自动套 Text；传 ReactNode 放 Switch / Stepper / Tag 等控件 */
+  /** 右侧 slot —— 字符串自动套 Text；传 ReactNode 放 Switch / Stepper / Tag 等控件。
+   *  **a11y 边界**：extra 为 ReactNode 时，外壳 Pressable 会关闭 `accessible`，
+   *  让 SR 直接穿透到 extra 控件（避免双播报）；extra 的 a11y 由其自身负责。
+   *  若 extra 是纯展示 ReactNode 且仍需外壳播报，请改用 string 或传 `accessibilityLabel`。 */
   extra?: ReactNode;
   /** 显示右侧 chevron-right 图标，常配合 onPress 表示「可进入下一级」 */
   arrow?: boolean;
@@ -31,7 +34,7 @@ export type CellProps = {
   /** 显式 SR 朗读文案,覆盖 Cell 默认从 string title 推断的 fallback。
    *  title 是 ReactNode(自定义渲染)时尤其需要,否则 SR 用户听不到任何内容。 */
   accessibilityLabel?: string;
-  /** SR 朗读 hint —— 说明 tap 后行为(参 CLAUDE.md a11y 章节,短 ≤8 字)。
+  /** SR 朗读 hint —— 说明 tap 后行为(短 ≤8 字)。
    *  常用:"查看详情" / "打开应用" 等;onPress 缺省时此 prop 无意义。 */
   accessibilityHint?: string;
 };