@unif/react-native-design 0.1.0

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

@@ -0,0 +1,32 @@
+import type { ImageSourcePropType } from 'react-native';
+
+/** 头像尺寸（对应 avatar.xs..xl）：xs=18 / sm=28 / md=32 / lg=40 / xl=56 */
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * 头像配色变体（仅在显示 letter / fallback 时生效，showImage 时被覆盖）：
+ * - `brand` 品牌橙底（AI 头像专用）
+ * - `info` 蓝底（用户头像专用）
+ * - `soft` 浅橙底（次要场景）
+ * - `neutral` 中性灰底（默认）
+ */
+export type AvatarVariant = 'brand' | 'info' | 'soft' | 'neutral';
+
+export type AvatarProps = {
+  /**
+   * 头像里显示的文字（建议 1-2 字符）。
+   * 同时作为 a11y label（screen reader 朗读）；source 加载失败时回退展示。
+   */
+  label: string;
+  /** 尺寸，默认 'md' */
+  size?: AvatarSize;
+  /** 配色变体，默认 'neutral' */
+  variant?: AvatarVariant;
+  /**
+   * 真实头像图片（URL `{ uri: '...' }` 或 `require(...)`）。
+   * 提供时优先渲染 image；onError 触发后自动 fallback 到 label。
+   */
+  source?: ImageSourcePropType;
+  /** E2E / 测试定位 */
+  testID?: string;
+};

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

@@ -0,0 +1,44 @@
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+import { BlurView } from '@sbaiahmed1/react-native-blur';
+import { blur as blurTokens, useColors, useTheme } from '../../../theme';
+import type { BlurLayerProps } from './types';
+
+/** Blur backdrop 双层 —— BlurView + tint。
+ *
+ *  blurType 跟 scheme 自动切(亮 'light' / 暗 'dark',避免暗色奶白雾)。
+ *
+ *  - `'soft'` 玻璃数据条 / 小区域
+ *  - `'strong'` 焦点引导 backdrop(BottomSheet blur 模式) */
+export function BlurLayer({
+  intensity,
+  tint,
+  style,
+  testID,
+}: BlurLayerProps): React.JSX.Element {
+  const c = useColors();
+  const { scheme } = useTheme();
+  const blurType = scheme === 'dark' ? 'dark' : 'light';
+  const defaultTint =
+    intensity === 'strong' ? c.sheetBackdrop : c.glassTintLight;
+
+  return (
+    <View
+      style={[StyleSheet.absoluteFill, style]}
+      pointerEvents="none"
+      testID={testID}
+    >
+      <BlurView
+        style={StyleSheet.absoluteFill}
+        blurType={blurType}
+        blurAmount={blurTokens[intensity]}
+      />
+      <View
+        style={[
+          StyleSheet.absoluteFill,
+          { backgroundColor: tint ?? defaultTint },
+        ]}
+      />
+    </View>
+  );
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Web 端 BlurLayer —— CSS `backdrop-filter` 代替 native BlurView。
+ *
+ * `@sbaiahmed1/react-native-blur` 不支持 web(库内部 codegenNativeComponent
+ * 在浏览器会炸 "is not a function",见上游 issue #79)。docusaurus-rnw plugin
+ * 配 `extensions: ['.web.tsx', ...]` 优先,webpack 选这份;Metro 不识别该后缀,
+ * iOS / Android 走原 `BlurLayer.tsx`。
+ */
+import React from 'react';
+import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+import { blur as blurTokens, useColors, useTheme } from '../../../theme';
+import type { BlurLayerProps } from './types';
+
+export function BlurLayer({
+  intensity,
+  tint,
+  style,
+  testID,
+}: BlurLayerProps): React.JSX.Element {
+  const c = useColors();
+  const { scheme } = useTheme();
+  const blurAmount = blurTokens[intensity];
+  const defaultTint =
+    intensity === 'strong' ? c.sheetBackdrop : c.glassTintLight;
+  // RN style typedef 不识别 web-only 属性,cast 绕过 TS;RN-Web 浏览器侧原样输出
+  const webBlurStyle = {
+    backdropFilter: `blur(${blurAmount}px) saturate(180%)`,
+    WebkitBackdropFilter: `blur(${blurAmount}px) saturate(180%)`,
+    backgroundColor: tint ?? defaultTint,
+    opacity: scheme === 'dark' ? 0.96 : 1,
+  } as unknown as StyleProp<ViewStyle>;
+
+  return (
+    <View
+      style={[StyleSheet.absoluteFill, webBlurStyle, style]}
+      pointerEvents="none"
+      testID={testID}
+    />
+  );
+}

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

@@ -0,0 +1,2 @@
+export { BlurLayer } from './BlurLayer';
+export type { BlurLayerProps } from './types';

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

@@ -0,0 +1,15 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { BlurIntensity } from '../../../theme';
+
+export type BlurLayerProps = {
+  /** 模糊强度,对齐设计稿 token:
+   *  - 'soft' = blurAmount 10,玻璃数据条 / 小区域玻璃感
+   *  - 'strong' = blurAmount 40,焦点引导 backdrop */
+  intensity: BlurIntensity;
+  /** Tint override(不传按 intensity 推:soft → c.glassTintLight / strong → c.sheetBackdrop) */
+  tint?: string;
+  /** 附加样式;默认 absoluteFill,caller 通常不需要传 */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
+};

package/src/components/ui/BottomSheet/BottomSheet.tsx

@@ -0,0 +1,117 @@
+import React, { useCallback, useMemo } from 'react';
+import { View } from 'react-native';
+import GorhomBottomSheet, {
+  BottomSheetBackdrop,
+  BottomSheetScrollView,
+  type BottomSheetBackdropProps,
+} from '@gorhom/bottom-sheet';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { useThemedStyles } from '../../../theme';
+import { BlurLayer } from '../BlurLayer';
+import { makeStyles } from './styles';
+import type { BottomSheetProps } from './types';
+
+/** 底部 sheet —— @gorhom/bottom-sheet 的薄壳层。
+ *
+ *  适合 navigation `presentation: 'transparentModal'` 屏内 root 用法:mount 时
+ *  默认 animateOnMount=true 从 -1 动画到 index=0,goBack() 自然关闭。
+ *  state-driven sheet 应用 @gorhom 原生 `<BottomSheetModal>`,本 wrapper 不覆盖。
+ *
+ *  - `snapPoints` 必传(`['50%']` / `['50%', '90%']` 等)
+ *  - `backdrop` 三档:`'scrim'` / `'blur'`(BlurLayer)/ `'none'` */
+// 默认 30% / 60% / 95%,模块顶层 const 引用稳定。
+const DEFAULT_SNAP_POINTS: (string | number)[] = ['30%', '60%', '95%'];
+
+export function BottomSheet({
+  snapPoints = DEFAULT_SNAP_POINTS,
+  children,
+  sheetStyle,
+  backdrop = 'scrim',
+  grabber = true,
+  onClose,
+  testID,
+}: BottomSheetProps): React.JSX.Element {
+  const styles = useThemedStyles(makeStyles);
+
+  /** BlurView backdrop —— 复用 @gorhom BottomSheetBackdrop 的手势 + animatedIndex
+   *  插值,opacity=1 + bg=transparent 让 backdrop 本身不画 scrim,只画 BlurLayer。
+   *  tap-to-close + opacity 淡入 / pointer-events disable 全部继承自 @gorhom 内核。
+   *
+   *  useCallback + styles dep 保引用稳定(主题切换时才重建),避免每次渲染新引用让
+   *  @gorhom 内部 memo 失效 / remount backdrop 树。 */
+  const BlurBackdrop = useCallback(
+    (props: BottomSheetBackdropProps) => (
+      <BottomSheetBackdrop
+        {...props}
+        appearsOnIndex={0}
+        disappearsOnIndex={-1}
+        opacity={1}
+        style={[props.style, styles.backdropTransparent]}
+      >
+        <BlurLayer intensity="strong" />
+      </BottomSheetBackdrop>
+    ),
+    [styles.backdropTransparent]
+  );
+
+  /** Scrim backdrop —— 走 c.scrim token(亮 rgba(0,0,0,0.5) / 暗 0.7),opacity=1
+   *  让 @gorhom 只跑透明度淡入动画,scrim 实色由 token 决定 → 暗色自动加深。 */
+  const ScrimBackdrop = useCallback(
+    (props: BottomSheetBackdropProps) => (
+      <BottomSheetBackdrop
+        {...props}
+        appearsOnIndex={0}
+        disappearsOnIndex={-1}
+        opacity={1}
+        style={[props.style, styles.scrimBackdrop]}
+      />
+    ),
+    [styles.scrimBackdrop]
+  );
+
+  const renderBackdrop = useMemo(() => {
+    switch (backdrop) {
+      case 'none':
+        return undefined;
+      case 'blur':
+        return BlurBackdrop;
+      case 'scrim':
+        return ScrimBackdrop;
+    }
+  }, [backdrop, BlurBackdrop, ScrimBackdrop]);
+
+  // @gorhom onChange:index === -1 即关闭。配合 transparentModal route 必传
+  // caller 的 onClose → navigation.goBack(),否则路由 stack 不 pop,native overlay 继续吞触摸。
+  const onChange = (index: number) => {
+    if (index === -1) onClose?.();
+  };
+
+  return (
+    <GestureHandlerRootView style={styles.root}>
+      <GorhomBottomSheet
+        snapPoints={snapPoints}
+        index={0}
+        backdropComponent={renderBackdrop}
+        handleComponent={grabber ? undefined : null}
+        backgroundStyle={styles.sheet}
+        onChange={onChange}
+        // enableDynamicSizing=false 关键 —— @gorhom v5 默认 true 会让 sheet 跟内容
+        // 自动撑高忽略 snapPoints max,设 false 强制按 snapPoints 锁高度(gorhom#1783 / #918)
+        enableDynamicSizing={false}
+        enableOverDrag={false}
+        // @gorhom 默认 false:user 下拉到底部 snap 后不会关闭 sheet,只是 bounce
+        // (BottomSheetScrollView 在 scrollOffset=0 时下拉看着像下拉刷新效果)。
+        // 设 true 后超过最低 snap 阈值直接 dismiss → 走 onChange(-1) → onClose。
+        enablePanDownToClose
+      >
+        <BottomSheetScrollView
+          testID={testID}
+          showsVerticalScrollIndicator={false}
+        >
+          {/* sheetStyle 给内层 View,ScrollView 只负责 scroll,不接管 padding / gap / maxHeight。 */}
+          <View style={sheetStyle}>{children}</View>
+        </BottomSheetScrollView>
+      </GorhomBottomSheet>
+    </GestureHandlerRootView>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { BottomSheet } from './BottomSheet';
+export type { BottomSheetProps } from './types';

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

@@ -0,0 +1,20 @@
+import { StyleSheet } from 'react-native';
+import { space } from '../../../theme';
+import type { ColorTokens } from '../../../theme';
+
+/** @gorhom 接管动画 / handle / scrim,这里只控 root flex + sheet bg + 顶部圆角 24
+ *  + scrim/blur backdrop 背景色(走 c.scrim token,亮 rgba(0,0,0,0.5) / 暗 0.7)。 */
+export const makeStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    root: { flex: 1 },
+    sheet: {
+      backgroundColor: c.surface,
+      borderTopLeftRadius: space['9'],
+      borderTopRightRadius: space['9'],
+    },
+    /** Scrim backdrop:c.scrim token,亮暗自动切换(亮 0.5 / 暗 0.7 alpha)。
+     *  与 @gorhom 默认 backgroundColor:'black' + opacity 0.5 等价但走 token。 */
+    scrimBackdrop: { backgroundColor: c.scrim },
+    /** Blur backdrop:bg 透明,由 BlurLayer child 接管视觉。 */
+    backdropTransparent: { backgroundColor: 'transparent' },
+  });

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

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type BottomSheetProps = {
+  /** snap points,默认 `['30%', '60%', '95%']` 三档可拖。
+   *  专用场景显式覆盖,如单档不可调 `['90%']`、短确认 + 中 `['40%', '85%']`。 */
+  snapPoints?: (string | number)[];
+  /** Sheet 内容 */
+  children: ReactNode;
+  /** Sheet 容器附加样式(影响 BottomSheetView style) */
+  sheetStyle?: StyleProp<ViewStyle>;
+  /** Backdrop 模式,默认 'scrim':
+   *  - `'scrim'`:@gorhom 默认 BottomSheetBackdrop,单色半透黑
+   *  - `'blur'`:自定义 BlurBackdrop(BlurLayer intensity='strong')
+   *  - `'none'`:无 backdrop,适合"屏 root 已有自己 backdrop"场景 */
+  backdrop?: 'scrim' | 'blur' | 'none';
+  /** 是否显示顶部 grabber(默认 true) */
+  grabber?: boolean;
+  /** Sheet 关闭(animatedIndex 收到 -1)时触发。
+   *
+   *  **transparentModal route 模式必传 `navigation.goBack()`** —— 不然关闭 sheet 后,
+   *  屏 route 没 pop,native overlay 屏继续覆盖,触摸全被屏吞掉。 */
+  onClose?: () => void;
+  /** E2E / 测试定位 */
+  testID?: string;
+};

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

@@ -0,0 +1,61 @@
+import React from 'react';
+import { Text } from 'react-native';
+import { useThemedStyles } from '../../../theme';
+import { Icon } from '../Icon';
+import { ButtonBase } from './ButtonBase';
+import { makeStyles } from './styles';
+import type { ButtonProps } from './types';
+
+/**
+ * 6 variant × 3 size 文本按钮。
+ * 内部组合 ButtonBase + content(label + 可选 leftIcon / rightIcon),
+ * ButtonBase 接管 chrome(sizing / palette / disabled / loading / a11y)。
+ *
+ * `loading=true` 时 ButtonBase 把 children render prop 短路为 ActivityIndicator。
+ */
+export function Button({
+  label,
+  onPress,
+  size,
+  variant,
+  block,
+  disabled,
+  loading,
+  leftIcon,
+  rightIcon,
+  style,
+  testID,
+  accessibilityHint,
+}: ButtonProps): React.JSX.Element {
+  const styles = useThemedStyles(makeStyles);
+  return (
+    <ButtonBase
+      onPress={onPress}
+      size={size}
+      variant={variant}
+      block={block}
+      disabled={disabled}
+      loading={loading}
+      accessibilityLabel={label}
+      accessibilityHint={accessibilityHint}
+      style={style}
+      testID={testID}
+    >
+      {({ sizing, palette }) => (
+        <>
+          {leftIcon ? (
+            <Icon name={leftIcon} size={sizing.fs + 2} color={palette.fg} />
+          ) : null}
+          <Text
+            style={[styles.label, { color: palette.fg, fontSize: sizing.fs }]}
+          >
+            {label}
+          </Text>
+          {rightIcon ? (
+            <Icon name={rightIcon} size={sizing.fs + 2} color={palette.fg} />
+          ) : null}
+        </>
+      )}
+    </ButtonBase>
+  );
+}

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

@@ -0,0 +1,100 @@
+import React, { useMemo } from 'react';
+import {
+  ActivityIndicator,
+  type AccessibilityRole,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { Pressable } from 'react-native-gesture-handler';
+import { useColors, useThemedStyles } from '../../../theme';
+import { makeStyles, paletteFor, sizingFor } from './styles';
+import type {
+  ButtonBaseRenderContext,
+  ButtonSize,
+  ButtonVariant,
+} from './types';
+
+export type ButtonBaseProps = {
+  onPress?: () => void;
+  size?: ButtonSize;
+  variant?: ButtonVariant;
+  disabled?: boolean;
+  loading?: boolean;
+  block?: boolean;
+  /** 方形约束 — width=height=sizing.h,优先级高于 horizontal padding。IconButton 用。 */
+  square?: boolean;
+  accessibilityLabel?: string;
+  accessibilityRole?: AccessibilityRole;
+  /** SR 朗读 label 后的行为说明 hint。仅在"行为不显然"时加。 */
+  accessibilityHint?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  /** 强制函数形态 — 消费者通过 ctx.sizing / ctx.palette 渲染内容,
+   *  sizing / palette 在 ButtonBase 内单点计算。 */
+  children: (ctx: ButtonBaseRenderContext) => React.ReactNode;
+};
+
+/** ButtonBase —— Button / IconButton 共享的 internal primitive。
+ *  职责:Pressable / sizing / palette / 视觉态 / a11y / text variant 特殊处理 /
+ *  block / square。children 强制 render prop,sizingFor / paletteFor 在 styles.ts。 */
+export function ButtonBase({
+  onPress,
+  size = 'md',
+  variant = 'primary',
+  disabled,
+  loading,
+  block,
+  square,
+  accessibilityLabel,
+  accessibilityRole = 'button',
+  accessibilityHint,
+  style,
+  testID,
+  children,
+}: ButtonBaseProps): React.JSX.Element {
+  const c = useColors();
+  const styles = useThemedStyles(makeStyles);
+
+  const sizing = useMemo(() => sizingFor(size), [size]);
+  const palette = useMemo(() => paletteFor(variant, c), [variant, c]);
+
+  const isText = variant === 'text';
+  const isInteractive = !disabled && !loading;
+
+  return (
+    <Pressable
+      accessibilityRole={accessibilityRole}
+      accessibilityState={{ disabled: !isInteractive }}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityHint={accessibilityHint}
+      disabled={!isInteractive}
+      onPress={onPress}
+      testID={testID}
+      style={({ pressed }) => [
+        styles.base,
+        {
+          // text variant 撕掉所有 chrome,只剩 inline 文字
+          height: isText ? undefined : sizing.h,
+          // square 时方形:width=height,horizontal padding=0
+          width: square ? sizing.h : undefined,
+          paddingHorizontal: isText || square ? 0 : sizing.px,
+          borderRadius: sizing.br,
+          backgroundColor: palette.bg,
+          borderColor: palette.border ?? 'transparent',
+          borderWidth: palette.border ? 1 : 0,
+          opacity: disabled ? 0.5 : pressed ? 0.7 : 1,
+          alignSelf: block ? 'stretch' : 'flex-start',
+          flexGrow: block ? 1 : 0,
+          gap: sizing.gap,
+        },
+        style,
+      ]}
+    >
+      {loading ? (
+        <ActivityIndicator size="small" color={palette.fg} />
+      ) : (
+        children({ sizing, palette })
+      )}
+    </Pressable>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { Button } from './Button';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './types';

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

@@ -0,0 +1,89 @@
+import { StyleSheet } from 'react-native';
+import {
+  control,
+  fw,
+  r,
+  radius,
+  space,
+  type as t,
+  type ColorTokens,
+} from '../../../theme';
+import type {
+  ButtonPalette,
+  ButtonSize,
+  ButtonSizing,
+  ButtonVariant,
+} from './types';
+
+/** Button 静态 base —— flex 居中容器(高度 / padding / 圆角由 sizingFor 派生)。
+ *  label 字号 / 颜色由 caller 注入 dynamic style。 */
+export const makeStyles = (_c: ColorTokens) =>
+  StyleSheet.create({
+    base: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
+    label: {
+      fontWeight: fw.semi,
+    },
+  });
+
+/** Button 尺寸推导:3 档 size → { h, px, fs, br, gap }。
+ *  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'],
+    };
+  }
+  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。 */
+export function paletteFor(
+  variant: ButtonVariant,
+  c: ColorTokens
+): ButtonPalette {
+  switch (variant) {
+    case 'primary':
+      return { bg: c.primary, fg: c.onPrimary, border: undefined };
+    case 'secondary':
+      return {
+        bg: c.surfaceContainerHigh,
+        fg: c.foreground,
+        border: undefined,
+      };
+    case 'ghost':
+      return { bg: 'transparent', fg: c.primary, border: undefined };
+    case 'neutral':
+      return { bg: 'transparent', fg: c.foreground, border: undefined };
+    case 'outline':
+      return { bg: c.surface, fg: c.foreground, border: c.outline };
+    case 'danger':
+      return { bg: c.error, fg: c.onError, border: undefined };
+    case 'text':
+      return { bg: 'transparent', fg: c.primary, border: undefined };
+  }
+}

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

@@ -0,0 +1,79 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../Icon';
+
+/** Button 尺寸：sm=28 / md=36 / lg=44（对应 control.sm/md/lg） */
+export type ButtonSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Button 视觉变体：
+ * - `primary` 品牌橙底（主操作，业务页面通常只有 1 个）
+ * - `secondary` 浅灰底（次要操作）
+ * - `ghost` 透明底 + 品牌橙字（弱化的主操作；IconButton 用作"高亮 icon"）
+ * - `neutral` 透明底 + 主文字色（深灰 / 白）—— 中性 icon-only 场景，
+ *   避免 header right-tray 多个 icon 都染成主橙色，视觉过重
+ * - `outline` 白底 + 灰边框 + 深色字（中性操作）
+ * - `danger` 红底（破坏性操作：删除 / 退出 / 解绑）
+ * - `text` 纯文字按钮，无背景无 padding（行内链接式触发）
+ */
+export type ButtonVariant =
+  | 'primary'
+  | 'secondary'
+  | 'ghost'
+  | 'neutral'
+  | 'outline'
+  | 'danger'
+  | 'text';
+
+export type ButtonProps = {
+  /** 按钮文案；icon-only 场景请用其他组件（Pressable + Icon） */
+  label: string;
+  /** 点击回调；disabled / loading 时不触发 */
+  onPress?: () => void;
+  /** 尺寸，默认 'md' */
+  size?: ButtonSize;
+  /** 视觉变体，默认 'primary' */
+  variant?: ButtonVariant;
+  /** 撑满父容器宽度（alignSelf: stretch + flexGrow: 1） */
+  block?: boolean;
+  /** 整体禁用：透明度 0.5 + 不响应 onPress */
+  disabled?: boolean;
+  /** 加载态：显示 ActivityIndicator 替代 label，自动 disabled */
+  loading?: boolean;
+  /** 左侧图标，与文本同色同高 */
+  leftIcon?: IconName;
+  /** 右侧图标，与文本同色同高 */
+  rightIcon?: IconName;
+  /** 额外样式覆盖（merge 到 Pressable 的 style 数组末尾） */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
+  /** SR 朗读 label 后的行为说明 hint。仅在"行为不显然"时加(如 "切换主题")。 */
+  accessibilityHint?: string;
+};
+
+/** ButtonBase 内部根据 size 算出的视觉参数集合,通过 render prop 暴露给消费者。 */
+export type ButtonSizing = {
+  /** 高度(对应 control.sm/md/lg) */
+  h: number;
+  /** 水平 padding(text variant 强制 0;square=true 也强制 0) */
+  px: number;
+  /** 字号(消费者据此 derive Icon size) */
+  fs: number;
+  /** 圆角(radius.sm/md/lg) */
+  br: number;
+  /** 内容之间 gap */
+  gap: number;
+};
+
+/** ButtonBase 内部根据 variant + 主题色算出的调色板。 */
+export type ButtonPalette = {
+  bg: string;
+  fg: string;
+  border?: string;
+};
+
+/** ButtonBase children render prop 接收的上下文。 */
+export type ButtonBaseRenderContext = {
+  sizing: ButtonSizing;
+  palette: ButtonPalette;
+};

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

@@ -0,0 +1,39 @@
+import React from 'react';
+import { View } from 'react-native';
+import { radius, space, useShadow, useThemedStyles } from '../../../theme';
+import { makeStyles, variantToStyle } from './styles';
+import type { CardProps } from './types';
+
+export function Card({
+  children,
+  variant = 'default',
+  padding,
+  borderRadius,
+  borderColor,
+  borderWidth,
+  bare,
+  style,
+  testID,
+}: CardProps): React.JSX.Element {
+  const styles = useThemedStyles(makeStyles);
+  const shadow = useShadow();
+
+  return (
+    <View
+      testID={testID}
+      style={[
+        styles.base,
+        { borderRadius: borderRadius ?? radius.xl },
+        !bare && { padding: padding ?? space[6] },
+        variantToStyle(variant, shadow, styles),
+        borderColor != null && {
+          borderColor,
+          borderWidth: borderWidth ?? 2,
+        },
+        style,
+      ]}
+    >
+      {children}
+    </View>
+  );
+}