@unif/react-native-design 0.1.0

package/src/components/business/Decorations/RadialHalo.tsx

@@ -0,0 +1,74 @@
+import React, { useId } from 'react';
+import { View } from 'react-native';
+import Svg, {
+  Defs,
+  Ellipse,
+  RadialGradient as SvgRadialGradient,
+  Stop,
+} from 'react-native-svg';
+import type { RadialHaloProps } from './types';
+
+const DEFAULT_MAX_OPACITY = 0.16;
+
+const buildStops = (maxOpacity: number) => [
+  { offset: 0, opacity: maxOpacity },
+  { offset: 0.65, opacity: 0 },
+  { offset: 1, opacity: 0 },
+];
+
+/**
+ * 中央径向柔光圆 / 椭圆 —— 单色等距圆形 radial gradient,3 stop 默认"中心亮、65% 处归零"。
+ *
+ * 渲染是 **等距圆形 gradient + Ellipse clip**,不是椭圆形随容器拉伸 ——
+ * 对齐 CSS `radial-gradient(circle, ...)` 默认 ending-shape `farthest-corner`:
+ * r = sqrt(cx² + cy²),65% 归零落在容器内。BBox 默认会让渐变随 rx/ry 拉伸,
+ * 椭圆边缘内容会因 x 维度过早归零而透明,所以走 userSpaceOnUse + 像素 r。
+ */
+export function RadialHalo({
+  size,
+  height,
+  color,
+  maxOpacity = DEFAULT_MAX_OPACITY,
+  stops,
+  style,
+  gradientId,
+}: RadialHaloProps): React.JSX.Element {
+  const w = size;
+  const h = height ?? size;
+  const autoId = useId();
+  const id = gradientId ?? `rh-${autoId.replace(/[^a-zA-Z0-9_-]/g, '')}`;
+  const resolvedStops = stops ?? buildStops(maxOpacity);
+  const cx = w / 2;
+  const cy = h / 2;
+  // farthest-corner:r = 中心到最远角的距离
+  const r = Math.sqrt(cx * cx + cy * cy);
+  return (
+    <View pointerEvents="none" style={[{ width: w, height: h }, style]}>
+      <Svg width={w} height={h}>
+        <Defs>
+          {/* userSpaceOnUse + r=farthest-corner 实现等距圆形渐变,
+              容器 Ellipse 边缘做 clip。 */}
+          <SvgRadialGradient
+            id={id}
+            cx={cx}
+            cy={cy}
+            r={r}
+            fx={cx}
+            fy={cy}
+            gradientUnits="userSpaceOnUse"
+          >
+            {resolvedStops.map((s, i) => (
+              <Stop
+                key={`${s.offset}-${i}`}
+                offset={s.offset}
+                stopColor={color}
+                stopOpacity={s.opacity}
+              />
+            ))}
+          </SvgRadialGradient>
+        </Defs>
+        <Ellipse cx={cx} cy={cy} rx={cx} ry={cy} fill={`url(#${id})`} />
+      </Svg>
+    </View>
+  );
+}

package/src/components/business/Decorations/ScreenBackdrop.tsx

@@ -0,0 +1,122 @@
+import React from 'react';
+import { StyleSheet, useWindowDimensions, View } from 'react-native';
+import { useColors, useTheme, warmOrangePalette } from '../../../theme';
+import { GradientWash } from './GradientWash';
+import { RadialHalo } from './RadialHalo';
+import type {
+  GradientStop,
+  ScreenBackdropHalo,
+  ScreenBackdropPreset,
+  ScreenBackdropProps,
+} from './types';
+
+type PresetConfig = {
+  light: ReadonlyArray<GradientStop>;
+  dark: ReadonlyArray<GradientStop>;
+  halos: ReadonlyArray<ScreenBackdropHalo>;
+};
+
+/** 把 4 stop palette 数组 → GradientWash stops 配置(均布 offset)。
+ *  数据从 theme/palettes.ts 取,组件内只负责 offset 分布。 */
+function buildStops(
+  palette: ReadonlyArray<string>,
+  offsets: ReadonlyArray<number>
+): ReadonlyArray<GradientStop> {
+  return palette.map((color, i) => ({
+    offset: offsets[i] ?? i / (palette.length - 1),
+    color,
+    opacity: 1,
+  }));
+}
+
+const WARM_ORANGE_OFFSETS = [0, 0.35, 0.75, 1] as const;
+
+/** 全屏渐变 + halo 预设表。新增 preset:加 palette token + 配 halo。 */
+const PRESETS: Record<ScreenBackdropPreset, PresetConfig> = {
+  /** 暖橙沉浸 —— 名片屏 / 扫码屏 / Splash 等"整屏暖色"场景。
+   *  亮 / 暗 4 stop palette 来自 theme/palettes.ts;halo 3 件套(顶/底中心 + 右上)。 */
+  warmOrange: {
+    light: buildStops(warmOrangePalette.light, WARM_ORANGE_OFFSETS),
+    dark: buildStops(warmOrangePalette.dark, WARM_ORANGE_OFFSETS),
+    halos: [
+      { size: 520, height: 420, maxOpacity: 0.22, top: -120, centerX: true },
+      { size: 560, height: 380, maxOpacity: 0.18, bottom: -160, centerX: true },
+      { size: 220, maxOpacity: 0.16, top: 180, right: -80 },
+    ],
+  },
+};
+
+/** 整屏沉浸渐变背景容器 —— 暗色 theme 自适配。
+ *
+ *  使用:
+ *  ```tsx
+ *  <ScreenBackdrop preset="warmOrange">
+ *    <NavBar ... />
+ *    <View style={styles.body}>...</View>
+ *  </ScreenBackdrop>
+ *  ```
+ *
+ *  内部布局:
+ *  1. 外壳 View(flex:1 + overflow:hidden + 瞬态 c.background 底)
+ *  2. GradientWash absolute fill(scheme 切换 stops)
+ *  3. halo 列表 absolute 定位(可水平居中)
+ *  4. children(在装饰层之上,zIndex 由渲染顺序保证)
+ *
+ *  自定义:`stops` 和 `halos` 都可绕过 preset。两者都不传且 preset 不传时,
+ *  仅渲染 c.background 实色外壳(等价于普通 View)。 */
+export function ScreenBackdrop({
+  preset,
+  stops,
+  halos,
+  children,
+  style,
+}: ScreenBackdropProps): React.JSX.Element {
+  const c = useColors();
+  const { scheme } = useTheme();
+  const { width: winW, height: winH } = useWindowDimensions();
+  const isDark = scheme === 'dark';
+
+  const cfg = preset ? PRESETS[preset] : undefined;
+  const resolvedStops =
+    stops ?? (cfg ? { light: cfg.light, dark: cfg.dark } : undefined);
+  const resolvedHalos = halos ?? cfg?.halos ?? [];
+
+  return (
+    <View
+      style={[backdropStyles.root, { backgroundColor: c.background }, style]}
+    >
+      {resolvedStops ? (
+        <GradientWash
+          height={winH}
+          stops={isDark ? resolvedStops.dark : resolvedStops.light}
+          style={backdropStyles.gradient}
+        />
+      ) : null}
+      {resolvedHalos.map((h, i) => {
+        const left = h.centerX ? (winW - h.size) / 2 : h.left;
+        const right = h.centerX ? undefined : h.right;
+        return (
+          <RadialHalo
+            key={`halo-${i}`}
+            size={h.size}
+            height={h.height}
+            color={h.color ?? c.primary}
+            maxOpacity={h.maxOpacity}
+            gradientId={`screen-backdrop-halo-${i}`}
+            style={[
+              backdropStyles.haloAbsolute,
+              { top: h.top, bottom: h.bottom, left, right },
+            ]}
+          />
+        );
+      })}
+      {children}
+    </View>
+  );
+}
+
+const backdropStyles = StyleSheet.create({
+  root: { flex: 1, position: 'relative', overflow: 'hidden' },
+  gradient: { position: 'absolute', top: 0, left: 0, right: 0 },
+  haloAbsolute: { position: 'absolute' },
+});

package/src/components/business/Decorations/index.ts

@@ -0,0 +1,10 @@
+export { GradientWash } from './GradientWash';
+export { RadialHalo } from './RadialHalo';
+export { ScreenBackdrop } from './ScreenBackdrop';
+export type {
+  GradientWashProps,
+  RadialHaloProps,
+  ScreenBackdropHalo,
+  ScreenBackdropPreset,
+  ScreenBackdropProps,
+} from './types';

package/src/components/business/Decorations/types.ts

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/**
+ * Gradient stop —— 设定渐变停止点的颜色和透明度。
+ * - offset: 0~1,沿 gradient 轴的归一化位置
+ * - color: 任意有效颜色字符串(hex / rgb / rgba / hsl ...)
+ * - opacity: 可选,0~1,不设等价 1
+ *
+ * SVG `<Stop>` 接 stopOpacity,opacity 单独透传(不要合到 rgba 字符串里),
+ * 这样 color 接受任意格式。
+ */
+export type GradientStop = {
+  offset: number;
+  color: string;
+  opacity?: number;
+};
+
+/** 简单单色模式:顶部 fromOpacity → 底部 toOpacity */
+type GradientWashSimple = {
+  height: number;
+  /** 单色 wash 的颜色 */
+  color: string;
+  /** 顶部透明度,默认 0.1 */
+  fromOpacity?: number;
+  /** 底部透明度,默认 0 */
+  toOpacity?: number;
+  stops?: never;
+  style?: StyleProp<ViewStyle>;
+  gradientId?: string;
+};
+
+/** 多 stop 自定义模式 */
+type GradientWashCustom = {
+  height: number;
+  stops: ReadonlyArray<GradientStop>;
+  color?: never;
+  fromOpacity?: never;
+  toOpacity?: never;
+  style?: StyleProp<ViewStyle>;
+  gradientId?: string;
+};
+
+export type GradientWashProps = GradientWashSimple | GradientWashCustom;
+
+export type RadialHaloProps = {
+  /** halo 宽度(圆模式即直径)。 */
+  size: number;
+  /** 椭圆高度,不传则 = size(圆模式)。 */
+  height?: number;
+  /** 中心颜色 —— 透明度从 maxOpacity 或 stops 控制。 */
+  color: string;
+  /** 简化用法:中心最大透明度,默认 0.16。组件自动生成
+   *  `[{0, maxOpacity}, {0.65, 0}, {1, 0}]` 标准 3 stop。传了 stops 时本字段忽略。 */
+  maxOpacity?: number;
+  /** 完全自定义透明度分布(覆盖 maxOpacity)。 */
+  stops?: ReadonlyArray<{ offset: number; opacity: number }>;
+  /** 容器附加样式(position absolute / top / left 等定位)。 */
+  style?: StyleProp<ViewStyle>;
+  /** SVG 内 gradient id —— 同屏多 halo 必须不同 id。 */
+  gradientId?: string;
+};
+
+/** ScreenBackdrop 预设名 —— 全屏沉浸式渐变背景。
+ *  - `warmOrange`:暖橙(亮:#FFE3C8→#FBD9B6 / 暗:#1F1208→#0A0A0A)+
+ *    顶/底中心 + 右上 3 个橙色 halo。名片屏 / 扫码屏 / Splash 通用。 */
+export type ScreenBackdropPreset = 'warmOrange';
+
+/** ScreenBackdrop 装饰 halo 配置 —— absolute 定位 + 可选水平居中。 */
+export type ScreenBackdropHalo = {
+  /** halo 宽度 */
+  size: number;
+  /** 椭圆高度,不传 = size */
+  height?: number;
+  /** halo 颜色,不传默认 c.primary */
+  color?: string;
+  /** 最大透明度,默认 0.16(RadialHalo 默认) */
+  maxOpacity?: number;
+  /** 定位偏移 */
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+  /** true 时按 (screenWidth - size)/2 水平居中,覆盖 left/right */
+  centerX?: boolean;
+};
+
+export type ScreenBackdropProps = {
+  /** 内置预设。preset 提供的 stops/halos 可被自定义 stops/halos 覆盖。 */
+  preset?: ScreenBackdropPreset;
+  /** 自定义全屏渐变 stops(scheme-aware)。覆盖 preset。
+   *  注:GradientStop[].opacity 不传默认 1。 */
+  stops?: {
+    light: ReadonlyArray<GradientStop>;
+    dark: ReadonlyArray<GradientStop>;
+  };
+  /** 自定义 halo 列表。覆盖 preset。 */
+  halos?: ReadonlyArray<ScreenBackdropHalo>;
+  /** 内容层(在装饰层之上) */
+  children?: ReactNode;
+  /** 外层附加样式 */
+  style?: StyleProp<ViewStyle>;
+};

package/src/components/business/GlassStats/GlassStats.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+import { BlurLayer } from '../../ui';
+import { useThemedStyles } from '../../../theme';
+import { makeGlassStatsStyles } from './styles';
+import type { GlassStatsProps } from './types';
+
+/**
+ * 玻璃数据条 —— BlurLayer 真 backdrop blur + 内部 N 列数据。
+ *
+ * BlurLayer 接管 backdrop 双层结构(BlurView soft + glassTintLight tint),
+ * blurType 跟 scheme 自动切。
+ */
+export function GlassStats({ items }: GlassStatsProps): React.JSX.Element {
+  const styles = useThemedStyles(makeGlassStatsStyles);
+  return (
+    // 外层 shell 承担 shadow(无 overflow,iOS Core Animation masksToBounds=true
+    // 会裁掉 outer shadow);内层 glass 承担 overflow:hidden + border 裁圆角。
+    // 单层 overflow + shadow 在 iOS 上 shadow 完全不可见。
+    <View style={styles.glassShell}>
+      <View style={styles.glass}>
+        <BlurLayer intensity="soft" />
+        {/* 顶部 1px inset 白高光,让数据条顶部"凸起" */}
+        <View style={styles.topHighlight} pointerEvents="none" />
+        <View style={styles.inner}>
+          {items.map(([count, label], i) => (
+            <React.Fragment key={label}>
+              {i > 0 ? <View style={styles.sep} /> : null}
+              <View style={styles.col}>
+                <Text style={styles.countText}>{count}</Text>
+                <Text style={styles.labelText}>{label}</Text>
+              </View>
+            </React.Fragment>
+          ))}
+        </View>
+      </View>
+    </View>
+  );
+}

package/src/components/business/GlassStats/index.ts

@@ -0,0 +1,2 @@
+export { GlassStats } from './GlassStats';
+export type { GlassStatsProps, GlassStatItem } from './types';

package/src/components/business/GlassStats/styles.ts

@@ -0,0 +1,58 @@
+import { StyleSheet } from 'react-native';
+import { fontMono, fw, radius, rf, space, type as t } from '../../../theme';
+import type { ColorTokens, ShadowTokens } from '../../../theme';
+
+/** 玻璃质感数据条 styles。
+ *
+ *  **双层结构**(必要):
+ *  - `glassShell`:外层只承担 shadow + borderRadius(无 overflow:hidden);
+ *    iOS Core Animation `masksToBounds=true` 会裁掉 outer shadow。
+ *  - `glass`:内层承担 borderRadius + overflow:hidden + border 边线。
+ *
+ *  BlurView + tint 双层由 `<BlurLayer intensity="soft"/>` 接管。 */
+export const makeGlassStatsStyles = (c: ColorTokens, s: ShadowTokens) => {
+  /** count 数字 mono display 字号,无对应 type token,保留 rf(20) 走字号缩放(非 r)。 */
+  const countSize = rf(20);
+  return StyleSheet.create({
+    glassShell: {
+      borderRadius: radius['2xl'],
+      ...s.glassBar,
+    },
+    glass: {
+      borderRadius: radius['2xl'],
+      overflow: 'hidden',
+      borderWidth: StyleSheet.hairlineWidth,
+      borderColor: c.glassBorder,
+    },
+    /** 顶部 1px inset 白高光,borderTopWidth + borderRadius 让高光线只在 radius 内部弧形顶部生效。 */
+    topHighlight: {
+      ...StyleSheet.absoluteFill,
+      borderRadius: radius['2xl'],
+      borderTopWidth: StyleSheet.hairlineWidth,
+      borderTopColor: c.glassStatsHighlight,
+    },
+    inner: {
+      flexDirection: 'row',
+      paddingVertical: space['5'],
+    },
+    sep: {
+      width: StyleSheet.hairlineWidth,
+      backgroundColor: c.glassSeparator,
+      marginVertical: space['1'],
+    },
+    col: { flex: 1, alignItems: 'center' },
+    countText: {
+      fontSize: countSize,
+      fontWeight: fw.bold,
+      color: c.foreground,
+      letterSpacing: -0.3,
+      fontFamily: fontMono,
+      lineHeight: countSize * 1.1,
+    },
+    labelText: {
+      fontSize: t.micro,
+      color: c.foregroundMuted,
+      paddingTop: space['1'],
+    },
+  });
+};

package/src/components/business/GlassStats/types.ts

@@ -0,0 +1,7 @@
+/** 单元格元组 —— [count, label] —— count 已格式化好(如 '12' / '¥2,016') */
+export type GlassStatItem = readonly [count: string, label: string];
+
+export type GlassStatsProps = {
+  /** 数据列。一般 2~4 列均可,不强制数量。 */
+  items: ReadonlyArray<GlassStatItem>;
+};

package/src/components/business/VersionPill/VersionPill.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+import { useColors, useThemedStyles } from '../../../theme';
+import { makeVersionPillStyles } from './styles';
+import type { VersionPillProps } from './types';
+
+/** 版本徽章胶囊 —— success dot + 版本 + 分点 + build mono。 */
+export function VersionPill({
+  version,
+  build,
+  statusColor,
+  style,
+}: VersionPillProps): React.JSX.Element {
+  const c = useColors();
+  const styles = useThemedStyles(makeVersionPillStyles);
+  const dotColor = statusColor ?? c.success;
+  return (
+    <View style={[styles.pill, style]}>
+      <View style={[styles.dot, { backgroundColor: dotColor }]} />
+      <Text style={styles.version}>版本 {version}</Text>
+      {build ? (
+        <>
+          <Text style={styles.sep}>·</Text>
+          <Text style={styles.build}>build {build}</Text>
+        </>
+      ) : null}
+    </View>
+  );
+}

package/src/components/business/VersionPill/index.ts

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

package/src/components/business/VersionPill/styles.ts

@@ -0,0 +1,46 @@
+import { StyleSheet } from 'react-native';
+import {
+  fontMono,
+  r,
+  radius,
+  space,
+  type,
+  type ColorTokens,
+} from '../../../theme';
+
+/** VersionPill 样式工厂 —— hairline 描边 + surface 底胶囊。
+ *  字号走 type.microPlus(11.5),与 SplashScreen / profileCard / carousel 共用。 */
+export const makeVersionPillStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    pill: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: space[2],
+      paddingHorizontal: r(11),
+      paddingVertical: r(5),
+      borderRadius: radius.pill,
+      backgroundColor: c.surface,
+      borderWidth: StyleSheet.hairlineWidth,
+      borderColor: c.outline,
+    },
+    dot: {
+      width: r(5),
+      height: r(5),
+      borderRadius: radius.pill,
+    },
+    version: {
+      fontSize: type.microPlus,
+      color: c.foregroundMuted,
+      fontVariant: ['tabular-nums'],
+    },
+    sep: {
+      opacity: 0.5,
+      color: c.foregroundMuted,
+      fontSize: type.microPlus,
+    },
+    build: {
+      fontSize: type.micro,
+      color: c.foregroundMuted,
+      fontFamily: fontMono,
+    },
+  });

package/src/components/business/VersionPill/types.ts

@@ -0,0 +1,12 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type VersionPillProps = {
+  /** 版本号,如 "2.8.0"。 */
+  version: string;
+  /** 可选 build 号;为空时省略分点与 build 字。 */
+  build?: string;
+  /** 状态点颜色,默认 c.success。 */
+  statusColor?: string;
+  /** 容器附加样式覆盖。 */
+  style?: StyleProp<ViewStyle>;
+};

package/src/components/business/index.ts

@@ -0,0 +1,22 @@
+// 业务级复合组件 barrel(design 包通用部分)。区别于 src/components/ui:
+// - ui/ = atomic widgets(Button / Card / Cell / NavBar / Icon / ...),无业务上下文依赖
+// - business/ = 业务复合组件,通用部分(不耦合 navigation / store / SMS 流等)
+//   navigation / store 耦合的(ScreenLayout / ModernAppCell / CellList /
+//   SmsCodeInput)留在 consumer 仓库
+export { GradientWash, RadialHalo, ScreenBackdrop } from './Decorations';
+export type {
+  GradientWashProps,
+  RadialHaloProps,
+  ScreenBackdropHalo,
+  ScreenBackdropPreset,
+  ScreenBackdropProps,
+} from './Decorations';
+
+export { GlassStats } from './GlassStats';
+export type { GlassStatsProps, GlassStatItem } from './GlassStats';
+
+export { AvatarWithRing } from './AvatarWithRing';
+export type { AvatarWithRingProps } from './AvatarWithRing';
+
+export { VersionPill } from './VersionPill';
+export type { VersionPillProps } from './VersionPill';

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export * from './ui';
+export * from './business';

package/src/components/ui/Avatar/Avatar.tsx

@@ -0,0 +1,69 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { Image, Text, View } from 'react-native';
+import { useColors } from '../../../theme';
+import { paletteFor, sizingFor, styles } from './styles';
+import type { AvatarProps } from './types';
+
+/**
+ * 圆形头像 —— 5 档尺寸 × 4 种配色 × 可选图片 source。
+ *
+ * 传 source 且未失败时渲染 Image(onError 后自动 fallback 到 label 文字),
+ * 否则渲染 label + variant 背景色。
+ */
+export function Avatar({
+  label,
+  size = 'md',
+  variant = 'neutral',
+  source,
+  testID,
+}: AvatarProps): React.JSX.Element {
+  const c = useColors();
+  const [imageFailed, setImageFailed] = useState(false);
+  // 避免 unmount 后 Image 网络回包仍调 setState 的 React warning
+  const mountedRef = useRef(true);
+  useEffect(
+    () => () => {
+      mountedRef.current = false;
+    },
+    []
+  );
+  const handleImageError = () => {
+    if (mountedRef.current) setImageFailed(true);
+  };
+  const dims = sizingFor(size);
+  const palette = paletteFor(variant, c);
+
+  const showImage = source != null && !imageFailed;
+
+  return (
+    <View
+      style={[
+        styles.base,
+        {
+          width: dims.box,
+          height: dims.box,
+          borderRadius: dims.box / 2,
+          backgroundColor: palette.bg,
+        },
+      ]}
+      accessibilityLabel={label}
+      testID={testID}
+    >
+      {showImage ? (
+        <Image
+          source={source}
+          onError={handleImageError}
+          style={styles.image}
+          resizeMode="cover"
+        />
+      ) : (
+        <Text
+          style={[styles.label, { fontSize: dims.fs, color: palette.fg }]}
+          numberOfLines={1}
+        >
+          {label}
+        </Text>
+      )}
+    </View>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { Avatar } from './Avatar';
+export type { AvatarProps, AvatarSize, AvatarVariant } from './types';

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

@@ -0,0 +1,54 @@
+import { StyleSheet } from 'react-native';
+import { avatar, fw, type ColorTokens } from '../../../theme';
+import type { AvatarSize, AvatarVariant } from './types';
+
+/** Avatar 静态 base —— 圆形容器(borderRadius / 尺寸由 sizingFor 派生)。 */
+export const styles = StyleSheet.create({
+  base: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+  },
+  label: {
+    fontWeight: fw.semi,
+    lineHeight: undefined,
+  },
+  image: {
+    width: '100%',
+    height: '100%',
+  },
+});
+
+/** Avatar 尺寸推导:5 档 size → { box, fs }。box 走 avatar.<size> token。
+ *  新增 size 在 types.ts 加 union + 这里加 case + tokens.ts 补 avatar.<key>。 */
+export function sizingFor(size: AvatarSize): { box: number; fs: number } {
+  switch (size) {
+    case 'xs':
+      return { box: avatar.xs, fs: 10 };
+    case 'sm':
+      return { box: avatar.sm, fs: 12 };
+    case 'md':
+      return { box: avatar.md, fs: 13 };
+    case 'lg':
+      return { box: avatar.lg, fs: 15 };
+    case 'xl':
+      return { box: avatar.xl, fs: 20 };
+  }
+}
+
+/** Avatar 配色推导:4 种 variant → { bg, fg }。签名与 Tag/Tool 的 paletteFor 一致。 */
+export function paletteFor(
+  variant: AvatarVariant,
+  c: ColorTokens
+): { bg: string; fg: string } {
+  switch (variant) {
+    case 'brand':
+      return { bg: c.primary, fg: c.onPrimary };
+    case 'info':
+      return { bg: c.info, fg: c.onInfo };
+    case 'soft':
+      return { bg: c.primaryContainer, fg: c.primary };
+    case 'neutral':
+      return { bg: c.surfaceContainerHighest, fg: c.foreground };
+  }
+}