@unif/react-native-design 0.1.0

package/lib/typescript/src/theme/tokens.d.ts

@@ -0,0 +1,102 @@
+export declare const fontMono: string;
+export declare const type: {
+    readonly display: number;
+    readonly h1: number;
+    readonly h2: number;
+    readonly h3: number;
+    readonly body: number;
+    readonly sm: number;
+    readonly xs: number;
+    readonly xxs: number;
+    readonly micro: number;
+    readonly nano: number;
+    /** micro(11)与 xxs(12)之间:VersionPill / profileCard / Splash / carousel 副标题。 */
+    readonly microPlus: number;
+    /** xs(13)与 sm(14)之间:Privacy 长文阅读字号。 */
+    readonly xsPlus: number;
+    /** sm(14)与 body/h3(15)之间:dashboard card 标题"小一档 semi"惯例
+     *  (NewsArea / AssistantCard / ApplicationArea 共用)。 */
+    readonly smPlus: number;
+    /** Hero 区主标题档(一级 brand hero,带 Logo,Login 屏)。 */
+    readonly heroLg: number;
+    /** Hero 区中等档(独立屏 + NavBar 的二级 hero,ForgotPassword)。 */
+    readonly heroMd: number;
+    /** Hero 区小档(承接式 hero,Group 选组/选角色子区)。 */
+    readonly heroSm: number;
+};
+export declare const fw: {
+    readonly regular: "400";
+    readonly medium: "500";
+    readonly semi: "600";
+    readonly bold: "700";
+    readonly heavy: "800";
+};
+export declare const space: {
+    readonly px: number;
+    readonly '1': number;
+    readonly '2': number;
+    readonly '3': number;
+    readonly '4': number;
+    readonly '5': number;
+    readonly '6': number;
+    readonly '7': number;
+    readonly '8': number;
+    readonly '9': number;
+    readonly '10': number;
+};
+export declare const radius: {
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+    readonly '2xl': number;
+    readonly '3xl': number;
+    readonly pill: 999;
+};
+/** 头像容器尺寸阶梯:xs=18 列表 / sm=28 二级 / md=32 默认 / lg=40 卡片 / xl=56 hero。 */
+export declare const avatar: {
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+};
+/** 图标盒尺寸阶梯(IconBox / 浅色 bg + 中心 icon)。
+ *  icon['2xl'] 与 avatar.xl 同值但语义不同(图标 vs 头像),业务按语义选不要混用。 */
+export declare const icon: {
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+    readonly '2xl': number;
+};
+/** 控件高度阶梯(Button / Stepper / Input / Segmented 通用)。
+ *  lg 44 数值与 fixed.hitTarget 一致,但 lg 是 scaled / hitTarget 是物理常量,语义不同
+ *  不要合用。 */
+export declare const control: {
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+};
+/** 散尺寸 —— 未归到 avatar/icon/control 阶梯的单点常量。 */
+export declare const dim: {
+    /** 发送按钮 32px —— chat PromptInput / 主送出按钮专用,与 avatar.md 同值 */
+    readonly sendBtn: number;
+};
+/** 物理常量表 —— **不**参与缩放,在任何设备上保持同一物理尺寸。
+ *  iOS HIG 要求触控目标 ≥44pt 物理。 */
+export declare const fixed: {
+    readonly hitTarget: 44;
+    readonly navbarH: 44;
+    readonly tabbarH: 50;
+    readonly hairline: number;
+};
+export declare const motion: {
+    readonly fast: 150;
+    readonly base: 200;
+    readonly slow: 300;
+    readonly pulse: 1600;
+};
+//# sourceMappingURL=tokens.d.ts.map

package/lib/typescript/src/theme/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../../src/theme/tokens.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,QAAQ,QAInB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;IAYf,8EAA8E;;IAE9E,uCAAuC;;IAEvC;2DACuD;;IAEvD,gDAAgD;;IAEhD,uDAAuD;;IAEvD,yCAAyC;;CAEjC,CAAC;AAEX,eAAO,MAAM,EAAE;;;;;;CAML,CAAC;AAEX,eAAO,MAAM,KAAK;;;;;;;;;;;;CAYR,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC;AAEX;4DAC4D;AAC5D,eAAO,MAAM,IAAI;;;;;;;CAOP,CAAC;AAEX;;YAEY;AACZ,eAAO,MAAM,OAAO;;;;CAIV,CAAC;AAEX,8CAA8C;AAC9C,eAAO,MAAM,GAAG;IACd,6DAA6D;;CAErD,CAAC;AAEX;+BAC+B;AAC/B,eAAO,MAAM,KAAK;;;;;CAKR,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;CAKT,CAAC"}

package/lib/typescript/src/theme/useTheme.d.ts

@@ -0,0 +1,5 @@
+import { type ThemeContextValue } from './ThemeProvider';
+export declare function useTheme(): ThemeContextValue;
+export declare function useColors(): import("./colors").ColorTokens;
+export declare function useShadow(): import("./shadow").ShadowTokens;
+//# sourceMappingURL=useTheme.d.ts.map

package/lib/typescript/src/theme/useTheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../../../src/theme/useTheme.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAUvE,wBAAgB,QAAQ,IAAI,iBAAiB,CAG5C;AAED,wBAAgB,SAAS,mCAExB;AAED,wBAAgB,SAAS,oCAExB"}

package/lib/typescript/src/theme/useThemedStyles.d.ts

@@ -0,0 +1,19 @@
+import type { ImageStyle, TextStyle, ViewStyle } from 'react-native';
+import type { ColorTokens } from './colors';
+import type { ShadowTokens } from './shadow';
+/** RN 0.85 strict-api 不再导出 `StyleSheet.NamedStyles`,这里本地保留同名约束:
+ *  `{ [k]: ViewStyle | TextStyle | ImageStyle }` —— 给 maker 返回值兜底。 */
+type NamedStyles<T> = {
+    [P in keyof T]: ViewStyle | TextStyle | ImageStyle;
+};
+export type StylesMaker<S extends NamedStyles<S>> = (c: ColorTokens, s: ShadowTokens) => S;
+/**
+ * 接收 (colors, shadow) => StyleSheet 工厂,返回当前主题对应的 themed StyleSheet。
+ *
+ * 缓存依赖 [colors, shadow, maker]。`maker` 必须定义在模块顶层(不要写在组件内联),
+ * 否则引用每次变,缓存失效。ThemeProvider 通过 useMemo([scheme]) 保证主题不变时
+ * colors / shadow 引用稳定。
+ */
+export declare function useThemedStyles<S extends NamedStyles<S>>(maker: StylesMaker<S>): S;
+export {};
+//# sourceMappingURL=useThemedStyles.d.ts.map

package/lib/typescript/src/theme/useThemedStyles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThemedStyles.d.ts","sourceRoot":"","sources":["../../../../src/theme/useThemedStyles.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C;sEACsE;AACtE,KAAK,WAAW,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU;CAAE,CAAC;AAE7E,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,IAAI,CAClD,CAAC,EAAE,WAAW,EACd,CAAC,EAAE,YAAY,KACZ,CAAC,CAAC;AAEP;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,CAAC,EACtD,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GACpB,CAAC,CAGH"}

package/lib/typescript/src/utils/logger/index.d.ts

@@ -0,0 +1,4 @@
+export { createLogger, setLogLevel, getLogLevel, addTransport, removeTransport, } from './logger';
+export type { LogLevel, LogRecord, LogTransport, Logger } from './types';
+export { consoleTransport } from './transports/console';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/utils/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/utils/logger/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/typescript/src/utils/logger/logger.d.ts

@@ -0,0 +1,7 @@
+import type { LogLevel, LogTransport, Logger } from './types';
+export declare function createLogger(scope: string): Logger;
+export declare function setLogLevel(level: LogLevel): void;
+export declare function getLogLevel(): LogLevel;
+export declare function addTransport(t: LogTransport): void;
+export declare function removeTransport(id: string): void;
+//# sourceMappingURL=logger.d.ts.map

package/lib/typescript/src/utils/logger/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../../src/utils/logger/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAa,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAuCzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAGlD;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEhD"}

package/lib/typescript/src/utils/logger/transports/console.d.ts

@@ -0,0 +1,3 @@
+import type { LogTransport } from '../types';
+export declare const consoleTransport: LogTransport;
+//# sourceMappingURL=console.d.ts.map

package/lib/typescript/src/utils/logger/transports/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../../../../src/utils/logger/transports/console.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,YAAY,EAAE,MAAM,UAAU,CAAC;AAelE,eAAO,MAAM,gBAAgB,EAAE,YAO9B,CAAC"}

package/lib/typescript/src/utils/logger/types.d.ts

@@ -0,0 +1,19 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogRecord {
+    level: LogLevel;
+    scope: string;
+    message: string;
+    args: unknown[];
+    ts: number;
+}
+export interface LogTransport {
+    readonly id: string;
+    log(record: LogRecord): void;
+}
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/utils/logger/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/utils/logger/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD"}

package/lib/typescript/src/utils/testID/index.d.ts

@@ -0,0 +1,2 @@
+export { childTestID } from './testID';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/utils/testID/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/utils/testID/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/lib/typescript/src/utils/testID/testID.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `childTestID` —— 把"父 testID + 子 id → 子 testID"的拼接逻辑收口。
+ *
+ * 业务侧 7 处 list-like 组件(Tabs / Segmented / TabBar / Grid / Task /
+ * Sources / ChainOfThought)重复同一三元:
+ *
+ * ```ts
+ * const itemTestID = item.testID ?? (testID ? `${testID}-${item.id}` : undefined);
+ * ```
+ *
+ * 抽 helper:
+ * - `override` 命中 → 用 caller 显式指定
+ * - 父 `parent` 缺失 → undefined(testID 不强制)
+ * - 都没问题 → `{parent}-{id}` 拼接
+ */
+export declare function childTestID(parent: string | undefined, id: string | number, override?: string): string | undefined;
+//# sourceMappingURL=testID.d.ts.map

package/lib/typescript/src/utils/testID/testID.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testID.d.ts","sourceRoot":"","sources":["../../../../../src/utils/testID/testID.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAGpB"}

package/package.json

@@ -0,0 +1,179 @@
+{
+  "name": "@unif/react-native-design",
+  "version": "0.1.0",
+  "description": "Unif 设计系统:theme + icons + utils + components",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace @unif/react-native-design-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest --passWithNoTests",
+    "release": "release-it --only-version"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unif-design/react-native-design.git"
+  },
+  "author": "unif-design <382724935@qq.com> (https://github.com/unif-design)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/unif-design/react-native-design/issues"
+  },
+  "homepage": "https://github.com/unif-design/react-native-design#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/compat": "^2.0.3",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@gorhom/bottom-sheet": "^5.2.14",
+    "@jest/globals": "^30.0.0",
+    "@react-native/babel-preset": "0.85.0",
+    "@react-native/eslint-config": "0.85.0",
+    "@react-native/jest-preset": "0.85.0",
+    "@release-it/conventional-changelog": "^10.0.6",
+    "@sbaiahmed1/react-native-blur": "^4.6.2",
+    "@types/react": "^19.2.0",
+    "commitlint": "^20.5.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.5",
+    "jest": "^30.3.0",
+    "lefthook": "^2.1.4",
+    "prettier": "^3.8.1",
+    "react": "19.2.3",
+    "react-native": "0.85.0",
+    "react-native-builder-bob": "^0.41.0",
+    "react-native-gesture-handler": "^2.31.2",
+    "react-native-reanimated": "^4.3.1",
+    "react-native-reanimated-carousel": "^5.0.0-beta.5",
+    "react-native-safe-area-context": "^5.7.0",
+    "react-native-svg": "^15.15.5",
+    "react-native-worklets": "0.9.1",
+    "release-it": "^19.2.4",
+    "turbo": "^2.8.21",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "@gorhom/bottom-sheet": ">=5",
+    "@sbaiahmed1/react-native-blur": ">=4",
+    "react": "*",
+    "react-native": "*",
+    "react-native-gesture-handler": ">=2",
+    "react-native-reanimated": ">=4",
+    "react-native-reanimated-carousel": ">=5.0.0-beta.0",
+    "react-native-safe-area-context": ">=5",
+    "react-native-svg": ">=15",
+    "react-native-worklets": ">=0.9"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "jest": {
+    "preset": "@react-native/jest-preset",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "create-react-native-library": {
+    "type": "library",
+    "languages": "js",
+    "tools": [
+      "eslint",
+      "jest",
+      "lefthook",
+      "release-it"
+    ],
+    "version": "0.62.0"
+  }
+}

package/src/components/business/AvatarWithRing/AvatarWithRing.tsx

@@ -0,0 +1,59 @@
+import React, { useId, useMemo } from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+import Svg, {
+  Defs,
+  LinearGradient as SvgLinearGradient,
+  Rect,
+  Stop,
+} from 'react-native-svg';
+import { avatarGradient, useTheme } from '../../../theme';
+import { makeAvatarStyles } from './styles';
+import type { AvatarWithRingProps } from './types';
+
+/**
+ * 圆形头像 + 白色 ring + 品牌橙渐变底 + 品牌色 shadow。
+ *
+ * 用 outer shell (bg=ringColor 圆) + inner avatarCore (圆形 overflow:hidden,
+ * 内含 SVG 渐变 + label) 双层模拟 ring,避免 RN Fabric `borderColor + alpha
+ * + borderRadius: 50%` 的 anti-aliasing 渲染缺失(详见 styles.ts)。
+ */
+export function AvatarWithRing({
+  label,
+  size = 64,
+  ringColor,
+  style,
+}: AvatarWithRingProps): React.JSX.Element {
+  const { colors: c, shadow } = useTheme();
+  const autoId = useId();
+  const id = `av-${autoId.replace(/[^a-zA-Z0-9_-]/g, '')}`;
+  const { inner, styles } = useMemo(
+    () =>
+      makeAvatarStyles(size, ringColor ?? c.avatarRing, shadow.brandAvatar, c),
+    [size, ringColor, c, shadow.brandAvatar]
+  );
+  return (
+    <View style={[styles.shell, style]}>
+      <View style={styles.avatarCore}>
+        <Svg width={inner} height={inner} style={StyleSheet.absoluteFill}>
+          <Defs>
+            {/* userSpaceOnUse + 像素坐标 + Rect 数值:
+                避免 BBox 0-1 模式在 RN-svg 小尺寸 + alpha 下渲染为单色。 */}
+            <SvgLinearGradient
+              id={id}
+              x1={0}
+              y1={0}
+              x2={inner}
+              y2={inner}
+              gradientUnits="userSpaceOnUse"
+            >
+              <Stop offset={0} stopColor={avatarGradient[0]} />
+              <Stop offset={1} stopColor={avatarGradient[1]} />
+            </SvgLinearGradient>
+          </Defs>
+          <Rect width={inner} height={inner} fill={`url(#${id})`} />
+        </Svg>
+        <Text style={[styles.label, { lineHeight: inner }]}>{label}</Text>
+      </View>
+    </View>
+  );
+}

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

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

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

@@ -0,0 +1,61 @@
+import { StyleSheet, type ViewStyle } from 'react-native';
+import { fw, r, type ColorTokens } from '../../../theme';
+
+/**
+ * 头像样式工厂 —— **非标 maker 签名**:`(size, ringColor, shadowStyle, c)` 4 参,
+ * 而非项目通用 `(c: ColorTokens, s: ShadowTokens) => StyleSheet` 2 参。
+ *
+ * **为何破例**:`size` / `ringColor` 是 **props 派生**(每次调用值不同,如 ring 宽度
+ * = `size * 0.0625`、label 字号 = `size * 0.40`、inner 直径 = `size - ringWidth*2`),
+ * 标准 `useThemedStyles(maker)` 按 `[colors, shadow]` memo 假设 maker 是模块顶层
+ * 常量,无法承接 props 变化。改走调用点自带 `useMemo([size, ringColor, c,
+ * shadow.brandAvatar])` 精确缓存,signature 因此带上 size/ringColor/shadow 三个
+ * 运行期入参,c 仍传入用于 label 文字色。
+ *
+ * **不用 borderWidth + borderColor 实现 ring**:RN new arch (Fabric) 在
+ * iOS 上对 `borderColor: rgba alpha + borderRadius: width/2`(完全圆)的组合
+ * anti-aliasing 失败,60% 白 ring 在暗 hero 上渲染为接近透明,视觉缺失。
+ *
+ * 改用 outer (shell) + inner (avatarCore) 双层:
+ * - shell:size×size 圆,backgroundColor = ringColor(承担 ring 视觉)+ shadow
+ * - avatarCore:inner×inner 圆,在 shell 内 flex center,内部放 SVG 渐变 + label
+ */
+export const makeAvatarStyles = (
+  size: number,
+  ringColor: string,
+  shadowStyle: ViewStyle,
+  c: ColorTokens
+) => {
+  const dim = r(size);
+  const half = dim / 2;
+  const ringWidth = Math.max(2, r(Math.round(size * 0.0625)));
+  const inner = dim - ringWidth * 2;
+  const innerHalf = inner / 2;
+  const styles = StyleSheet.create({
+    shell: {
+      width: dim,
+      height: dim,
+      borderRadius: half,
+      backgroundColor: ringColor,
+      ...shadowStyle,
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
+    avatarCore: {
+      width: inner,
+      height: inner,
+      borderRadius: innerHalf,
+      overflow: 'hidden',
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
+    label: {
+      fontSize: r(Math.round(size * 0.4)),
+      fontWeight: fw.bold,
+      color: c.onPrimary,
+      letterSpacing: -0.5,
+      textAlign: 'center',
+    },
+  });
+  return { ringWidth, dim, inner, styles };
+};

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

@@ -0,0 +1,15 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type AvatarWithRingProps = {
+  /** 显示在中心的字符(通常 userName 首字母 / 中文名首字)。 */
+  label: string;
+  /**
+   * 头像总直径(含 ring),默认 64(r() 缩放在内部)。
+   * 视觉占比:label 字号约 size * 0.40,ring 宽度约 size * 0.0625。
+   */
+  size?: number;
+  /** ring + 填充背景色,默认 c.primary。 */
+  ringColor?: string;
+  /** 容器附加样式(margin / position 等定位)。 */
+  style?: StyleProp<ViewStyle>;
+};

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

@@ -0,0 +1,81 @@
+import React, { useId } from 'react';
+import { View } from 'react-native';
+import Svg, {
+  Defs,
+  LinearGradient as SvgLinearGradient,
+  Rect,
+  Stop,
+} from 'react-native-svg';
+import type { GradientWashProps } from './types';
+
+/**
+ * 垂直线性渐变 wash —— 全宽矩形 + 顶到底的 SVG LinearGradient。
+ *
+ * 两种用法:
+ * - 简单单色:`<GradientWash height color fromOpacity toOpacity />`,内部生成 2 stop
+ * - 多 stop:`<GradientWash height stops={[...]} />`
+ *
+ * `pointerEvents="none"` 透传,装饰层不捕事件。
+ *
+ * gradientId 不传时用 `useId()` 自动唯一;React 19 useId 返回含冒号 `:r0:`,
+ * 不是合法 SVG id 字符,sanitize 后再用。
+ */
+/** 解析 rgba(r,g,b,a) 字符串拆出 alpha,返回 { color: rgb(...), opacity }。
+ *  非 rgba 输入(hex / rgb / named)原样返回 + opacity=1。
+ *
+ *  Why:react-native-svg `<Stop stopColor>` 接 rgba 时 alpha 可能被忽略
+ *  (stopColor 只解析 RGB,需要 stopOpacity 分离),拆分后跨平台一致。 */
+function parseRgba(color: string): { color: string; opacity: number } {
+  const m = color.match(/^rgba\(([^)]+)\)$/);
+  if (!m || !m[1]) return { color, opacity: 1 };
+  const parts = m[1].split(',').map((s) => s.trim());
+  if (parts.length !== 4) return { color, opacity: 1 };
+  const alphaStr = parts[3];
+  if (alphaStr === undefined) return { color, opacity: 1 };
+  const alpha = parseFloat(alphaStr);
+  if (Number.isNaN(alpha)) return { color, opacity: 1 };
+  return { color: `rgb(${parts.slice(0, 3).join(',')})`, opacity: alpha };
+}
+
+export function GradientWash(props: GradientWashProps): React.JSX.Element {
+  const { height, style, gradientId } = props;
+  const autoId = useId();
+  const id = gradientId ?? `gw-${autoId.replace(/[^a-zA-Z0-9_-]/g, '')}`;
+  const stops = props.stops ?? [
+    { offset: 0, color: props.color, opacity: props.fromOpacity ?? 0.1 },
+    { offset: 1, color: props.color, opacity: props.toOpacity ?? 0 },
+  ];
+  return (
+    <View pointerEvents="none" style={[{ height }, style]}>
+      <Svg width="100%" height={height}>
+        <Defs>
+          {/* gradientUnits="userSpaceOnUse":y1/y2 走像素坐标,
+              否则默认 BBox(0–1)模式下 y2={height} 被解读为 height 倍容器高,
+              渐变退化为均匀色 + 容器底硬切。 */}
+          <SvgLinearGradient
+            id={id}
+            x1={0}
+            y1={0}
+            x2={0}
+            y2={height}
+            gradientUnits="userSpaceOnUse"
+          >
+            {stops.map((s, i) => {
+              const parsed = parseRgba(s.color);
+              const opacity = s.opacity ?? parsed.opacity;
+              return (
+                <Stop
+                  key={`${s.offset}-${i}`}
+                  offset={s.offset}
+                  stopColor={parsed.color}
+                  stopOpacity={opacity}
+                />
+              );
+            })}
+          </SvgLinearGradient>
+        </Defs>
+        <Rect width="100%" height={height} fill={`url(#${id})`} />
+      </Svg>
+    </View>
+  );
+}