# Unif Design — 全文文档聚合

> 单文件聚合版。每段都带源路径与标题，方便整体粘贴给 LLM。

## 目录

- 完整规范
- AvatarWithRing 圆环头像
- Avatar 头像
- BlurLayer 玻璃模糊层
- Button 按钮
- Card 卡片
- Carousel 轮播
- Cell · List 列表行
- Checkbox 复选框
- Chip 标签
- Confirm 确认对话框
- Decorations 装饰图元
- Empty 空态
- EntryCard 入口卡
- Form 表单
- GlassStats 玻璃数据条
- Grid 九宫格
- IconButton 图标按钮
- 图标
- Input 输入框
- Loading 加载
- Logo 主标
- NavBar 导航栏
- 组件概览
- PasswordInput 密码输入框
- Pulse · PulseDot · usePulse
- Radio 单选
- Reveal
- Search 搜索栏
- Skeleton 骨架屏
- StatusDot 状态点
- Stepper 步进器
- Switch 开关
- TabBar 底部 tab 栏
- Tabs 标签页
- Tag 标签
- TextField 输入框 base(internal)
- Textarea 多行输入
- Thumbnail 缩略图
- Toast 轻提示
- VersionPill 版本号药丸
- 全局 Don'ts
- 设计系统
- 设计原则
- 颜色
- 动效
- 间距 · 圆角 · 阴影
- 字体
- 语调与文案
- 快速开始
- 升级 / 迁移
- AI Skill
- 常见问题

## 完整规范

*Source: `docs/UNIF-DESIGN.md` · Slug: `/unif-design`*

# Unif Design — 完整规范

**品牌:** Unif(统一企业 / Uni-President China)
**真相源代码:** `src/theme/`、`src/components/ui/`、`src/components/business/`

> 这是一份**单文件设计宪法** —— 把品牌、原则、token、组件、Don'ts 收在一处,供整体把握与 AI 全量索引(llms-full 锚点)。逐项详情见各拆分页:[原则](/docs/design/principles)、[颜色](/docs/design/tokens/colors)、[字体](/docs/design/tokens/typography)、[间距·圆角·阴影](/docs/design/tokens/spacing-radii-shadows)、[动效](/docs/design/tokens/motion)、[组件概览](/docs/components)。所有 token 值取自 `src/theme`,与代码冲突时以代码为准。

---

## 1. 品牌与 voice {#品牌与-voice}

### 大小写
- 主品牌一律写作 **Unif** —— 不写 `UNIF`、`unif` 或加连字符。
- 子产品形如 `Unif <中文名>`(单个半角空格)。
- 拉丁字符与 CJK 字符之间用单个半角空格。

### 语言
- **中文优先。** 所有 UI 文案、按钮、placeholder、错误提示都是简体中文。
- 英文只出现在代码标识符、wordmark 和品牌名里。

### 语气
- 冷静、指示性、略正式。
- 助手像一个已经熟悉用户业务的同事。
- 不闲聊、不致歉。句子短、动词在前、**不加感叹号**。

### 人称
- 助手:`AI` 或 `助手`(头像内)。
- 用户:`我`(自己头像内)。
- 正文避免第一 / 第二人称,直接陈述事实:`已思考 3s`、`正在执行…`、`AI 回复中…`。

### 状态文案速查
| 场景 | 文案 |
|---|---|
| 工具运行中 | `执行中` |
| 工具完成 | `完成`(或 `完成 · 0.6s`) |
| 工具失败 | `失败` |
| 推理进行中 | `思考中…` |
| 推理完成 | `已思考 3s` |
| 确认发起 | `操作确认` |
| 确认完成 | `已确认，正在执行…` |
| 确认取消 | `已取消` |
| 发送失败 | `发送失败，请重试` |
| 输入空闲 | `输入消息…` |
| AI 流式回复 | `AI 回复中…` |

### 建议 chip(空状态)
像用户口气 —— 疑问句或祈使句,**不加句号**:`今天要拜访哪些客户？` · `帮我查一下今天的计划` · `新建一个拜访记录`。

### 标点
- 全角中文:`，` `。` `？` `：`
- 西文省略号 `…` 用于流式 / 加载。
- 中点 `·` 分隔行内元数据:`名称 · 地址`。

### Emoji
**禁用。** 无国旗 emoji、贴纸、装饰字符。功能性状态走图标。字符不传递信息就不该出现。

> 详见[语调与文案](/docs/design/voice)。

---

## 2. 设计原则(5 条) {#设计原则}

1. **中文优先。** 所有 UI 简体中文,英文仅品牌与代码。
2. **橙色克制。** `#EB6E00` 仅用于主按钮、用户气泡、活动标签、关键强调。蓝色(`#3775F6`)专属用户头像。
3. **无装饰。** 无插画、无渐变背景(仅品牌橙渐变)、无装饰 emoji。所有图标是手绘 24×24 描边 SVG。
4. **列表用 gap,不用 border。** 每行独立白卡,行间 gap 形成分组(iOS 17 / 微信新版风格)。
5. **气泡内角方。** 聊天气泡 14px 圆角,但指向头像的内角**直角(0)**。这是 Unif 最辨识度的视觉签名。

> 详见[设计原则](/docs/design/principles);硬性禁忌见[全局 Don'ts](/docs/design/donts)与本文 §14。

---

## 3. 颜色系统 {#颜色系统}

> Token 按 Material 3 system tokens 风格 **role 化命名**;不引入 reference layer / tonal palette。
> 主题跟随系统(`useColorScheme()`),亮 / 暗各一套值,role 名固定不变。值的真相源是 `src/theme/colors.ts`。

### 3.1 Brand {#brand}

| role | light | dark | 用途 |
|---|---|---|---|
| `primary` | `#EB6E00` | `#EB6E00` | 品牌橙;亮 / 暗共用(identity 不变) |
| `primaryPressed` | `#D06200` | `#D06200` | 按下态;亮 / 暗共用 |
| `primaryContainer` | `#FFF5EB` | `#3D1F00` | 高亮选中背景 |
| `primaryContainerSubtle` | `#FFF8F0` | `#2A1500` | Card 选中背景 |
| `onPrimary` | `#FFFFFF` | `#FFFFFF` | 品牌底上的内容色 |
| `onPrimaryMuted` | `rgba(255,255,255,0.85)` | `rgba(255,255,255,0.85)` | 品牌底上的次级文字 |

**Avatar 渐变**(数组,不暴露为 role):`avatarGradient = ['#F49443', '#EB6E00']`(135°,Me hero 头像;亮 / 暗共用)。平铺橙 `#EB6E00` 在 90% 场景足够,**不要引入新渐变**。历史 `brandGradient` / `brandGradientSoft` 已随死代码清理移除(0 消费)。

### 3.2 Semantic {#semantic}

| role | light | dark | 用途 |
|---|---|---|---|
| `success` | `#52C41A` | `#52C41A` | 成功态 |
| `successContainer` | `#F0FFF0` | `#0E2810` | success badge 底 |
| `onSuccess` | `#FFFFFF` | `#FFFFFF` | success 上的内容 |
| `error` | `#F4511E` | `#FF6B40` | 错误 / destructive |
| `errorContainer` | `#FFF5F5` | `#2A1010` | error badge 底 |
| `onError` | `#FFFFFF` | `#FFFFFF` | error 上的内容 |
| `info` | `#3775F6` | `#5A91FF` | **仅用户头像**(Tag info variant 历史沿用) |
| `infoContainer` | `#F0F5FF` | `#0F1A33` | info badge 底 |
| `onInfo` | `#FFFFFF` | `#FFFFFF` | info 上的内容 |

### 3.3 Surface(5 层) {#surface}

| role | light | dark | 用途 |
|---|---|---|---|
| `background` | `#F5F5F5` | `#0A0A0A` | 整页底色(OLED 友好) |
| `surface` | `#FFFFFF` | `#1C1C1E` | Card / Sheet / 气泡 |
| `surfaceContainer` | `#F5F5F5` | `#2C2C2E` | 卡内输入框 / 次级面 |
| `surfaceContainerHigh` | `#F0F0F0` | `#3A3A3C` | 次按钮 / 按下态 |
| `surfaceContainerHighest` | `#E0E0E0` | `#48484A` | disabled 按钮 / pill |

### 3.4 Foreground {#foreground}

| role | light | dark | 用途 |
|---|---|---|---|
| `foreground` | `#333333` | `#FFFFFF` | 主文字 |
| `foregroundMuted` | `#666666` | `rgba(235,235,245,0.6)` | 次级文字 |
| `foregroundSubtle` | `#999999` | `rgba(235,235,245,0.3)` | 三级文字 / placeholder |
| `onSurface` | = `foreground` | = `foreground` | 别名 |
| `onSurfaceMuted` | = `foregroundMuted` | = `foregroundMuted` | 别名 |

### 3.5 Outline {#outline}

| role | light | dark | 用途 |
|---|---|---|---|
| `outline` | `#EDEDED` | `#3A3A3C` | 默认 hairline |
| `outlineVariant` | `#E8E8E8` | `#48484A` | 次级 hairline |
| `outlineFaint` | `#F5F5F5` | `rgba(84,84,88,0.65)` | 最弱 hairline |

### 3.6 Inverse {#inverse}

| role | light | dark | 用途 |
|---|---|---|---|
| `inverseSurface` | `#1C1C1E` | `#FFFFFF` | toast / tooltip 反色底 |
| `inverseOnSurface` | `#FFFFFF` | `#000000` | inverseSurface 上的内容 |

### 3.7 Misc {#misc}

| role | light | dark | 用途 |
|---|---|---|---|
| `scrim` | `rgba(0,0,0,0.5)` | `rgba(0,0,0,0.7)` | Sheet 遮罩;暗色加深 |
| `sheetBackdrop` | `rgba(245,245,247,0.72)` | `rgba(245,245,247,0.72)` | 合规 sheet 之下浅 tint(焦点引导) |

> `colors.ts` 另有一批玻璃感(`glassTintLight` / `glassBorder` / `glassActiveFg` / `glassPillBg`…)、Hero 渐变(`heroGradient0/1/2`)、淡阶图标(`iconFaint40/30/25`)、头像 ring 等专用 role,多数亮 / 暗 alpha **故意不同**(逐条注释了原因,不要归一化)。完整清单见源码。

### 3.8 为什么 role-based、不要 reference layer {#为什么-role-based}

行业(Material 3 / Apple HIG / Tailwind / GitHub Primer / IBM Carbon)共识:design token 按**角色**命名(`primary` / `surface` / `outline`),而非按强度档(`gray100` / `orange500`)。Unif 不引入 M3 的 reference layer / tonal palette:

1. reference layer 的价值在"多 brand / 多产品共享 palette";Unif 单 brand 单 app,无此需求。
2. role 层已是组件需要的全部抽象,reference 多一层间接、无功能收益。
3. Tailwind / shadcn-ui 也是单层 role + hex,生态无差异。

未来要加 reference 是纯加法:role 里的 hex 抽到 reference,role 改成引用 reference,组件代码 0 改动。

### 3.9 暗色哲学 {#暗色哲学}

- **iOS HIG dark 风格**:纯黑 / 近黑 `background`(`#0A0A0A`)+ 深灰多层 `surface`(`#1C / #2C / #3A / #48`),OLED 友好。
- **品牌橙保留原值**(亮 / 暗均 `#EB6E00`):在 `#0A0A0A` 上对比度过 WCAG AA,无需调亮。
- **layered surface 替代 shadow**:暗色下 shadow token 的 `shadowOpacity` / `elevation` 多数置 0(例外见 §7);深度靠 surface 5 层明度差。
- **"内角方"气泡签名完整保留**。

### 3.10 颜色规则 {#颜色规则}

- 无近黑、无米白、无染色灰,中性色保持纯净。
- 品牌橙只在主按钮 / 用户气泡 / 活动标签 / 关键强调。
- 蓝色(`info`)专属用户头像(Tag info variant 历史沿用,不扩散)。
- **绝不内联 hex / rgba** —— 走 `useColors()` role token,新硬编码挂 CI。取色优先级链见[颜色 → 取色优先级链](/docs/design/tokens/colors#取色优先级链)。旧 token → 新 role 的 grep 对照见[迁移](/docs/migration#旧-token-名--新-role-名)。

---

## 4. 字体 {#字体}

### 字体栈(仅系统,无 webfont)
```
-apple-system, BlinkMacSystemFont, "PingFang SC", "Hiragino Sans GB",
"Microsoft YaHei", "Helvetica Neue", Helvetica, Arial, sans-serif
```
Mono(`fontMono` token):iOS `Menlo` / Android `monospace`。品牌刻意依赖 OS 渲染原生中文字形,**不引入 webfont**。

### 字号阶梯 `type`(移动优先,经 `rf()` 缩放)
| Token | 基准 px | 用途 |
|---|---|---|
| `display` | 22 | 品牌标题 |
| `h1` | 18 | 页面标题 |
| `h2` | 17 | 区块标题 |
| `h3` | 15 | 卡片标题 / 强调正文 |
| `body` | 15 | 默认正文 |
| `sm` | 14 | 次级正文 / 按钮 |
| `xs` | 13 | 提示、说明 |
| `xxs` | 12 | meta、caption |
| `micro` | 11 | 徽章、工具名 |
| `nano` | 10 | TabBar / Grid / Citation / Sources 角标 |

半档微调:`smPlus`(14.5)· `xsPlus`(13.5)· `microPlus`(11.5)。Hero 档:`heroLg`(26)· `heroMd`(22)· `heroSm`(18)。完整说明见[字体](/docs/design/tokens/typography)。

应用级字号缩放(app 内字体大小档):接入方传 `<ThemeProvider fontScale={…}>`(默认 1),`useThemedStyles` 出口对 maker 产物的 `fontSize / lineHeight / letterSpacing` 统一缩放 —— 与 RN `allowFontScaling` 的原生缩放范围一致,只缩文字不缩布局。与 `rf()` 正交:`rf()` 是按屏宽的静态适配,`fontScale` 是运行期用户档位。

### 行高(惯例,非 token)
**没有 `lineHeight` token。** 行高用字号乘系数:标题 ×1.25、正文 ×1.45(直接写 `lineHeight: t.body * 1.45`)。

### 字重 `fw`
`fw.regular` `'400'` · `fw.medium` `'500'` · `fw.semi` `'600'` · `fw.bold` `'700'` · `fw.heavy` `'800'`。用 `as const` 声明,无需再 cast。

---

## 5. 间距 `space` {#间距}

4px 基准网格(多数值经 `r()` 像素对齐缩放):
| Token | 基准 px | 常用 |
|---|---|---|
| `px` | 1 | hairline 级位移 |
| `1` | 4 | 最紧间隙 |
| `2` | 6 | 图标-文字间隙 |
| `3` | 8 | 头像-气泡间隙、列表行间 gap |
| `4` | 10 | 气泡纵向 padding |
| `5` | 12 | 气泡横向 padding、栏间距 |
| `6` | 14 | 卡片 padding |
| `7` | 16 | 区块栏间距 |
| `8` | 20 | 较大区块间距 |
| `9` | 24 | Hero padding |
| `10` | 32 | 通栏区块间距 |

**规则。** 屏幕侧边距 12–16px。气泡 padding `10px 12px`。卡片 `12–14px`。尊重安全区(iOS home indicator 34px)。`space` key 是字符串字面量(`space['7']`)。

---

## 6. 圆角 `radius` {#圆角}

| Token | 基准 px | 用途 |
|---|---|---|
| `xs` | 4 | Radio / Checkbox / Tag / Citation 内圈 |
| `sm` | 6 | 小按钮、徽章 |
| `md` | 8 | 输入框、默认按钮 |
| `lg` | 10 | 卡片、列表行 |
| `xl` | 12 | 大卡片、列表容器 |
| `2xl` | 14 | **聊天气泡** |
| `3xl` | 18 | 输入框 wrapper |
| `pill` | 999 | chip、pill(大数哨兵,不缩放) |

### 气泡 motif(签名)
- **AI 气泡:** `border-radius: 0 14px 14px 14px`(左上角直角)
- **用户气泡:** `border-radius: 14px 0 14px 14px`(右上角直角)

直角指向头像 —— Unif 最辨识度的 UI motif,保留它。

---

## 7. 阴影 `shadow`(themed) {#阴影}

中性卡片阴影 + 品牌橙光晕两类。**无内阴影、无霓虹光晕、无双重边框。** 走 `useShadow()` / `useThemedStyles` 第二参拿。

| Token | 用途 | RN(亮色) |
|---|---|---|
| `subtle` | Segmented active 段等轻提示浮起 | `{0,1}` · op 0.06 · r 2 · elev 1 |
| `card` | 标准卡片下沉(Card default) | `{0,1}` · op 0.08 · r 4 · elev 2 |
| `floating` | 中性浮岛(贴底浮起胶囊) | `{0,16}` · op 0.1 · r 40 · elev 12 |
| `brandSm` | 品牌光晕 sm | 橙 · `{0,6}` · op 0.08 · r 18 · elev 3 |
| `brandMd` | 主按钮 / Avatar ring 中等强调 | 橙 · `{0,12}` · op 0.26 · r 24 · elev 12 |
| `brandLg` | Login Logo halo | 橙 · `{0,16}` · op 0.22 · r 36 · elev 12 |
| `brandXl` | Splash Logo 最重浮起 | 橙 · `{0,20}` · op 0.2 · r 50 · elev 12 |
| `brandAbout` | About icon halo | 橙 · `{0,18}` · op 0.28 · r 40 · elev 12 |
| `brandAssistant` | AssistantCard icon tile | 橙 · `{0,8}` · op 0.3 · r 18 · elev 12 |
| `brandAvatar` | Avatar 品牌橙光晕 | 橙 · `{0,10}` · op 0.28 · r 24 · elev 12 |
| `glassBar` | GlassStats 数据条专用 | 橙 · `{0,6}` · op 0.08 · r 18 · elev 3 |
| `none` | 列表行 / 设置项 | 全 0 |

**暗色态:layered surface 替代 shadow。** 多数 token 暗色下 `shadowOpacity` / `elevation` 置 0;深度靠 `surface` 5 层明度差(§3.3)。**例外:`floating` / `glassBar`(黑色 drop shadow)与 `brandAvatar`(橙光晕)暗色不置零** —— 否则浮岛 / 数据条 / 头像在暗底贴平。确认卡片用 `2px` 彩色边框,无阴影。

---

## 8. 动效 `motion` {#动效}

功能性、快速。仅 fade + layout,**无弹簧、无回弹、无入场缩放**。尊重 reduced-motion。

| Token | 值 | 用途 |
|---|---|---|
| `fast` | 150ms | 按压态、hover |
| `base` | 200ms | 分段控件、布局变化、Modal fade |
| `slow` | 300ms | Drawer 过渡 |
| `pulse` | 1600ms | "思考中" spark 脉冲全周期(`usePulse` 取半周期 = `pulse / 2`) |

**没有 easing token** —— 缓动由 reanimated `withTiming` 默认曲线承担(Spinner 显式用 `Easing.linear`),自定义缓动从 `react-native-reanimated` import `Easing`。

**按压态。** 非品牌表面 `opacity: 0.7`;品牌 CTA 切到 `c.primaryPressed`(`#D06200`);禁用 = 按钮 `opacity: 0.5` 或送出键背景 `c.surfaceContainerHighest`(`#E0E0E0`)。

---

## 9. 图标 {#图标}

仅 inline SVG —— **无 icon font、无 Unicode 承载 UI、无装饰 emoji**。

### 绘制规范(每个 glyph)
| 属性 | 值 |
|---|---|
| viewBox | `0 0 24 24` |
| stroke-width | `1.75`(heavy 变体 `2`) |
| stroke-linecap | `round` |
| stroke-linejoin | `round` |
| fill | `none`(填充 glyph 用 `fill="currentColor"`) |
| color | 经 `currentColor` 继承 |
| 默认尺寸 | inline 16–20px,standalone 24px |

**头像**是字符型(单字符 monogram 落在色盘上)。不要发明插画式 SVG(云朵、有表情的机器人、波浪线)。

**RN 实现。** `src/components/ui/Icon/Icon.tsx` 用 `react-native-svg`(`<Svg>` + `<Path>` / `<Circle>` / `<Rect>`),从 `src/icons` 目录读路径数据。源 SVG 在 `src/icons/svg/<name>.svg`,生成的目录在 `src/icons/data.ts`(由 `scripts/build-icons.js` 离线生成,**不要手改**,头部有 `AUTO-GENERATED — DO NOT EDIT BY HAND`)。

**加新图标:** 扔 SVG 到 `src/icons/svg/<name>.svg` → 跑 `node scripts/build-icons.js` → `yarn lint --fix`(prettier 把 `IconName` union 拆行)→ `yarn typecheck`。`IconName` 是闭集,组件 prop 类型自动同步;文档站镜像在 `website/src/components/iconsCatalog.ts`。详见[图标页](/docs/components/icons)。

---

## 10. 组件库 {#组件库}

按设计系统分组。**本包(`@unif/react-native-design`)实现 38 个 ui 原子 + 4 个通用业务复合组件**;聊天 / IM 组件(Message / PromptInput 等)是同一套设计语言,但代码在 portal 仓库,这里只描述其视觉契约。

### 品牌
- **Logo** —— `<Image>` 包装容器,接 `source` prop(母版 mark 由消费者提供)。
- **Icon** —— 24×24 描边 SVG 目录。

### 通用
- **Button** —— variant:`primary` / `secondary` / `ghost` / `outline` / `danger` / `text`;size:`sm` / `md` / `lg`;可 `block`。
- **IconButton** —— 纯图标按钮,`accessibilityLabel` 类型必填。
- **Avatar** —— 单字符 monogram。variant:`brand` / `info` / `soft` / `neutral`;size:`xs`(18)/ `sm`(28)/ `md`(32)/ `lg`(40)/ `xl`(56)。
- **Tag** —— 状态徽章,5 语义 × 2 尺寸(`md` / `lg`)。
- **Chip** —— 胶囊形可选中 pill;`selected` 切主色边框 / 文本;可带 leading / trailing。Suggestion 底层。
- **Confirm** —— 命令式 `confirm(): Promise<boolean>` + `<ConfirmHost />`,高风险二次确认(同一时间只 1 个对话框;裸 RN Modal + pub/sub,不依赖 @gorhom)。
- **Thumbnail** —— 16:9.5 缩略图,`sm 64×40 / md 113×67 / lg 160×96`。
- **Loading** —— `Spinner`(reanimated 4 旋转)+ 线性进度。
- **Pulse** —— `usePulse` + `<Pulse>` + `<PulseDot>`,reanimated 4 worklet 通用脉冲。Skeleton / Shimmer / Reasoning 等建立其上。
- **StatusDot** —— `done` / `active` / `pending` 圆点,`flat` / `soft` 双 tone。

### 表单
- **Input** —— 单行;状态 `idle` / `focus` / `filled` / `error`。
- **PasswordInput** —— Input + secureTextEntry + 明文切换。
- **Textarea** —— 多行(复用 Input,顶对齐)。
- **TextField** —— 带 label / 校验的字段封装。
- **Search** —— 搜索条(Input 预设,`accessibilityRole='search'`)。
- **Checkbox / Radio / Switch / Stepper** —— 选择 / 开关 / 步进。
- **Form** —— Form / FormGroup / FormRow(行间 hairline)。

### 导航
- **NavBar** —— 固定顶部头,44px。default(白 + hairline)/ `brand`(渐变)。
- **TabBar** —— 固定底部 tab,50px,带 badge。
- **Tabs / Segmented** —— 页级下划线 / 局部分段,共用 `TabItem` 形状。
- **Drawer** —— `DrawerHeader` + `@react-navigation/drawer`。

### 反馈
- **Toast** —— 命令式 `toast()` + `<ToastHost />`,全局轻提示,自动消失。
- **Empty** —— 空状态。
- **Skeleton** —— 骨架占位,`shape='line'/'rect'/'circle'`(走 `usePulse`)。

### 数据展示
- **Cell · List** —— 列表行 + List 容器,两模式互斥:**grouped**(默认,白卡 + 8px gap,无 cell 间分隔线)/ **flush**(`<List flush />`,透明底 + cell 间 hairline)。
- **Card** —— 内容卡。variant `default`(白底 + card shadow + 边框)/ `plain`(仅白底,无阴影无边框);`flat` 已 deprecated 等价 `plain`。
- **Grid** —— 九宫格图标网格。
- **Carousel** —— 轮播(包装 reanimated-carousel v5)。

### 其他 ui
- **BlurLayer** —— BlurView + tint 双层,intensity `soft`(10)/ `strong`(40)。
- **EntryCard** —— 横向小卡入口(Me 屏"设置 / 关于"双列)。
- **Reveal** —— 进出过渡封装(收口 web 特化)。

### 业务复合(本包 4 个)
通用部分(不耦合 navigation / store);耦合的(ScreenLayout / CellList / ModernAppCell / SmsCodeInput)留在消费者仓库。
- **AvatarWithRing** —— 圆形头像 + ring + 品牌 shadow。
- **GlassStats** —— 玻璃数据条(BlurView + N 列)。
- **Decorations** —— `GradientWash`(线性渐变)+ `RadialHalo`(径向柔光)+ `ScreenBackdrop`(整屏沉浸渐变,`preset="warmOrange"` + 暗色自适配),纯装饰层 `pointerEvents="none"`。
- **VersionPill** —— 版本号药丸。

### 聊天(设计语言,代码在 portal)
Message(非对称圆角气泡)· PromptInput(4 态)· Attachments · Suggestion · Sources · Citation · Reasoning(`思考中…` → `已思考 N.Ns`)· ChainOfThought · Task · Tool · Confirmation(**内联**,绝不模态)· Shimmer · DayDivider。Conversation = 完整线程,由 chat 与 ui 原子组合而成。

> 逐组件 API / props / variant / size 见各[组件页](/docs/components)与远程 [llms.txt](https://unif-design.github.io/react-native-design/llms.txt)。

---

## 11. 布局规则 {#布局规则}

- **固定顶部头**,44px;**固定底部输入框**;消息流在两者之间滚动;Drawer 从左滑入。
- 聊天列表**不**用悬浮操作按钮或 sticky banner。
- 确认与队列**内联**渲染在消息流里,绝不模态(模态仅留给登录选租户)。
- **透明与模糊:** 玻璃感由专用 token(`glassTintLight` 等)+ `BlurLayer` 承担;通用遮挡用 `scrim`。
- **图像:** app 内无图像。头像是单字符 monogram。无照片、插画。
- **卡片:** 白底、`radius.xl`(12)、`12–14px` padding、`card` shadow;列表式卡片(设置行 / 组项)无阴影无边框,靠灰底上的 gap 分隔。

---

## 12. RN 落地图 {#rn-落地图}

路径别名 `@/*` → `src/*`(`tsconfig.json` paths + `babel.config.js` module-resolver)。动画走 `react-native-reanimated@4` worklet;触控走 `react-native-gesture-handler`;键盘走 `react-native-keyboard-controller`。**库代码内部走相对路径,不用 `@/` 别名。**

```
src/
├── icons/                   ← 图标目录(见 §9)
│   ├── svg/*.svg            ← 源 SVG(在这编辑)
│   ├── data.ts              ← 生成的 IconName / ICONS(只读,勿手改)
│   └── index.ts             ← barrel(从 src/icons import)
│
├── theme/
│   ├── colors.ts            ← lightColors / darkColors / ColorTokens(role-based,§3)
│   ├── palettes.ts          ← 渐变序列(warmOrangePalette,塞不进单值 role 的色组)
│   ├── shadow.ts            ← lightShadow / darkShadow / ShadowTokens(themed;暗色趋零)
│   ├── tokens.ts            ← type / fw / space / radius / avatar / icon / control / dim / fixed / motion(非主题)
│   ├── scale.ts             ← r() 像素对齐缩放 / rf() 字号缩放(基准宽 402)
│   ├── blur.ts              ← blur soft(10)/ strong(40)
│   ├── ThemeProvider.tsx    ← context provider,读 useColorScheme();forceScheme? 可强制;fontScale?(默认 1)应用级字号缩放
│   ├── useTheme.ts          ← useTheme / useColors / useShadow(缺 Provider 时 fallback light)
│   ├── useThemedStyles.ts   ← useThemedStyles(maker),含 useMemo([colors, shadow, fontScale, maker]) 缓存;出口按 fontScale 缩放 fontSize / lineHeight / letterSpacing(=1 恒等)
│   └── index.ts             ← barrel
│
├── components/ui/           ← 38 个原子组件(Avatar / Button / Card / Cell / Icon / Input / NavBar / Toast / ...)
│   └── index.ts             ← barrel(从 @unif/react-native-design 包根导出)
│
└── components/business/     ← 4 个通用业务复合(AvatarWithRing / Decorations / GlassStats / VersionPill)
    └── index.ts             ← barrel
```

公共入口 `src/index.tsx` re-export:`./theme`(token + Provider + hooks + r/rf)、`./icons`、`./utils/testID`、`./utils/logger`、`./components/ui`、`./components/business`。

> 关于 example / website workspace、构建(react-native-builder-bob)、测试边界、TS 严格度等工程细节,见仓库 `CLAUDE.md`。

---

## 13. Recipes {#recipes}

### 用 token(themed,role-based)
颜色和 shadow 走 hook(跨亮 / 暗自动切换);非颜色 token(type / fw / space / radius / motion)静态 import。

```ts
// styles.ts —— maker 工厂,接收 (c, s) 注入主题
import { StyleSheet } from 'react-native';
import type { ColorTokens, ShadowTokens } from '@unif/react-native-design';
import { type as t, fw, space, radius } from '@unif/react-native-design';

export const makeStyles = (c: ColorTokens, s: ShadowTokens) =>
  StyleSheet.create({
    card: {
      backgroundColor: c.surface,
      borderRadius: radius.xl,
      padding: space['6'],
      ...s.card,                  // 暗色下 shadowOpacity / elevation 自动趋零
    },
    title: { fontSize: t.h3, fontWeight: fw.semi, color: c.foreground },
  });
```

```tsx
// Component.tsx —— 入口加 hook,组件消费 styles
import { useThemedStyles } from '@unif/react-native-design';
import { makeStyles } from './styles';

export function MyCard({ title }: { title: string }) {
  const styles = useThemedStyles(makeStyles);
  return (
    <View style={styles.card}>
      <Text style={styles.title}>{title}</Text>
    </View>
  );
}
```

字面量颜色(`'#fff'` / `rgba(...)`)在组件层禁止,必须经 token。inline 取色用 `useColors()`。

### 命令式 toast
根附近挂一次 `<ToastHost />`,然后任意位置调用:
```tsx
import { toast } from '@unif/react-native-design';

toast('已保存');
toast.success('订单提交成功');
toast.error('网络异常，请重试');
```

### 加新颜色 / token
- 颜色 role:在 `src/theme/colors.ts` 给 `lightColors` 和 `darkColors` **同时**加同名 key(TS 编译期强制对齐键集合)。
- shadow:在 `src/theme/shadow.ts` 给 `lightShadow` / `darkShadow` 同时加;暗色版 `shadowOpacity` / `elevation` 通常置 0。
- 非主题 token(type / fw / space / radius / motion / dim):在 `src/theme/tokens.ts` 加。
- 同步更新本文 §3–§8。
- 不引入紫 / 蓝 accent(蓝色专属用户头像);不在品牌橙之外加渐变。

### 加新组件
1. 读 §1(voice)与 §2(原则)。
2. 定位(每组件一个独立目录 `<Name>/<Name>.tsx + types.ts + styles.ts + index.ts`):净新原子 → `src/components/ui/<Name>/`;通用业务复合 → `src/components/business/<Name>/`。
3. **组合现有原子**,不重造样式(如"带 Switch 的设置行" = `<Cell title="..." extra={<Switch ... />} />`)。
4. token 从包根 import,绝不硬编码 hex / px / radius。
5. 从本地 `index.ts` barrel 导出,并在本文 §10 / §12 登记。

---

## 14. Don'ts(load-bearing) {#donts}

- ❌ 不在品牌橙(Logo 圆 / Drawer header)之外加渐变。
- ❌ 不加紫 / 蓝 accent —— 蓝色**专属**用户头像。
- ❌ UI 文案不用装饰 / 国旗 emoji,功能性状态走图标。
- ❌ 不写英文 UI 文案(除非明确要求),产品出货简体中文。
- ❌ 不引入新字体,系统栈 + PingFang SC 是全部。
- ❌ 不用模态替换内联确认(模态仅留给登录选租户)。
- ❌ 不破坏 §6 气泡非对称圆角(指向头像的直角是签名)。
- ❌ 列表行不用 `border-bottom`,用白卡 + 8px gap。
- ❌ 不硬编码颜色 / 字号 / 间距;不把 `makeStyles` 内联进组件。

> 完整清单见[全局 Don'ts](/docs/design/donts)。

---

## 15. Logo {#logo}

`Logo` 组件是 `<Image>` 的标准化包装(尺寸 / 圆角 / a11y),**母版 PNG 由消费者提供**,通过 `source` prop 传入 —— 本设计包不内置 logo 资源。

```tsx
// React Native
import { Logo } from '@unif/react-native-design';
<Logo source={require('@/assets/logo.png')} size={64} label="Unif" />
```

文档站的 navbar / OG / favicon 三槽都指向 `website/static/img/logo.png` 这一份(`docusaurus.config.ts`)。母版是 `#EB6E00` 橙底的品牌标识,**不要重绘 / 替换 / 重新着色 / 加阴影滤镜**;最小尺寸 24×24。

---

## 16. 给新 agent / 新会话的 Quickstart {#quickstart}

接手项目时它有:

- RN 0.85 / React 19,新架构(Fabric + TurboModules)默认开启。
- 完整设计系统:38 ui + 4 业务复合组件,全套 token(`colors / shadow / type / fw / space / radius / avatar / icon / control / dim / fixed / motion / blur / fontMono`)在 `src/theme/`,亮 / 暗双套经 `ThemeProvider` + `useThemedStyles`;SVG 图标目录在 `src/icons/svg/` + 生成的 `src/icons/data.ts`(只读)。
- 单元 / 集成测试在 `__tests__/`(Jest + `@testing-library/react-native`)。
- Docusaurus 文档站在 `website/`。
- 本文 —— 单一权威文本参考。

### Provider 栈
`GestureHandlerRootView → KeyboardProvider → SafeAreaProvider → ThemeProvider → NavigationContainer → RootNavigator` + `<ToastHost />`(挂一次,任意位置可 `toast(...)`)。worklets babel 插件 `react-native-worklets/plugin` 注册在最后。

### 任何 UI 改动的流程
1. 读 §1(voice)与 §2(原则)—— 不可妥协。
2. 读 §3–§9(token / 图标)。
3. **组合,不重造** —— 看 §10 有哪些原子,复用 `Card` / `Cell` / `Tag` / `Chip` / `Avatar` / `Button`。
4. import 走包根 barrel,token 从包根。
5. 新组件按 §13 流程,完成后更新 §10 / §12。
6. 提交前:`yarn typecheck` · `yarn lint` · `yarn test`。

### "X 长什么样"去哪看
- **静态规范:** 本文 §3–§11 + 对应 `website/docs/...` 页。
- **可视 + 交互:** `cd website && npm start`,每个组件页有 `<LiveDemo>`。
- **生产代码:** `src/components/{ui,business}/<Component>.tsx`,直接读。
- **用法示例:** `__tests__/...` 文件可当代码样例。

---

_权威参考结束。_

## AvatarWithRing 圆环头像

*Source: `docs/components/avatar-with-ring.mdx` · Slug: `/components/avatar-with-ring`*

# AvatarWithRing 圆环头像

中心字符(userName 首字)+ **品牌橙渐变内核** + 外圈 ring + 品牌橙 shadow,用于个人名片 / 头像区。比 `<Avatar>` 多一圈强调边,适合视觉重心。

内核底色固定为品牌橙渐变(`#F49443 → #EB6E00`),`ringColor` 只控制外圈 ring 的颜色;label 字号约 `size * 0.40`,ring 宽度约 `size * 0.0625`(随 `size` 缩放)。

## 实时预览

下方渲染的就是 `src/components/business/AvatarWithRing/AvatarWithRing.tsx` 本体。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">默认 · 64 直径 · c.avatarRing ring</span>
      <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
        <AvatarWithRing label="刘" />
        <AvatarWithRing label="A" />
        <AvatarWithRing label="张" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">size · 48 / 64 / 88 / 120</span>
      <div style={{ display: 'flex', gap: 16, alignItems: 'flex-end' }}>
        <AvatarWithRing label="刘" size={48} />
        <AvatarWithRing label="刘" size={64} />
        <AvatarWithRing label="刘" size={88} />
        <AvatarWithRing label="刘" size={120} />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">ringColor · 自定义 hex</span>
      <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
        <AvatarWithRing label="A" ringColor="#3775F6" />
        <AvatarWithRing label="B" ringColor="#22A56E" />
        <AvatarWithRing label="C" ringColor="#8C8C8C" />
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { AvatarWithRing } from '@unif/react-native-design';

{/* 个人名片屏 hero 头像 */}
<AvatarWithRing label={userName.charAt(0)} size={96} />

{/* 自定义品牌色 ring */}
<AvatarWithRing label="A" ringColor="#3775F6" size={64} />
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `label` | `string` | — | 中心文字(通常 1 字符,姓名首字) |
| `size` | `number` | `64` | 总直径(含 ring),`r()` 缩放在内部处理 |
| `ringColor` | `string` | `c.avatarRing` | **外圈 ring** 颜色(内核底色固定为品牌橙渐变,不受此控制) |
| `style` | `StyleProp<ViewStyle>` | — | 容器附加样式(margin / position) |

## 无障碍（a11y）

来源：`src/components/business/AvatarWithRing/AvatarWithRing.tsx`、`types.ts`。

本组件为展示 / 装饰用，无交互（渲染为 `<View>` 外壳，内含 SVG 渐变 + `<Text>` label）。源码**未设置任何 a11y prop**（既无 `accessibilityRole` 也无 `accessibilityLabel`）——中心 `label` 仅作为可见 `<Text>` 渲染，因此 screen reader 默认会读到该文字，但不会带头像语义。如需承载语义（如可点击进入资料页），请由父级可点区域设置 `accessibilityLabel` / `accessibilityRole`。

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.avatarRing` | `useColors()` | 外圈 ring 默认色(可被 `ringColor` 覆盖) |
| `c.onPrimary` | `useColors()` | 中心 label 文字色(恒定白) |
| `avatarGradient` | `@unif/react-native-design` | 内核渐变底(`#F49443 → #EB6E00`,亮 / 暗共用) |
| `s.brandAvatar` | `useTheme().shadow` | 品牌橙光晕 shadow(暗色保留橙晕托起头像) |
| `fw.bold` | `@unif/react-native-design` | label 字重 |

## 视觉规范

| 元素 | 比例 / 取值 |
|---|---|
| label 字号 | `size × 0.40` |
| ring 宽度 | `size × 0.0625`(下限 2px) |
| 内核底色 | `avatarGradient`(135° 品牌橙渐变,固定) |
| label 色 | `c.onPrimary`(恒定) |
| shadow | `s.brandAvatar`(品牌橙 elevation) |

## 不要

- 不要塞多字符 label —— 设计是单字符(姓名首字 / 字母),多了会溢出
- 不要替代 `<Avatar>` —— Avatar 是基础原子(无 ring),AvatarWithRing 是装饰强化版,仅用于视觉重心场景
- 不要把 `ringColor` 当随机调色板 —— 优先复用 token(`c.primary` / `c.info` / `c.success`)

## Avatar 头像

*Source: `docs/components/avatar.mdx` · Slug: `/components/avatar`*

# Avatar 头像

圆形 monogram 头像(建议 1–2 字符)。`brand` / `info` / `soft` / `neutral` · `xs` 18 / `sm` 28 / `md` 32 / `lg` 40 / `xl` 56。可传 `source` 渲染真实头像图片,加载失败时自动回退到 `label` 文字。

:::warning 蓝色规则
`info` 变体（蓝底 `#3775F6`）**专用于用户头像**。其它头像用 `brand` / `soft` / `neutral`。
:::

## 实时预览

下方渲染的就是 `src/components/ui/Avatar/Avatar.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">变体</span>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center' }}>
        <Avatar label="AI" variant="brand" size="lg" />
        <Avatar label="我" variant="info" size="lg" />
        <Avatar label="王" variant="soft" size="lg" />
        <Avatar label="P" variant="neutral" size="lg" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">尺寸</span>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center' }}>
        <Avatar label="1" variant="neutral" size="xs" />
        <Avatar label="A" variant="brand" size="sm" />
        <Avatar label="A" variant="brand" size="md" />
        <Avatar label="A" variant="brand" size="lg" />
        <Avatar label="A" variant="brand" size="xl" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">xs（脚注引用 / 列表序号专用）</span>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center' }}>
        <Avatar label="1" variant="neutral" size="xs" />
        <Avatar label="2" variant="neutral" size="xs" />
        <Avatar label="3" variant="neutral" size="xs" />
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { Avatar } from '@unif/react-native-design';

<Avatar label="AI" variant="brand" size="lg" />
<Avatar label="我" variant="info" size="md" />
<Avatar label="王" variant="soft" />
<Avatar label="P" variant="neutral" size="sm" />
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `label` | `string` | — | 显示文字(建议 1–2 字符);同时作为 a11y label,图片加载失败时回退展示 |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | 18 / 28 / 32 / 40 / 56 |
| `variant` | `'brand' \| 'info' \| 'soft' \| 'neutral'` | `'neutral'` | 配色变体(仅在显示 label 时生效,有 `source` 时被图片覆盖) |
| `source` | `ImageSourcePropType` | — | 真实头像图片(`{ uri }` 或 `require(...)`);优先渲染,`onError` 后回退 label |
| `testID` | `string` | — | E2E / 测试定位 |

`xs`（18px）专为内联序号 / 脚注引用使用 —— 例如 Sources 列表里的来源编号 badge。

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.primary` / `c.onPrimary` | `useColors()` | `brand` 变体底色 / 文字 |
| `c.info` / `c.onInfo` | `useColors()` | `info` 变体底色 / 文字 |
| `c.primaryContainer` / `c.primary` | `useColors()` | `soft` 变体底色 / 文字 |
| `c.surfaceContainerHighest` / `c.foreground` | `useColors()` | `neutral` 变体底色 / 文字 |
| `avatar.xs … avatar.xl` | `@unif/react-native-design` | 五档容器直径(18 / 28 / 32 / 40 / 56) |
| `fw.semi` | `@unif/react-native-design` | label 字重 |

## 无障碍（a11y）

来源：`src/components/ui/Avatar/Avatar.tsx`、`types.ts`。

本组件为展示用，无交互（渲染为 `<View>`，不接收点击）。源码在根 `<View>` 上设了 `accessibilityLabel={label}`，且 `label` 为必填，因此 screen reader 会朗读该文字（即使 `source` 图片加载成功，朗读的仍是 `label`；图片加载失败时也回退展示 `label`）。无 `accessibilityRole`，继承底层 `<View>` 默认。如需让头像可点击，请由父级可点区域承载语义。

```tsx
// label 同时作为 SR 朗读文案
<Avatar label="王" variant="info" />
```

## BlurLayer 玻璃模糊层

*Source: `docs/components/blur-layer.mdx` · Slug: `/components/blur-layer`*

# BlurLayer 玻璃模糊层

封装 `@sbaiahmed1/react-native-blur` 的 `BlurView` + 颜色 tint 双层,
对齐设计稿 backdrop-filter 二档 token(soft 10 / strong 40)。`blurType`
跟主题 scheme 自动切(亮 'light' / 暗 'dark'),避免暗色叠暗底变奶白雾。

## 实时预览

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
    <span className="demo-label">soft —— 玻璃数据条小区域(blurAmount 10)</span>
    <View style={{ position: 'relative', height: 80, backgroundColor: 'linear-gradient(135deg, #F49443, #EB6E00)', borderRadius: 14, overflow: 'hidden' }}>
      <BlurLayer intensity="soft" />
      <View style={{ position: 'absolute', inset: 0, alignItems: 'center', justifyContent: 'center' }}>
        <Text style={{ color: 'var(--ifm-color-emphasis-800)', fontWeight: '600' }}>soft blur</Text>
      </View>
    </View>
    <span className="demo-label">strong —— 焦点引导大面积 backdrop(blurAmount 40)</span>
    <View style={{ position: 'relative', height: 80, backgroundColor: 'linear-gradient(135deg, #F49443, #EB6E00)', borderRadius: 14, overflow: 'hidden' }}>
      <BlurLayer intensity="strong" />
      <View style={{ position: 'absolute', inset: 0, alignItems: 'center', justifyContent: 'center' }}>
        <Text style={{ color: 'var(--ifm-color-emphasis-800)', fontWeight: '600' }}>strong blur</Text>
      </View>
    </View>
  </div>
```

## 用法

```tsx
import { BlurLayer } from '@unif/react-native-design';

{/* GlassStats 玻璃数据条 backdrop */}
<View style={{ position: 'relative' }}>
  <BlurLayer intensity="soft" />
  <View>...</View>
</View>

{/* 自定义 tint override */}
<BlurLayer intensity="soft" tint="rgba(255,255,255,0.3)" />
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `intensity` | `'soft' \| 'strong'` | — | 模糊强度(必传)。`'soft'` 对齐 `blur(10)`,`'strong'` 对齐 `blur(40)` |
| `tint` | `string?` | 推算 | 不传按 intensity 推:soft → `c.glassTintLight` / strong → `c.sheetBackdrop` |
| `style` | `StyleProp<ViewStyle>` | `StyleSheet.absoluteFill` | 附加样式,通常不需要传 |
| `testID` | `string` | — | E2E / 测试定位 |

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.glassTintLight` | `useColors()` | `soft` 默认 tint(0.55 白纱) |
| `c.sheetBackdrop` | `useColors()` | `strong` 默认 tint(0.72 浅灰焦点引导) |
| `blur.soft` / `blur.strong` | `@unif/react-native-design` | BlurView `blurAmount`(10 / 40) |

## 无障碍（a11y）

来源：`src/components/ui/BlurLayer/BlurLayer.tsx`、`BlurLayer.web.tsx`、`types.ts`。

本组件为纯装饰用的视觉模糊层，无交互，无任何 a11y 语义：源码根 `<View>` 显式设 `pointerEvents="none"`（native 与 web 两份实现一致），不拦截触摸、不暴露给 screen reader。无 `accessibilityRole` / `accessibilityLabel`。语义应由其覆盖 / 承载的内容自行提供。

## 设计稿对照

| intensity | blurAmount | 默认 tint | 设计稿语义 |
|---|---|---|---|
| `soft` | 10 | `glassTintLight 0.55 白` | 玻璃数据条 / 小区域玻璃感(`blur(10) saturate(160%)`) |
| `strong` | 40 | `sheetBackdrop 0.72 浅灰` | 焦点引导大面积 backdrop(`blur(40) saturate(180%)`) |

CSS `saturate(N%)` 部分 RN BlurView 无对应 prop,在我们项目暂不实现。

## 不要

- ❌ 不要把 `<BlurLayer>` 放到没有相对定位的父容器内 —— `absoluteFill` 会撑到屏顶
- ❌ 不要传 hardcode blurAmount —— 走 `intensity` token,设计稿更新时单点改 `theme/blur.ts`

## Button 按钮

*Source: `docs/components/button.mdx` · Slug: `/components/button`*

# Button 按钮

文本按钮,7 视觉变体 × 3 尺寸 · 支持块级 / 内联。变体:`primary` 主操作 · `secondary` 次操作 · `ghost` 透明底品牌橙字 · `neutral` 透明底主文字色(多 icon 场景避免全染主橙)· `outline` 白底灰边 · `danger` 破坏性操作 · `text` 纯文字。

## 实时预览

下方渲染的就是 `src/components/ui/Button/Button.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">Button · 变体</span>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
        <Button label="主按钮" variant="primary" />
        <Button label="次按钮" variant="secondary" />
        <Button label="ghost" variant="ghost" />
        <Button label="中性" variant="neutral" />
        <Button label="描边" variant="outline" />
        <Button label="危险" variant="danger" />
        <Button label="文字" variant="text" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">Button · 尺寸</span>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
        <Button label="Small" size="sm" />
        <Button label="Medium" size="md" />
        <Button label="Large" size="lg" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">状态</span>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
        <Button label="禁用" disabled />
        <Button label="加载中" loading />
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { Button } from '@unif/react-native-design';

<Button label="确认" variant="primary" onPress={...} />
<Button label="取消" variant="secondary" />
<Button label="查看详情" variant="outline" />
<Button label="重新发起" variant="text" size="sm" />
<Button label="提交" variant="primary" block size="lg" />
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `label` | `string` | — | 按钮文字(icon-only 场景请用 [IconButton](/docs/components/icon-button)) |
| `onPress` | `() => void` | — | 点击回调;`disabled` / `loading` 时不触发 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 高度 28 / 36 / 44 |
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'neutral' \| 'outline' \| 'danger' \| 'text'` | `'primary'` | 视觉变体 |
| `block` | `boolean` | `false` | 撑满父容器宽度（`alignSelf: stretch + flexGrow: 1`） |
| `disabled` | `boolean` | `false` | 禁用（opacity 0.5 + 不响应 onPress） |
| `loading` | `boolean` | `false` | 加载态:用 `ActivityIndicator` 替代 label,自动 disabled |
| `leftIcon` | `IconName` | — | 左侧图标,与文本同色同高 |
| `rightIcon` | `IconName` | — | 右侧图标,与文本同色同高 |
| `style` | `StyleProp<ViewStyle>` | — | 额外样式覆盖（merge 到末尾） |
| `testID` | `string` | — | E2E / 测试定位 |
| `accessibilityHint` | `string` | — | SR 行为说明 hint,仅在「行为不显然」时加 |

## 无障碍（a11y）

来源：`src/components/ui/Button/ButtonBase.tsx`、`Button.tsx`、`types.ts`。

- 默认 `accessibilityRole`：`'button'`（在 `ButtonBase` 中硬编码，`accessibilityRole = 'button'`）。
- a11y props：`accessibilityLabel` 自动取自必填的 `label`（`<ButtonBase accessibilityLabel={label}>`），无需另传；`accessibilityHint` 可选，仅在「行为不显然」时补充（如「切换主题」）。
- 状态语义：`accessibilityState.disabled` 取 `!isInteractive`，即 `disabled` **或** `loading` 任一为真时都会上报 disabled（`loading` 时 label 被 `ActivityIndicator` 替换）。

```tsx
// label 即 a11y label;hint 仅在行为不显然时补
<Button label="确认" variant="primary" onPress={...} />
<Button label="切换" accessibilityHint="切换深浅主题" onPress={...} />
```

## 主题键（Tokens）

读取来源：`src/components/ui/Button/styles.ts`、`ButtonBase.tsx`。

| Token | 来源 | variant / 说明 |
|---|---|---|
| `c.primary` | `useColors()` | `primary` 变体背景色；`ghost` / `text` 变体文字色 |
| `c.onPrimary` | `useColors()` | `primary` 变体文字/图标色 |
| `c.surfaceContainerHigh` | `useColors()` | `secondary` 变体背景色 |
| `c.foreground` | `useColors()` | `secondary` / `neutral` / `outline` 变体文字色 |
| `c.surface` | `useColors()` | `outline` 变体背景色 |
| `c.outline` | `useColors()` | `outline` 变体边框色 |
| `c.error` | `useColors()` | `danger` 变体背景色 |
| `c.onError` | `useColors()` | `danger` 变体文字色 |
| `radius.lg` / `radius.md` / `radius.sm` | 静态 token | 按 `size='lg'/'md'/'sm'` 对应圆角 |
| `control.lg` / `control.md` / `control.sm` | 静态 token（`src/theme`） | 按尺寸对应高度（44 / 36 / 28） |
| `space['6']` / `space['4']` | 静态 token | `md` / `sm` 水平内边距(`lg` 用 `r(18)`) |
| `space['2']` / `space['1']` | 静态 token | 内容 gap(`lg`/`md` 用 `'2'`,`sm` 用 `'1'`) |
| `fw.semi` | 静态 token | 按钮文字字重（`600`） |
| `type.body` / `type.sm` / `type.xxs` | 静态 token | 按 `size='lg'/'md'/'sm'` 对应字号 |

## Card 卡片

*Source: `docs/components/card.mdx` · Slug: `/components/card`*

# Card 卡片

通用内容卡片——白底，12px 圆角，14px padding，唯一的卡片阴影。

## 实时预览

下方渲染的就是 `src/components/ui/Card/Card.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
    <span className="demo-label">default · 带阴影</span>
    <Card>
      <Text style={{ fontSize: 15, fontWeight: '600', color: 'var(--ifm-color-emphasis-800)', marginBottom: 6 }}>东方便利店 · 浦东店</Text>
      <Text style={{ fontSize: 13, lineHeight: 20, color: '#666' }}>
        本月订单合计 ¥12,480，主要采购统一冰红茶、阿萨姆奶茶。距离 1.2 km。
      </Text>
    </Card>
    <span className="demo-label">flat · (deprecated 等价 plain，新代码请用 plain)</span>
    <Card variant="flat">
      <Text style={{ fontSize: 15, fontWeight: '600', color: 'var(--ifm-color-emphasis-800)', marginBottom: 6 }}>说明</Text>
      <Text style={{ fontSize: 13, lineHeight: 20, color: '#666' }}>
        历史 variant，视觉与 plain 一致。新代码改用 plain。
      </Text>
    </Card>
    <span className="demo-label">plain · 仅圆角，无阴影无描边（嵌套用）</span>
    <View style={{ backgroundColor: 'var(--ifm-color-emphasis-100)', padding: 12, borderRadius: 12 }}>
      <Card variant="plain">
        <Text style={{ fontSize: 13, lineHeight: 20, color: '#666' }}>
          plain 卡片不带视觉外延 —— 嵌套到已有 surface 容器内时仅靠 padding + radius 区分内容。
        </Text>
      </Card>
    </View>
    <span className="demo-label">plain + borderColor · 状态彩边（如 Confirmation）</span>
    <Card variant="plain" borderColor="#EB6E00" borderWidth={2}>
      <Text style={{ fontSize: 13, lineHeight: 20, color: '#666' }}>
        2px 主橙描边，用于操作确认这种需要"挑出来看一眼"的卡片。
      </Text>
    </Card>
    <span className="demo-label">组合内容</span>
    <Card>
      <View style={{ flexDirection: 'row', alignItems: 'center', marginBottom: 6 }}>
        <View style={{ width: 8, height: 8, borderRadius: 4, backgroundColor: '#52C41A', marginRight: 8 }} />
        <Text style={{ fontSize: 15, fontWeight: '600', color: 'var(--ifm-color-emphasis-800)' }}>已完成 · 拜访</Text>
        <Text style={{ fontSize: 12, color: 'var(--ifm-color-emphasis-600)', marginLeft: 'auto' }}>14:02</Text>
      </View>
      <Text style={{ fontSize: 13, lineHeight: 20, color: '#666' }}>已完成本日全部 4 个客户拜访，待提交日报。</Text>
    </Card>
  </div>
```

## 视觉规范

| 元素 | 规则 |
|---|---|
| 背景 | `#FFFFFF` |
| 圆角 | 12px (`radius.xl`) |
| Padding | 14px (`space.6`) |
| 阴影 | `0 1px 4px rgba(0,0,0,0.08)` (`shadow.card`) |
| Variant `plain` | 无阴影、无描边（嵌套场景；`flat` 已 deprecated 等价 `plain`） |

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.surface` | `useColors()` | 卡片背景色（白 / 暗色 surface） |
| `radius.xl` | `@unif/react-native-design` | 默认圆角（12，可被 `borderRadius` 覆盖） |
| `space['6']` | `@unif/react-native-design` | 默认内边距（14，可被 `padding` 覆盖） |
| `s.card` | `useShadow()` | `default` 变体卡片阴影（暗色置零） |

## 用法

```tsx
import { Card } from '@unif/react-native-design';

{/* default — 白卡 + 阴影 */}
<Card>
  <Text>普通卡片</Text>
</Card>

{/* plain — 仅圆角，无阴影无描边（嵌套场景） */}
<Card variant="plain">
  <Text>嵌套用</Text>
</Card>

{/* 状态色边框（如 Confirmation）— 2px 彩边，颜色走 useColors() */}
function Confirm() {
  const c = useColors();
  return (
    <Card variant="plain" borderColor={c.primary}>
      <Text>操作确认</Text>
    </Card>
  );
}

{/* bare — 内容自控 padding（如 Tool 卡片头/体不同 padding）*/}
<Card variant="plain" bare>
  <Header />
  <Body />
</Card>

{/* fill — Card 撑满 flex 父 + 内部列表滚动（如 Me 屏会话列表）*/}
<View style={{ flex: 1 }}>
  <Card variant="plain" fill>
    <Header />
    <ScrollView style={{ flex: 1 }}>{/* 长列表 */}</ScrollView>
  </Card>
</View>
```

> `variant="flat"` 已 deprecated，等价 `plain`，新代码请用 `plain`。

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `children` | `ReactNode` | — | 卡片内容 |
| `variant` | `'default' \| 'flat' \| 'plain'` | `'default'` | 带阴影 / 仅圆角无阴影。`'flat'` 已 deprecated 等价 `'plain'` |
| `padding` | `number` | `14`（`space['6']`） | 内边距 |
| `borderRadius` | `number` | `12`（`radius.xl`） | 圆角 |
| `borderColor` | `string` | — | 强调描边色（任意 variant 均生效;启用时默认 2px） |
| `borderWidth` | `number` | `2` | 与 `borderColor` 配合 |
| `bare` | `boolean` | `false` | 抑制内边距,内容自控（与 variant 正交） |
| `fill` | `boolean` | `false` | 撑满模式:外层 + 内层 clip 均 `flex:1`,Card 在 flex 父里撑满、内容区填满外层（内部 `flex:1` 滚动列表据此拿到高度） |
| `style` | `StyleProp<ViewStyle>` | — | 额外样式覆盖 |
| `testID` | `string` | — | E2E / 测试定位 |

## 无障碍（a11y）

来源：`src/components/ui/Card/Card.tsx`、`types.ts`。

本组件为展示 / 容器用，无交互（渲染为 `<View>`，仅负责背景 / 圆角 / 阴影 / 内边距）。源码未设置任何 a11y prop，继承底层 `<View>` 默认。a11y 语义由其 `children` 内容自行承载；若整张卡片需可点击，请在 `children` 内放可点区域（如 [Cell](./cell) 的 `onPress` 或 [Button](./button)），不要把点击语义挂在 Card 本身。

## 不要

- ❌ 不要叠加多层阴影——卡片只有一种阴影
- ❌ 不要把 List 行做成 Card——List 行用 [Cell](./cell)
- ❌ 不要给 Card 加渐变背景——只有 logo 和 drawer header 允许渐变

## Carousel 轮播

*Source: `docs/components/carousel.mdx` · Slug: `/components/carousel`*

# Carousel 轮播

包装 `react-native-reanimated-carousel@5.0.0` 正式版的薄壳层,沿用上游正式命名并收口本设计系统需要的布局与交互:

1. dot indicator 走 `c.primary` token,使用正式版 `Pagination`(`useSharedValue` + `progress` 驱动,无需自己跟 active state)
2. `indicatorPosition` 控制指示器位置:`'bottom'` 独立行(占额外 16px 高度) / `'overlay-bottom-right'` 浮在 banner 右下角
3. 类型泛型 `<T>` 让 `data`、`renderItem`、`keyExtractor` 和点击回调共享同一 item 类型
4. `forwardRef` 直接透传正式版 `CarouselRef`,支持 `scrollTo` / `prev` / `next` / `getCurrentIndex`

## 实时预览

下方渲染的就是 `src/components/ui/Carousel/Carousel.tsx` 本体,通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div
    style={{ display: 'flex', flexDirection: 'column', gap: 18, maxWidth: 360 }}
  >
    <span className="demo-label">
      3 张色块 · autoplay 3.5s · 底部 dot 指示器
    </span>
    <Carousel
      data={[
        { id: '1', color: '#EB6E00', label: 'A' },
        { id: '2', color: '#3775F6', label: 'B' },
        { id: '3', color: '#52C41A', label: 'C' },
      ]}
      height={120}
      itemSize={360}
      autoplay
      autoplayInterval={3500}
      keyExtractor={(item) => item.id}
      showIndicator
      renderItem={({ item }) => (
        <View
          style={{
            flex: 1,
            backgroundColor: item.color,
            alignItems: 'center',
            justifyContent: 'center',
            borderRadius: 12,
            margin: 4,
          }}
        >
          <Text style={{ color: '#fff', fontSize: 32, fontWeight: '600' }}>
            {item.label}
          </Text>
        </View>
      )}
    />
  </div>
```

## 用法

```tsx
import { Carousel } from '@unif/react-native-design';
import { Image } from 'react-native';

type Banner = {
  id: string;
  imageUrl: string;
  linkUrl?: string;
  title?: string;
};

const banners: Banner[] = [
  /* … */
];

<Carousel<Banner>
  data={banners}
  height={140}
  autoplay
  autoplayInterval={3500}
  keyExtractor={(item) => item.id}
  showIndicator
  indicatorPosition="overlay-bottom-right"
  onPressItem={(item) => {
    if (item.linkUrl) openWebview(item.linkUrl);
  }}
  getAccessibilityLabel={(item) => item.title ?? 'Banner'}
  renderItem={({ item }) => (
    <Image source={{ uri: item.imageUrl }} style={{ flex: 1 }} />
  )}
  testID="dashboard-carousel"
/>;
```

## API

| Prop                    | Type                                                                                        | 默认                          | 说明                                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`                  | `T[]`                                                                                       | —                             | 数据数组;空数组建议 caller 自行 `return null`                                                                                                                  |
| `renderItem`            | `(info: { item: T; index: number; relativeProgress: SharedValue<number> }) => ReactElement` | —                             | 单项渲染,参数与上游正式 API 一致                                                                                                                               |
| `keyExtractor`          | `(item: T, index: number) => string`                                                        | —                             | 稳定 key 解析器,数据更新时用于保持 item 身份                                                                                                                   |
| `height`                | `number`                                                                                    | —                             | 每张高度(宽度默认 = 屏宽,被 `itemSize` 覆盖)                                                                                                                   |
| `itemSize`              | `number?`                                                                                   | `useWindowDimensions().width` | 每张宽度和水平翻页步长;caller 外层有 `marginHorizontal`(例如 Dashboard banner inset 16)时必须传 `屏宽 - 左右 margin*2`,否则 slide 撑满全屏宽,右侧被裁掉        |
| `autoplay`              | `boolean?`                                                                                  | `false`                       | 是否自动播放                                                                                                                                                   |
| `autoplayInterval`      | `number?`                                                                                   | `3000`                        | 自动播放间隔 ms                                                                                                                                                |
| `loop`                  | `boolean?`                                                                                  | `true`                        | 是否循环播放                                                                                                                                                   |
| `showIndicator`         | `boolean?`                                                                                  | `true`                        | 是否显示底部 dot indicator                                                                                                                                     |
| `indicatorPosition`     | `'bottom' \| 'overlay-bottom-right'`                                                        | `'bottom'`                    | `'bottom'` 独立行 +16px / `'overlay-bottom-right'` 浮层不占高                                                                                                  |
| `onPressItem`           | `(item: T, index: number) => void`                                                          | —                             | 单项点击回调                                                                                                                                                   |
| `getAccessibilityLabel` | `(item: T, index: number) => string`                                                        | —                             | 单项 a11y label 解析器,**仅 `onPressItem` 存在时启用**(Pressable 自动声明 `accessibilityRole='button'`,纯展示型轮播不声明 button 语义);未传 fallback `第 N 项` |
| `style`                 | `StyleProp<ViewStyle>?`                                                                     | —                             | 外层 View 附加样式                                                                                                                                             |
| `testID`                | `string?`                                                                                   | —                             | E2E / 测试定位,子项自动加 `${testID}-item-${i}`                                                                                                                |

## 命令式 ref

组件直接透传并导出上游正式版 `CarouselRef`:

```tsx
import { useRef } from 'react';
import { Carousel, type CarouselRef } from '@unif/react-native-design';

const carouselRef = useRef<CarouselRef>(null);

<Carousel
  ref={carouselRef}
  data={banners}
  height={140}
  renderItem={({ item }) => (
    <Image source={{ uri: item.imageUrl }} style={{ flex: 1 }} />
  )}
/>;

carouselRef.current?.next({ animated: true });
carouselRef.current?.prev({ count: 2, animated: false });
carouselRef.current?.scrollTo({ index: 0, animated: false });
const settledIndex = carouselRef.current?.getCurrentIndex();
```

`getCurrentIndex()` 返回最后一次完成落位的 index;滑动或动画进行中仍返回上一次 settled index。`scrollTo` 只接受绝对 `index`,相对移动请使用 `next` / `prev`。

## 无障碍（a11y）

来源：`src/components/ui/Carousel/Carousel.tsx`、`types.ts`。

每张 slide 都包在一个 `<Pressable>` 里，但 a11y 语义是**条件性**的：

- 默认 `accessibilityRole`：仅当传了 `onPressItem` 时，slide 才声明 `accessibilityRole='button'`；纯展示型轮播（无 `onPressItem`）**不声明** button 语义，避免读屏器误导。
- a11y props：`getAccessibilityLabel(item, index)` 可选，仅在 `onPressItem` 存在时启用 —— 解析为每张 slide 的 `accessibilityLabel`；不传则 fallback 为 `第 N 项`（`第 ${index + 1} 项`）。
- 状态语义：源码未设 `selected` / 当前页等状态语义。

```tsx
// 可点轮播:role=button 自动,label 由 getAccessibilityLabel 提供
<Carousel
  data={banners}
  height={140}
  onPressItem={(item) => openWebview(item.linkUrl)}
  getAccessibilityLabel={(item) => item.title ?? 'Banner'}
  renderItem={({ item }) => (
    <Image source={{ uri: item.imageUrl }} style={{ flex: 1 }} />
  )}
/>
```

## 视觉规范

| 元素                     | 规则                                                                                      |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| Dot · 默认               | 4×4 圆(`space['1']`),`c.primary` @ opacity 0.32                                           |
| Dot · active             | 12×4 长条(`space['5']`),`c.primary` @ opacity 1;每个 dot 都预留 12pt 宽避免切换时布局跳动 |
| `'bottom'` 占位          | 容器高度 = `height + 16`(`space['7']`)                                                    |
| `'overlay-bottom-right'` | dot 浮层 absolute 在右下角,不占额外高度                                                   |
| `loop`                   | 默认开启 —— 最后一张滑回第一张                                                            |

## 主题键（Tokens）

| Token                       | 来源                        | 作用                                             |
| --------------------------- | --------------------------- | ------------------------------------------------ |
| `c.primary`                 | `useColors()`               | dot indicator 颜色(默认 0.32 / active 1 opacity) |
| `space['1']` / `space['5']` | `@unif/react-native-design` | dot 尺寸(4)/ active dot 宽(12)                   |
| `space['7']`                | `@unif/react-native-design` | `'bottom'` 模式指示器预留行高(16)                |
| `radius.pill`               | `@unif/react-native-design` | dot 圆角(clamp 成圆)                             |

## 备注

- 内部用了 `useSharedValue` + `progress`,指示器更新在 UI 线程完成,不走 JS 每帧回调
- `autoplayInterval` 从上一段切换动画完成后开始计时;触摸和滑动期间由上游暂停,落位后恢复
- `testID` 自动生成子项 testID `carousel-item-${i}`,可用于消费者侧集成测试

## 不要

- 不要把 Carousel 当 `<ScrollView horizontal>` 用 —— 简单横滚列表请用原生 `<ScrollView>` 即可
- 不要传 `data.length <= 1` —— 单张直接渲染 `<Image>`,不必上 Carousel
- 不要忘了 `itemSize` —— 一旦外层加了 `marginHorizontal`,默认全屏宽会让 slide 右侧被裁。`屏宽 - margin*2` 是稳妥值,`useWindowDimensions()` 拿屏宽

## Cell · List 列表行

*Source: `docs/components/cell.mdx` · Slug: `/components/cell`*

# Cell · List 列表行

每行独立白卡，行间 8px gap。**不用 border-bottom 分隔**——这是 Unif 列表的核心规则（与 iOS 17 / 微信新版一致）。

## 实时预览

下方渲染的就是 `src/components/ui/Cell/Cell.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
      <span className="demo-label" style={{ paddingLeft: 8 }}>设置</span>
      <List>
        <Cell leading="settings" title="主题" extra="跟随系统" arrow onPress={() => {}} />
        <Cell leading="bell" title="通知" arrow onPress={() => {}} />
        <Cell leading="lock" title="隐私" desc="位置 / 相机 / 麦克风" arrow onPress={() => {}} />
        <Cell leading="info" title="关于" extra="v1.0" arrow onPress={() => {}} />
      </List>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
      <span className="demo-label" style={{ paddingLeft: 8 }}>客户</span>
      <List>
        <Cell title="东方便利店" desc="浦东 · 1.2 km" extra="¥12,480" arrow onPress={() => {}} />
        <Cell title="明珠超市" desc="浦东 · 2.8 km" extra="¥8,960" arrow onPress={() => {}} />
        <Cell title="优家便利" desc="浦东 · 4.1 km" extra="¥3,200" arrow onPress={() => {}} />
      </List>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
      <span className="demo-label" style={{ paddingLeft: 8 }}>disabled · 不可点击 / 视觉变灰</span>
      <List>
        <Cell leading="lock" title="云同步" desc="未登录" arrow disabled />
        <Cell leading="bell" title="通知（开发中）" extra="即将开放" disabled />
      </List>
    </div>
  </div>
```

## 视觉规范

| 元素 | 规则 |
|---|---|
| 整组容器（grouped） | `c.background` 浅灰底（视觉分组），`padding: 8`（`space[3]`），`borderRadius: 12`（`radius.xl`），`gap: 8` |
| 单行 | `c.surface` 白底，`borderRadius: 10`（`radius.lg`），`min-height: 56`，`padding: 14`（`space[6]`，水平 + 垂直同值） |
| 行内布局 | 左 icon (grouped 22 / flush 28 盒) + 中 (title 15/500 + desc 13/subtle) + 右 extra (13/subtle) + arrow (grouped 20 / flush 18) |
| **绝不**（grouped） | `border-bottom`、`hairline` 分隔（flush 模式才用 inset hairline） |

## 用法

```tsx
import { Cell, List } from '@unif/react-native-design';

<List>
  <Cell title="主题" extra="跟随系统" arrow leading="settings" onPress={...} />
  <Cell title="通知" arrow leading="bell" />
  <Cell title="拜访提醒" desc="按计划自动推送" extra={<Switch value={...} onChange={...} />} />
</List>

{/* 平铺式（无浅灰背景容器，用于嵌套在其它白卡内）*/}
<List flush>
  <Cell title="客户名" desc="地址" extra="¥1,200" arrow />
</List>
```

## API

### `<Cell>`

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `title` | `ReactNode` | — | 主标题(必填);string 自动套 `<Text>` + `numberOfLines=titleLines`,传 ReactNode 完全自定义 |
| `titleLines` | `number` | `1` | `title` 为 string 时的 `numberOfLines`(如新闻标题传 2) |
| `desc` | `ReactNode` | — | 副标题 / 描述;string 自动 `numberOfLines=2` |
| `extra` | `ReactNode` | — | 右侧 slot — 文字、Tag、Switch、Stepper 等 |
| `arrow` | `boolean` | `false` | 显示右侧 chevron-right(`danger` 时不渲染) |
| `leading` | `IconName \| ReactNode` | — | 左侧 icon 名（grouped 渲染 22px 裸 icon / flush 渲染 28×28 橙盒 + 16px icon）或自定义节点（如 Avatar） |
| `onPress` | `() => void` | — | 点击回调（提供时启用按压态;不传则为纯展示 `<View>`） |
| `disabled` | `boolean` | `false` | 仅对带 `onPress` 的 cell 有效,true 时 onPress 不触发 + 整体半透明 + a11y disabled |
| `danger` | `boolean` | `false` | 危险态：icon 盒子 + 标题用 error 红,且不渲染 arrow（常用于退出登录 / 删除等） |
| `style` | `StyleProp<ViewStyle>` | — | 额外样式覆盖（合并到 cell 容器的 style 数组） |
| `testID` | `string` | — | E2E / 测试定位 |
| `accessibilityLabel` | `string` | title(string 时) | 显式 SR 朗读文案;`title` 传 ReactNode 时务必显式传 |
| `accessibilityHint` | `string` | — | SR 行为说明 hint(≤8 字,如「查看详情」);`onPress` 缺省时无意义 |

### `<List>`

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `children` | `ReactNode` | — | 一组 `<Cell>` |
| `flush` | `boolean` | `false` | 透明背景（嵌套用）；省略则白卡 + 8px gap + 浅灰底容器 |
| `divider` | `'full' \| 'none'` | `'full'` | flush 模式下行间分隔线:`'full'` 铺满全宽 hairline / `'none'` 不画 |
| `style` | `StyleProp<ViewStyle>` | — | 额外样式覆盖 |
| `testID` | `string` | — | E2E / 测试定位 |

## 无障碍（a11y）

来源：`src/components/ui/Cell/Cell.tsx`、`types.ts`。

a11y 语义是**条件性**的：仅当传了 `onPress` 时，Cell 才用 `<Pressable>` 包裹并声明语义；不可点的纯展示 Cell 渲染为 `<View>`，无 a11y 角色。

- 默认 `accessibilityRole`：可点时为 `'button'`（`onPress` 缺省则无角色）。
- a11y props（仅 `onPress` 时生效）：`accessibilityLabel` 取 `accessibilityLabel ?? (typeof title === 'string' ? title : undefined)` —— 即 `title` 为字符串时自动作 label；**`title` 传 ReactNode（自定义渲染）时务必显式传 `accessibilityLabel`，否则 SR 用户听不到内容**。`accessibilityHint` 可选，说明 tap 后行为（短句，如「查看详情」）。
- 状态语义：`disabled=true` 时上报 `accessibilityState={{ disabled: true }}`（仅对带 `onPress` 的 cell 有效）。

```tsx
// string title 自动作 label
<Cell title="主题" extra="跟随系统" arrow onPress={...} />

// ReactNode title 必须显式给 label
<Cell
  title={<CustomTitle />}
  accessibilityLabel="客户：东方便利店"
  accessibilityHint="查看详情"
  onPress={...}
/>
```

## 与 Form 的区别

| 用途 | 选哪个 |
|---|---|
| 数据展示 / 跳转 | **Cell · List** — 白卡 + gap |
| 数据录入 / 表单 | [Form](./form) — 白卡 + 行间 hairline |

## 主题键（Tokens）

读取来源：`src/components/ui/Cell/styles.ts`。

| Token | 来源 | 作用 |
|---|---|---|
| `c.surface` | `useColors()` | grouped 模式下单行白卡背景色 |
| `c.foreground` | `useColors()` | 主标题文字色（`title` / `titleFlush`） |
| `c.foregroundSubtle` | `useColors()` | 副标题 / extra 文字色（grouped 模式） |
| `c.foregroundMuted` | `useColors()` | 副标题 / extra 文字色（flush 模式，另加 `opacity: 0.55`） |
| `c.background` | `useColors()` | `<List>` grouped 模式外容器背景色（浅灰底） |
| `c.outline` | `useColors()` | flush 模式行间 hairline 分隔线颜色 |
| `radius.lg` | 静态 token | grouped 模式单行卡片圆角 |
| `radius.xl` | 静态 token | `<List>` grouped 模式外容器圆角 |
| `space[5]` / `space[6]` / `space[3]` | 静态 token | 行内 leading↔body↔extra gap(12)/ 行内水平+垂直内边距(14)/ List 行间 gap + 容器 padding(8) |
| `space[4]` | 静态 token | flush 模式行内元素间 gap（`cellFlush.gap`） |
| `type.body` / `type.xs` | 静态 token | 主标题 / 副标题字号（grouped 模式） |
| `fw.medium` | 静态 token | 主标题字重 |
| `StyleSheet.hairlineWidth` | React Native | flush 模式分隔线物理宽度（不参与 token 缩放） |

## Checkbox 复选框

*Source: `docs/components/checkbox.mdx` · Slug: `/components/checkbox`*

# Checkbox 复选框

受控多选控件——20×20 盒子，未选透明描边、已选主橙实心 + 白勾、禁用半透明。`shape='circle'` 切圆形,用于需要强调的必勾项(如协议同意)。

## 实时预览

下方渲染的就是 `src/components/ui/Checkbox/Checkbox.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<CheckboxDemo />

## 状态

| 状态 | 视觉 |
|---|---|
| 未选 | 20×20 盒子,1.5px 描边 `c.outline`,透明背景 |
| 已选 | 20×20 `c.primary` 背景 + `c.onPrimary` 白勾(check,strokeWidth 2.5) |
| 禁用 | `opacity: 0.5` |

## 用法

```tsx
import { Checkbox } from '@unif/react-native-design';

<Checkbox checked={agree} onChange={setAgree} label="同意服务条款" />

{/* 多项选择 */}
{customers.map(c => (
  <Checkbox
    key={c.id}
    checked={picked.includes(c.id)}
    onChange={() => togglePick(c.id)}
    label={c.name}
  />
))}
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `checked` | `boolean` | — | 当前是否选中(受控) |
| `onChange` | `(checked: boolean) => void` | — | 状态变更回调,传入新的 `checked` 值 |
| `label` | `string` | — | 旁标文字(不传则只渲染勾选盒子) |
| `shape` | `'square' \| 'circle'` | `'square'` | 形状;`'circle'` 用于强调的必勾项(如协议同意) |
| `disabled` | `boolean` | `false` | 禁用 |
| `testID` | `string` | — | E2E / 测试定位 |

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.outline` | `useColors()` | 未选盒子描边色 |
| `c.primary` | `useColors()` | 已选盒子填充 + 边框色 |
| `c.onPrimary` | `useColors()` | 白勾(check icon)色 |
| `c.foreground` | `useColors()` | label 文字色 |
| `radius.xs` | `@unif/react-native-design` | 方形盒子圆角(4) |
| `space['4']` | `@unif/react-native-design` | 盒子↔label 间距(10) |
| `type.sm` | `@unif/react-native-design` | label 字号 |

## 无障碍（a11y）

来源：`src/components/ui/Checkbox/Checkbox.tsx`、`types.ts`。

- 默认 `accessibilityRole`：`'checkbox'`（在 `<Pressable>` 上硬编码）。
- a11y props：`accessibilityLabel` 取自 `label`，但 `label` 是**可选**的 —— 不传 `label` 时（仅渲染勾选方框）无朗读文案，此时应由外部上下文或包裹元素提供语义。
- 状态语义：`accessibilityState={{ checked, disabled: !!disabled }}` —— `checked` 直接映射受控的 `checked` prop，`disabled` 映射 `disabled` prop。

```tsx
// label 同时作为 SR 朗读文案
<Checkbox checked={agree} onChange={setAgree} label="同意服务条款" />
```

## Chip 标签

*Source: `docs/components/chip.mdx` · Slug: `/components/chip`*

# Chip 标签

胶囊形（pill）标签：圆角 999、可点击、可选中。Suggestion / 多选筛选 / 内联标记等场景的底层组件。

## 实时预览

下方渲染的就是 `src/components/ui/Chip/Chip.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<ChipDemo />

## 状态

| 状态 | 视觉 |
|---|---|
| 默认 | `c.surface` 白底 + 1px `c.outline` 细边框,`c.foreground` 文本 |
| 选中 (`selected`) | `c.primary` 边框 + `c.primaryContainerSubtle` 浅橙底 + `c.primary` 文本 |
| 按下 | 透明度 0.7（仅当传 `onPress` 时） |
| 禁用 (`disabled`) | 透明度 0.5 + 不响应 `onPress` |
| 处理中 (`busy`) | leading 位换 spinner + 透明度 0.6 + 不响应二次点击（label 保留） |
| 非交互（无 `onPress`） | 不响应按压、不显示按压态 |

`disabled` 与 `busy` 的分工：**`disabled` = 现在不能点**（更暗、无动效）；**`busy` = 点过了，正在办**（spinner 传达进行中）。两者同时为真按 `disabled` 的视觉走。

## 用法

```tsx
import { Chip, Icon } from '@unif/react-native-design';

{/* 单个可选中 chip */}
<Chip
  label="待跟进"
  selected={filter === 'pending'}
  onPress={() => setFilter('pending')}
/>

{/* 带 leading icon */}
<Chip
  label="今天的安排"
  leading={<Icon name="spark" size={12} />}
  onPress={onSuggestion}
/>

{/* 静态展示（消息气泡里附带的 meta 标签等） */}
<Chip label="VIP" />

{/* 带 trailing 关闭按钮（多选 token 风格） */}
<Chip
  label="王经理"
  selected
  trailing={<Icon name="close" size={12} />}
  onPress={() => removeFilter('manager-wang')}
/>

{/* 点了就发请求的 chip：busy 顶住等待窗口，同时吞掉二次点击 */}
<Chip
  label="今日拜访计划"
  leading={<Icon name="spark" size={12} />}
  busy={pending === 'plan'}
  onPress={openTodayPlan}
/>
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `label` | `string` | — | 显示文本(单行 numberOfLines=1 截断) |
| `selected` | `boolean` | `false` | 选中态（主色边框 + 浅橙底 + 主色文本） |
| `onPress` | `() => void` | — | 点击回调；不传时 chip 渲染为静态 `<View>`，不响应按压 |
| `disabled` | `boolean` | `false` | 禁用（透明度 0.5 + 不响应 `onPress`） |
| `busy` | `boolean` | `false` | 处理中（leading 换 spinner + 透明度 0.6 + 吞掉二次点击） |
| `leading` | `ReactNode` | — | 前置插槽（图标 / 小圆点等） |
| `trailing` | `ReactNode` | — | 后置插槽（关闭按钮等） |
| `style` | `StyleProp<ViewStyle>` | — | 附加样式 |
| `testID` | `string` | — | E2E / 测试定位 |

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.surface` | `useColors()` | 默认背景色 |
| `c.outline` | `useColors()` | 默认边框色 |
| `c.primary` | `useColors()` | 选中边框 + 文本色 |
| `c.primaryContainerSubtle` | `useColors()` | 选中浅橙底色 |
| `c.foreground` | `useColors()` | 默认文本色（`busy` spinner 也跟随它 / 选中时跟 `c.primary`） |
| `radius.pill` | `@unif/react-native-design` | 胶囊圆角 |
| `space['2']` / `space['5']` / `space['3']` | `@unif/react-native-design` | 内容 gap(6)/ 水平内边距(12)/ 垂直内边距(8) |
| `type.xs` | `@unif/react-native-design` | 文本字号 |

## 无障碍（a11y）

来源：`src/components/ui/Chip/Chip.tsx`、`types.ts`。

a11y 语义是**条件性**的：仅当传了 `onPress` 时，Chip 才用 `<Pressable>` 包裹并声明语义；静态展示型（无 `onPress`）渲染为纯 `<View>`，无 a11y 角色（与「不响应按压」一致）。

- 默认 `accessibilityRole`：可点时为 `'button'`（`onPress` 缺省则无角色）。
- a11y props（仅 `onPress` 时生效）：`accessibilityLabel` 取自必填的 `label`。
- 状态语义：可点时上报 `accessibilityState={{ selected, disabled, busy }}` —— `disabled` 为 `disabled || busy`（两者都不可点），`busy` 单独映射，读屏据此念出「忙碌」而不是「已停用」。

```tsx
// 可点 + 可选中:role=button、label=label、state.selected 自动
<Chip label="待跟进" selected={filter === 'pending'} onPress={() => setFilter('pending')} />

// 处理中:state.busy=true、state.disabled=true（点击被吞，读屏念「忙碌」）
<Chip label="今日拜访计划" busy onPress={openTodayPlan} />
```

## 不要

- ❌ 不要把 `<Chip>` 当成"按钮的小号版" —— 实际按钮（包括小号）走 [Button](./button) `size="sm"`。Chip 的视觉重心在"可选状态"，不在"主操作"。
- ❌ 不要在 Chip 内嵌长文本 —— 单行 numberOfLines=1 截断；超过两个字的多选项考虑用 [Cell](./cell) 列表。
- ❌ 不要用 Chip 表达状态语义（`done`/`error`）—— 那是 [Tag](./tag) 的领域。

## Confirm 确认对话框

*Source: `docs/components/confirm.mdx` · Slug: `/components/confirm`*

# Confirm 确认对话框

命令式 `await confirm(...)` 返回 `Promise<boolean>`,跟 Toast 同款 imperative API,
不需要 caller 维护 `useState / open / onClose`。背后是 `<ConfirmHost />`(裸 RN
`Modal` + pub/sub,**不依赖 @gorhom**),App 根挂一次。

## 用法

```tsx
import { confirm } from '@unif/react-native-design';

const ok = await confirm({
  title: '确认注销账号?',
  message: '注销后所有数据将被删除,且无法恢复。',
  confirmLabel: '确认注销',
  destructive: true,        // 红色按钮 c.error
});
if (ok) doLogout();
```

## API

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `title` | `string` | — | 主标题(必传),短句:`确认注销账号?` / `确认退出登录?` |
| `message` | `string?` | — | 说明文本(可选)1-2 句解释操作后果 |
| `confirmLabel` | `string?` | `'确认'` | 确认按钮文案 |
| `cancelLabel` | `string?` | `'取消'` | 取消按钮文案 |
| `destructive` | `boolean?` | `false` | 标记破坏性操作 → 确认按钮变红(`c.error`)|

## 无障碍（a11y）

来源：`src/components/ui/Confirm/ConfirmHost.tsx`、`confirm.ts`、`types.ts`。

`confirm()` 是命令式 API，`ConfirmOptions` 里**没有任何 a11y 入参**，a11y 全部来自底层组合：

- 对话框容器走 RN 原生 `<Modal transparent animationType="slide">`，backdrop 是 `<Pressable accessibilityRole="button" accessibilityLabel="关闭">`（点击取消）。
- 标题 / 说明用 `<Text>`（`entry.title` / `entry.message`）渲染，screen reader 可读到文字。
- 取消 / 确认两个按钮用本库 [Button](./button) 渲染，自动带 `accessibilityRole='button'`，且 `accessibilityLabel` 取自各自的文案：取消← `cancelLabel ?? '取消'`、确认← `confirmLabel ?? '确认'`。

要让 SR 读到清晰语义，给 `title`（必填）/ `confirmLabel` / `cancelLabel` 传明确文案即可；组件层无额外 a11y 旋钮。

```tsx
// title 必填即标题语义;按钮文案即按钮 a11y label
await confirm({ title: '确认注销账号?', confirmLabel: '确认注销', destructive: true });
```

## 返回值

`Promise<boolean>`:
- `true` — 用户点确认按钮
- `false` — 用户点取消 / 点 backdrop

## 设计稿对照

| 视觉态 | 规则 |
|---|---|
| 容器 | RN `<Modal transparent animationType="slide">` + backdrop,底部弹层卡片 |
| 标题 | `t.heroSm`(18)+ `fw.semi` + `c.foreground` |
| 说明 | `t.body`(15)+ `c.foregroundMuted` + `lineHeight 1.45` |
| 按钮行 | `<Button variant="secondary" block>` 取消 + `<Button variant="primary"\|"danger" block>` 确认,横向均分 |

## 主题键（Tokens）

读取来源:`src/components/ui/Confirm/styles.ts`、`ConfirmHost.tsx`。

| Token | 来源 | 作用 |
|---|---|---|
| `c.surface` | `useColors()` | sheet 背景色 |
| `c.foreground` | `useColors()` | 标题文字色 |
| `c.foregroundMuted` | `useColors()` | 说明文字色 |
| `type.heroSm` | `@unif/react-native-design` | 标题字号(18) |
| `type.body` | `@unif/react-native-design` | 说明字号(15) |
| `fw.semi` | `@unif/react-native-design` | 标题字重 |
| `space['9']` / `space['4']` / `space['5']` / `space['7']` | `@unif/react-native-design` | sheet / actions 内边距与 gap |

## 业务消费示例

- **注销账号**(`AccountSecurity.tsx`)— `destructive: true`,取消则不调用注销 API
- **退出登录**(`Setting.tsx`)— `destructive: true`,取消则保持 `authed=true`
- 未来:删除会话 / 取消订单 / webview 跳转前提示(根据 UX 决策)

## 业务侧 loading

`confirm()` 立即关闭对话框 + resolve,**不内置 loading**。caller 自行处理:

```tsx
const [loggingOut, setLoggingOut] = useState(false);

const handleLogout = async () => {
  const ok = await confirm({ title: '确认退出?', destructive: true });
  if (!ok) return;
  setLoggingOut(true);
  try {
    await logout();
  } catch {
    setLoggingOut(false);
  }
};

// 在 cell title 上展示 "退出中…" + disabled
```

## 不要

- ❌ 不要嵌套 confirm(同一时间只允许 1 个,新请求被拒绝 + dev warn)
- ❌ 不要把"信息提示"用 confirm(用 `toast()`),confirm 只用于"用户决策"
- ❌ 不要假设 confirm 一直在等(用户切屏 / app suspend 可能让 promise hang,关键路径上做超时保护)

## 关联组件

- [Toast](/docs/components/toast)— 单向反馈(不需用户决策)

## Decorations 装饰图元

*Source: `docs/components/decorations.mdx` · Slug: `/components/decorations`*

# Decorations 装饰图元

3 个用于沉浸式屏 / hero 区的视觉装饰原子,全部基于 `react-native-svg` 渲染,可与任何容器组合用。**它们是 absolute 定位的纯装饰,不接管 hit area / 布局,放在屏底部图层即可。**

| 组件 | 用途 |
|---|---|
| `GradientWash` | 线性渐变带 —— 屏顶 / 屏底 的颜色淡入淡出 |
| `RadialHalo` | 圆 / 椭圆径向光晕 —— hero 区点缀光斑 |
| `ScreenBackdrop` | 整屏沉浸式预设 —— 渐变底 + 多个 halo 组合(如 `warmOrange`) |

## 实时预览

下方渲染的就是 `src/components/business/Decorations/*.tsx` 本体。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">GradientWash · 单色顶部 wash</span>
      <div style={{ height: 120, position: 'relative', background: '#fff', borderRadius: 8, overflow: 'hidden' }}>
        <GradientWash height={120} color="#EB6E00" fromOpacity={0.15} toOpacity={0} />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">RadialHalo · 单光晕</span>
      <div style={{ height: 160, position: 'relative', background: '#fff', borderRadius: 8, overflow: 'hidden' }}>
        <RadialHalo size={200} color="#EB6E00" maxOpacity={0.25} style={{ position: 'absolute', top: -20, left: 60 }} />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">ScreenBackdrop warmOrange · 整屏预设(在 ScreenBackdrop 内层叠加 wash + 3 个 halo)</span>
      <div style={{ height: 240, width: 320, position: 'relative', borderRadius: 8, overflow: 'hidden' }}>
        <ScreenBackdrop preset="warmOrange" />
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { GradientWash, RadialHalo, ScreenBackdrop } from '@unif/react-native-design';

{/* 名片屏整屏沉浸式背景(预设) */}
<View style={{ flex: 1 }}>
  <ScreenBackdrop preset="warmOrange" />
  {/* 真实内容 */}
</View>

{/* 自定义 hero 区:屏顶橙色 wash + 右上 halo 点缀 */}
<View style={{ height: 220, position: 'relative' }}>
  <GradientWash height={220} color={c.primary} fromOpacity={0.18} toOpacity={0} />
  <RadialHalo
    size={180}
    color={c.primary}
    maxOpacity={0.20}
    style={{ position: 'absolute', top: -30, right: -30 }}
  />
  <View>{/* hero 内容 */}</View>
</View>
```

## GradientWash API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `height` | `number` | — | 渐变带高度 |
| `color` | `string` | — | 单色模式必填(顶 fromOpacity → 底 toOpacity) |
| `fromOpacity` | `number?` | `0.1` | 顶部透明度(单色模式) |
| `toOpacity` | `number?` | `0` | 底部透明度(单色模式) |
| `stops` | `ReadonlyArray<GradientStop>?` | — | 完全自定义 stops(与 color/fromOpacity 互斥) |
| `gradientId` | `string?` | 自动 | 同屏多 GradientWash 需要不同 id |
| `style` | `StyleProp<ViewStyle>` | — | 容器附加样式 |

## RadialHalo API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `size` | `number` | — | 宽(圆模式即直径) |
| `height` | `number?` | `size` | 椭圆高度,不传 = 圆 |
| `color` | `string` | — | 中心颜色 |
| `maxOpacity` | `number?` | `0.16` | 简化用法的中心最大透明度,自动生成 3 stop |
| `stops` | `ReadonlyArray<{offset, opacity}>?` | — | 完全自定义透明度分布(覆盖 maxOpacity) |
| `gradientId` | `string?` | 自动 | 同屏多 halo 需要不同 id |
| `style` | `StyleProp<ViewStyle>` | — | absolute 定位用 |

## ScreenBackdrop API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `preset` | `ScreenBackdropPreset` | — | 预设名,目前只有 `'warmOrange'`(暖橙渐变 + 3 halo)。**不传且无 `stops`/`halos` 时仅渲染 `c.background` 实色外壳** |
| `stops` | `{ light: GradientStop[]; dark: GradientStop[] }` | preset 推算 | 自定义全屏渐变 stops(scheme-aware),覆盖 preset |
| `halos` | `ReadonlyArray<ScreenBackdropHalo>` | preset 推算 | 自定义 halo 列表,覆盖 preset |
| `children` | `ReactNode` | — | 内容层(渲染在装饰层之上) |
| `style` | `StyleProp<ViewStyle>` | — | 外层附加样式 |

`ScreenBackdropHalo`:`{ size, height?, color?(默认 c.primary), maxOpacity?(默认 0.16), top?, bottom?, left?, right?, centerX? }`。

## useSvgId（生成 gradientId）

`useSvgId(prefix, override?)` —— 公共 hook,生成**唯一且 SVG 合法**的渐变 id,用来喂 `GradientWash` / `RadialHalo` 的 `gradientId`(或你自建 SVG 渐变的 `<LinearGradient id>` / `<RadialGradient id>`)。

React 19 的 `useId()` 返回含冒号的串(`:r0:`),不是合法的 SVG id(XML NCName);`useSvgId` 消毒冒号后拼上 `prefix`,保证同屏多渐变 id 互不覆盖 —— 正是上文「不要忘传 `gradientId`」的标准解法。

```tsx
import { GradientWash, useSvgId } from '@unif/react-native-design';

function Hero() {
  const gid = useSvgId('hero-wash');
  return (
    <GradientWash gradientId={gid} height={220} color="#EB6E00" fromOpacity={0.18} toOpacity={0} />
  );
}
```

| 参数 | Type | 说明 |
|---|---|---|
| `prefix` | `string` | 短前缀,区分同屏多 gradient(如 `"gw"` / `"rh"` / `"av"`) |
| `override` | `string?` | 有值时直接返回(跳过 `useId` 分配),用于外部受控 id |

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.background` | `useColors()` | `ScreenBackdrop` 外壳实色底 |
| `c.primary` | `useColors()` | `ScreenBackdrop` halo 默认色(`color` 缺省时) |
| `warmOrangePalette` | `@unif/react-native-design` | `warmOrange` preset 的 4 stop 渐变(light / dark) |

> `GradientWash` / `RadialHalo` 本身不读主题色 —— 颜色全由 `color` / `stops` 入参决定(`ScreenBackdrop` 内部才注入 `c.background` / `c.primary`)。

## 无障碍（a11y）

来源：`src/components/business/Decorations/{GradientWash,RadialHalo,ScreenBackdrop}.tsx`、`types.ts`。

3 个组件都是纯视觉装饰图层,均**无 `accessibilityRole` / `accessibilityLabel`**,也无可传的 a11y prop。

- `GradientWash` / `RadialHalo`:根 `<View>` 显式设 `pointerEvents="none"`,不拦截触摸、不暴露给 SR,只渲染 SVG 渐变。
- `ScreenBackdrop`:外壳 `<View>` 本身不设 a11y(它在装饰层之上承载 `children`);其内部叠加的 `GradientWash` / `RadialHalo` 子层各自 `pointerEvents="none"`。

语义应由这些装饰所承载 / 覆盖的内容(`children` 或上层业务屏)自行提供,不要给装饰图元挂交互或 a11y。

## 不要

- 不要在装饰组件上挂 onPress —— 它们是纯视觉图层,加交互会拦截真内容的 hit
- 不要在屏内放超过 3 个 RadialHalo —— SVG 太多影响渲染性能,真要多就考虑 Image 静态导出
- 不要把 ScreenBackdrop 用在普通业务屏 —— 用于品牌 hero(名片 / Splash / 扫码屏);普通 ScreenLayout 自带白底就够了
- 不要忘传 `gradientId` —— 同屏多 GradientWash / RadialHalo 共享一个默认 id,SVG defs 互覆盖导致后一个生效

## Empty 空态

*Source: `docs/components/empty.mdx` · Slug: `/components/empty`*

# Empty 空态

无内容状态——浅橙圆盘 illust（默认橙色 spark）+ 大字标题 + 小字描述。`icon` 可换成强语义图标(相机 / 权限 / 出错场景),常配合 SuggestionList 给出下一步操作。

## 实时预览

下方渲染的就是 `src/components/ui/Empty/Empty.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <Empty title="你好，我是 AI 助手" desc="告诉我你今天的工作目标，我来帮你规划" />
```

## 用法

```tsx
import { Empty } from '@unif/react-native-design';

<Empty
  title="你好，我是 AI 助手"
  desc="告诉我你今天的工作目标，我来帮你规划"
/>
```

通常配合 SuggestionList 使用，给用户初始话术：

```tsx
<Empty title="..." desc="..." />
<SuggestionList align="center" items={[
  { label: '今天的安排', leading: 'spark' },
  { label: '帮我查询数据', leading: 'spark' },
  { label: '新建一条记录', leading: 'spark' },
]} onPress={(item) => sendMessage(item.label)} />
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `title` | `string` | — | 大字标题（如「暂无数据」,15px / 600） |
| `desc` | `string` | — | 小字描述（建议下一步操作,13px / 400 / `c.foregroundSubtle`） |
| `icon` | `IconName` | `'spark'` | 圆盘内图标;相机域可传 `'camera-off'` / `'permission-denied'` / `'error-alert'` 等 |
| `testID` | `string` | — | E2E / 测试定位 |

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.primaryContainer` | `useColors()` | 圆盘背景色（浅橙） |
| `c.primary` | `useColors()` | 圆盘内 icon 色 |
| `c.foreground` | `useColors()` | 标题文字色 |
| `c.foregroundSubtle` | `useColors()` | 描述文字色 |
| `icon['2xl']` | `@unif/react-native-design` | 圆盘尺寸（56） |
| `type.h3` / `type.xs` | `@unif/react-native-design` | 标题（15）/ 描述（13）字号 |
| `space['4']` / `space['3']` / `space['7']` | `@unif/react-native-design` | gap（10）/ 水平 padding（8）/ 垂直 padding（16） |

## 无障碍（a11y）

来源：`src/components/ui/Empty/Empty.tsx`、`types.ts`。

本组件为展示型空态,无交互。源码是 `<View>` + 圆盘 `<Icon>` + 标题 `<Text>` +（可选）描述 `<Text>`,**未设置任何 a11y prop**(无 `accessibilityRole` / `accessibilityLabel`),也无可传的 a11y prop（仅 `title` / `desc` / `icon` / `testID`）。`title` / `desc` 文本默认对 SR 可读;圆盘内的 `<Icon>` 按其自身实现对 SR 隐藏（见 [图标](./icons)），故朗读内容即标题 + 描述。若需把「建议操作」做成可点项,放在 Empty 之外的 SuggestionList / [Button](./button) 上,各自带交互语义。

## 视觉规范

| 元素 | 规则 |
|---|---|
| illust | 56×56 圆（`icon['2xl']`），背景 `c.primaryContainer`，icon 28px `c.primary` |
| title | 15px / 600 / `c.foreground`（`type.h3` + `fw.semi`） |
| desc | 13px / 400 / `c.foregroundSubtle`（`type.xs`），居中 |
| 间距 | gap 10（`space['4']`），整体居中 |

## EntryCard 入口卡

*Source: `docs/components/entry-card.mdx` · Slug: `/components/entry-card`*

# EntryCard 入口卡

入口小卡 —— 横向 row,左 30×30 灰底 icon tile + 右 title/sub column。

跟 [Cell](./cell) 的区别:
- **独立 surface 小卡视觉**(bg + radius 14 + padding 12/14),不依赖 List 容器
- icon tile **灰底**(`surfaceContainer`)+ `foregroundMuted` icon,语义弱化
- **无 arrow / extra**,纯入口语义,适合放在 grid 双列里靠 caller `style={{flex:1}}` 撑等宽

retail biz2 设计稿 v7:Me 屏底部"设置 / 关于"两个入口从纵向 CellList 退化成 2×1 grid 横向小卡,省纵向空间。

## 实时预览

下方渲染的就是 `src/components/ui/EntryCard/EntryCard.tsx` 本体,通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'row', gap: 10, maxWidth: 360 }}>
    <EntryCard
      icon="settings"
      title="设置"
      sub="账号 / 通知 / 权限"
      onPress={() => {}}
      style={{ flex: 1 }}
    />
    <EntryCard
      icon="info"
      title="关于 Unif"
      sub="V 2.6.0"
      onPress={() => {}}
      style={{ flex: 1 }}
    />
  </div>
```

## 视觉规范

| 元素 | 规则 |
|---|---|
| 容器 | `bg: surface`,radius 14,padding `12px 14px` |
| 排布 | flex row + align center,gap 10 |
| icon tile | 30×30,radius 9,`bg: surfaceContainer`,内部 icon 16px `foregroundMuted` |
| title | 13.5 / medium / letterSpacing -0.2,`foreground` |
| sub | 11,`foregroundMuted`,可选省略 |
| 按下 | opacity 0.7(仅 `onPress` 存在时) |

## 用法

```tsx
import { EntryCard } from '@unif/react-native-design';
import { View } from 'react-native';

{/* grid 双列入口 —— Me 屏底部"设置 / 关于" */}
<View style={{ flexDirection: 'row', gap: 10 }}>
  <EntryCard
    icon="settings"
    title="设置"
    sub="账号 / 通知 / 权限"
    onPress={() => navigation.navigate('Setting')}
    style={{ flex: 1 }}
  />
  <EntryCard
    icon="info"
    title={`关于 ${env.appName}`}
    sub={`V ${APP_VERSION}`}
    onPress={() => navigation.navigate('About')}
    style={{ flex: 1 }}
  />
</View>
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `icon` | `IconName` | — | 左侧 icon tile 内的图标 |
| `title` | `string` | — | 主标题(13.5 medium,numberOfLines=1) |
| `sub` | `string` | — | 副标题(11 muted),省略不渲染该行 |
| `onPress` | `() => void` | — | 点击回调;不传时不挂 Pressable,静态展示 |
| `style` | `StyleProp<ViewStyle>` | — | 外层附加样式,常用于 grid 列设 `flex: 1` |
| `testID` | `string` | — | E2E / 测试定位 |

## 主题键（Tokens）

| Token | 来源 | 作用 |
|---|---|---|
| `c.surface` | `useColors()` | 卡片背景色 |
| `c.surfaceContainer` | `useColors()` | icon tile 灰底色 |
| `c.foregroundMuted` | `useColors()` | tile 内 icon 色 + sub 文字色 |
| `c.foreground` | `useColors()` | title 文字色 |
| `radius['2xl']` | `@unif/react-native-design` | 卡片圆角(14) |
| `icon.lg` | `@unif/react-native-design` | icon tile 尺寸(30) |
| `space['4']` / `space['5']` / `space['6']` | `@unif/react-native-design` | row gap(10)/ 垂直 padding(12)/ 水平 padding(14) |

## 无障碍（a11y）

来源：`src/components/ui/EntryCard/EntryCard.tsx`、`types.ts`。

a11y 语义是**条件性**的:仅当传了 `onPress` 时,EntryCard 才用 `<Pressable>` 包裹并声明语义;无 `onPress` 时渲染为纯 `<View>`,无 a11y 角色（与「不响应按压」一致）。

- 默认 `accessibilityRole`：可点时为 `'button'`(`onPress` 缺省则无角色)。
- a11y props(仅 `onPress` 时生效):`accessibilityLabel` 取自必填的 `title`(`<Pressable accessibilityLabel={title}>`),无需另传。
- 状态语义:源码未设 `accessibilityState`(无 disabled/selected/checked 概念)。

```tsx
// 可点:role=button、label 自动取 title
<EntryCard icon="settings" title="设置" sub="账号 / 通知 / 权限" onPress={() => ...} />
```

## 不要

- ❌ 不要在 EntryCard 内放 arrow —— 它的语义是"独立入口卡",不是 List 行。需要 chevron 用 [Cell](./cell)。
- ❌ 不要把 title 拉长到换行 —— 单卡是紧凑入口,设计上只 numberOfLines=1。长文本用 [Card](./card) + 自渲。
- ❌ 不要做超过 4 张并排 —— 4 张以上信息密度过高,改用 [Grid](./grid) + ModernAppCell。

## Form 表单

*Source: `docs/components/form.mdx` · Slug: `/components/form`*

# Form 表单

表单容器——分组标题 + 行（label + 控件）+ 行间 hairline 分隔。

## 实时预览

下方渲染的就是 `src/components/ui/Form/Form.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<FormDemo />

## API

来源：`src/components/ui/Form/types.ts`、`{Form,FormGroup,FormRow}.tsx`。

### `<Form>`

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `children` | `ReactNode` | — | 通常是若干 `FormGroup` / `FormRow`；根容器纵向堆叠，组间 `gap: space[7]`（16） |
| `testID` | `string?` | — | E2E / 测试定位 |

### `<FormGroup>`

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `label` | `string?` | — | 分组标题（uppercase 小标签风格）；不传则不渲染标题行 |
| `children` | `ReactNode` | — | 该分组下若干 `FormRow`；行间自动插 1px hairline 分隔（除首行外） |
| `testID` | `string?` | — | E2E / 测试定位 |

### `<FormRow>`

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `label` | `string` | — | 字段标题（左侧） |
| `children` | `ReactNode` | — | 字段控件（Input / Switch 等，右侧） |
| `required` | `boolean?` | `false` | 必填标记，label 后渲染红色 `*`（色值 `c.error`） |
| `error` | `string?` | — | 错误信息，渲染在该行下方（红字） |
| `testID` | `string?` | — | E2E / 测试定位 |

> `FormGroup` 动态列表（运行时增删 `FormRow`）必须给每个 child 传稳定 `key`；不传时 fallback 到 `__row-${i}`，仅适用于**静态**列表，动态列表会导致 state 漂移。

## 视觉规范

来源：`src/components/ui/Form/styles.ts`（值取自 `src/theme/tokens.ts`）。

| 元素 | 规则 |
|---|---|
| 分组标题 | `t.xs`（13）/ `fw.semi`（600）/ `c.foregroundSubtle`，全大写、`letterSpacing: 1`、`paddingHorizontal: space[1]`（4） |
| 分组卡片 | `c.surface` 白底，`radius.lg`（10）圆角，`overflow: hidden`，组内 `gap: space[3]`（8） |
| Form Row | `minHeight: 48`，左 label + 右控件，`paddingHorizontal: space[7]`（16）/ `paddingVertical: space[5]`（12） |
| 行 label | `t.sm`（14）/ `fw.medium`（500）/ `c.foreground` |
| 行间分隔 | `StyleSheet.hairlineWidth`、`c.outline`（亮色 `#EDEDED`）（这是 form 的例外，**不**用 gap） |
| 必填标记 | label 后带 `*`，色 `c.error`（亮色 `#F4511E`） |
| 错误提示 | 行下方 `t.micro`（11）/ `c.error` 红字 |

## 用法

```tsx
import { Form, FormGroup, FormRow, Input, Switch } from '@unif/react-native-design';

<Form>
  <FormGroup label="基本信息">
    <FormRow label="姓名" required>
      <Input value={name} onChangeText={setName} placeholder="请输入" />
    </FormRow>
    <FormRow label="手机号" error="格式不正确">
      <Input value={phone} onChangeText={setPhone} keyboardType="phone-pad" />
    </FormRow>
  </FormGroup>

  <FormGroup label="拜访设置">
    <FormRow label="提醒">
      <Switch value={remind} onChange={setRemind} />
    </FormRow>
  </FormGroup>
</Form>
```

## 无障碍（a11y）

来源：`src/components/ui/Form/{Form,FormGroup,FormRow}.tsx`、`types.ts`。

`Form` / `FormGroup` / `FormRow` 都是纯布局容器,源码全是 `<View>` + `<Text>`(分组标题 / 字段 label / 必填星号 / 错误文字),**三者均未设置任何 a11y prop**(无 `accessibilityRole` / `accessibilityLabel` / state),也无可传的 a11y prop。

- 真正的 a11y 语义来自传入 `FormRow` 的**控件 children**(如 [Input](./input) 的 `<TextInput>`、[Switch](./switch)),由控件自身承载 role / label / state。
- `FormRow` 的 `label`、必填 `*`、`error` 文字渲染为相邻 `<Text>`,默认对 SR 可读,但**未与控件做程序化关联**(无 `accessibilityLabelledBy` / describedBy)。为确保 SR 把字段名读到对应控件上,建议在控件上显式补 `accessibilityLabel`(如 `<Input accessibilityLabel="姓名" />`),错误态可补 `accessibilityHint`。

```tsx
// label 是视觉文本;控件上显式补 accessibilityLabel 把字段名关联到输入
<FormRow label="姓名" required>
  <Input value={name} onChangeText={setName} accessibilityLabel="姓名" />
</FormRow>
```

## 与 Cell · List 的区别

| 用途 | 选哪个 |
|---|---|
| 数据展示（设置项、客户列表）| [Cell · List](./cell) — 白卡 + gap |
| 数据录入（表单）| **Form** — 白卡 + 行间 hairline |

录入场景密度更高，hairline 分隔比 gap 更高效；展示场景反之。

## GlassStats 玻璃数据条

*Source: `docs/components/glass-stats.mdx` · Slug: `/components/glass-stats`*

# GlassStats 玻璃数据条

横向多列数据展示条,每格显示一个数字 + 标签。玻璃质感(半透明 + blur),适合放在沉浸式背景上(名片屏 / 数据汇总卡)。

数据格式是元组 `[count, label]`,count 已经格式化好(如 `'12'` / `'¥2,016'` / `'99+'`),组件不做格式化。

## 实时预览

下方渲染的就是 `src/components/business/GlassStats/GlassStats.tsx` 本体。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">2 列</span>
      <GlassStats items={[['12', '今日'], ['86', '本月']]} />
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">3 列 · 个人业绩</span>
      <GlassStats items={[['¥2,016', '销售额'], ['28', '订单'], ['12', '客户']]} />
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">4 列 · 综合统计</span>
      <GlassStats
        items={[
          ['256', '总数'],
          ['18', '本周'],
          ['¥12.3万', '金额'],
          ['98%', '完成率'],
        ]}
      />
    </div>
  </div>
```

## 用法

```tsx
import { GlassStats } from '@unif/react-native-design';

{/* 个人名片屏业绩 */}
<GlassStats
  items={[
    [String(visitCount), '本月拜访'],
    [`¥${formatAmount(amount)}`, '销售额'],
    [String(orderCount), '订单'],
  ]}
/>
```

## API

| Prop | Type | 必填 | 说明 |
|---|---|---|---|
| `items` | `ReadonlyArray<[count: string, label: string]>` | ✓ | 数据列,2~4 列均可。`count` 已格式化字串,`label` 是中文标签 |

## 无障碍（a11y）

来源：`src/components/business/GlassStats/GlassStats.tsx`、`types.ts`。

本组件为纯数据展示条,无交互。源码全是 `<View>` + `<Text>`(每列一个 `count` 文本 + 一个 `label` 文本),**未设置任何 a11y prop**(无 `accessibilityRole` / `accessibilityLabel`),也没有可传的 a11y prop(仅 `items`)。底层 `<Text>` 默认对 SR 可读,会按「数字 + 标签」顺序逐列朗读;配套的 `BlurLayer` 是 `pointerEvents="none"` 装饰层。无受控状态(checked/selected/disabled 均不适用)。

## 视觉规范

来源：`src/components/business/GlassStats/styles.ts`（值取自 `src/theme/{tokens,colors,shadow}.ts`）。

| 元素 | 规则 |
|---|---|
| count 字号 | `rf(20)`（本地常量,无对应 type token）· `fw.bold` · `c.foreground` · `fontFamily: fontMono` · `letterSpacing: -0.3` |
| label 字号 | `t.micro`（11）· `c.foregroundMuted` · `paddingTop: space[1]` |
| 列间分隔 | `StyleSheet.hairlineWidth` 竖线 · `c.glassSeparator`（亮色 `rgba(0,0,0,0.08)`） |
| 容器 | 双层：外层 `glassShell` 仅 `radius['2xl']`（14）+ `s.glassBar` shadow；内层 `glass` `radius['2xl']` + `overflow:hidden` + `c.glassBorder` 边框；顶部 1px inset 高光线 `c.glassStatsHighlight` |
| 玻璃底 | 由 `<BlurLayer intensity="soft" />` 接管（BlurView + `c.glassTintLight` 白纱），随 light/dark scheme 自动切 |

## 不要

- 不要在组件内做数字格式化 —— 业务层(`@/utils/format`)做好再传入,避免 i18n / 千分位 / 单位逻辑散落
- 不要超过 4 列 —— 屏宽限制,5 列以上 label 会挤换行,改用 [Cell](./cell.mdx) 列表
- 不要单列用 —— 单数字直接用 `<Text>` + `t.heroLg`,没必要套 GlassStats 的胶囊容器

## Grid 九宫格

*Source: `docs/components/grid.mdx` · Slug: `/components/grid`*

# Grid 九宫格

主页或分类页的图标入口——3 列 / 4 列网格，每格 icon + label。

## 实时预览

下方渲染的就是 `src/components/ui/Grid/Grid.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
    <span className="demo-label">4 列</span>
    <Grid columns={4} items={items} />
    <span className="demo-label">3 列</span>
    <Grid columns={3} items={items.slice(0, 6)} />
    <span className="demo-label">2 列 · 大图标卡片入口</span>
    <Grid columns={2} items={items.slice(0, 4)} />
    <span className="demo-label">6 列 · 紧凑入口</span>
    <Grid columns={6} items={items.slice(0, 6)} />
    <span className="demo-label">{'card={false} · 嵌套已有白卡，去掉外层背景'}</span>
    <View style={{ backgroundColor: '#fff', padding: 12, borderRadius: 12, borderWidth: 1, borderColor: 'var(--ifm-color-emphasis-200)' }}>
      <Grid columns={4} items={items.slice(0, 4)} card={false} />
    </View>
  </div>
```

## API

来源：`src/components/ui/Grid/types.ts`、`Grid.tsx`。

### `<Grid>`

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `items` | `GridItem[]` | — | 入口列表（见下） |
| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `4` | 列数；类型外的值（如 `7`）会**静默回退到 4 列**并打 warn |
| `onPress` | `(item: GridItem) => void` | — | 点击某格回调；可选，但每格恒挂 Pressable，角色恒为 `button` |
| `card` | `boolean` | `true` | 是否套白色卡片；`false` 则背景透明（嵌进已有白卡时用） |
| `testID` | `string?` | — | 容器 testID；每格自动派生为 `${testID}-${item.id}` |

### `GridItem`

| 字段 | Type | 默认 | 说明 |
|---|---|---|---|
| `id` | `string` | — | 唯一键，也用于派生 testID |
| `icon` | `IconName` | — | 图标名（[图标 catalog](./icons)） |
| `label` | `string` | — | 格子文字，同时作为该格 `accessibilityLabel` |
| `badge` | `number \| string?` | — | icon 右上角标（用 string 才能写 `'99+'`） |
| `testID` | `string?` | — | 单格 testID（不传则自动用 `${gridTestID}-${id}`） |

## 视觉规范

来源：`src/components/ui/Grid/styles.ts`（值取自 `src/theme/tokens.ts`）。

| 元素 | 规则 |
|---|---|
| 容器（`card`） | `c.surface` 白底，`radius.xl`（12）圆角，`paddingVertical: space[5]`（12）/ `paddingHorizontal: space[3]`（8），1px `c.outline` 边框 |
| 列宽 | 等宽，按 `columns` 取 `100% / 50% / 33.3% / 25% / 20% / 16.7%`（StyleSheet 预生成） |
| 单格 | `paddingVertical: space[5]`（12），居中 icon + label，`gap: space[2]`（6） |
| Icon | `size=28`（介于 `icon.md`/`icon.lg`），色固定 `c.foregroundMuted` |
| Label | `t.xxs`（12）/ `fw.medium`（500）/ `c.foreground` |
| Badge | 叠在 icon 右上的小红角标：`c.error` 底、`c.onError` 字、`t.nano`（10）、`fw.bold` |

## 用法

```tsx
import { Grid } from '@unif/react-native-design';

<Grid
  columns={4}
  items={[
    { id: 'visit',   icon: 'location', label: '拜访' },
    { id: 'orders',  icon: 'order',    label: '订单', badge: 3 },
    { id: 'sku',     icon: 'box-list', label: '商品' },
    { id: 'reports', icon: 'list',     label: '报表' },
    { id: 'msg',     icon: 'mail',     label: '消息' },
    { id: 'team',    icon: 'user',     label: '团队' },
    { id: 'settings',icon: 'settings', label: '设置' },
    { id: 'more',    icon: 'more-h',   label: '更多' },
  ]}
  onPress={(item) => navigation.push(item.id)}
/>
```

## 无障碍（a11y）

来源：`src/components/ui/Grid/Grid.tsx`、`types.ts`。

- 默认 `accessibilityRole`：每个格子都渲染为 `<Pressable accessibilityRole="button">`（无论 `onPress` 是否传 —— `onPress` 可选,但 Pressable 恒以 `onPress={() => onPress?.(item)}` 挂载,故角色恒为 `button`）。
- a11y props：每格 `accessibilityLabel` 取自必填的 `item.label`（`GridItem.label: string`）—— icon 自身对 SR 隐藏（见 [图标](./icons)），label 文本即朗读内容。`badge` 角标未单独纳入 a11y 朗读。
- 状态语义：源码未设 `accessibilityState`（无 selected/disabled/checked 概念）。

```tsx
// 每格 role=button、label 取 item.label
<Grid columns={4} items={[{ id: 'visit', icon: 'location', label: '拜访' }]} onPress={(item) => ...} />
```

## IconButton 图标按钮

*Source: `docs/components/icon-button.mdx` · Slug: `/components/icon-button`*

# IconButton 图标按钮

只放 icon 的方形按钮,常用于 NavBar 左右 slot、卡片右上 action、列表行 trailing。区别于 Button,IconButton 没文本,**必须显式传 `accessibilityLabel`** 给 SR 用户。

`size` 走 `ButtonSize`(sm/md/lg = 28/36/44),`variant` 走 `ButtonVariant`(默认 `'ghost'` 透明底)。

## 实时预览

下方渲染的就是 `src/components/ui/IconButton/IconButton.tsx` 本体。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">size · sm 28 / md 36 / lg 44</span>
      <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
        <IconButton icon="bell" size="sm" accessibilityLabel="通知" />
        <IconButton icon="bell" size="md" accessibilityLabel="通知" />
        <IconButton icon="bell" size="lg" accessibilityLabel="通知" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">variant · neutral 中性 / primary 橙底 / ghost 透明</span>
      <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
        <IconButton icon="scan" variant="neutral" accessibilityLabel="扫码" />
        <IconButton icon="scan" variant="primary" accessibilityLabel="扫码" />
        <IconButton icon="scan" variant="ghost" accessibilityLabel="扫码" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">disabled · opacity 0.5 + 不响应</span>
      <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
        <IconButton icon="check" variant="primary" accessibilityLabel="确认" disabled />
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { IconButton } from '@unif/react-native-design';

{/* NavBar 右侧扫码按钮 */}
<IconButton
  icon="scan"
  size="md"
  variant="neutral"
  accessibilityLabel="扫码"
  accessibilityHint="打开二维码扫描"
  onPress={() => navigation.navigate('Scanner')}
/>

{/* 卡片右上关闭 */}
<IconButton
  icon="close"
  size="sm"
  variant="ghost"
  accessibilityLabel="关闭"
  onPress={onClose}
/>
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `icon` | `IconName` | — | 图标名(来自 `@/components/ui/Icon` catalog) |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 方形边长 28 / 36 / 44 |
| `variant` | `ButtonVariant` | `'ghost'` | 视觉变体,跟 Button 同一套 palette |
| `color` | `string?` | variant fg | icon 描色 override(仅 icon 色,bg/border 仍由 variant 决定) |
| `disabled` | `boolean` | `false` | 不响应 + opacity 0.5 |
| `accessibilityLabel` | `string` | — | **必填** —— icon-only 按钮 SR 用户唯一信息源 |
| `accessibilityHint` | `string?` | — | 行为不显然时填(如"打开扫描器") |
| `onPress` | `() => void` | — | 点击回调 |
| `style` | `StyleProp<ViewStyle>` | — | 容器附加样式 |
| `testID` | `string?` | — | E2E / 测试定位 |

## 无障碍（a11y）

来源：`src/components/ui/IconButton/types.ts`、`IconButton.tsx`、`Button/ButtonBase.tsx`。

- 默认 `accessibilityRole`：`'button'`（IconButton 透传给共享的 `ButtonBase`，其 `accessibilityRole = 'button'` 为默认参数）。
- a11y props：`accessibilityLabel` **是 TS 强制必填**（`types.ts` 中 `accessibilityLabel: string`，无 `?`）—— icon-only 无可见文本，缺则编译报错；`accessibilityHint` 可选，仅在「行为不显然」时补（如「切换密码可见」），普通「确认 / 取消 / 返回」不必加。
- 状态语义：`accessibilityState.disabled` 取 `!isInteractive`（在 `ButtonBase` 内由 `disabled` 推导，IconButton 无 `loading`）。

```tsx
// label 必填(SR 唯一信息源);hint 仅在行为不显然时补
<IconButton icon="scan" accessibilityLabel="扫码" accessibilityHint="打开二维码扫描" onPress={...} />
```

## 不要

- 不要把 icon 当装饰用 IconButton —— 装饰用 `<Icon>` 即可,没 hit area 浪费
- 不要在 IconButton 内文字 + icon 混搭 —— 用 [Button](./button.mdx) 的 `rightIcon` / `leftIcon` prop

## 图标

*Source: `docs/components/icons.mdx` · Slug: `/components/icons`*

# 图标

手绘 24×24 描边 SVG。所有图标遵守同一组绘制规则。**无 icon font、无 Unicode 承载 UI、无装饰 emoji。**

按业务语义分 15 类堆栈展示,顶部搜索框 `⌘K` 聚焦,点击 cell 复制图标语义名。

<IconCatalog />

## 在 RN 中使用

```tsx
import { Icon } from '@unif/react-native-design';
import { useColors } from '@unif/react-native-design';

function Demo() {
  const c = useColors();
  return (
    <>
      <Icon name="send" size={20} />
      <Icon name="check" size={18} color={c.success} />
      <Icon name="close" size={14} color={c.foregroundSubtle} strokeWidth={2} />
    </>
  );
}
```

`name` 是 TypeScript 字面量联合类型——所有图标名都有自动补全；`IconName` 由 `src/icons/data.ts` 生成（该文件 **AUTO-GENERATED，请勿手改**）。

### `<Icon>` props

来源：`src/components/ui/Icon/types.ts`、`Icon.tsx`。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `name` | `IconName` | — | 图标语义名（字面量联合类型，自动补全） |
| `size` | `number?` | `r(18)`（随设备宽度缩放） | 宽高（正方形）；传入值应已经过 `r()` 缩放 |
| `color` | `string?` | `c.foregroundMuted` | 传给 SVG `stroke`（及 `fill="currentColor"` 元素） |
| `strokeWidth` | `number?` | 每图标自带值（多数 `1.75`，`check` 为 `2`） | 覆盖描边宽度 |
| `style` | `StyleProp<ViewStyle>?` | — | 外层 `<View>` 样式 |
| `testID` | `string?` | — | E2E / 测试定位（挂在外层 `<View>`） |

> 未知 `name` 不抛错：打 `warn` 并渲染一个等尺寸空 `<View>` 占位（同样对 SR 隐藏）。

## 绘制规则

每个新图标必须满足：

| 属性 | 值 |
|---|---|
| `viewBox` | `0 0 24 24` |
| `stroke-width` | `1.75`（加粗变体 `2`，仅 `check`） |
| `stroke-linecap` | `round` |
| `stroke-linejoin` | `round` |
| `fill` | `none`（实心填充用 `fill="currentColor"`） |
| `color` | `<Icon>` 的 `color` prop → `stroke`，默认 `c.foregroundMuted`（不传 color 时） |
| 组件默认 `size` | `r(18)`（随设备宽度缩放）；调用方传值应包 `r()`，如 `size={r(20)}` |

## 添加新图标

1. 在 `src/icons/svg/<name>.svg` 加新文件,遵守上面的绘制规则(只用 `<path>` / `<rect>` / `<circle>`;polyline / polygon 先转 path)
2. 运行 `node scripts/build-icons.js`,脚本扫 `src/icons/svg/*.svg` 重新生成 `src/icons/data.ts`(纯 regex 抽属性,无第三方依赖)。**不要手改 `data.ts`** —— 它是生成产物(`{ strokeWidth, elements }`),改 SVG 再跑脚本
3. 文档站走的 `website/src/components/iconsCatalog.ts` 是从 `@unif/react-native-design` barrel re-export 的薄壳(`ICONS` / `ICON_NAMES` / `IconName`),自动同步,无需再生成
4. `IconName` TypeScript 字面量类型自动包含新名字,IDE 立即给出补全
5. 若新图标属于某个语义类别,把它加进 `website/src/components/IconCatalog.tsx` 的 `CATEGORIES` 数组对应组里;若它是某个 appId 的图标,补 `APP_MAPPINGS`

## 实现细节

`src/components/ui/Icon/Icon.tsx` 用 `react-native-svg` 渲染——`<Svg>` + `<Path>` / `<Circle>` / `<Rect>`，路径数据来自 `src/assets/icons/data.ts`。`color` prop 传给 `stroke`，`strokeWidth` 走每图标默认值或可覆盖。

```tsx
// 摘录
import Svg, { Circle, Path, Rect } from 'react-native-svg';
import { ICONS } from '@unif/react-native-design';

<Svg width={size} height={size} viewBox="0 0 24 24"
     fill="none" stroke={color}
     strokeWidth={def.strokeWidth}
     strokeLinecap="round" strokeLinejoin="round">
  {def.elements.map((el, i) => /* path/circle/rect */)}
</Svg>
```

## 无障碍（a11y）

来源：`src/components/ui/Icon/Icon.tsx`、`types.ts`。

`<Icon>` 是纯视觉图元，**源码刻意把它对 SR 隐藏**：外层 `<View>`（正常路径与未知图标 fallback 路径都）显式设 `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`。它**不**设 `accessibilityRole` / `accessibilityLabel`，也没有可传的 a11y prop（仅 `name` / `size` / `color` / `strokeWidth` / `style` / `testID`）。

这是有意为之：图标的语义应由**承载它的可交互父组件**提供朗读文案 —— 如 [IconButton](./icon-button) 的必填 `accessibilityLabel`、[Button](./button) 的 `label`。独立装饰用 `<Icon>` 即可，无需也不应给它单独挂 a11y。

## 头像

头像不是图标，是实体。所有头像都是**单字符 monogram**（`我` / `AI` / 客户首字母）放在彩色圆盘上。**绝不**在头像里放图片或多于 1 个字符。

详见 [Avatar 组件](/docs/components/avatar)。

## Input 输入框

*Source: `docs/components/input.mdx` · Slug: `/components/input`*

# Input 输入框

单行输入。**44px** 高（`control.lg`），**8px** 圆角（`radius.md`），灰底无边框，focus 时显橙色描边。

> 多行内容请用 [`<Textarea />`](./textarea)。Input 不接受 `multiline` / `numberOfLines`。

## 实时预览

下方渲染的就是 `src/components/ui/Input/Input.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<InputDemo />

## 状态

来源：`src/components/ui/TextField/styles.ts`（值取自 `src/theme/colors.ts`）。状态优先级 `error > focus > filled > idle`。

| 状态 | 背景 | 边框 |
|---|---|---|
| `idle` | `c.surfaceContainerHigh`（亮色 `#F0F0F0`） | 透明 |
| `focus` | `c.surface`（`#FFFFFF`） | 1px `c.primary`（`#EB6E00`） |
| `filled` | `c.surface`（`#FFFFFF`） | 1px `c.outline`（`#EDEDED`） |
| `error` | `c.surface`（`#FFFFFF`） | 1px `c.error`（`#F4511E`） |

## 视觉规范

来源：`src/components/ui/TextField/styles.ts`。

| 元素 | 规则 |
|---|---|
| 高度 | 44px（`control.lg`，可用 `height` prop 覆盖） |
| 圆角 | 8px（`radius.md`） |
| 内边距 | `paddingHorizontal: space[5]`（12） |
| 字号 | `t.body`（15），色 `c.foreground`（`#333333`） |
| 占位文字 | `c.foregroundSubtle`（`#999999`） |
| 错误文字 | 下方独立 `<Text>`，`t.micro`（11）/ `c.error` |
| leading / trailing | 任意 `ReactNode`（自填 `<Icon>` 等）；间距 `gap: space[3]`（8） |
| disabled | 容器 `opacity: 0.5` + `editable=false` |

## 用法

```tsx
import { Input, Icon } from '@unif/react-native-design';
import { useColors } from '@unif/react-native-design';

<Input value={text} onChangeText={setText} placeholder="搜索…" />

{/* 密码：直接透传 RN TextInput 的 secureTextEntry */}
<Input
  value={pwd}
  onChangeText={setPwd}
  secureTextEntry
  placeholder="密码"
/>

{/* 多行：用 Textarea，不要再用 Input multiline */}
<Textarea
  value={text}
  onChangeText={setText}
  minHeight={88}
  placeholder="详细说明…"
/>

{/* 错误态 */}
<Input
  value={text}
  onChangeText={setText}
  error="格式不正确"
/>

{/* 自定义前后插槽 —— 颜色走 hook */}
function MyForm() {
  const c = useColors();
  return (
    <Input
      value={text}
      onChangeText={setText}
      leading={<Icon name="search" size={18} color={c.foregroundSubtle} />}
      trailing={text ? <Icon name="close" size={14} color={c.foregroundSubtle} /> : null}
    />
  );
}
```

## API

`InputProps` = **`Omit<TextInputProps, 'style' | 'multiline' | 'numberOfLines'>`** + 这 6 个扩展。所有 RN [`TextInput` props](https://reactnative.dev/docs/textinput)（`value` / `onChangeText` / `placeholder` / `secureTextEntry` / `keyboardType` / `returnKeyType` / `autoCapitalize` 等）都直接可用。

| Prop | Type | 说明 |
|---|---|---|
| `leading` | `ReactNode?` | 前置插槽（图标、label 等） |
| `trailing` | `ReactNode?` | 后置插槽（清除按钮、显示密码切换等） |
| `error` | `string?` | 错误文字 —— 容器进入 error 态（红描边）并在下方显示 |
| `height` | `number?` | 覆盖容器高度，默认 `dim.controlLg`（44） |
| `disabled` | `boolean?` | 整体禁用 + 视觉变灰，优先级高于 `editable` |
| `containerStyle` | `StyleProp<ViewStyle>?` | 容器外层样式（不是 TextInput 的 style） |

> `testID` 来自透传的 `TextInputProps`：设在外层容器，内层 `<TextInput>` 自动派生 `${testID}-input`。`style` / `multiline` / `numberOfLines` 被 `Omit` 掉——容器样式走 `containerStyle`，多行请用 [`<Textarea />`](./textarea)。

> 没有内置的 `clearable` / `leadingIcon` —— 自己组合 `<Icon>` 给 `leading`/`trailing` 即可。`Search` 组件就是基于这种组合的预设。多行文本请用 [`<Textarea />`](./textarea)。

## 无障碍（a11y）

来源：`src/components/ui/Input/Input.tsx`、`TextField/TextFieldBase.tsx`、`types.ts`。

输入框的核心 a11y 来自 RN 内置的 [`TextInput`](https://reactnative.dev/docs/textinput)（Input 是 `TextFieldBase` 的薄 wrap，最终渲染原生 `<TextInput>`）。

- 默认 `accessibilityRole`：不显式设置 —— 继承底层 `<TextInput>`（RN/平台自带文本框语义，无需我们硬编码 role）。
- a11y props：`InputProps` = `Omit<TextInputProps, 'style' | 'multiline' | 'numberOfLines'>` + 6 个扩展，所以 RN `TextInput` 的全部 a11y / 行为 props（`accessibilityLabel`、`placeholder`、`keyboardType`、`secureTextEntry` 等）都直接透传到 `<TextInput>`。朗读文案优先来自 `accessibilityLabel`，缺省时由 `placeholder` / `value` 提供。
- 包裹层**唯一额外设置**的 a11y 是：`disabled` 时对内层 `<TextInput>` 设 `accessibilityState={{ disabled: true }}`（同时 `editable=false`，`disabled` 优先级高于 `editable`）；非 disabled 时不附加该状态。
- `error` 文字渲染为下方独立 `<Text>`，**未**与输入框做程序化关联（无 `accessibilityLabelledBy` / describedBy），SR 会作为相邻文本读到。

```tsx
// placeholder 无法完全替代 label;无可见 label 时显式传 accessibilityLabel
<Input value={phone} onChangeText={setPhone} placeholder="11 位手机号" accessibilityLabel="手机号" keyboardType="phone-pad" />
```

## Loading 加载

*Source: `docs/components/loading.mdx` · Slug: `/components/loading`*

# Loading 加载

旋转加载指示器。`size` 调直径（默认 18，`< 8` 会被钳到 8），`thickness` 调描边粗细（默认 2），`color` 默认主橙 `c.primary`。

## 实时预览

下方渲染的就是 `src/components/ui/Spinner/Spinner.tsx` 本体（reanimated 4 worklet 驱动旋转动画），通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">尺寸</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
        <Spinner size={14} />
        <Spinner size={18} />
        <Spinner size={24} />
        <Spinner size={32} />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">颜色</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
        <Spinner color="#EB6E00" />
        <Spinner color="#52C41A" />
        <Spinner color="#3775F6" />
        <Spinner color="#999" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">thickness · 描边粗细</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
        <Spinner thickness={1} />
        <Spinner thickness={2} />
        <Spinner thickness={3} />
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { Spinner } from '@unif/react-native-design';
import { useColors } from '@unif/react-native-design';

function Demo() {
  const c = useColors();
  return (
    <>
      <Spinner />                                       {/* 默认 18px 主橙 */}
      <Spinner size={24} />                             {/* 24px */}
      <Spinner color={c.success} />                     {/* 绿色 */}
      <Spinner color={c.foregroundSubtle} thickness={1.5} />  {/* 细线灰 */}
    </>
  );
}
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `size` | `number?` | `18` | 直径（含 stroke）；非有限或 `< 8` 钳到 8（打 warn） |
| `color` | `string?` | `c.primary`（运行期 hook 取） | 旋转弧颜色（轨道色固定 `c.outline`） |
| `thickness` | `number?` | `2` | 描边粗细；`≤ 0` fallback 到 2 |
| `style` | `StyleProp<ViewStyle>?` | — | 外层样式 |
| `testID` | `string?` | — | E2E / 测试定位 |

## 无障碍（a11y）

来源：`src/components/ui/Spinner/Spinner.tsx`、`Spinner.web.tsx`、`types.ts`。

Spinner 是纯视觉旋转指示器，**源码刻意把自己对 SR 隐藏**：根节点（native 的 `Animated.View` / web 的 `View`）显式设 `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`（两端实现一致）。它**不**设 `accessibilityRole='progressbar'`、也不设 `accessibilityState={{ busy }}` 或 `accessibilityLabel`。

因此「正在加载」的语义必须由**外部上下文**声明 —— 例如在包裹容器上设 `accessibilityState={{ busy: true }}`、或用一段状态文案（如 `<Text>加载中…</Text>` / live region）告知 SR；不要指望 Spinner 自身朗读。组件本身无可配置的 a11y prop（仅 `size` / `color` / `thickness` / `style` / `testID`）。

## 节奏

900ms 一圈，线性 easing，不要回弹。这是设计令牌 [`motion`](/docs/design/tokens/motion) 之外的特例——加载体感需要稳定均匀。

## Logo 主标

*Source: `docs/components/logo.mdx` · Slug: `/components/logo`*

# Logo 主标

Unif 品牌主标——白色简化飞鸟剪影 + 底部"健康快乐"中文标语，整体置于主橙 `#EB6E00` 背景上。

## 实时预览

下方渲染的就是 `src/components/ui/Logo/Logo.tsx` 本体,通过 `react-native-web` 翻译成浏览器节点。`source` 由 consumer 自传(品牌资产由消费者持有),文档站这里通过本地包装传入 `static/img/logo.png`。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">默认 size=64 · borderRadius=size/4 squircle</span>
      <Logo />
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">尺寸档位 32 / 64 / 96 / 120</span>
      <div style={{ display: 'flex', alignItems: 'flex-end', gap: 16 }}>
        <Logo size={32} />
        <Logo size={64} />
        <Logo size={96} />
        <Logo size={120} />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">borderRadius 覆盖</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
        <Logo size={64} borderRadius={0} />
        <Logo size={64} />
        <Logo size={64} borderRadius={32} />
      </div>
      <span style={{ fontSize: 12, color: '#999' }}>0 直角 · 默认 squircle · 32 满圆</span>
    </div>
  </div>
```

## 资源位置

| 用途 | 路径 | 说明 |
|---|---|---|
| RN App / 设计系统 `Logo` 组件 | `src/assets/logo.png` | 主标 1024×1024 RGBA（飞鸟 + "健康快乐"） |
| 文档站 navbar / OG image / Favicon | `website/static/img/logo.png` | 同源镜像，`docusaurus.config.ts` 内三处都引用同一份 |

## 用法

### React Native（推荐：用 `<Logo>` 组件）

```tsx
import { Logo } from '@unif/react-native-design';

<Logo />                                       // 默认 64×64 squircle
<Logo size={120} />                            // App icon 预览
<Logo size={32} borderRadius={32} />           // 满圆 / drawer 头像
```

### Web / Docusaurus（静态资源）

```html
<img src="/img/logo.png" alt="Unif" width="64" height="64" />
```

### App Icon 预设尺寸

| 平台 | 输出尺寸 |
|---|---|
| iOS App icon | 1024×1024（源文件即用） |
| iOS @1x/@2x/@3x | 60 / 120 / 180 |
| Android `mdpi → xxxhdpi` | 48 / 72 / 96 / 144 / 192 |
| 浏览器 favicon | 32 / 48 / 64 |

源文件足够大（1024×1024），按需下采样即可。

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `source` | `ImageSourcePropType` | — | **必填** —— 品牌 logo 图片源（`require('./logo.png')` / `{ uri: '...' }`）；组件不持有任何资产 |
| `size` | `number?` | `64` | 渲染正方形边长 |
| `borderRadius` | `number?` | `size / 4` | 圆角；不传走柔和的 squircle |
| `label` | `string?` | `'Logo'` | SR / 测试用文案，设为 `<Image>` 的 `accessibilityLabel` |
| `style` | `StyleProp<ImageStyle>?` | — | 附加样式 |
| `testID` | `string?` | — | E2E 定位 |

> 底层渲染为单个 `<Image>`，`resizeMode="cover"`。

## 无障碍（a11y）

来源：`src/components/ui/Logo/Logo.tsx`、`types.ts`。

本组件渲染为单个 `<Image>`，源码显式设 `accessibilityLabel={label}`，`label` 为**可选** prop、默认 `'Logo'`，故即便不传也有兜底朗读文案。未设置 `accessibilityRole`（继承底层 `<Image>` 默认）。品牌主标作为有意义的图片对 SR 可读，若上下文需要更具体的朗读（如「Unif 健康快乐」），显式传 `label` 覆盖默认值。

```tsx
// 传 label 覆盖默认 'Logo'
<Logo source={require('@/assets/logo.png')} label="Unif" />
```

## 用法规则

- **背景色** 主橙 `#EB6E00`，**不要换其它底色**。如需放在浅色背景上，外层包一层主橙圆角容器或留 padding。
- **不要变形** 等比缩放可以；扁平拉伸 / 改色 / 加阴影 / 加描边都不行。
- **最小尺寸 24×24** 飞鸟主标在 ≥24px 清晰可读；更小尺寸（如 16×16 浏览器 tab）就接受糊感，或临时用一张降采样后的 PNG，不要为了清晰度重画 logo。
- **不要替换 "健康快乐" 标语** 这是 logo 内嵌文字，不是 caption——不要外加自定义副标。
- **不要重新绘制飞鸟** 直接用 `<Logo>` 组件或 `src/assets/logo.png`，不要用 SVG 重画。

## Favicon

文档站 (`docusaurus.config.ts`) 的 `favicon` / `themeConfig.image` / `navbar.logo.src` 三处都指向同一份 `img/logo.png` —— 站点视觉一致性优先于小尺寸辨识度。

## NavBar 导航栏

*Source: `docs/components/navbar.mdx` · Slug: `/components/navbar`*

# NavBar 导航栏

顶部导航 · 44px 高 · 三变体：`default` 白底 hairline · `brand` 品牌橙底白字 · `transparent` 透明无边框 + **深字**（`c.foreground`，用于浮在浅色 hero 渐变之上的子页）。

## 实时预览

下方渲染的就是 `src/components/ui/NavBar/NavBar.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
    <span className="demo-label">默认 · 含副标题</span>
    <View style={{ borderWidth: 1, borderColor: 'var(--ifm-color-emphasis-200)', borderRadius: 12, overflow: 'hidden' }}>
      <NavBar
        title="AI 助手"
        subtitle="在线 · 已同步"
        left={{ icon: 'menu', onPress: () => {}, accessibilityLabel: '抽屉' }}
        right={{ icon: 'more-h', onPress: () => {}, accessibilityLabel: '更多' }}
      />
    </View>
    <span className="demo-label">品牌橙底 · variant="brand"</span>
    <View style={{ borderWidth: 1, borderColor: 'var(--ifm-color-emphasis-200)', borderRadius: 12, overflow: 'hidden' }}>
      <NavBar
        title="登录"
        variant="brand"
        left={{ icon: 'arrow-left', onPress: () => {}, accessibilityLabel: '返回' }}
        right={{ icon: 'more-h', onPress: () => {}, accessibilityLabel: '更多' }}
      />
    </View>
    <span className="demo-label">透明无边框 · variant="transparent"（深字，浮在浅色 hero 渐变上）</span>
    <View style={{ borderWidth: 1, borderColor: 'var(--ifm-color-emphasis-200)', borderRadius: 12, overflow: 'hidden', background: 'linear-gradient(180deg, #FFE3C8, #FFF0DD)' }}>
      <NavBar
        title="我的名片"
        variant="transparent"
        left={{ icon: 'arrow-left', onPress: () => {}, accessibilityLabel: '返回' }}
        right={{ icon: 'more-h', onPress: () => {}, accessibilityLabel: '更多' }}
      />
    </View>
  </div>
```

## 用法

```tsx
import { NavBar } from '@unif/react-native-design';

<NavBar
  title="AI 助手"
  subtitle="在线 · 已同步"
  left={{ icon: 'menu', onPress: openDrawer }}
  right={{ icon: 'more-h' }}
/>

{/* 品牌橙底 */}
<NavBar title="登录" variant="brand" />

{/* 透明浮层（深字）—— 浮在浅色 hero 渐变之上的子页 */}
<NavBar title="我的名片" variant="transparent" left={{ icon: 'arrow-left', onPress: goBack }} />
```

## API

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `title` | `string` | — | 居中标题 |
| `subtitle` | `string?` | — | 副标题（小字号，主标题下方） |
| `left` | `ReactNode \| { icon, onPress, accessibilityLabel? }` | — | 左槽，传 config 自动用 Slot 渲染 |
| `right` | `ReactNode \| { icon, onPress, accessibilityLabel? }` | — | 右槽，同 `left` |
| `variant` | `'default' \| 'brand' \| 'transparent'` | `'default'` | 视觉变体：`default` 白底 hairline + 深字 / `brand` 品牌橙底 + 白字 / `transparent` 透明无边框 + **深字 `c.foreground`**（浮在浅色 hero 上；若需白字深色浮层后续加 `transparentLight`） |
| `testID` | `string?` | — | E2E 定位 |

> `left` / `right` 传 config 对象时渲染为内部 `IconButton`（`variant='ghost'`，icon 色按 variant tint：brand 用 `c.onPrimary`、其余 `c.foreground`）；传 `ReactNode` 则原样渲染。标题用 `t.h3 + 0.5` / `fw.semi` / `letterSpacing: -0.2`，副标题 `t.micro`（11）。

## 安全区（Safe Area）

**NavBar 不内置 top safe-area inset**，由宿主页面负责。推荐做法：

```tsx
import { SafeAreaView } from 'react-native-safe-area-context';

// 方式 A：SafeAreaView 包裹
<SafeAreaView edges={['top']}>
  <NavBar title="首页" />
</SafeAreaView>

// 方式 B：react-navigation Stack.Screen header 配置
// headerStatusBarHeight 会自动注入 inset，无需手动包裹
```

这样 NavBar 本体可在任何场景复用（modal、底部抽屉 header、全屏画中画等不需要 top inset 的场景）。

## 无障碍（a11y）

来源：`src/components/ui/NavBar/NavBar.tsx`、`types.ts`。

- 默认 `accessibilityRole`：NavBar 根 `<View>` **未**设置 role（无 `header` 等），`title` / `subtitle` 渲染为普通 `<Text>`，按文本默认对 SR 可读。
- a11y props：`left` / `right` 槽传 config 对象时由内部 `IconButton` 渲染，其 `accessibilityLabel` 在 `NavBarSlotConfig` 中**可选但强烈建议传**——缺省时 dev 下告警且 SR 回退读英文 icon 名（体验不佳）。若 `left` / `right` 直接传 `ReactNode`，则 a11y 由该节点自行负责。
- 状态语义：NavBar 自身无可切换状态，不附加 `accessibilityState`。

```tsx
// accessibilityLabel 可选但强烈建议传，请传人类可读短语
<NavBar
  title="登录"
  left={{ icon: 'arrow-left', onPress: goBack, accessibilityLabel: '返回' }}
  right={{ icon: 'more-h', onPress: openMenu, accessibilityLabel: '更多' }}
/>
```

## 组件概览

*Source: `docs/components/overview.md` · Slug: `/components`*

# 组件概览

按使用场景分组的组件索引。所有组件都从**包根 barrel** 导出 —— `import { Button, Cell, useColors } from '@unif/react-native-design'`,**不要深路径**。每个组件一个独立文档页(Props 表 + Tokens 表 + 可交互 `<LiveDemo>`),点名称进入。

:::info 逐组件 API 在各组件页
本页只做索引,不镜像每个组件的完整 API。点进各组件页查 Props / variant / size;AI 可按需 fetch 远程 [llms.txt](https://unif-design.github.io/react-native-design/llms.txt) / 单组件 `md/components/<name>.md`。
:::

> 聊天专属组件(Message / PromptInput / Suggestion / Reasoning 等)在 portal 仓库文档站维护,不在本表。其总纲见[完整规范 → Component library](/docs/unif-design)。

## 品牌 {#品牌}

| 组件 | 说明 |
|---|---|
| [Logo](/docs/components/logo) | 品牌标识(`<Image>` 包装 `assets/logo.png`) |
| [图标 Icon](/docs/components/icons) | 24×24 描边 SVG 目录,`<Icon name="..." />` |

## 通用 {#通用}

| 组件 | 说明 |
|---|---|
| [Button](/docs/components/button) | 主操作按钮,6 variant × 3 size,可 block |
| [IconButton](/docs/components/icon-button) | 纯图标按钮,`accessibilityLabel` 类型必填 |
| [Avatar](/docs/components/avatar) | 单字符 monogram 头像,variant `brand`/`info`/`soft`/`neutral` |
| [Tag](/docs/components/tag) | 状态徽章,5 语义 × 2 尺寸 |
| [Chip](/docs/components/chip) | 胶囊形可选中 pill(Suggestion 底层) |
| [Confirm](/docs/components/confirm) | 命令式 `confirm()` + `<ConfirmHost />` 高风险二次确认 |
| [Thumbnail](/docs/components/thumbnail) | 16:9.5 缩略图,sm / md / lg 三档 |
| [Loading](/docs/components/loading) | `Spinner`(reanimated 4 旋转)+ 线性进度 |
| [Pulse](/docs/components/pulse) | `usePulse` + `<Pulse>` + `<PulseDot>`,通用脉冲底座 |
| [Reveal](/docs/components/reveal) | 入/出场淡入容器,收口 reanimated layout 动画的 web 特化 |
| [StatusDot](/docs/components/status-dot) | `done`/`active`/`pending` 圆点,`flat`/`soft` 双 tone |

## 表单 {#表单}

| 组件 | 说明 |
|---|---|
| [Input](/docs/components/input) | 单行输入,idle / focus / filled / error |
| [PasswordInput](/docs/components/password-input) | Input + secureTextEntry + 明文切换 |
| [Textarea](/docs/components/textarea) | 多行输入(复用 Input,顶对齐) |
| [TextField](/docs/components/text-field) | 带 label / 校验的表单字段封装 |
| [Search](/docs/components/search) | 搜索条(Input 预设 + 清除按钮) |
| [Checkbox](/docs/components/checkbox) | 复选 |
| [Radio](/docs/components/radio) | 单选 + RadioGroup |
| [Switch](/docs/components/switch) | 开关(reanimated 4 worklet) |
| [Stepper](/docs/components/stepper) | `[−] N [+]` 步进 |
| [Form](/docs/components/form) | Form / FormGroup / FormRow(行间 hairline) |

## 导航 {#导航}

| 组件 | 说明 |
|---|---|
| [NavBar](/docs/components/navbar) | 固定顶部头,44px,default / brand variant |
| [TabBar](/docs/components/tabbar) | 固定底部 tab,50px,带 badge |
| [Tabs](/docs/components/tabs) | 页级下划线 tabs(局部分段用 `Segmented`) |

> Drawer 用 `DrawerHeader` + `@react-navigation/drawer` 组合,无独立组件页。

## 反馈 {#反馈}

| 组件 | 说明 |
|---|---|
| [Toast](/docs/components/toast) | 命令式 `toast()` + `<ToastHost />` 全局轻提示 |
| [Empty](/docs/components/empty) | 空状态 |
| [Skeleton](/docs/components/skeleton) | 骨架占位,`shape='line'/'rect'/'circle'`(走 `usePulse`) |

## 数据展示 {#数据展示}

| 组件 | 说明 |
|---|---|
| [Cell · List](/docs/components/cell) | 列表行 + List 容器,grouped(白卡 + gap)/ flush(hairline)两模式 |
| [Card](/docs/components/card) | 内容卡,`default` / `plain`(`flat` 已 deprecated 等价 `plain`) |
| [Grid](/docs/components/grid) | 九宫格图标网格 |
| [Carousel](/docs/components/carousel) | 轮播(包装 reanimated-carousel v5) |

## 业务复合 {#业务复合}

`@unif/react-native-design` 暴露的通用业务复合组件(耦合 navigation / store 的留在消费者仓库):

| 组件 | 说明 |
|---|---|
| [AvatarWithRing](/docs/components/avatar-with-ring) | 圆形头像 + ring + 品牌 shadow |
| [GlassStats](/docs/components/glass-stats) | 玻璃数据条(BlurView + N 列) |
| [Decorations](/docs/components/decorations) | `GradientWash` + `RadialHalo` + `ScreenBackdrop`(整屏沉浸渐变,暖橙 preset + 暗色自适配) |
| [VersionPill](/docs/components/version-pill) | 版本号药丸 |

## 其他 {#其他}

| 组件 | 说明 |
|---|---|
| [BlurLayer](/docs/components/blur-layer) | BlurView + tint 双层,intensity `soft`(10)/ `strong`(40) |
| [EntryCard](/docs/components/entry-card) | 横向小卡入口(Me 屏"设置 / 关于"双列) |

## 基础令牌 {#基础令牌}

颜色 / 字体 / 间距 / 圆角 / 阴影 / 动效 / 图标 → [设计令牌](/docs/design/tokens/colors)。

## 组件页统一结构 {#组件页统一结构}

每个组件文档页遵循:

1. **LiveDemo 预览** —— 可交互的实时演示(`<LiveDemo>`)。
2. **Props 表** —— 完整 API 参数(prop · 类型 · 默认 · 说明)。
3. **Tokens 表** —— 该组件实际读取的设计令牌:

| Token | 来源 | 作用 |
|---|---|---|
| `c.primary` | `useColors()` | 主按钮背景色 |
| `radius.md` | `@unif/react-native-design` | 中等圆角 |
| `s.brandLg` | `useThemedStyles` 第二参 | 品牌卡片阴影 |

**Token 来源说明:**

- `useColors()` —— 运行期主题色,随亮 / 暗自动切换(`ColorTokens`)。
- `space.*` / `radius.*` / `type.*` / `fw.*` —— 静态 token,直接 import。
- shadow 参数(`s.*`)—— `useThemedStyles((c, s) => ...)` 第二参,暗色下大多数趋零。

参考实现:[Button](/docs/components/button) 与 [Cell · List](/docs/components/cell)。

## PasswordInput 密码输入框

*Source: `docs/components/password-input.mdx` · Slug: `/components/password-input`*

# PasswordInput 密码输入框

ui 层组件,封装"密码 Input + 眼睛切换明文/密文"通用 pattern。caller 只关心
value/onChangeText,组件内部 `useState(showPw)` 自管。

## 实时预览

下方渲染的就是 `src/components/ui/PasswordInput/PasswordInput.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。点右侧眼睛切换明文 / 密文。

<PwDemo />

## 用法

```tsx
import { PasswordInput } from '@unif/react-native-design';

<PasswordInput
  value={pw}
  onChangeText={setPw}
  placeholder="请输入新密码"
/>
```

## API

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `value` | `string` | — | 受控 value |
| `onChangeText` | `(v: string) => void` | — | 受控 onChange |
| `placeholder` | `string?` | `'请输入密码'` | placeholder 文案 |
| `testID` | `string?` | — | 测试定位;trailing eye Pressable 自动 `${testID}-toggle` |
| `inputProps` | `Partial<TextInputProps>?` | — | 透传给底层 Input(maxLength 等)。**不要传 `secureTextEntry`,组件自管,会被组件覆盖** |

## 设计稿对照

| 视觉态 | 规则 |
|---|---|
| leading | `<Icon name="lock" size={18} color={c.iconFaint40} />` |
| trailing | Pressable eye toggle,默认 `eye-off`(密文),切到 `eye`(明文)|
| secureTextEntry | 默认 true,点 eye 切 false |

## 业务消费

- Login(`login-password`)
- ForgotPassword(`forgot-newPw` / `forgot-newPw2`)
- ChangePassword(`change-password-newPw`)

## 无障碍（a11y）

来源：`src/components/ui/PasswordInput/PasswordInput.tsx`、`types.ts`。

- 默认 `accessibilityRole`：组件本体渲染为底层 [`Input`](./input)（最终原生 `<TextInput>`），输入框 a11y 继承 RN `TextInput`，不显式设 role。trailing 的眼睛切换 `<Pressable>` 硬编码 `accessibilityRole="button"`。
- a11y props：`PasswordInputProps` 不直接暴露输入框的 a11y prop，但可通过 `inputProps`(`Partial<TextInputProps>`) 透传 `accessibilityLabel` 等到底层 `TextInput`（⚠ 唯独 `secureTextEntry` 组件自管、会被覆盖，不要传）。眼睛按钮的 `accessibilityLabel` 由源码按当前态动态给出：明文显示中 → `'隐藏密码'`，密文中 → `'显示密码'`。
- 状态语义：`secureTextEntry={!showPw}` 随内部 `showPw` 切换；眼睛按钮**有意不加 `accessibilityHint`**——`accessibilityLabel` 已表达切换意图，再加 hint 会被 SR over-hint（见 CLAUDE.md a11y 规范）。

```tsx
// 眼睛按钮的 role/label 内置；如需给输入框加 label 走 inputProps
<PasswordInput value={pw} onChangeText={setPw} inputProps={{ accessibilityLabel: '新密码' }} />
```

## 不要

- ❌ 不要传 `inputProps.secureTextEntry`(组件自管,会被覆盖)
- ❌ 不要在 caller 自己加 showPw state(组件内部已经有)
- ❌ 不要把 PasswordInput 用在"非密码"场景(它写死了 leading lock + eye toggle 语义)

## 关联组件

- [Input](./input.mdx)— 底层 Input
- SmsCodeInput— SMS 验证码 Input

## Pulse · PulseDot · usePulse

*Source: `docs/components/pulse.mdx` · Slug: `/components/pulse`*

# Pulse · PulseDot · usePulse

通用脉冲原语，基于 `react-native-reanimated@4` worklet 实现 —— UI 线程驱动、原生 driver、不占 JS 桥。三个 API：

- **`usePulse(options)`** — 钩子，返回 `useAnimatedStyle`，可直接拼到 `Animated.View` 上
- **`<Pulse>{children}</Pulse>`** — 把 children 包进一个 opacity 循环动画
- **`<PulseDot />`** — 一个固定的圆点（默认 6×6 主橙），用于"思考中"等指示器

## 实时预览

下方渲染的就是 `src/components/ui/Pulse/PulseDot.tsx` 与 `Pulse.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。worklet 在 web 端走 reanimated 的 web 实现，效果跟 RN 端一致。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">PulseDot · 默认 6×6 主橙</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
        <PulseDot />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">PulseDot · 自定义 size / color</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
        <PulseDot size={6} />
        <PulseDot size={10} color="#3775F6" />
        <PulseDot size={14} color="#52C41A" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">PulseDot · delay 错峰（打字中三连点）</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
        <PulseDot delay={0} />
        <PulseDot delay={200} />
        <PulseDot delay={400} />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">{'<Pulse>'} 包装 · spark 图标</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
        <Pulse from={0.4} duration={500}>
          <Icon name="spark" size={20} color="#EB6E00" />
        </Pulse>
        <Pulse from={0.3} duration={800}>
          <Icon name="thinking" size={20} color="#3775F6" />
        </Pulse>
      </div>
    </div>
  </div>
```

## 用法

### `usePulse` hook

```tsx
import Animated from 'react-native-reanimated';
import { usePulse } from '@unif/react-native-design';

export function MyShimmerLine({ width }) {
  const animatedStyle = usePulse({ from: 0.6, to: 1, duration: 700 });
  return (
    <Animated.View style={[
      { width, height: 11, borderRadius: 3, backgroundColor: '#EDEDED' },
      animatedStyle,
    ]} />
  );
}
```

### `<Pulse>` 包装组件

```tsx
import { Pulse, Icon } from '@unif/react-native-design';

<Pulse from={0.4} duration={500}>
  <Icon name="spark" size={14} color="#EB6E00" />
</Pulse>
```

### `<PulseDot>`

```tsx
import { PulseDot } from '@unif/react-native-design';

<PulseDot />                                  // 默认 6×6 主橙
<PulseDot size={10} color="#3775F6" />        // 自定义
<PulseDot delay={200} />                      // 错峰开始（多个排成一行做"打字中"）
```

## API

### `usePulse(options?)`

| Option | 类型 | 默认 | 说明 |
|---|---|---|---|
| `from` | `number` | `0.6` | 透明度下界 |
| `to` | `number` | `1` | 透明度上界 |
| `duration` | `number` | `700` | 半周期时长（ms），完整一圈 = `2 × duration` |
| `delay` | `number` | `0` | 首次开始之前的延迟（ms） |

返回 `useAnimatedStyle(() => ({ opacity }))`，可直接传给 `Animated.View` 的 `style`。

### `<Pulse>`

接受 `usePulse` 全部 options（`from` / `to` / `duration` / `delay`）+ `children` + 可选 `testID`。把 children 渲在一个 `<Animated.View>` 里，opacity 走脉冲循环。

### `<PulseDot>`

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `size` | `number?` | `6` | 圆点直径（px） |
| `color` | `string?` | `c.primary`（运行期 hook 取） | 填充色 |
| `from` / `to` / `duration` / `delay` | `number?` | from=0.5 / to=1 / duration=700 / delay=0 | 透传给 `usePulse`（注意 `PulseDot` 的 `from` 默认 0.5，`usePulse` / `<Pulse>` 默认 0.6） |
| `testID` | `string?` | — | E2E / 测试定位 |

## 无障碍（a11y）

来源：`src/components/ui/Pulse/PulseDot.tsx`、`Pulse.tsx`、`usePulse.ts`。

纯视觉脉冲原语，三个 API 均无交互、无 `accessibilityRole`：

- `<PulseDot>` 源码在其 `<Animated.View>` 上显式设 `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`，对 SR **完全隐藏**（圆点是装饰性指示器，无朗读价值）。
- `<Pulse>` 是透明包装层（仅给 children 套一个 opacity 循环的 `<Animated.View>`），自身**未设置任何 a11y prop**，a11y 语义完全由其 `children` 承载——把语义放在被包裹的内容上（如有意义的图标加 `accessibilityLabel`）。
- `usePulse` 只返回动画 `style`，不涉及 a11y。

## 内部使用

| 消费者 | 做什么 |
|---|---|
| [Skeleton](./skeleton) Line/Rect/Circle | `usePulse({ from: 0.5 })` 驱动 opacity 闪烁 |
| Shimmer ShimmerLine / Dot | 同上，参数定制 |
| Reasoning | `<Pulse from={0.4} duration={motion.pulse / 2}>` 包裹 spark 图标 |
| Task / ChainOfThought | 通过 `<StatusDot>` 间接 —— active 状态内嵌 `<PulseDot>` |
| Message BlinkCursor | `usePulse({ from: 0, to: 1, duration: 400 })` |

## 不要

- ❌ 不要自己 `new Animated.Value` + `Animated.loop` 实现脉冲 —— 老 RN Animated API 在 RN 0.85 + 新架构下被迫走 JS 桥；用 `usePulse`。
- ❌ 不要在 `useAnimatedStyle` 里引用 React state（worklet 闭包只能读 SharedValue）。
- ❌ 不要传非 primitive 的 options 对象（每次 render 都新身份会触发 effect 重启）—— 直接传 `from`/`to`/`duration`/`delay`。

## Radio 单选

*Source: `docs/components/radio.mdx` · Slug: `/components/radio`*

# Radio 单选

单选控件——20×20 圆，未选透明描边、已选主橙描边 + 中心 8×8 主橙圆点。

## 实时预览

下方渲染的就是 `src/components/ui/Radio/Radio.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<RadioDemo />

## 状态

| 状态 | 视觉 |
|---|---|
| 未选 | 20×20 圆，1.5px 描边 `#EDEDED` |
| 已选 | 20×20 圆，1.5px 主橙描边 + 中心 8×8 主橙圆点 |
| 禁用 | `opacity: 0.5` |

## 用法

```tsx
import { Radio } from '@unif/react-native-design';

<Radio.Group value={tier} onChange={setTier}>
  <Radio value="vip"     label="VIP 客户" />
  <Radio value="normal"  label="普通客户" />
  <Radio value="pending" label="待审核客户" />
</Radio.Group>
```

## API

### `<Radio.Group>`

来源：`src/components/ui/Radio/types.ts`、`RadioGroup.tsx`。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `value` | `string \| number` | — | 当前选中值（受控） |
| `onChange` | `(value: string \| number) => void` | — | 切换回调 |
| `children` | `ReactNode` | — | `<Radio>` 列表（渲染为普通 `<View>`，组内 `gap: space[1]`） |
| `testID` | `string?` | — | 容器 testID；每个 `Radio` 自动派生 `${testID}-${value}` |

### `<Radio>`

来源：`src/components/ui/Radio/types.ts`、`Radio.tsx`。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `value` | `string \| number` | — | 此项的值（与 Group 的 `value` 比较得 checked） |
| `label` | `string?` | — | 右侧文字；同时作为 `accessibilityLabel`（**可选**，不传则仅渲染圆点、无朗读文案） |
| `disabled` | `boolean?` | `false` | 禁用（`opacity: 0.5` + 不响应） |
| `testID` | `string?` | — | 单项 testID（不传则从父 Group 派生 `${groupTestID}-${value}`） |

> `<Radio>` 必须放在 `<Radio.Group>` 内使用；脱离 Group 会打 warn 并渲染空 `<View>`。

## 无障碍（a11y）

来源：`src/components/ui/Radio/Radio.tsx`、`RadioGroup.tsx`、`types.ts`。

- 默认 `accessibilityRole`：每个 `<Radio>` 在其 `<Pressable>` 上硬编码 `'radio'`。`<Radio.Group>` 渲染为普通 `<View>`，源码**未**设置 `radiogroup` role（仅作布局容器 + Context 派发，无 group 语义）。
- a11y props：`accessibilityLabel` 取自 `label`，但 `label` 在 `types.ts` 中是**可选**的（`label?`）——不传 `label` 时（仅渲染圆点）无朗读文案，此时应由外部上下文提供语义。
- 状态语义：`accessibilityState={{ checked, disabled: !!disabled }}`——`checked` 由 `Radio.Group` 的受控 `value` 派生（`ctx.value === value`），`disabled` 映射本项 `disabled` prop。

```tsx
// label 同时作为 SR 朗读文案；checked 由 Group 的 value 决定
<Radio.Group value={tier} onChange={setTier}>
  <Radio value="vip" label="VIP 客户" />
  <Radio value="normal" label="普通客户" />
</Radio.Group>
```

## 与 Checkbox 的区别

| Radio | Checkbox |
|---|---|
| 同组只能选一个 | 多选 |
| 圆形指示器 | 方形指示器 |
| 用 `<Radio.Group>` 包裹 | 独立使用，多个 `<Checkbox>` |
| 适合"在 N 个选项中选一个"| 适合"勾选若干项" |

## Reveal

*Source: `docs/components/reveal.mdx` · Slug: `/components/reveal`*

# Reveal

内容**入 / 出场淡入淡出**容器。把会"出现 / 消失"的内容包进 `<Reveal>`,挂载时淡入、卸载时淡出:

- **native**(RN app)走 `react-native-reanimated` 的 `FadeIn` / `FadeOut` layout 动画。
- **web**(react-native-web)自动切到 `Reveal.web.tsx` —— 用 React state + CSS transition 复刻入场淡入(退场省略,卸载即移除)。

它存在的核心理由:**reanimated 4 的 layout 动画在 react-native-web 运行时会崩**(`layoutReanimation/web` 的 `_updatePropsJS` 里 `Object.keys` 抛 `TypeError`,渲染即每帧崩)。`<Reveal>` 把这个 web 特化**收口在设计系统内**,共享代码(portal `src/` 等双端消费的代码)做进出过渡一律用它,不要直接写 `FadeIn` / `FadeOut`。

## 实时预览

下方内容由 `<Reveal>` 包裹,页面加载时淡入(本页是 web,走的就是 CSS transition 特化;刷新页面可重看入场)。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">默认时长(motion.base = 200ms)</span>
      <Reveal>
        <Tag label="我是淡入进场的内容" variant="info" />
      </Reveal>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">duration=800 · 慢速入场</span>
      <Reveal duration={800}>
        <Tag label="慢速淡入(800ms)" variant="success" />
      </Reveal>
    </div>
  </div>
```

## 用法

```tsx
import { Reveal } from '@unif/react-native-design';

// 条件渲染的内容包进 Reveal:挂载淡入、卸载淡出(native)
{loaded && (
  <Reveal>
    <ResultCard data={data} />
  </Reveal>
)}

// 自定义时长
<Reveal duration={320} style={{ flex: 1 }}>
  <Section />
</Reveal>
```

## API

### `<Reveal>`

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `children` | `ReactNode` | —(必填) | 要做入 / 出场过渡的内容 |
| `style` | `StyleProp<ViewStyle>?` | — | 容器样式(传给外层容器) |
| `duration` | `number?` | `motion.base`(200) | 入 / 出场时长(ms) |
| `testID` | `string?` | — | E2E / 测试定位 |

## Tokens

| Token | 来源 | 作用 |
|---|---|---|
| `motion.base` | `@unif/react-native-design`(静态 token) | 默认入 / 出场时长(200ms) |

## 平台差异

| | native(`Reveal.tsx`) | web(`Reveal.web.tsx`) |
|---|---|---|
| 实现 | reanimated `FadeIn` / `FadeOut` layout 动画 | React state + CSS `opacity` transition(双 RAF 保证有 `opacity:0` 起点) |
| 入场 | ✅ 淡入 | ✅ 淡入 |
| 退场 | ✅ 淡出 | ❌ 省略(卸载即移除) |

> 需要 web 端也有退场动画的场景不要依赖 `<Reveal>`(web 退场是直接移除);native-only 代码里直接用 reanimated 也可以,但**共享代码必须走 `<Reveal>`**。

## 无障碍(a11y)

来源:`src/components/ui/Reveal/Reveal.tsx`、`Reveal.web.tsx`。

纯视觉过渡容器,自身**不设置任何 a11y prop**,语义完全由 `children` 承载——内容该有的 `accessibilityRole` / `accessibilityLabel` 写在被包裹的组件上。

## 不要

- ❌ 不要在共享代码(`src/` 双端消费)里直接用 reanimated 的 `entering={FadeIn}` / `exiting={FadeOut}` —— RN-Web 上运行时崩;包 `<Reveal>`。
- ❌ 不要给 web 端依赖退场动画的交互(web 退场被省略,内容卸载即消失)。
- ❌ 不要用它做循环 / 强调动画 —— 那是 [Pulse](./pulse) 的事;`<Reveal>` 只管挂载 / 卸载这一次过渡。

## Search 搜索栏

*Source: `docs/components/search.mdx` · Slug: `/components/search`*

# Search 搜索栏

`Input` 的搜索预设——左侧带 search 图标，输入后右侧出现 clear。常放在页面顶部或 NavBar 下方。

## 实时预览

下方渲染的就是 `src/components/ui/Search/Search.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<SearchDemo />

## 视觉规范

来源：`src/components/ui/Search/Search.tsx`（底层 Input/TextFieldBase styles）。

| 元素 | 规则 |
|---|---|
| 高度 | 36px（`height={36}`，普通 Input 为 44） |
| 圆角 | 8px（`radius.md`） |
| 背景（idle） | `c.surfaceContainerHigh`（亮色 `#F0F0F0`）；focus 时白底 |
| 左图标 | `search` · `size={18}` · `c.foregroundSubtle`（`#999999`） |
| 占位 | 默认「搜索…」，可覆盖（如「搜索客户」） |
| Clear | `value` 非空时出现的 `close` 图标 · `size={14}` · `c.foregroundSubtle`，点击清空 |

## 用法

```tsx
import { Search } from '@unif/react-native-design';

<Search
  value={q}
  onChangeText={setQ}
  placeholder="搜索客户"
  onSubmit={handleSearch}
/>
```

## API

来源：`src/components/ui/Search/types.ts`、`Search.tsx`。

`SearchProps` = **`Omit<TextInputProps, 'style'>`** + 这 2 个扩展。所有 RN [`TextInput` props](https://reactnative.dev/docs/textinput)（`value` / `onChangeText` / `accessibilityLabel` / `autoFocus` 等）都直接可用；`style` 被 omit。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `onSubmit` | `(value: string) => void` | — | 提交回调（按 return 键触发，回传当前 `value`） |
| `placeholder` | `string?` | `'搜索…'` | 占位文字 |

> 这些是 Search 在底层 `<Input>` 上写死的预设（**非可配置 prop**）：`leading` = `<Icon name="search" />`、`value` 非空时 `trailing` 出现清除按钮、`height={36}`、`returnKeyType="search"`、`accessibilityRole="search"`。支持 `ref`（`forwardRef` 透传到内部 `TextInput`，可 `searchRef.current?.focus()`）。

## 无障碍（a11y）

来源：`src/components/ui/Search/Search.tsx`、`types.ts`。

- 默认 `accessibilityRole`：Search 在底层 [`Input`](./input)（最终为原生 `<TextInput>`）上显式设 `'search'`，并设 `returnKeyType="search"`（键盘 return 键显示「搜索」）。
- a11y props：`SearchProps = Omit<TextInputProps, 'style'> & { onSubmit?, placeholder? }`，故 RN `TextInput` 的全部 a11y props（`accessibilityLabel`、`placeholder` 等）都透传到底层输入框。朗读文案优先来自 `accessibilityLabel`，缺省时由 `placeholder`（默认「搜索…」）/ `value` 提供。
- 清除按钮：`value` 非空时出现的 clear `<Pressable>` 硬编码 `accessibilityRole="button"` + `accessibilityLabel="清除"`，点击清空输入。

```tsx
// placeholder 已能表意；如需更明确朗读可显式传 accessibilityLabel
<Search value={q} onChangeText={setQ} placeholder="搜索客户" accessibilityLabel="搜索客户" />
```

## 与 Input 的区别

`Search` 是 `Input` 的常用预设（这些都是 Search 内部写死、非 Input 的可配置 prop —— Input 本身**没有** `leadingIcon` / `clearable` 这类 prop，需自行组合 `leading` / `trailing`）：
- 内置 `leading` 为 `<Icon name="search" />`
- `value` 非空时内置 `trailing` 清除按钮
- 高度 36px（Input 默认 44px）
- 提交回调 `onSubmit`，`returnKeyType="search"`、`accessibilityRole="search"`

## Skeleton 骨架屏

*Source: `docs/components/skeleton.mdx` · Slug: `/components/skeleton`*

# Skeleton 骨架屏

页面加载占位，呈现内容大致结构。区别于 Shimmer（聊天专属流式占位）——Skeleton 是页面级。

## 实时预览

下方渲染的就是 `src/components/ui/Skeleton/*` 本体（reanimated 4 worklet 驱动 opacity 脉冲），通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
    <span className="demo-label">列表项骨架</span>
    <View style={{ backgroundColor: 'var(--ifm-background-surface-color)', borderRadius: 12, padding: 12, borderWidth: 1, borderColor: 'var(--ifm-color-emphasis-200)', gap: 14 }}>
      {[0, 1, 2].map((i) => (
        <View key={i} style={{ flexDirection: 'row', alignItems: 'center', gap: 12 }}>
          <Skeleton shape="circle" size={40} />
          <View style={{ flex: 1, gap: 8 }}>
            <Skeleton shape="line" width="60%" height={14} />
            <Skeleton shape="line" width="80%" height={11} />
          </View>
        </View>
      ))}
    </View>
    <span className="demo-label">卡片骨架</span>
    <Skeleton shape="rect" width="100%" height={140} radius={12} />
  </div>
```

## 视觉规范

来源：`src/components/ui/Skeleton/Skeleton.tsx`、`types.ts`、共享 [`usePulse`](./pulse)。

| 元素 | 规则 |
|---|---|
| 颜色 | `c.surfaceContainerHigh`（亮色 `#F0F0F0`） |
| 圆角 | line：3px / rect：8px / circle：`size/2`（均可用 `radius` 覆盖） |
| 动画 | opacity 脉冲（共享 [`usePulse`](./pulse) hook，传 `from: 0.5`），半周期 700ms、全周期 1.4s，`0.5 ↔ 1` 循环 |

## 形状

| `shape` | 默认值 | 用途 |
|---|---|---|
| `'line'` | width 100% / height 11 / radius 3 | 文本占位 |
| `'rect'`(默认) | width 100% / height 80 / radius 8 | 图片 / 卡片占位 |
| `'circle'` | size 40 / radius = size/2 | 头像占位 |

## API

来源：`src/components/ui/Skeleton/types.ts`、`Skeleton.tsx`。

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `shape` | `'line' \| 'rect' \| 'circle'` | `'rect'` | 形状，决定默认尺寸与圆角 |
| `width` | `DimensionValue?` | 形状相关 | 宽度（line / rect）；circle 忽略，走 `size` |
| `height` | `number?` | 形状相关 | 高度（line / rect）；circle 忽略，走 `size` |
| `size` | `number?` | `40` | 直径（circle）；line / rect 忽略 |
| `radius` | `number?` | 形状相关 | 覆盖圆角（line 3 / rect 8 / circle `size/2`） |
| `style` | `StyleProp<ViewStyle>?` | — | 额外样式覆盖 |
| `testID` | `string?` | — | E2E / 测试定位 |

## 用法

```tsx
import { Skeleton } from '@unif/react-native-design';

{/* 列表项骨架 */}
<View>
  <Skeleton shape="circle" size={40} />
  <View style={{ flex: 1, gap: 8 }}>
    <Skeleton shape="line" width="60%" height={14} />
    <Skeleton shape="line" width="80%" height={11} />
  </View>
</View>

{/* 卡片骨架 */}
<Skeleton shape="rect" width="100%" height={120} radius={12} />
```

> 单一组件 + `shape` prop(MUI Skeleton 同款 variant 模式),旧的
> `Skeleton.Line / .Rect / .Circle` 命名空间访问已移除。

## 无障碍（a11y）

来源：`src/components/ui/Skeleton/Skeleton.tsx`、`types.ts`。

加载占位骨架为纯视觉元素，无交互。源码在其 `<Animated.View>` 上显式设 `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`，对 SR **完全隐藏**——占位块没有朗读价值，隐藏可避免在加载阶段读出无意义节点。无 `accessibilityRole` / `accessibilityLabel`，也无可传的 a11y prop（仅 `shape` / `width` / `height` / `size` / `radius` / `style` / `testID`）。加载完成后用真实内容整体替换骨架即可，真实内容自带其语义。

## 与 Shimmer 的区别

| Skeleton | Shimmer (chat) |
|---|---|
| 页面级，初次加载 | 单个气泡里，AI 思考中 |
| 整体块状（卡片、行）| 几行不等宽 + 头像 |
| 加载完成后整体替换 | 气泡内文字流式填充 |

## StatusDot 状态点

*Source: `docs/components/status-dot.mdx` · Slug: `/components/status-dot`*

# StatusDot 状态点

任务列表 / 推理链通用的状态圆点。四态（done / error / active / pending）× 两风格（flat / soft）。

| 状态 | 视觉 | 内部 |
|---|---|---|
| `done` | 绿底 + 白勾 | `success` 填充 + `<Icon name="check" />` |
| `error` | 红底 + 白叉 | `error` 填充 + `<Icon name="close" />` |
| `active` | 边框 + 内嵌 `<PulseDot>` | `primary` 边框 + 跳动 |
| `pending` | 仅边框 | `outline` 灰边 |

`tone='flat'`（默认）—— pending/active 底色透明（`'transparent'`），用于 Task。
`tone='soft'` —— pending = `c.surface`、active = `c.primaryContainer`，用于 ChainOfThought（推理链气氛更柔）。

## 实时预览

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">flat（任务列表风格）</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
          <StatusDot status="done" size={16} />
          <span>done</span>
        </div>
        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
          <StatusDot status="error" size={16} />
          <span>error</span>
        </div>
        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
          <StatusDot status="active" size={16} />
          <span>active</span>
        </div>
        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
          <StatusDot status="pending" size={16} />
          <span>pending</span>
        </div>
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">soft（推理链风格）</span>
      <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
          <StatusDot status="done" size={18} tone="soft" />
          <span>done</span>
        </div>
        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
          <StatusDot status="error" size={18} tone="soft" />
          <span>error</span>
        </div>
        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
          <StatusDot status="active" size={18} tone="soft" />
          <span>active</span>
        </div>
        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
          <StatusDot status="pending" size={18} tone="soft" />
          <span>pending</span>
        </div>
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { StatusDot } from '@unif/react-native-design';

// 任务列表风格
<StatusDot status="done" size={16} />
<StatusDot status="active" size={16} />
<StatusDot status="pending" size={16} />

// 推理链风格（柔色）
<StatusDot status="active" size={18} tone="soft" />
```

## API

来源：`src/components/ui/StatusDot/types.ts`、`StatusDot.tsx`、`styles.ts`。

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `status` | `'pending' \| 'active' \| 'done' \| 'error'` | — | 当前状态（必填） |
| `size` | `number?` | `16` | 圆点直径（done 勾 ≈ `size*0.6`） |
| `tone` | `'flat' \| 'soft'` | `'flat'` | flat 透明底；soft 柔色底（pending=`c.surface`、active=`c.primaryContainer`） |
| `testID` | `string?` | — | E2E / 测试定位 |

> 颜色派生（`paletteFor`）：done = `c.success` 底+边；error = `c.error` 底+边；active = `c.primary` 边框（底 flat 透明 / soft `c.primaryContainer`）；pending = `c.outline` 边框（底 flat 透明 / soft `c.surface`）。圆点带 1.5px 边框。

## 无障碍（a11y）

来源：`src/components/ui/StatusDot/StatusDot.tsx`、`types.ts`。

视觉状态指示器，无交互。源码渲染为一个普通 `<View>`，**未设置任何 a11y prop**（无 `accessibilityRole` / `accessibilityLabel`），也无可传的 a11y prop（仅 `status` / `size` / `tone` / `testID`），继承底层 `<View>` 默认。内部内容随状态变化：`active` 时嵌入对 SR 隐藏的 `<PulseDot>`，`done` 时是一个 `<Icon name="check">`、`error` 时是 `<Icon name="close">`（按图标自身实现处理，见 [图标](./icons)），`pending` 时为空。因此圆点本身不向 SR 朗读「完成 / 进行中 / 待办」语义——状态文案应由相邻可见文本承载（如任务行的标题或状态标签），不要依赖 StatusDot 单独传达状态。

## 内部使用

- Task `TaskRow` —— `<StatusDot status={mapped} size={16} />`（todo→pending、running→active、done→done）
- ChainOfThought `Step` —— `<StatusDot status={step.status} size={18} tone="soft" />`

## 设计原则

设计上的"做完了 / 在做 / 还没做"在 Unif 系统里只有这一种视觉表达，新组件需要状态指示请直接用 `StatusDot`，不要自画。

## Stepper 步进器

*Source: `docs/components/stepper.mdx` · Slug: `/components/stepper`*

# Stepper 步进器

数字步进控件——`[−][ N ][+]` 三段拼接，到达 min/max 自动禁用对应按钮。

## 实时预览

下方渲染的就是 `src/components/ui/Stepper/Stepper.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<StepperDemo />

## 视觉规范

来源：`src/components/ui/Stepper/styles.ts`、`Stepper.tsx`。

| 元素 | 规则 |
|---|---|
| 高度 | md 32px（默认）/ sm 28px（`control.sm`） |
| 圆角 | 8px（`radius.md`，外层左右两角），中间数字框无独立圆角 |
| 按钮 | md 32×32 / sm 28×28，`±` 字号 18px（`type.h1`） |
| 数字框 | min-width md 48 / sm 40，1px 上下边线，无左右边线，字号 md 14 / sm 13 |
| 背景 / 描边 | `c.surface` 底 + 1px `c.outline`（亮色 `#EDEDED`）边 |
| 禁用 | 按钮 `opacity: 0.4`（达到 min/max 或整体 `disabled` 时；按下 0.7） |

## 用法

```tsx
import { Stepper } from '@unif/react-native-design';

const [qty, setQty] = useState(12);

<Stepper value={qty} onChange={setQty} min={1} max={99} />

{/* 自定义步长 */}
<Stepper value={packs} onChange={setPacks} step={6} min={0} max={120} />

{/* 小尺寸 */}
<Stepper size="sm" value={n} onChange={setN} min={0} max={9} />
```

## API

来源：`src/components/ui/Stepper/types.ts`、`Stepper.tsx`。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `value` | `number` | — | 当前值（受控，必填） |
| `onChange` | `(value: number) => void` | — | 变更回调（已自动夹到 `[min, max]`，必填） |
| `min` | `number?` | `0` | 下限（达到时 `−` 禁用） |
| `max` | `number?` | `99` | 上限（达到时 `+` 禁用） |
| `step` | `number?` | `1` | 步长（非正数 / 非有限数回退为 1） |
| `size` | `'sm' \| 'md'` | `'md'` | 高度 28 / 32 |
| `disabled` | `boolean?` | `false` | 整体禁用（两个按钮都不可点） |
| `testID` | `string?` | — | E2E 定位（派生 `-decrement` / `-value` / `-increment`） |

> 健壮性：`value` 为 `NaN` 时显示为 `min`；`±Infinity` 钳到 `[min, max]`；`min > max` 时整体按 `min` 渲染（避免写出乱序值）。无 `style` prop。

## 无障碍（a11y）

来源：`src/components/ui/Stepper/Stepper.tsx`、`types.ts`。

- 默认 `accessibilityRole`：`−` / `+` 两个 `<Pressable>` 均硬编码 `'button'`；中间数字框 `<View>` 硬编码 `'adjustable'`（可调整值容器）。根 `<View>` 不设 role。
- a11y props：标签由源码硬编码、不可由外部传入——`−` 为 `accessibilityLabel="减少"`、`+` 为 `accessibilityLabel="增加"`，两者各带 `accessibilityHint`（`` `当前值 ${value}，减/加 ${step}` ``，动态拼当前值与步长）。数字框设 `accessibilityValue={{ min, max, now }}`，把范围与当前值暴露给 SR。`StepperProps` 不含任何 a11y prop（仅 `value` / `onChange` / `min` / `max` / `step` / `size` / `disabled` / `testID`）。
- 状态语义：两个按钮各自 `accessibilityState={{ disabled }}`——`−` 在 `disabled || value <= min` 时禁用，`+` 在 `disabled || value >= max` 时禁用（到达边界自动禁用对应按钮）。

```tsx
// 角色 / 标签 / hint 全部内置，无需额外 a11y prop
<Stepper value={qty} onChange={setQty} min={1} max={99} />
```

## 不要

- ❌ 不要在 Stepper 中间放可输入的 TextInput——下单场景请用专门的 InputNumber 控件（待规划）
- ❌ 不要去掉描边或圆角——Stepper 必须看起来"可点击"

## Switch 开关

*Source: `docs/components/switch.mdx` · Slug: `/components/switch`*

# Switch 开关

布尔开关——32×20 轨道 + 16×16 圆形 thumb，关时灰底 thumb 在左，开时主橙底 thumb 在右，200ms 动画。

## 实时预览

下方渲染的就是 `src/components/ui/Switch/Switch.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点（reanimated 4 worklet 驱动动画）。

<SwitchDemo />

## 状态

来源：`src/components/ui/Switch/styles.ts`、`Switch.tsx`。

| 状态 | 视觉 |
|---|---|
| 关 | 32×20 灰底 `c.surfaceContainerHighest`（亮色 `#E0E0E0`），16×16 白圆 thumb（`c.onPrimary`）在左 |
| 开 | 32×20 主橙底 `c.primary`（`#EB6E00`），16×16 白圆 thumb 在右 |
| 禁用 | 整体 `opacity: 0.5` |

切换动画：thumb 水平移动 12px（off `x=2` → on `x=14`），背景颜色插值，200ms（`motion.base`）。native 走 reanimated 4 worklet，web 走 CSS transition（见 `Switch.web.tsx`）。

## 用法

```tsx
import { Switch, Cell, List } from '@unif/react-native-design';

{/* 独立使用 */}
<Switch value={enabled} onChange={setEnabled} />

{/* 设置场景 — 配 Cell 使用，Switch 作为 extra */}
<List>
  <Cell
    title="拜访提醒"
    desc="按计划自动推送提醒"
    extra={<Switch value={notify} onChange={setNotify} />}
  />
  <Cell
    title="语音输入"
    desc="长按说话输入消息"
    extra={<Switch value={voice} onChange={setVoice} />}
  />
</List>
```

## API

来源：`src/components/ui/Switch/types.ts`、`Switch.tsx`。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `value` | `boolean` | — | 当前状态（受控，必填） |
| `onChange` | `(value: boolean) => void` | — | 切换回调（必填） |
| `disabled` | `boolean?` | — | 禁用（不可点 + `opacity: 0.5`） |
| `accessibilityLabel` | `string?` | — | 无障碍朗读文案（独立使用时建议传） |
| `testID` | `string?` | — | E2E / 测试定位 |

## 无障碍（a11y）

来源：`src/components/ui/Switch/Switch.tsx`、`Switch.web.tsx`、`types.ts`（native 与 web 两份实现 a11y 完全一致）。

- 默认 `accessibilityRole`：包裹的 `<Pressable>` 上硬编码 `'switch'`。
- a11y props：`accessibilityLabel` 在 `types.ts` 中是**可选**的（`accessibilityLabel?`）——Switch 本身不带可见 label（设计上 label 交给左侧 [Cell](./cell)），所以独立使用时不传 `accessibilityLabel` 则无朗读文案，应由承载它的 Cell / 上下文提供语义。
- 状态语义：`accessibilityState={{ checked: value, disabled: !!disabled }}`——`checked` 直接映射必填的 `value`，`disabled` 映射 `disabled` prop。

```tsx
// 独立使用时显式给 accessibilityLabel；checked 由 value 自动上报
<Switch value={enabled} onChange={setEnabled} accessibilityLabel="拜访提醒" />
```

## 不要

- ❌ 不要换其它颜色——开必须是主橙（这是品牌一致性）
- ❌ 不要在 Switch 上加 label——配 [Cell](./cell) 把 label 放左侧、Switch 放 `extra` slot
- ❌ 不要做"中间态"——Switch 只有开/关，三态用 [Radio](./radio)

## TabBar 底部 tab 栏

*Source: `docs/components/tabbar.mdx` · Slug: `/components/tabbar`*

# TabBar 底部 tab 栏

固定底部主导航 · 50px 高 · 各 tab `icon + 文字` 垂直居中。

## 实时预览

下方渲染的就是 `src/components/ui/TabBar/TabBar.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<TabBarDemo />

## 视觉规范

来源：`src/components/ui/TabBar/styles.ts`、`TabBar.tsx`。

| 元素 | 规则 |
|---|---|
| 高度 | 50px（`fixed.tabbarH`，物理常量不缩放） |
| 背景 | `c.surface`（亮色 `#FFFFFF`） |
| 顶部边线 | hairline `c.outline`（亮色 `#EDEDED`） |
| Tab 项 | `flex: 1`，垂直居中 icon + 文字 |
| Icon | 22×22（`icon.sm`），`c.foregroundSubtle`（亮色 `#999`，默认）/ `c.primary`（`#EB6E00`，active） |
| 文字 | 10px（`type.nano`）/ 500，与 icon 同色 |
| Badge | `c.error` 底数字徽章（`number \| string`），叠在 icon 右上 |
| 安全区 | bottom inset（iOS home indicator 34px）不计入 50px——外面包 `<SafeAreaView edges={['bottom']}>` |

## 用法

```tsx
import { TabBar } from '@unif/react-native-design';

<TabBar
  active="home"
  onChange={setActive}
  items={[
    { id: 'home',     icon: 'home',     label: '首页' },
    { id: 'visits',   icon: 'location', label: '拜访', badge: 3 },
    { id: 'agent',    icon: 'spark',    label: 'AI' },
    { id: 'me',       icon: 'user',     label: '我的' },
  ]}
/>
```

## API

来源：`src/components/ui/TabBar/types.ts`、`TabBar.tsx`。

`TabBarProps`：

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `active` | `string` | — | 当前激活 tab 的 `id`（必填） |
| `onChange` | `(id: string) => void` | — | 切换回调，回传点中 tab 的 `id`（必填） |
| `items` | `TabBarItem[]` | — | tab 列表（必填） |
| `testID` | `string?` | — | 容器 testID；item testID 自动派生为 `${testID}-${id}` |

`TabBarItem`：

| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `id` | `string` | — | 唯一标识，用作 key 与选中判定 |
| `icon` | `IconName` | — | 图标名（见 [图标](./icons)） |
| `label` | `string` | — | tab 文字（同时作 `accessibilityLabel`） |
| `badge` | `number \| string` | — | 图标右上角数字角标（用 `string` 才能写 `'99+'`） |
| `testID` | `string?` | — | 单 tab testID（默认 `${barTestID}-${id}`） |

## 无障碍（a11y）

来源：`src/components/ui/TabBar/TabBar.tsx`、`types.ts`。

- 默认 `accessibilityRole`：每个 tab 的 `<Pressable>` 上硬编码 `'tab'`。外层容器是普通 `<View>`，源码**未**设置 `tablist` role（仅作 50px 高的布局栏）。
- a11y props：每个 tab 的 `accessibilityLabel` 取自 `item.label`，而 `label` 在 `TabBarItem` 中是**必填**的——所以每个 tab 默认都有朗读文案。`badge` 仅作视觉角标渲染，不进入 a11y 文案。
- 状态语义：`accessibilityState={{ selected: on }}`——`selected` 由 `item.id === active` 派生。无 `disabled` 语义（`TabBarItem` 无 `disabled` 字段）。

```tsx
// 每个 tab 自动 role=tab、label=item.label、selected 由 active 决定
<TabBar
  active={active}
  onChange={setActive}
  items={[
    { id: 'home',   icon: 'home',     label: '首页' },
    { id: 'visits', icon: 'location', label: '拜访', badge: 3 },
  ]}
/>
```

## 不要

- ❌ 不要做 5 个以上 tab——超过就用左侧 Drawer
- ❌ 不要在 active 状态用其他颜色——必须主橙
- ❌ 不要在 TabBar 里加按钮（"发布"等）——用单独的 FAB 或 NavBar 右槽

## Tabs 标签页

*Source: `docs/components/tabs.mdx` · Slug: `/components/tabs`*

# Tabs 标签页

页面内分类切换 · 两种风格：**下划线 Tabs**（页面级）/ **分段控件 Segmented**（局部分组）。

## 实时预览

下方渲染的就是 `src/components/ui/Tabs/Tabs.tsx` 与 `src/components/ui/Segmented/Segmented.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

<TabsDemo />

## 下划线 Tabs

页面级分类切换，全宽分布。来源：`src/components/ui/Tabs/styles.ts`、`Tabs.tsx`。

| 元素 | 规则 |
|---|---|
| 容器 | 高 44px（`fixed.hitTarget`），背景 `c.surface`，底部 hairline `c.outline` |
| Tab 项 | `flex: 1` 平分，`14px`（`type.sm`），激活态 `c.primary` + 字重 600（非激活 `c.foregroundMuted` + 500） |
| 下划线 | 2px `c.primary`，宽 36px（`icon.xl`，居中、非随 label），底对齐 |

## 分段控件

局部分组（如 Filter "全部 / 已完成 / 待跟进"）。来源：`src/components/ui/Segmented/styles.ts`、`Segmented.tsx`。

| 元素 | 规则 |
|---|---|
| 容器 | `alignSelf: 'flex-start'` 内容自适应宽，背景 `c.surfaceContainerHigh`（亮色 `#F0F0F0`），圆角 8（`radius.md`），内 padding 2 |
| 项 | 内容宽（非平分）；`minHeight` / 水平 padding / 字号随 `size`：`md` 44 / 16 / 13（`fixed.hitTarget`·`space[7]`·`type.xs`，默认、触控达标）· `sm` 28 / 12 / 12（高 28pt 物理常量·`space[5]`·`type.xxs`，紧凑、触控 < 44px） |
| 激活 | 白底 thumb（暗色 `surfaceContainerHighest`），圆角 6（`radius.sm`），亮色态柔阴影 |

## 用法

```tsx
import { Tabs, Segmented } from '@unif/react-native-design';

{/* 页面级 */}
<Tabs
  value={tab}
  onChange={setTab}
  items={[
    { id: 'all',       label: '全部' },
    { id: 'pending',   label: '待跟进' },
    { id: 'done',      label: '已完成' },
  ]}
/>

{/* 局部分段 */}
<Segmented
  value={range}
  onChange={setRange}
  items={[
    { id: 'day',   label: '日' },
    { id: 'week',  label: '周' },
    { id: 'month', label: '月' },
  ]}
/>
```

## API

来源：`src/components/ui/Tabs/types.ts`、`src/components/ui/Segmented/types.ts`。`Tabs` 与 `Segmented` props 形状一致，共用 `TabItem`。

`TabsProps` / `SegmentedProps`：

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `value` | `string` | — | 当前选中项的 `id`（必填） |
| `onChange` | `(id: string) => void` | — | 切换回调，回传点中项的 `id`（必填） |
| `items` | `TabItem[]` | — | 列表项（Tabs ≥2 项才有意义；必填） |
| `size` | `'sm' \| 'md'` | `'md'` | **仅 Segmented**；`'md'` 默认（高 44px 触控达标），`'sm'` 紧凑（高 28px / 字号 12，给模型下拉等局促位用，触控 < 44px） |
| `testID` | `string?` | — | 容器 testID；item testID 自动派生为 `${testID}-${id}` |

`TabItem`：

| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `id` | `string` | — | 唯一标识，用作 key 与选中判定 |
| `label` | `string` | — | 显示文本（同时作 `accessibilityLabel`） |
| `testID` | `string?` | — | 单 item testID（默认 `${tabsTestID}-${id}`） |

## 无障碍（a11y）

来源：`src/components/ui/Tabs/Tabs.tsx`、`src/components/ui/Segmented/Segmented.tsx`、`types.ts`（两者 a11y 实现一致，共用 `TabItem` 形状）。

- 默认 `accessibilityRole`：`Tabs` 与 `Segmented` 的每个项 `<Pressable>` 上都硬编码 `'tab'`。外层容器是普通 `<View>`，源码**未**设置 `tablist` role（仅作布局）。
- a11y props：每个项的 `accessibilityLabel` 取自 `item.label`，而 `label` 在 `TabItem` 中是**必填**的——每个 tab 默认都有朗读文案。
- 状态语义：`accessibilityState={{ selected: on }}`——`selected` 由 `item.id === value` 派生。无 `disabled` 语义（`TabItem` 无 `disabled` 字段）。

```tsx
// 每个 tab 自动 role=tab、label=item.label、selected 由 value 决定
<Tabs
  value={tab}
  onChange={setTab}
  items={[
    { id: 'all',     label: '全部' },
    { id: 'pending', label: '待跟进' },
  ]}
/>
```

## Tag 标签

*Source: `docs/components/tag.mdx` · Slug: `/components/tag`*

# Tag 标签

纯展示状态标签 · 6 种配色变体 · 2 种尺寸。

## 实时预览

下方渲染的就是 `src/components/ui/Tag/Tag.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
      <Tag label="VIP 客户" variant="brand" />
      <Tag label="已完成" variant="success" />
      <Tag label="已取消" variant="error" />
      <Tag label="新单" variant="info" />
      <Tag label="待跟进" variant="neutral" />
      <Tag label="描边" variant="outline" />
    </div>
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
      <Tag label="Lg" variant="brand" size="lg" />
      <Tag label="Md" variant="brand" size="md" />
    </div>
  </div>
```

## 用法

```tsx
import { Tag } from '@unif/react-native-design';

<Tag label="VIP 客户" variant="brand" />
<Tag label="已完成" variant="success" />
<Tag label="已取消" variant="error" />
<Tag label="新单" variant="info" />
<Tag label="待跟进" variant="neutral" />
```

## API

来源：`src/components/ui/Tag/types.ts`、`Tag.tsx`。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `label` | `string` | — | 标签文字（必填） |
| `variant` | `'neutral' \| 'brand' \| 'success' \| 'error' \| 'info' \| 'outline'` | `'neutral'` | 配色变体 |
| `size` | `'md' \| 'lg'` | `'md'` | 高度 22 / 26 |
| `numberOfLines` | `number?` | `1` | 文本行数（超长 ellipsis） |
| `style` | `StyleProp<ViewStyle>?` | — | 额外样式覆盖 |
| `testID` | `string?` | — | E2E / 测试定位 |

## 配色（Tokens）

来源：`src/components/ui/Tag/styles.ts`（`paletteFor` / `sizingFor`）。

| variant | 底色 | 文字 | 边框 |
|---|---|---|---|
| `neutral`（默认） | `c.surfaceContainerHigh` | `c.foregroundMuted` | — |
| `brand` | `c.primaryContainer` | `c.primary` | — |
| `success` | `c.successContainer` | `c.success` | — |
| `error` | `c.errorContainer` | `c.error` | — |
| `info` | `c.infoContainer` | `c.info` | — |
| `outline` | 透明 | `c.foregroundMuted` | `c.outline`（1px） |

尺寸：`md` = 高 22 / 横向 padding 8 / 字号 12；`lg` = 高 26 / padding 10 / 字号 13。圆角统一 `radius.sm`（6）。

## 无障碍（a11y）

来源：`src/components/ui/Tag/Tag.tsx`、`types.ts`。

Tag 是**纯展示**标签，源码是 `<View>` + `<Text>`（无 `onPress`、无交互变体），**未设置任何 `accessibilityRole`**，也没有可传的 a11y prop（无 `accessibilityLabel`）。底层 `<Text>` 默认对 screen reader 可读，会朗读必填的 `label`；`variant` 只是配色语义，不会被读出（如需把"成功 / 失败"读给 SR，应在 `label` 文字本身体现，例如 `label="已完成"`）。无受控状态（`checked` / `selected` / `disabled` 均不适用）。

## TextField 输入框 base(internal)

*Source: `docs/components/text-field.mdx` · Slug: `/components/text-field`*

# TextField 输入框 base(internal)

`src/components/ui/TextField/` 是 `Input` / `Textarea` / `PasswordInput` / `Search` 这些公开输入组件共享的**内部 base**,处理:

- TextInput 基础 props 透传
- `leading` / `trailing` slot(图标 / 按钮槽位)
- `error` 文案 + border 红色态切换
- `disabled` 整体半透明 + editable 锁
- 单行 / 多行布局切换(`multiline` prop)

**业务层不应直接 import `TextField`**。所有调用方场景都有更精准的封装:

| 场景 | 用 |
|---|---|
| 单行输入 | [`<Input>`](./input.mdx) |
| 密码 / 隐显切换 | [`<PasswordInput>`](./password-input.mdx) |
| 搜索栏(图标 + 占位) | [`<Search>`](./search.mdx) |
| 多行输入 | `<Textarea>` |

## 设计意图

TextField 抽出来是为了消除 Input / Textarea 之间 50%+ 重复代码(focus 态 border 切换 / disabled 灰化 / error 文案下挂 / leading-trailing slot 布局)。**它是实现细节,不是稳定 API**,后续重构可能换内部结构。

如果你正在调用 TextField,99% 的可能性是该用 Input / Textarea。

## 实现路径

```
src/components/ui/
├── TextField/        ← 共享 base(本组件,internal)
├── Input/            ← multiline=false 单行封装
├── Textarea/         ← multiline=true 多行封装
├── PasswordInput/    ← Input + trailing 眼睛 toggle + secureTextEntry
└── Search/           ← Input + leading 搜索图标 + 圆角胶囊预设
```

## Props（internal）

来源：`src/components/ui/TextField/types.ts`、`TextFieldBase.tsx`。**非公开 API**——下表仅说明 [`Input`](./input.mdx) / `Textarea` 通过封装间接暴露了哪些行为，请勿直接 import。`TextFieldBaseProps` = `TextInputProps`（全部 RN `TextInput` props 透传）+ 这些扩展：

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `multiline` | `boolean?` | `false` | false=Input 单行固定 height；true=Textarea 多行 minHeight/maxHeight + 顶对齐 |
| `height` | `number?` | `control.lg`(44) | 单行高度（`multiline=false` 时生效） |
| `minHeight` | `number?` | `96` | 最小高度（`multiline=true` 时生效） |
| `maxHeight` | `number?` | — | 最大高度（`multiline=true`）；超出 ScrollView 内滚 |
| `leading` | `ReactNode?` | — | 左侧 slot（Icon / 装饰） |
| `trailing` | `ReactNode?` | — | 右侧 slot（Icon / 操作按钮） |
| `error` | `string?` | — | 非空字符串时 border 切 error 色并在下方显示文本（`""` / undefined 不进 error 态） |
| `disabled` | `boolean?` | — | 整体禁用：`opacity 0.5` + `editable=false`，优先级高于 `editable` |
| `containerStyle` | `StyleProp<ViewStyle>?` | — | 外层 `View` 附加 style |

> `forwardRef<TextInputRef>`：业务表单可 `inputRef.current?.focus()`（实际通过 Input / Textarea 透传）。视觉 4 态优先级：error > focus > filled > idle。

## 无障碍（a11y）

来源：`src/components/ui/TextField/TextFieldBase.tsx`、`types.ts`。

`TextFieldBase` 包裹原生 `<TextInput>`，因此**继承 RN TextInput 内置的可编辑文本 a11y 语义**——源码**未**额外硬编码 `accessibilityRole`（依赖 TextInput 默认）。

- a11y props（继承）：`TextFieldBaseProps` extends `TextInputProps`，并把 `{...rest}` 透传给 `<TextInput>`，所以 RN 原生 a11y props（`accessibilityLabel`、`accessibilityHint`、`placeholder` 等）都可由调用方传入并生效；本 base 自身不暴露专门的 a11y prop。
- 状态语义：仅显式设置 `accessibilityState={disabled ? { disabled: true } : undefined}`——`disabled`（优先级高于 `editable`）会同时令 `editable=false`。`error` 仅作视觉态 + 下方 `<Text>` 文案，源码**未**把它接入 a11y（如 `accessibilityInvalid`），需要时由上层封装补。
- 该组件是 internal base：实际 a11y 由公开封装 [Input](./input) / `Textarea` / [PasswordInput](./password-input) / [Search](./search) 在各自层面传入 label。

```tsx
// 调用方（如 Input/Textarea）透传 RN 原生 a11y props
<Textarea accessibilityLabel="拜访备注" placeholder="详细说明…" />
```

## 不要

- 不要 `import { TextField } from '@unif/react-native-design'` —— 用对应高层组件,见上表
- 不要把 TextField 当公共 API 写测试 —— 测 Input / Textarea / PasswordInput / Search 的行为,TextField 实现细节会变

## Textarea 多行输入

*Source: `docs/components/textarea.mdx` · Slug: `/components/textarea`*

# Textarea 多行输入

多行文本输入框，视觉与 [Input](./input) 完全一致，但内置 `multiline=true` + 顶对齐 + `[minHeight, maxHeight]` 自适应。

> 单行内容请用 [`<Input />`](./input)。Textarea 内部固定 multiline=true，不可关闭。

## 实时预览

下方渲染的就是 `src/components/ui/Textarea/Textarea.tsx` 本体。

<TextareaDemo />

## 状态

跟 Input 一致：`idle / focus / filled / error / disabled`。状态由 props 隐式驱动，无需业务管。

## 视觉规范

| 元素 | 规则 |
|---|---|
| 最小高度 | 96px (约 5 行；可用 `minHeight` 覆盖) |
| 最大高度 | 不限 (传 `maxHeight` 后超出滚动) |
| 圆角 | 8px |
| 内边距 | `10 12px` (左右 12px，上下 10px) |
| 字号 | 15px (`body`) |
| 文本对齐 | 顶部 (`textAlignVertical='top'`，跨平台统一) |

## 用法

```tsx
import { Textarea } from '@unif/react-native-design';

{/* 默认 minHeight=96 */}
<Textarea value={note} onChangeText={setNote} placeholder="详细说明…" />

{/* 固定区间高度（超出滚动） */}
<Textarea
  value={text}
  onChangeText={setText}
  minHeight={120}
  maxHeight={240}
  placeholder="可拖动滚动的长文本…"
/>

{/* 错误态 */}
<Textarea value={text} onChangeText={setText} error="字数太少（≥10字）" />

{/* 禁用 */}
<Textarea value={text} onChangeText={setText} disabled />

{/* forwardRef + focus */}
const textareaRef = useRef<TextInput>(null);
<Textarea ref={textareaRef} placeholder="内容" />
{/* 业务调 textareaRef.current?.focus() 主动聚焦 */}
```

## API

`TextareaProps` = **`Omit<TextInputProps, 'style' | 'multiline' | 'numberOfLines'>`** + 这 7 个扩展（`leading` / `trailing` / `error` / `minHeight` / `maxHeight` / `disabled` / `containerStyle`）。`multiline` 已内置无需传；`numberOfLines` 故意 omit（用 `minHeight` / `maxHeight` 表达更直观）。下表最后的 `testID` 等来自透传的 `TextInputProps`。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `leading` | `ReactNode?` | — | 前置插槽（顶对齐渲染） |
| `trailing` | `ReactNode?` | — | 后置插槽（如字符计数器） |
| `error` | `string?` | — | 错误文字 —— 容器进入 error 态并在下方显示（`""` / undefined 不进 error 态） |
| `minHeight` | `number?` | `96` | 最小高度（约 5 行）；内部 input minHeight 减去上下 padding 后 `Math.max(0, …)` 保护 |
| `maxHeight` | `number?` | — | 最大高度，超过后内部滚动；不传则不限 |
| `disabled` | `boolean?` | — | 整体禁用 + 视觉变灰，优先级高于 `editable` |
| `containerStyle` | `StyleProp<ViewStyle>?` | — | 容器外层样式（含 leading/trailing 整个 wrap） |
| `testID` | `string?` | — | 测试定位（经 `TextInputProps` 透传；input 派生 `${testID}-input`） |

> 余下 RN `TextInput` props（`value` / `onChangeText` / `placeholder` / `accessibilityLabel` / `autoFocus` 等）均直接可用；仅 `style` / `multiline` / `numberOfLines` 被 omit。支持 `ref`（`forwardRef` 到内部 `TextInput`）。

## 无障碍（a11y）

来源：`src/components/ui/Textarea/Textarea.tsx`（薄 wrap）→ `src/components/ui/TextField/TextFieldBase.tsx`。

Textarea 是 `<TextFieldBase multiline>` 的薄封装，最终落到原生 `<TextInput multiline>`，因此**继承 RN TextInput 内置的多行可编辑文本 a11y 语义**——源码**未**硬编码 `accessibilityRole`。

- a11y props（继承）：`TextareaProps = Omit<TextInputProps, 'style' | 'multiline' | 'numberOfLines'>` + 扩展，`{...props}` 透传给 base 再到 `<TextInput>`，所以 RN 原生 a11y props（`accessibilityLabel`、`accessibilityHint`、`placeholder` 等）均可传入生效；Textarea 自身不新增专门 a11y prop。
- 状态语义：`disabled` 经 base 设 `accessibilityState={{ disabled: true }}` 并令 `editable=false`。`error` 只是视觉态 + 下方文案，源码未接入 a11y（无 `accessibilityInvalid`）。

```tsx
// 传 RN 原生 accessibilityLabel；disabled 自动上报 a11y 禁用态
<Textarea value={note} onChangeText={setNote} accessibilityLabel="拜访备注" placeholder="详细说明…" />
```

## 跟 Input 的区别

| 维度 | Input | Textarea |
|---|---|---|
| 行数 | 单行（`multiline` 已 omit） | 多行（内置 `multiline=true`） |
| 高度策略 | `height` 固定，默认 44 | `[minHeight, maxHeight]` 自适应，默认 96 |
| 文本对齐 | 居中 | 顶对齐（跨平台统一） |
| 适用场景 | 短文本（用户名 / 手机号 / 验证码） | 长文本（备注 / 评论 / 反馈） |

## Thumbnail 缩略图

*Source: `docs/components/thumbnail.mdx` · Slug: `/components/thumbnail`*

# Thumbnail 缩略图

列表 / 卡片右侧、chat 行内、Detail 头图 通用的小型预览图。固定 16:9.5 视频比,提供 `sm / md / lg` 三档尺寸。bg 占位 `c.surfaceContainer`,图未加载 / 失败时不出现空白闪烁。

| Size | 尺寸 | 用法 |
|---|---|---|
| `sm` | 64×40 | chat 行内、列表二级缩略 |
| `md`(默认)| 113×67 | `NewsList` / `NewsArea` 公告右侧 |
| `lg` | 160×96 | 详情页 hero 小图、卡片头图 |

## 实时预览

下方渲染的就是 `src/components/ui/Thumbnail/Thumbnail.tsx` 本体，通过 `react-native-web` 翻译成浏览器节点。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">三档尺寸 · sm / md / lg</span>
      <div style={{ display: 'flex', gap: 16, alignItems: 'flex-end' }}>
        <Thumbnail uri={IMG} size="sm" accessibilityLabel="示例图 sm" />
        <Thumbnail uri={IMG} size="md" accessibilityLabel="示例图 md" />
        <Thumbnail uri={IMG} size="lg" accessibilityLabel="示例图 lg" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">selected · 外侧 2pt 品牌色 ring</span>
      <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
        <Thumbnail uri={IMG} selected accessibilityLabel="已选中的示例图" />
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { Thumbnail } from '@unif/react-native-design';

// 远程 URL —— 列表行最常见
<Thumbnail uri={item.coverUrl} />

// 自定义尺寸
<Thumbnail uri={item.coverUrl} size="lg" />

// 本地图片(降级 / placeholder)
<Thumbnail source={require('./fallback.png')} />

// 无图(uri / source 都空)→ 返回 null,不占布局
<Thumbnail uri={maybeEmpty} />
```

## API

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `uri` | `string` | — | 远程 URL,优先于 `source` |
| `source` | `ImageSourcePropType` | — | RN Image source(本地 `require` / 完整对象) |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸阶梯 |
| `resizeMode` | `'cover' \| 'contain' \| 'stretch' \| 'center'` | `'cover'` | RN Image.resizeMode |
| `style` | `StyleProp<ImageStyle>` | — | 微调样式(marginLeft 等),不覆盖 size 尺寸 |
| `accessibilityLabel` | `string` | — | SR 描述。不传 RN Image 默认 hidden |
| `testID` | `string` | — | 测试 |

## 无障碍（a11y）

来源：`src/components/ui/Thumbnail/Thumbnail.tsx`、`types.ts`。

Thumbnail 是一张 `<Image>`（可选外套 ring `<View>`），**未硬编码 `accessibilityRole`**，a11y 走"可选描述"模型：

- a11y props：`accessibilityLabel` 是**可选**的（`accessibilityLabel?`）。源码同时按 `accessible={!!accessibilityLabel}` 控制可访问性——**不传 `accessibilityLabel` 时该图对 screen reader 默认隐藏**（装饰图不打扰朗读）；传了才作为带描述的图片暴露。
- 状态语义：源码有 `selected` prop（选中时外层套 2pt 品牌色 ring `<View>`），但该 ring **仅为视觉**，源码**未**给它设置 `accessibilityState`（无 `selected` a11y 上报）；选中语义需由承载它的可选父级（如 picker 单元）提供。
- 无图（`uri` / `source` 都空）时组件返回 `null`，不渲染任何节点。

```tsx
// 内容图：给 accessibilityLabel 才会被 SR 读到
<Thumbnail uri={item.coverUrl} accessibilityLabel="客户门店照片" />
// 纯装饰缩略图：省略 accessibilityLabel → 对 SR 隐藏
<Thumbnail uri={item.coverUrl} />
```

## 内部使用

- [NewsList / NewsArea](/docs/components/cell) —— `newsToCellItem` 共享 mapper 内 `extra: <Thumbnail uri={images[0]} />`,两屏渲染一致

## 设计原则

新增"列表 / 卡片右侧缩略图 / chat 内嵌图片预览"场景请直接用 `Thumbnail`,不要自画 `<Image style={{width, height, borderRadius, bg}}>`。尺寸阶梯不够覆盖时来这里加 size,不要 inline 写死。

## Toast 轻提示

*Source: `docs/components/toast.mdx` · Slug: `/components/toast`*

# Toast 轻提示

非阻塞反馈——3 秒后自动消失，居中或底部出现。

## 实时预览

下方渲染的就是 `src/components/ui/Toast/ToastHost.tsx` 本体（reanimated 4 worklet 驱动 fade + slide），通过 `react-native-web` 翻译成浏览器节点。点按钮触发。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
    <Button label="信息" variant="secondary" onPress={() => toast.info('已切换到日报模式')} />
    <Button label="成功" variant="secondary" onPress={() => toast.success('订单提交成功')} />
    <Button label="失败" variant="secondary" onPress={() => toast.error('网络异常，请重试')} />
    <Button label="长文" variant="secondary" onPress={() => toast('正在同步最近 30 天的拜访记录…')} />
  </div>
  <ToastHost />
```

## 视觉规范

来源：`src/components/ui/Toast/styles.ts`、`ToastHost.tsx`、`toast.ts`。

| 元素 | 规则 |
|---|---|
| 形态 | 圆角 8（`radius.md`）`c.inverseSurface` 底（亮色 `#1C1C1E`），`c.inverseOnSurface` 白字 |
| 内边距 | 横向 14（`space[6]`）/ 纵向 10（`space[4]`） |
| 宽度 | max-width 85%，水平居中；距底部 32px（`space[10]`） |
| 字号 | 14px（`type.sm`）/ 500 |
| 出现 | 200ms（`motion.base`）fade + 8px slide-up |
| 停留 | 默认 3000ms（`duration` 可覆盖） |
| 退出 | 200ms fade + 下滑 8px |
| 层级 | host `position: absolute` + `zIndex: 200` + `pointerEvents: none` |

## 状态变体

`kind` 仅决定文本左侧 6×6 圆点的颜色（来源：`dotColorFor`）：

```text
✓ success · c.success 绿点（亮色 #52C41A）
✕ error   · c.error 红点（亮色 #F4511E）
ℹ info    · 无圆点（默认）
```

## 用法

```tsx
import { toast, ToastHost } from '@unif/react-native-design';

// 在应用根放一次 ToastHost
<ToastHost />

// 任意位置触发
toast('已保存');
toast.success('订单提交成功');
toast.error('网络异常，请重试');
toast.info('已切换到日报模式');

// 自定义时长
toast({ message: '正在同步…', duration: 5000 });
```

## API

来源：`src/components/ui/Toast/toast.ts`、`types.ts`、`ToastHost.tsx`。

命令式函数 `toast`（不是组件）：

| 调用 | 签名 | 说明 |
|---|---|---|
| `toast(input)` | `(input: ToastInput) => void` | 默认 `kind: 'info'` |
| `toast.info(input)` | `(input: ToastInput) => void` | info 提示 |
| `toast.success(input)` | `(input: ToastInput) => void` | success 提示（绿点） |
| `toast.error(input)` | `(input: ToastInput) => void` | error 提示（红点） |

`ToastInput` = `string`（简写，走默认 kind + 3000ms）`|` 对象：

| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `message` | `string` | — | 消息文本（必填） |
| `kind` | `'info' \| 'success' \| 'error'` | `'info'` | 类型（决定圆点颜色） |
| `duration` | `number?` | `3000` | 自动消失毫秒数 |
| `position` | `'top' \| 'bottom' \| 'center'` | `'bottom'` | 显示位置(top/center 自动避让 safe-area) |

`<ToastHost />` 组件 props（`ToastHostProps`，在 app 根附近挂一次）：

| Prop | 类型 | 默认 | 说明 |
|---|---|---|---|
| `testID` | `string?` | — | 容器 testID；文本节点派生 `${testID}-text` |

> 全局只需一个 `<ToastHost />`；同一时间只显示一条，新调用替换旧的。

## 无障碍（a11y）

来源：`src/components/ui/Toast/ToastHost.tsx`、`ToastHost.web.tsx`、`toast.ts`、`types.ts`。

- 默认 `accessibilityRole`：**无**。Toast 由 `<ToastHost>` 渲染为 `<View>` + `<Text>`（native 与 web 两份实现一致），源码**未**设置 `accessibilityRole`。
- 朗读 / live region：`<ToastHost>` 在每条 toast 出现时调用 `AccessibilityInfo.announceForAccessibility(message)`（native 与 web 两端一致，web 经 RN-Web 注入 aria-live region），**screen reader 会主动播报 message 文本**。host 容器仍 `pointerEvents="none"`（不抢焦点）。需要用户*停留确认*的关键操作（而非一次性通知）仍应改用会获得焦点的模态对话框。
- a11y props：命令式 `toast(...)` 入参（`ToastInput`：`message` / `kind` / `duration`）与 `ToastHostProps`（仅 `testID`）均**不含** a11y 字段；`kind`（success/error/info）只决定圆点颜色，不带语义角色。
- 无受控状态（`checked` / `selected` / `disabled` 均不适用）。

> 现状如实记录：Toast 出现时主动播报 message（SR 可感知），但仍是非阻塞提示（不抢焦点、自动消失）；需要用户停留确认的关键操作请用模态对话框。

- ❌ 不要在 Toast 里放按钮——需要交互的反馈用内联 Confirmation 或模态对话框
- ❌ 不要堆叠多个 Toast——同一时间最多 1 条，新的把旧的替换
- ❌ 不要超过 50 字——超过就用模态对话框承载

## VersionPill 版本号药丸

*Source: `docs/components/version-pill.mdx` · Slug: `/components/version-pill`*

# VersionPill 版本号药丸

About / Splash / 调试面板等显版本号的小药丸。左侧状态点 + 版本号 + 可选 build 后缀,圆角胶囊。

## 实时预览

下方渲染的就是 `src/components/business/VersionPill/VersionPill.tsx` 本体。

```tsx
// web demo 源码,组件用法可参考
  <div style={{ display: 'flex', flexDirection: 'column', gap: 18 }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">基础 · 仅版本号</span>
      <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
        <VersionPill version="2.8.0" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">带 build 号</span>
      <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
        <VersionPill version="2.8.0" build="20260525" />
      </div>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <span className="demo-label">statusColor · 自定义状态点</span>
      <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
        <VersionPill version="2.8.0" statusColor="#22A56E" />
        <VersionPill version="2.8.0-beta" statusColor="#EB6E00" />
        <VersionPill version="2.8.0-rc1" statusColor="#3775F6" />
      </div>
    </div>
  </div>
```

## 用法

```tsx
import { VersionPill } from '@unif/react-native-design';

{/* About 屏底 */}
<VersionPill version="0.2.0" />

{/* 内测版本醒目 */}
<VersionPill version="2.8.0-beta" statusColor="#EB6E00" build="20260525" />
```

## API

来源：`src/components/business/VersionPill/types.ts`、`VersionPill.tsx`。

| Prop | Type | 默认 | 说明 |
|---|---|---|---|
| `version` | `string` | — | 版本号字串（`'2.8.0'`，必填） |
| `build` | `string?` | — | build 号；为空时省略分点与 build 字 |
| `statusColor` | `string?` | `c.success` | 左侧 5×5 圆点颜色 |
| `style` | `StyleProp<ViewStyle>?` | — | 容器附加样式覆盖 |

## 视觉规范（Tokens）

来源：`src/components/business/VersionPill/styles.ts`。

| 元素 | 规则 |
|---|---|
| 胶囊 | `c.surface` 底 + hairline `c.outline` 边，圆角 `radius.pill`（999），横向 padding 11 / 纵向 5 |
| 状态点 | 5×5 圆点（`radius.pill`），色由 `statusColor` 决定（默认 `c.success`） |
| 版本文字 | `type.microPlus`（11.5）+ `c.foregroundMuted` + `tabular-nums`（等宽数字） |
| 分隔点 | `·`，`type.microPlus` + `opacity 0.5` |
| build 文字 | `type.micro`（11）+ `c.foregroundMuted` + 等宽字体（`fontMono`） |

## 无障碍（a11y）

来源：`src/components/business/VersionPill/VersionPill.tsx`、`types.ts`。

VersionPill 是**纯展示**徽章，源码为 `<View>` + 若干 `<Text>`（`版本 {version}`、可选 `· build {build}`），**未设置任何 `accessibilityRole`**，也没有可传的 a11y prop（无 `accessibilityLabel`）。底层 `<Text>` 默认对 screen reader 可读，会按"版本 … / build …"顺序逐段朗读必填的 `version`（及 `build`）；左侧 `statusColor` 圆点是装饰 `<View>`，无文本、不被朗读。无受控状态（`checked` / `selected` / `disabled` 均不适用）。

## 不要

- 不要硬编码 `version` —— 走 `@/config/brand` 的 `APP_VERSION`(package.json 派生),build 走 react-native-device-info `getBuildNumber()`
- 不要把 statusColor 滥用成"主题色徽章" —— 它的语义是"状态指示",通常 `c.success`(正常,默认)/ `c.primary` 或 `c.info`(beta / 内测)/ `c.error`(已废)

## 全局 Don'ts

*Source: `docs/design/donts.md` · Slug: `/design/donts`*

# 全局 Don'ts

硬性禁忌。违反这些会破坏品牌一致性。每条都对应一条[设计原则](/docs/design/principles)或 token 规则,载入即生效(load-bearing)。

<div className="unif-donts">
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>引入新的渐变色。仅保留品牌橙 135° 渐变(Logo 圆 / Drawer header)。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>添加紫色 / 蓝色装饰。蓝色 <code>c.info</code>(<code>#3775F6</code>)<em>专属</em>于用户头像(及 Tag info variant 历史沿用)。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>在 UI 文案中使用装饰 emoji(包括国旗、表情)。功能性状态走图标。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>写英文 UI 文案,除非用户明确要求。出货语言是简体中文。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>引入新字体。系统栈 + PingFang SC 是全部字体系统,不加 webfont。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>违反气泡的非对称圆角规则。"指向头像的内角是直角"是核心标识。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>在列表行使用 <code>border-bottom</code>。用白卡 + 8px gap + 浅灰底分组(<code>&lt;List&gt;</code> grouped 默认)。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>引入插画、装饰图形、卡通元素。视觉是功能性的、克制的。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>在头像里放图片或多于 1 个字符。所有头像都是单字符 monogram。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>硬编码颜色 / 字号 / 间距值。从 <code>@unif/react-native-design</code> 导入对应 token(颜色走 <code>useColors()</code>)。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>把 <code>makeStyles</code> 内联进组件函数体 —— 会打穿 <code>useThemedStyles</code> 缓存。定义在模块顶层。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>用模态替换内联确认。内联确认(Confirmation)在消息流里渲染;模态仅留给登录选租户。</div>
  </div>
  <div className="unif-dont">
    <div className="unif-dont__x">×</div>
    <div><strong>不要</strong>引入弹簧动画、缩放入场、霓虹光晕。动效仅 fade + layout,时长 150–300ms。</div>
  </div>
</div>

> 详细规则见[设计原则](/docs/design/principles)、[颜色 → 取色优先级链](/docs/design/tokens/colors#取色优先级链)、[动效](/docs/design/tokens/motion);单文件全量 Don'ts 见[完整规范](/docs/unif-design)。

## 设计系统

*Source: `docs/design/intro.md` · Slug: `/design`*

# Unif Design

Unif Design 是 [Unif](https://github.com/unif-design)(统一企业 / Uni-President China)的 React Native 设计系统 —— 一套**品牌理念 + role-based token + 组件视觉契约**,面向 RN 0.85 新架构(Fabric + TurboModules)。本区从设计师视角讲清楚:为什么这么设计、用哪些 token、组件该长什么样。

> 找**怎么装、怎么用代码**?去[快速开始](/docs/getting-started)。找**逐组件 API**?去[组件概览](/docs/components)。要一份单文件全量参考?去[完整规范](/docs/unif-design)。

## 设计理念 {#设计理念}

一句话:**克制、功能性、中文优先。** 界面不是被装饰出来的,是被信息和操作组织出来的。三条贯穿始终的取向:

- **中文优先** —— 产品只面向中文用户,所有 UI 文案是简体中文;英文只出现在品牌名和代码标识符里。
- **橙色克制** —— 品牌橙 `#EB6E00` 只点在主按钮、用户气泡、活动标签、关键强调上,不铺满、不滥用;蓝色专属用户头像。
- **无装饰** —— 无插画、无渐变背景(仅品牌橙渐变)、无装饰 emoji、无背景图。视觉是功能性的。

完整的 5 条不可违背规则见[设计原则](/docs/design/principles)。

## 核心概念 {#核心概念}

- **role-based token,不是强度档** —— 颜色按**角色**命名(`primary` / `surface` / `foreground`),不是按强度(`gray100` / `orange500`)。亮 / 暗主题切换时,改的是 role 指向哪个 hex,组件代码不动。
- **颜色 / 阴影走运行期 hook** —— 用 `useColors()` / `useThemedStyles()` 在组件内拿,自动跟随系统亮暗;顶层静态 `colors` 导出已删除。
- **非颜色 token 静态 import** —— `space` / `radius` / `type` / `fw` / `motion` 是静态值,直接 import。
- **组合优先,不重造** —— 屏级 UI 是把现成原子(`Card` / `Cell` / `Tag` / `Avatar` / `Button`…)拼起来,而不是新写一套样式。

## 这套系统里有什么 {#这套系统里有什么}

| 板块 | 内容 |
|---|---|
| [设计原则](/docs/design/principles) | 5 条不可违背的规则 —— 中文优先、橙色克制、无装饰、列表用 gap、气泡内角方 |
| [语调与文案](/docs/design/voice) | 大小写、人称、状态文案速查、建议 chip 语气、标点 |
| [颜色 token](/docs/design/tokens/colors) | role-based 角色 token、亮 / 暗各一套、取色优先级链 |
| [字体 token](/docs/design/tokens/typography) | `type` 字号阶梯 + `fw` 字重 + 系统字体栈 |
| [间距 · 圆角 · 阴影](/docs/design/tokens/spacing-radii-shadows) | `space` 4px 网格、`radius`(含气泡非对称)、themed `shadow` |
| [动效 token](/docs/design/tokens/motion) | `motion` 时长、reanimated 用法 |
| [图标](/docs/components/icons) | 24×24 描边 SVG 规则 |
| [全局 Don'ts](/docs/design/donts) | 硬性禁忌清单 |

## 一句话速记 {#一句话速记}

- **品牌色** `#EB6E00` —— 仅主按钮、用户气泡、活动标签、关键强调。
- **气泡** AI `0/14/14/14`,用户 `14/0/14/14` —— 直角永远指向头像。
- **列表** 白卡 + 8px gap,**不**用 border-bottom。
- **图标** 24×24 描边 SVG,`stroke-width: 1.75`,`stroke-linecap: round`。
- **字体** 仅系统栈,CJK 走 PingFang SC / Microsoft YaHei,不引入 webfont。

## 下一步 {#下一步}

- [设计原则](/docs/design/principles) —— 5 条不可违背的规则,新增组件 / 改样式前必读
- [颜色 token](/docs/design/tokens/colors) —— role-based 角色 token 与取色优先级链
- [组件概览](/docs/components) —— 40+ 组件索引,按场景分组
- [快速开始](/docs/getting-started) —— 装包、挂 ThemeProvider、5 分钟跑通

## 设计原则

*Source: `docs/design/principles.md` · Slug: `/design/principles`*

# 设计原则

5 条不可违背的规则。**新增组件、修改样式前必读。** 这些是品牌一致性的底线,违反会破坏识别度。

## 1. 中文优先 {#中文优先}

所有 UI 文案均为简体中文,正式且简洁。英文仅出现在品牌名和代码标识符中。语气见[语调与文案](/docs/design/voice)。

```tsx
// ✅ Correct
<Text>今日待办</Text>
<Button label="提交订单" onPress={onSubmit} />

// ❌ Incorrect
<Text>Today's tasks</Text>
<Button label="Submit" onPress={onSubmit} />
```

## 2. 橙色克制 {#橙色克制}

品牌橙 `c.primary`(`#EB6E00`)**仅用于**:

- 主按钮(primary CTA)
- 用户气泡背景
- 活动标签 / 选中状态
- 关键强调

蓝色 `c.info`(`#3775F6`)**专属于用户头像**(及 Tag 的 `info` variant 历史沿用),其它地方禁用 —— 这是 user / AI 视觉区分的关键。

```tsx
// ✅ Correct
<Button variant="primary" label="确认" onPress={onOk} />  // 橙底
<Avatar label="我" variant="info" />                       // 蓝底(用户)
<Avatar label="AI" variant="brand" />                      // 橙底(AI)

// ❌ Incorrect
<Avatar label="王" variant="info" />                       // 蓝色不能给客户
<View style={{ backgroundColor: '#3775F6' }} />            // 蓝色装饰,禁止
```

> `Avatar` 的 `variant` 取值:`brand` / `info` / `soft` / `neutral`(见 [Avatar 文档](/docs/components/avatar))。颜色一律走 token,不内联 hex(见[颜色 → 取色优先级链](/docs/design/tokens/colors#取色优先级链))。

## 3. 无装饰 {#无装饰}

- 无插画
- 无渐变背景(仅允许品牌橙渐变:Logo 圆 / Drawer header)
- 无装饰性 emoji
- 无背景图、无 pattern

所有图标都是手绘 24×24 描边 SVG,功能性状态走图标系统(见[图标](/docs/components/icons))。头像是单字符 monogram,不放图片。

## 4. 列表用 gap,不用 border {#列表用-gap-不用-border}

每行独立白卡,行间 8px 空隙形成分组(与 iOS 17 / 微信新版一致),而不是用 `border-bottom` 切分。

```tsx
// ✅ Correct:用 List(grouped 默认)—— 白卡 + 8px gap + 浅灰底,无 cell 间分隔线
<List>
  <Cell title="账号与安全" onPress={goSecurity} />
  <Cell title="通用" onPress={goGeneral} />
</List>

// ❌ Incorrect:手画 border-bottom 分隔
<View>
  <View style={{ borderBottomWidth: 1 }}>{/* row 1 */}</View>
  <View style={{ borderBottomWidth: 1 }}>{/* row 2 */}</View>
</View>
```

`<List>` 有两种模式:`grouped`(默认,白卡 + gap)与 `flush`(紧凑 + cell 间 hairline,嵌在已有底色区里)。详见 [Cell · List 文档](/docs/components/cell)。

## 5. 气泡内角方 {#气泡内角方}

聊天气泡用 `radius['2xl']`(14px)圆角,但**指向头像的内角是直角** —— 这是 Unif 最辨识度的视觉符号。

- **AI 气泡** —— `borderRadius: 0 14px 14px 14px`(左上角直角,指向 AI 头像)
- **用户气泡** —— `borderRadius: 14px 0 14px 14px`(右上角直角,指向用户头像)

不要为了对称就把四角都改成 14px —— 这会破坏品牌识别。完整代码见[间距 · 圆角 · 阴影 → 气泡非对称圆角](/docs/design/tokens/spacing-radii-shadows#气泡非对称圆角)。

---

> 这 5 条是**硬约束**;更细的"不要做什么"清单见[全局 Don'ts](/docs/design/donts)。token 全量见[设计令牌](/docs/design/tokens/colors)。

## 颜色

*Source: `docs/design/tokens/colors.mdx` · Slug: `/design/tokens/colors`*

# 颜色

Unif Design 的颜色是 **role-based(角色化)token**:role 名固定(`primary` / `surface` / `foreground`…),亮 / 暗主题切换时,改的是 role 指向哪个 hex,组件代码不动。值的唯一真相源是 `src/theme/colors.ts`。

:::info 取色只走 hook,不要顶层 import
颜色跟随系统亮暗切换,**必须**在组件内用 `useColors()` / `useTheme().colors` 运行期拿。顶层 `import { colors }` 导出已删除(见[迁移 → 令牌迁移](/docs/migration#令牌迁移)）。下方所有色块的 `hex` 仅供查阅;代码里写 role 名,不写 hex。
:::

## 取色优先级链 {#取色优先级链}

从语义匹配度由高到低,**不跳级**:

1. **角色 token** —— `useColors()` 返回的 `c.primary` / `c.surface` / `c.foreground` 等。语义对得上就用它,自动亮 / 暗。
2. **静态 palettes** —— 渐变序列(`avatarGradient`、`warmOrangePalette`),塞不进单值 role 的"色组 / 渐变",见[间距·圆角·阴影](/docs/design/tokens/spacing-radii-shadows)与下文。
3. **新增 token** —— 现有 role 都对不上时,在 `colors.ts` 给 `lightColors` 和 `darkColors` **同时**加同名 key(TS 编译期强制两套键集合对齐,少一个就报错)。

**永远不要内联 `#EB6E00` / `rgba(...)`。** 新硬编码颜色会被 CI 拦下。唯一例外:视觉锁定(QR 白卡、固定商标色),且必须加注释说明锁定理由。

## 品牌 / Brand {#品牌}

品牌橙 `#EB6E00` 是 Unif 的核心识别色。**亮 / 暗共用同一 hex** —— 在 `#0A0A0A` 暗底上对比度仍过 WCAG AA,brand identity 不随主题变。

<Swatches items={[
  { name: 'primary', hex: '#EB6E00', desc: '主品牌橙(亮/暗共用)' },
  { name: 'primaryPressed', hex: '#D06200', desc: '按下态(亮/暗共用)' },
  { name: 'primaryContainer', hex: '#FFF5EB', desc: '亮:高亮选中背景' },
  { name: 'primaryContainerSubtle', hex: '#FFF8F0', desc: '亮:Card 选中背景' },
  { name: 'onPrimary', hex: '#FFFFFF', desc: '品牌底上的内容色' },
]} />

| role | light | dark | 用途 |
|---|---|---|---|
| `primary` | `#EB6E00` | `#EB6E00` | 主按钮、用户气泡、活动标签、关键强调 |
| `primaryPressed` | `#D06200` | `#D06200` | 按下态 |
| `primaryContainer` | `#FFF5EB` | `#3D1F00` | 高亮选中背景 |
| `primaryContainerSubtle` | `#FFF8F0` | `#2A1500` | Card 选中背景 |
| `onPrimary` | `#FFFFFF` | `#FFFFFF` | 品牌底上的内容色 |
| `onPrimaryMuted` | `rgba(255,255,255,0.85)` | `rgba(255,255,255,0.85)` | 品牌底上的次级文字 |

**品牌渐变**(数组,不暴露为 role):`avatarGradient = ['#F49443', '#EB6E00']`(135°,Me hero 头像;亮 / 暗共用)。平铺橙 `#EB6E00` 在 90% 场景已足够,**不要引入新渐变**。

## 语义色 / Semantic {#语义色}

<Swatches items={[
  { name: 'success', hex: '#52C41A', desc: '成功 / 完成' },
  { name: 'error', hex: '#F4511E', desc: '错误 / 销毁(暗:#FF6B40)' },
  { name: 'info', hex: '#3775F6', desc: '⚠ 仅用于用户头像(暗:#5A91FF)' },
]} />

| role | light | dark | 用途 |
|---|---|---|---|
| `success` | `#52C41A` | `#52C41A` | 成功态 |
| `successContainer` | `#F0FFF0` | `#0E2810` | success badge 底 |
| `onSuccess` | `#FFFFFF` | `#FFFFFF` | success 上的内容 |
| `error` | `#F4511E` | `#FF6B40` | 错误 / destructive |
| `errorContainer` | `#FFF5F5` | `#2A1010` | error badge 底 |
| `onError` | `#FFFFFF` | `#FFFFFF` | error 上的内容 |
| `info` | `#3775F6` | `#5A91FF` | **仅用户头像**(Tag `info` variant 历史沿用) |
| `infoContainer` | `#F0F5FF` | `#0F1A33` | info badge 底 |
| `onInfo` | `#FFFFFF` | `#FFFFFF` | info 上的内容 |

:::warning 蓝色规则
`info`(`#3775F6`)**专属于用户头像**。除 Tag 的 `info` variant 历史沿用外,不要在按钮、提示、链接等任何其它地方铺蓝色 —— 这会破坏 user / AI 的视觉区分。详见[设计原则 → 橙色克制](/docs/design/principles#橙色克制)。
:::

## 表面 / Surface(5 层) {#表面}

5 层明度阶梯。**暗色不靠 shadow 表达深度,靠这 5 层 surface 的明度差**(见[阴影](/docs/design/tokens/spacing-radii-shadows#阴影))。

<Swatches items={[
  { name: 'background', hex: '#F5F5F5', desc: '整页底(暗:#0A0A0A,OLED 友好)' },
  { name: 'surface', hex: '#FFFFFF', desc: 'Card / Sheet / 气泡(暗:#1C1C1E)' },
  { name: 'surfaceContainer', hex: '#F5F5F5', desc: '卡内输入框 / 次级(暗:#2C2C2E)' },
  { name: 'surfaceContainerHigh', hex: '#F0F0F0', desc: '次按钮 / 按下态(暗:#3A3A3C)' },
  { name: 'surfaceContainerHighest', hex: '#E0E0E0', desc: 'disabled / pill(暗:#48484A)' },
]} />

| role | light | dark | 用途 |
|---|---|---|---|
| `background` | `#F5F5F5` | `#0A0A0A` | 整页底色(OLED 友好) |
| `surface` | `#FFFFFF` | `#1C1C1E` | Card / Sheet / 气泡 |
| `surfaceContainer` | `#F5F5F5` | `#2C2C2E` | 卡内输入框 / 次级面 |
| `surfaceContainerHigh` | `#F0F0F0` | `#3A3A3C` | 次按钮 / 按下态 |
| `surfaceContainerHighest` | `#E0E0E0` | `#48484A` | disabled 按钮 / pill |

## 前景 / Foreground {#前景}

<Swatches items={[
  { name: 'foreground', hex: '#333333', desc: '主文字(暗:#FFFFFF)' },
  { name: 'foregroundMuted', hex: '#666666', desc: '次级文字' },
  { name: 'foregroundSubtle', hex: '#999999', desc: '三级 / placeholder' },
]} />

| role | light | dark | 用途 |
|---|---|---|---|
| `foreground` | `#333333` | `#FFFFFF` | 主文字 |
| `foregroundMuted` | `#666666` | `rgba(235,235,245,0.6)` | 次级文字 |
| `foregroundSubtle` | `#999999` | `rgba(235,235,245,0.3)` | 三级文字 / placeholder |
| `onSurface` | `= foreground` | `= foreground` | 别名(语义同 `foreground`) |
| `onSurfaceMuted` | `= foregroundMuted` | `= foregroundMuted` | 别名 |

## 描边 / Outline {#描边}

| role | light | dark | 用途 |
|---|---|---|---|
| `outline` | `#EDEDED` | `#3A3A3C` | 默认 hairline |
| `outlineVariant` | `#E8E8E8` | `#48484A` | 次级 hairline |
| `outlineFaint` | `#F5F5F5` | `rgba(84,84,88,0.65)` | 最弱 hairline |

## 反色 / Inverse · 遮罩 / Scrim {#反色与遮罩}

| role | light | dark | 用途 |
|---|---|---|---|
| `inverseSurface` | `#1C1C1E` | `#FFFFFF` | toast / tooltip 反色底 |
| `inverseOnSurface` | `#FFFFFF` | `#000000` | inverseSurface 上的内容 |
| `scrim` | `rgba(0,0,0,0.5)` | `rgba(0,0,0,0.7)` | Sheet 遮罩(暗色加深) |
| `sheetBackdrop` | `rgba(245,245,247,0.72)` | `rgba(245,245,247,0.72)` | 合规 sheet 之下的浅 tint(焦点引导,亮 / 暗共用) |

:::note 玻璃 / 渐变等专用色
`colors.ts` 另有一批玻璃感(`glassTintLight` / `glassBorder` / `glassActiveFg`…)、Hero 渐变(`heroGradient0/1/2`)、淡阶图标(`iconFaint40/30/25`)等专用 role,多数亮 / 暗 alpha **故意不同**(逐条注释了原因,不要"归一化")。这些供具体组件内部使用,完整清单与注释见 `src/theme/colors.ts`。
:::

## 中性色规则 {#中性色规则}

**无近黑、无米白、无染色灰。** 中性色保持纯净 —— 不要在灰阶里掺品牌橙或其它色相。

## 在代码中使用 {#在代码中使用}

```tsx
import { StyleSheet } from 'react-native';
import { useColors, useThemedStyles } from '@unif/react-native-design';
import type { ColorTokens } from '@unif/react-native-design';

// makeStyles 必须定义在模块顶层(不要内联进组件,否则打穿 useThemedStyles 缓存)
const makeStyles = (c: ColorTokens) =>
  StyleSheet.create({
    primary: { backgroundColor: c.primary },   // 亮/暗同:#EB6E00
    text:    { color: c.foreground },          // 亮:#333333 / 暗:#FFFFFF
    border:  { borderColor: c.outline },       // 亮:#EDEDED / 暗:#3A3A3C
    error:   { color: c.error },               // 亮:#F4511E / 暗:#FF6B40
  });

function MyView() {
  const styles = useThemedStyles(makeStyles);
  const c = useColors(); // inline 取色(状态映射 / prop fallback)时用
  // ...
}
```

## 暗色哲学 {#暗色哲学}

- **iOS HIG dark 风格** —— 纯黑 / 近黑 `background`(`#0A0A0A`)+ 深灰多层 `surface`(`#1C / #2C / #3A / #48`),OLED 友好。
- **品牌橙保留原值** —— 亮 / 暗均 `#EB6E00`,brand identity 不变。
- **layered surface 替代 shadow** —— 暗色下 shadow token 的 `shadowOpacity` / `elevation` 多数置 0,深度靠 surface 5 层明度差(见[阴影](/docs/design/tokens/spacing-radii-shadows#阴影))。
- **气泡"内角方"签名完整保留**(见[设计原则 → 气泡内角方](/docs/design/principles#气泡内角方))。

> 完整 role → hex 对照、迁移 grep 表、为何不引入 reference layer,见[完整规范 → Color system](/docs/unif-design)。

## 动效

*Source: `docs/design/tokens/motion.md` · Slug: `/design/tokens/motion`*

# 动效

功能性、克制。仅 fade 与 layout animation。**无弹簧、无回弹、无入场缩放。** 尊重 reduced-motion。时长的真相源是 `src/theme/tokens.ts` 的 `motion`。

## 时长 / `motion` {#时长}

| Token | 值 | 用途 |
|---|---|---|
| `motion.fast` | 150ms | 按压态、hover |
| `motion.base` | 200ms | 分段控件、布局变化、Modal fade |
| `motion.slow` | 300ms | Drawer 过渡 |
| `motion.pulse` | 1600ms | "思考中" spark 脉冲全周期 |

`motion` 只有这四个时长键 —— **没有 easing token**。缓动曲线由 reanimated 的 `withTiming` 默认曲线承担(Spinner 旋转显式用 `Easing.linear`),需要自定义缓动时从 `react-native-reanimated` import `Easing`,不要去找不存在的 `motion.easeOut`。

:::tip pulse 是全周期,usePulse 取半周期
`motion.pulse`(1600ms)是脉冲一来一回的**全周期**。`usePulse` / `<Pulse>` 的 `duration` 是**半周期**(一个方向),所以脉冲场景常传 `motion.pulse / 2`(800ms)。
:::

## 按压态规则 {#按压态规则}

- **非品牌表面** —— 按压时 `opacity: 0.7`。
- **品牌 CTA** —— 按压时底色切到 `c.primaryPressed`(`#D06200`)。
- **禁用** —— 按钮整体 `opacity: 0.5`;送出键背景切到 `c.surfaceContainerHighest`(`#E0E0E0`)。

## 在代码中使用 {#在代码中使用}

整套动画走 `react-native-reanimated@4` —— worklet 在 UI 线程跑,**不要再写 `Animated.loop` / `useNativeDriver`**。常用脉冲 / 渐入请直接复用 `usePulse` / `<Pulse>` / `<PulseDot>` / `<Reveal>`,别自己重写。

### 通用 fade-in

```tsx
import React from 'react';
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withTiming,
} from 'react-native-reanimated';
import { motion } from '@unif/react-native-design';

function FadeIn({ children }: { children: React.ReactNode }) {
  const op = useSharedValue(0);
  React.useEffect(() => {
    op.value = withTiming(1, { duration: motion.fast });
  }, [op]);
  const style = useAnimatedStyle(() => ({ opacity: op.value }));
  return <Animated.View style={style}>{children}</Animated.View>;
}
```

### 脉冲(思考中 / shimmer / blink cursor 全走它) {#脉冲}

```tsx
import { Pulse, PulseDot, usePulse, Icon, motion } from '@unif/react-native-design';
import Animated from 'react-native-reanimated';

// 包裹任意 children
<Pulse from={0.4} duration={motion.pulse / 2}>
  <Icon name="spark" size={14} />
</Pulse>

// 圆点
<PulseDot />

// hook + 自定义 view
function Custom() {
  const animatedStyle = usePulse({ from: 0.5, duration: 700 });
  return <Animated.View style={[/* base */, animatedStyle]} />;
}
```

更多用法见 [Pulse 文档页](/docs/components/pulse)。

### 进出过渡(替代 LayoutAnimation) {#进出过渡}

```tsx
import Animated, { FadeIn, FadeOut } from 'react-native-reanimated';
import { motion } from '@unif/react-native-design';

{open ? (
  <Animated.View
    entering={FadeIn.duration(motion.base)}
    exiting={FadeOut.duration(motion.base)}
  >
    {/* children */}
  </Animated.View>
) : null}
```

iOS Fabric 下 `LayoutAnimation` 行为不稳定,统一改走 reanimated 的 `entering` / `exiting` 装饰器。design 包内的脉冲 / 渐入(含 `Reveal`)已收口 web 特化实现,在文档站 MDX 里不要直接用 `useAnimatedStyle`(见[常见问题 → 文档站动画崩溃](/docs/troubleshooting#useanimatedstyle--layout-动画在文档站崩溃))。

## 间距 · 圆角 · 阴影

*Source: `docs/design/tokens/spacing-radii-shadows.md` · Slug: `/design/tokens/spacing-radii-shadows`*

# 间距 · 圆角 · 阴影

`space` / `radius` 是静态 token(直接 import),`shadow` 是 themed token(走 hook,暗色自动趋零)。值的真相源是 `src/theme/tokens.ts`(space / radius)与 `src/theme/shadow.ts`(shadow)。

:::info 尺寸会随屏宽缩放
`space` / `radius` 的多数值经 `r()` 做像素对齐缩放(`PixelRatio.roundToNearestPixel`,避免 @3x 屏 0.5px 缝隙;基准宽 402pt)。下表是基准设计值。`radius.pill`(999)是大数哨兵,不缩放。
:::

## 间距 / `space` {#间距}

4px 基准网格。组件内部多用 `5–6`(12–14),板块之间用 `7–9`(16–24)。

| Token | 基准 px | 常用 |
|---|---|---|
| `space.px` | 1 | hairline 级位移 |
| `space['1']` | 4 | 最紧间隙 |
| `space['2']` | 6 | 图标-文字间隙 |
| `space['3']` | 8 | 头像-气泡间隙、列表行间 gap |
| `space['4']` | 10 | 气泡纵向 padding |
| `space['5']` | 12 | 气泡横向 padding、栏间距 |
| `space['6']` | 14 | 卡片 padding |
| `space['7']` | 16 | 区块栏间距 |
| `space['8']` | 20 | 较大区块间距 |
| `space['9']` | 24 | Hero padding |
| `space['10']` | 32 | 通栏区块间距 |

**规则。** 屏幕侧边距 12–16px。气泡 padding `10px 12px`。卡片 `12–14px`。尊重安全区(iOS home indicator 34px)。`space` 的 key 是字符串字面量,取值写 `space['7']` 或 `space[7]`。

## 圆角 / `radius` {#圆角}

小集合,明确分工。最重要的是**气泡的非对称圆角** —— 指向头像的内角是直角。

| Token | 基准 px | 用途 |
|---|---|---|
| `radius.xs` | 4 | Radio / Checkbox / Tag / Citation 内圈 |
| `radius.sm` | 6 | 小按钮、徽章 |
| `radius.md` | 8 | 输入框、默认按钮 |
| `radius.lg` | 10 | 卡片、列表行 |
| `radius.xl` | 12 | 大卡片、列表容器 |
| `radius['2xl']` | 14 | **聊天气泡** |
| `radius['3xl']` | 18 | 输入框 wrapper |
| `radius.pill` | 999 | chip、pill(大数哨兵,不缩放) |

### 气泡的非对称圆角(核心) {#气泡非对称圆角}

- **AI 气泡** —— `borderRadius: 0 14px 14px 14px`(左上角直角,指向 AI 头像)
- **用户气泡** —— `borderRadius: 14px 0 14px 14px`(右上角直角,指向用户头像)

直角指向头像,是设计系统最辨识度的视觉符号,**不要破坏**(见[设计原则 → 气泡内角方](/docs/design/principles#气泡内角方))。

```tsx
const aiBubble = {
  borderTopLeftRadius: 0,         // 直角,指向 AI 头像
  borderTopRightRadius: 14,
  borderBottomLeftRadius: 14,
  borderBottomRightRadius: 14,
};

const userBubble = {
  borderTopLeftRadius: 14,
  borderTopRightRadius: 0,        // 直角,指向用户头像
  borderBottomLeftRadius: 14,
  borderBottomRightRadius: 14,
};
```

## 阴影 / `shadow` {#阴影}

中性卡片阴影 + 品牌橙光晕两类。**无内阴影、无霓虹光晕、无双重边框。** `shadow` 是 **themed token** —— 走 `useShadow()` / `useThemedStyles` 第二参 `s` 拿,**暗色下绝大多数 `shadowOpacity` / `elevation` 自动置 0**(深度靠 surface 5 层明度差表达,见[颜色 → 表面](/docs/design/tokens/colors#表面))。

| Token | 用途 | RN(亮色) |
|---|---|---|
| `subtle` | 轻提示浮起(Segmented active 段) | `{0,1}` · opacity 0.06 · radius 2 · elev 1 |
| `card` | 标准卡片下沉(Card default) | `{0,1}` · opacity 0.08 · radius 4 · elev 2 |
| `floating` | 中性浮岛(贴底浮起胶囊,大半径柔散) | `{0,16}` · opacity 0.1 · radius 40 · elev 12 |
| `brandSm` | 品牌光晕 sm(轻量档) | 橙 · `{0,6}` · opacity 0.08 · radius 18 · elev 3 |
| `brandMd` | 品牌光晕 md(主按钮 / Avatar ring) | 橙 · `{0,12}` · opacity 0.26 · radius 24 · elev 12 |
| `brandLg` | 品牌光晕 lg(Login Logo halo) | 橙 · `{0,16}` · opacity 0.22 · radius 36 · elev 12 |
| `brandXl` | 品牌光晕 xl(Splash Logo 最重浮起) | 橙 · `{0,20}` · opacity 0.2 · radius 50 · elev 12 |
| `brandAbout` | About icon halo(brandLg / brandXl 之间) | 橙 · `{0,18}` · opacity 0.28 · radius 40 · elev 12 |
| `brandAssistant` | AssistantCard icon tile(hero 入口加权) | 橙 · `{0,8}` · opacity 0.3 · radius 18 · elev 12 |
| `brandAvatar` | Avatar 品牌橙光晕 | 橙 · `{0,10}` · opacity 0.28 · radius 24 · elev 12 |
| `glassBar` | GlassStats 数据条专用 | 橙 · `{0,6}` · opacity 0.08 · radius 18 · elev 3 |
| `none` | 显式去阴影(列表行 / 设置项) | 全 0 |

> `{w,h}` 是 `shadowOffset`;橙 = `shadowColor: '#EB6E00'`(其余为黑)。完整 5 件套数值见 `src/theme/shadow.ts`。

:::note 暗色例外项
暗色下 `subtle` / `card` / `brand*` 多数置零,但 **`floating` / `glassBar`(黑色 drop shadow)与 `brandAvatar`(橙光晕)在暗色不置零** —— 否则浮岛 / 数据条 / 头像在暗底上贴平、看不出层级。每个例外在源码里都注释了原因。
:::

确认卡片用 `2px` 彩色边框(橙 / 绿 / 灰),**不带阴影**。

```tsx
import { StyleSheet } from 'react-native';
import { useShadow, space, radius } from '@unif/react-native-design';

// 方式一:useShadow() 直接拿
function Demo() {
  const shadow = useShadow();
  const styles = StyleSheet.create({
    card:  { ...shadow.card },        // 默认卡片阴影(暗色自动趋零)
    float: { ...shadow.floating },    // 中性浮岛(大半径柔散)
    brand: { ...shadow.brandMd },     // 品牌橙光晕(主按钮 / Avatar ring)
    flat:  { ...shadow.none },        // 显式去阴影
  });
  // ...
}
```

```tsx
// 方式二(推荐):useThemedStyles 第二参 s 注入,与 colors 一起 memo
import { useThemedStyles } from '@unif/react-native-design';
import type { ColorTokens, ShadowTokens } from '@unif/react-native-design';

const makeStyles = (c: ColorTokens, s: ShadowTokens) =>
  StyleSheet.create({
    card: {
      backgroundColor: c.surface,
      borderRadius: radius.xl,
      padding: space['6'],
      ...s.card,                      // 暗色下 shadowOpacity / elevation 自动趋零
    },
  });
```

> 完整 token 速查与暗色哲学,见[完整规范](/docs/unif-design)的 Spacing / Radii / Shadows 三节。

## 字体

*Source: `docs/design/tokens/typography.md` · Slug: `/design/tokens/typography`*

# 字体

仅用系统字体栈 —— iOS 走 `-apple-system`,Android 走系统默认,CJK 走 PingFang SC / Microsoft YaHei。**不引入 webfont**:品牌刻意依赖 OS 渲染原生中文字形。字号 / 字重的真相源是 `src/theme/tokens.ts`。

:::info 字号会随屏宽缩放
`type` 的每个值经 `rf()` 做 moderate 缩放(系数 `0.3`,对中文字号最友好;基准宽 402pt = iPhone 17 Pro)。下表数值是**基准设计值**,真机上略有浮动。详见 `src/theme/scale.ts`。
:::

## 字体栈

系统栈在 RN 端由 OS 默认提供;文档站 / web 侧 CSS 栈:

```css
font-family:
  -apple-system, BlinkMacSystemFont,
  "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei",
  "Helvetica Neue", Helvetica, Arial, sans-serif;
```

等宽栈走 `fontMono` token(iOS `Menlo` / Android `monospace`,用于数字、代码风格元数据):

```tsx
import { fontMono } from '@unif/react-native-design';
// style={{ fontFamily: fontMono }}
```

## 字号阶梯 / `type` {#字号阶梯}

| Token | 基准 px | 用途 |
|---|---|---|
| `display` | 22 | 品牌标题 |
| `h1` | 18 | 页面标题 |
| `h2` | 17 | 区块标题 |
| `h3` | 15 | 卡片标题 / 强调正文 |
| `body` | 15 | 默认正文 |
| `sm` | 14 | 次级正文 / 按钮 |
| `xs` | 13 | 提示、说明 |
| `xxs` | 12 | meta、caption |
| `micro` | 11 | 徽章、工具名 |
| `nano` | 10 | TabBar / Grid / Citation / Sources 角标、最小标签 |

### 半档微调 {#半档微调}

为收敛"近似 token + delta"反模式,补了几个 0.5 step 的半档,各有固定语义:

| Token | 基准 px | 用途 |
|---|---|---|
| `smPlus` | 14.5 | dashboard card 标题("小一档 semi"惯例) |
| `xsPlus` | 13.5 | 长文阅读字号(Privacy 正文) |
| `microPlus` | 11.5 | VersionPill / profileCard / Splash / carousel 副标题 |

### Hero 档 {#hero-档}

Hero 区主标题的三档(带 Logo / NavBar 的品牌大标题):

| Token | 基准 px | 用途 |
|---|---|---|
| `heroLg` | 26 | 一级 brand hero(带 Logo,Login 屏) |
| `heroMd` | 22 | 二级 hero(独立屏 + NavBar,ForgotPassword) |
| `heroSm` | 18 | 承接式 hero(Group 选组 / 选角色子区) |

## 字重 / `fw` {#字重}

| Token | 值 | 别名 |
|---|---|---|
| `fw.regular` | `'400'` | regular |
| `fw.medium` | `'500'` | medium |
| `fw.semi` | `'600'` | semi |
| `fw.bold` | `'700'` | bold |
| `fw.heavy` | `'800'` | heavy |

`fw` 用 `as const` 声明,类型已收窄到字面量字符串,**不需要再写 `as '500'` / `as '600'` 这种 cast**。

## 行高(惯例,非 token) {#行高}

:::warning 行高没有独立 token
设计系统**没有** `lineHeight` token。行高按惯例用字号乘系数算:标题 ×1.25(紧凑)、正文 ×1.45。在 `makeStyles` 里直接写 `lineHeight: t.body * 1.45` 即可,不要去 import 不存在的 `lh` token。
:::

| 惯例 | 系数 | 用途 |
|---|---|---|
| 紧凑 | ×1.25 | 标题 |
| 正文 | ×1.45 | 正文段落(约 22 / 15) |

## 在代码中使用 {#在代码中使用}

```tsx
import { StyleSheet } from 'react-native';
import { type as t, fw, fontMono, useThemedStyles } from '@unif/react-native-design';
import type { ColorTokens } from '@unif/react-native-design';

const makeStyles = (c: ColorTokens) =>
  StyleSheet.create({
    title: {
      fontSize: t.h2,               // 17
      lineHeight: t.h2 * 1.25,      // 标题用 ×1.25
      fontWeight: fw.semi,          // '600'(无需 cast)
      color: c.foreground,
    },
    body: {
      fontSize: t.body,             // 15
      lineHeight: t.body * 1.45,    // 正文用 ×1.45
      color: c.foreground,
    },
    meta: {
      fontSize: t.micro,            // 11
      fontWeight: fw.semi,
      color: c.foregroundSubtle,
    },
    code: {
      fontFamily: fontMono,
      fontSize: t.xxs,              // 12
    },
  });

function Article() {
  const styles = useThemedStyles(makeStyles);
  // ...
}
```

> `type` 导入时常起别名 `t`(避开 JS 保留字 `type`):`import { type as t } from '@unif/react-native-design'`。

## 应用级字号缩放(fontScale)

app 内「字体大小」档位经 `<ThemeProvider fontScale={…}>` 传入(默认 `1`),`useThemedStyles` 出口对 maker 产物的 `fontSize / lineHeight / letterSpacing` 统一缩放:

- 与 RN `allowFontScaling` 的原生缩放范围一致 —— **只缩文字,不缩 padding / 高度等布局尺寸**;
- `fontScale = 1` 时恒等返回原引用,未接入的消费方(web 文档站等)行为与引用完全不变;
- 与 `rf()` 正交:`rf()` 是按屏宽的**静态**适配(模块加载时算一次),`fontScale` 是**运行期**用户档位(变更即触发全树 themed 样式重算)。

接入方自持档位状态(persist store 等);组件层零改动 —— 所有走 `useThemedStyles` 的样式自动生效。

## 语调与文案

*Source: `docs/design/voice.md` · Slug: `/design/voice`*

# 语调与文案

简体中文为唯一交互语言。语气**冷静、直接、克制** —— 状态描述事实,不寒暄、不致歉、不夸张,不加感叹号。助手像一个已经熟悉用户业务的同事。

## 大小写 {#大小写}

- 主品牌一律写作 **Unif** —— 不写 `UNIF`、`unif` 或加连字符。
- 子产品形如 `Unif <中文名>`(半角空格分隔)。
- 拉丁字符与 CJK 字符之间使用单个半角空格。

## 人称 {#人称}

- 助手显示为 `AI` 或 `助手`(头像内)。
- 用户显示为 `我`(自己头像内)。
- 正文避免第一 / 第二人称,直接陈述事实:`已思考 3s`、`正在执行…`、`AI 回复中…`。

## 状态文案速查 {#状态文案速查}

| 场景 | 文案 |
|---|---|
| 工具运行中 | `执行中` |
| 工具完成 | `完成` 或 `完成 · 0.6s` |
| 工具失败 | `失败` |
| 推理进行中 | `思考中…` |
| 推理完成 | `已思考 3s` |
| 确认发起 | `操作确认` |
| 确认完成 | `已确认，正在执行…` |
| 确认取消 | `已取消` |
| 发送失败 | `发送失败，请重试` |
| 输入空闲 | `输入消息…` |
| AI 流式回复 | `AI 回复中…` |

## 建议 chip 语气 {#建议-chip-语气}

像用户的口气 —— 疑问句或祈使句,**不加句号**:

- `今天要拜访哪些客户？`
- `帮我查一下今天的计划`
- `新建一个拜访记录`

## 标点 {#标点}

- 全角中文标点:`，` `。` `？` `：`
- 流式 / 加载用西文省略号 `…`
- 中点 `·` 用于分隔元数据:`客户名称 · 地址`

## Emoji {#emoji}

**禁用所有装饰 emoji。** 包括国旗、贴纸、装饰字符。功能性状态全部走[图标系统](/docs/components/icons)。如果一个字符不传递信息,它就不应该出现。

```tsx
// ❌ Incorrect
<Text>🎉 提交成功！</Text>
<Text>📍 当前位置</Text>

// ✅ Correct
<Text>提交成功</Text>
<Text>
  <Icon name="location" size={14} /> 当前位置
</Text>
```

> 这些约定是[中文优先原则](/docs/design/principles#中文优先)的细化;硬性禁忌清单见[全局 Don'ts](/docs/design/donts)。

## 快速开始

*Source: `docs/getting-started.md` · Slug: `/getting-started`*

# 快速开始

5 分钟跑通:装包 → 挂 `ThemeProvider` → 用 `useColors()` / `useThemedStyles()` 写第一个跟随亮暗的组件。

## 环境要求 {#环境要求}

- **React Native 0.85+**(新架构 Fabric + TurboModules 已开启,对应 React 19 concurrent)
- Node.js ≥ 24.13(见仓库 `.nvmrc`)、Yarn 4

:::info 仅支持新架构
本库面向 RN 0.85 新架构,依赖 `react-native-reanimated@4` + `react-native-worklets`。旧架构(Bridge)与更低 RN 版本不在支持范围。
:::

## 安装依赖 {#安装依赖}

### 1. 装本库

```sh
yarn add @unif/react-native-design
```

### 2. 装 peer dependencies

:::danger peerDeps 缺一即崩
本库**不打包**下列依赖,宿主工程必须自行安装并完成原生侧配置。缺任一,Metro 打包或运行时就会报 `Unable to resolve module` / `Cannot find module`。

```sh
yarn add react-native-svg \
  react-native-gesture-handler \
  react-native-reanimated \
  react-native-worklets \
  react-native-safe-area-context \
  react-native-reanimated-carousel \
  @sbaiahmed1/react-native-blur
```

iOS 装完原生包后,在 `ios/` 目录执行 `bundle exec pod install`。
:::

> 版本范围(来自 `package.json#peerDependencies`):`react-native-reanimated >=4.1.0`、`react-native-worklets >=0.9`、`react-native-gesture-handler >=3.0.0 <4.0.0`、`react-native-safe-area-context >=5`、`react-native-svg >=15`、`react-native-reanimated-carousel >=5.0.0 <6.0.0`、`@sbaiahmed1/react-native-blur >=4`。

:::caution npm 需要 Carousel scoped override
本包要求 Gesture Handler 3.x,但
`react-native-reanimated-carousel@5.0.0` 的 peer 范围暂未包含 Gesture Handler 3。
使用 npm 安装时,请在消费端根 `package.json` 加入只作用于 Carousel 的 scoped
override,再执行 `npm install`:

```json
{
  "overrides": {
    "react-native-reanimated-carousel": {
      "react-native-gesture-handler": "$react-native-gesture-handler"
    }
  }
}
```

不要使用全局 override、`--force` 或 `--legacy-peer-deps`;上面的
`$react-native-gesture-handler` 会复用消费端根依赖中满足 `>=3.0.0 <4.0.0`
的版本,避免安装第二份 Gesture Handler。
:::

### 3. 配 babel(worklets 插件必须最后)

```js
// babel.config.js —— react-native-worklets/plugin 必须排在 plugins 数组最后
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    // ... 其它插件
    'react-native-worklets/plugin',
  ],
};
```

## 根挂 ThemeProvider {#根挂-themeprovider}

在 App 根组件挂载一次 `ThemeProvider`(它读 `useColorScheme()`,自动跟随系统亮暗),并按需渲染命令式 host:

```tsx
import { ThemeProvider, ToastHost } from '@unif/react-native-design';

export function App() {
  return (
    <ThemeProvider>
      {/* 你的导航 / 屏幕 */}
      <ToastHost />
    </ThemeProvider>
  );
}
```

- `ToastHost` —— 渲染 `toast.success / error / info(...)` 命令式调用的弹层。

:::tip 完整 Provider 栈
实战里 `ThemeProvider` 通常嵌在手势 / 键盘 / 安全区 Provider 内:`GestureHandlerRootView → KeyboardProvider → SafeAreaProvider → ThemeProvider → NavigationContainer`。骨架见[完整规范 → Quickstart](/docs/unif-design)。`ThemeProvider` 接受 `forceScheme?: 'light' | 'dark'` 强制某主题(用于测试 / 设置项接入)。
:::

## 第一个主题化组件 {#第一个主题化组件}

颜色 / 阴影走 `useThemedStyles(maker)`,自动跟随亮暗。**`makeStyles` 必须定义在模块顶层** —— 内联进组件会让引用每次渲染都变、打穿缓存。

```tsx
import { StyleSheet, View, Text } from 'react-native';
import {
  Button,
  useThemedStyles,
  type ColorTokens,
} from '@unif/react-native-design';

// ✅ 模块顶层定义 maker:(colors, shadow) => StyleSheet
const makeStyles = (c: ColorTokens) =>
  StyleSheet.create({
    wrap: { padding: 16, backgroundColor: c.surface },
    title: { color: c.foreground, fontSize: 17, fontWeight: '600' },
  });

export function Demo() {
  const styles = useThemedStyles(makeStyles);
  return (
    <View style={styles.wrap}>
      <Text style={styles.title}>今日待办</Text>
      <Button label="保存" variant="primary" onPress={() => {}} />
    </View>
  );
}
```

只需 inline 取一两个颜色(状态映射 / prop fallback)时,用 `useColors()`:

```tsx
import { useColors } from '@unif/react-native-design';

function Banner({ active }: { active: boolean }) {
  const c = useColors(); // 跟随亮暗
  return <View style={{ backgroundColor: active ? c.primary : c.surfaceContainer }} />;
}
```

## 命令式 API {#命令式-api}

挂好 host 后,任意位置可直接调用:

```tsx
import { toast } from '@unif/react-native-design';

toast.success('已保存');
```

## 下一步 {#下一步}

- [设计原则](/docs/design/principles) —— 5 条不可违背的设计规则
- [颜色 token](/docs/design/tokens/colors) —— role-based 角色 token 与取色优先级链
- [组件概览](/docs/components) —— 40+ 组件,按场景分组索引
- [常见问题](/docs/troubleshooting) —— peer 缺失、Web 点击无响应、缓存不生效等排障

## 升级 / 迁移

*Source: `docs/migration.md` · Slug: `/migration`*

# 升级 / 迁移

破坏性变更与迁移方法。当前版本的完整 token 见[设计令牌](/docs/design/tokens/colors),组件 API 见[组件概览](/docs/components)。

---

## 令牌迁移:旧顶层导出 → 运行期 Hook {#令牌迁移}

### 背景 {#背景}

旧版 `@unif/react-native-design` 从顶层直接导出 `colors` 和 `shadow` 对象,可在模块顶层静态 import。这种写法只有单一亮色值,无法随系统亮暗切换 —— 顶层静态导出**已删除**:

```tsx
// ❌ Incorrect:顶层 colors / shadow 导出已删除,拿不到;且只有亮色值
import { colors, shadow } from '@unif/react-native-design';

const styles = StyleSheet.create({
  container: {
    backgroundColor: colors.surface,   // 静态,不随亮 / 暗切换
    ...shadow.brandLg,
  },
});
```

### 迁移方式 {#迁移方式}

**颜色 + 阴影**:改用运行期 hook。`useThemedStyles(maker)` 的 `maker` 签名是 `(c: ColorTokens, s: ShadowTokens) => StyleSheet`,在组件内调用即拿到当前主题的 styles。

```tsx
// ✅ Correct:运行期 hook,自动随主题切换
import { useThemedStyles } from '@unif/react-native-design';
import type { ColorTokens, ShadowTokens } from '@unif/react-native-design';
import { StyleSheet } from 'react-native';

// makeStyles 必须在模块顶层定义(不能内联进组件,否则打穿 useMemo 缓存)
const makeStyles = (c: ColorTokens, s: ShadowTokens) =>
  StyleSheet.create({
    container: {
      backgroundColor: c.surface,
      ...s.brandLg,                  // 暗色下 shadowOpacity / elevation 自动趋零
    },
  });

function MyComponent() {
  const styles = useThemedStyles(makeStyles);
  // ...
}
```

只需 inline 取色时用 `useColors()`(返回 `ColorTokens`),取阴影用 `useShadow()`(返回 `ShadowTokens`)。

**间距 / 圆角 / 字体 / 动效**:这些是静态 token,继续直接 import:

```tsx
import { space, radius, type as t, fw, fontMono, motion } from '@unif/react-native-design';
```

### 对照速查 {#对照速查}

| 旧写法(已删除) | 新写法(正确) |
|---|---|
| `import { colors } from '@unif/react-native-design'` | `const c = useColors()` |
| `import { shadow } from '@unif/react-native-design'` | `const s = useShadow()`,或 maker 第二参 `(c, s) => ...` |
| `colors.primary` / `colors.surface` / `colors.foreground` | `c.primary` / `c.surface` / `c.foreground` |
| `shadow.brandLg` | `...s.brandLg`(spread 进 StyleSheet) |
| 顶层 `StyleSheet.create({ ... colors.x ... })` | `useThemedStyles(maker)` 运行期 |

### 旧 token 名 → 新 role 名 {#旧-token-名--新-role-名}

历史代码里若残留旧的强度档命名,grep 替换为 role 名:

| 旧 | 新 |
|---|---|
| `colors.bgPage` | `c.background` |
| `colors.bgCard` | `c.surface` |
| `colors.bgInput` | `c.surfaceContainer` |
| `colors.bgMuted` | `c.surfaceContainerHigh` |
| `colors.bgPill` | `c.surfaceContainerHighest` |
| `colors.fg1` / `fg2` / `fg3` | `c.foreground` / `c.foregroundMuted` / `c.foregroundSubtle` |
| `colors.primary300` / `500` | `c.primary` / `c.primaryPressed` |
| `colors.primary0` / `50` | `c.primaryContainer` / `c.primaryContainerSubtle` |
| `colors.success300` / `successBg` | `c.success` / `c.successContainer` |
| `colors.error300` / `error0` | `c.error` / `c.errorContainer` |
| `colors.info300` / `infoBg` | `c.info` / `c.infoContainer` |
| `colors.border` / `borderSoft` / `borderFaint` | `c.outline` / `c.outlineVariant` / `c.outlineFaint` |

> 旧 `brandGradient` / `primary100/200/400/600` 等强度档已随死代码清理移除(0 消费方)。完整迁移表见[完整规范 → Migration map](/docs/unif-design)。

### 为什么不能继续用静态导出 {#为什么不能继续用静态导出}

`ThemeProvider` 读 `useColorScheme()` 动态算亮 / 暗,并以 `scheme` 为唯一 `useMemo` 依赖,把稳定的 `colors` / `shadow` 引用注入 Context。`useThemedStyles(maker)` 的 `useMemo([colors, shadow, maker])` 依赖这个引用 —— 静态顶层导出永远只有亮色值,亮暗切换对它无效。

---

## 版本升级注意事项 {#版本升级注意事项}

### 0.6.0：移除 BottomSheet / Confirm（去 @gorhom） {#0-6-0}

0.6.0 起移除了 `BottomSheet` 与 `Confirm` 组件、去掉 `@gorhom/bottom-sheet` 依赖 —— 设计系统不再内置 sheet / 命令式弹层实现，交由消费方按导航与交互需求自选：

```tsx
// ❌ 0.6.0 已移除，不再从包根导出
import { BottomSheet, confirm } from '@unif/react-native-design';
```

迁移建议：

- **底部 sheet / 弹层** → 用 React Navigation 的 `presentation: 'formSheet'`（原生 sheet，系统接管手势 / 动画 / 变暗），或自持 sheet 容器。
- **命令式确认** → 自持 `confirm()`（pub/sub + RN `Modal`），或用 `Alert.alert`。

同时 `Toast` 新增 `position`（`'top' | 'bottom' | 'center'`，默认 `'bottom'`），详见 [Toast](/docs/components/toast)。

### 升级 react-native-reanimated 4.x {#升级-reanimated-4}

Reanimated 4 使用新的 worklet 插件 `react-native-worklets/plugin` 替代旧的 `react-native-reanimated/plugin`。`babel.config.js` 里 worklets 插件**必须排在 plugins 数组最后**:

```js
// babel.config.js
module.exports = {
  plugins: [
    // ... 其它插件
    // worklets 插件必须最后
    'react-native-worklets/plugin',
  ],
};
```

## AI Skill

*Source: `docs/skills.md` · Slug: `/skills`*

# AI Skill：unif-design

## 这是什么

`unif-design` 是一个 **Agent Skill**,教 AI 编码助手(Claude Code / Cursor / Codex)正确调用 `@unif/react-native-design` 的 API、避免常见幻觉。

它把这个设计系统的关键约定、易错点和参考索引打包给 AI,让助手在你的项目里写代码时按真实 API 来,而不是凭记忆瞎猜。

## 覆盖什么

**何时会触发:** 用 `@unif/react-native-design` 搭任何 UI——按钮 / 卡片 / 列表 / 表单 / 弹窗 / 头像 / 标签,套颜色 token、用 `useColors` / `useThemedStyles`、主题切换、a11y。

**覆盖的能力:**

- 组件 API、props、variant、size(按需 fetch 远程 llms.txt,不靠记忆)。
- 颜色 token 规则:`useColors()` 角色 token、颜色优先级链、绝不内联 hex/rgba。
- 主题化样式:`useThemedStyles` + 模块顶层 `makeStyles`、shadow `...s.brandLg`。
- 与原生 RN 的关键差异(如 RNGH `Pressable`)、a11y 必填项、`createLogger` 取代 console。

> 拍照 / 扫码 / 分享各有专门 skill(camera / hms-scan / umeng),不在本 skill 范围内。

## 如何安装

**Claude Code 插件市场:**

```bash
/plugin marketplace add unif-design/skills
/plugin install unif@unif-skills
```

**或用 skills CLI:**

```bash
npx skills add unif-design/skills
```

## 在 GitHub 查看

skills 全部开源,发布在插件市场仓库 `unif-design/skills`。本 skill 的源码与参考文档:

👉 **[github.com/unif-design/skills · unif-design](https://github.com/unif-design/skills/tree/main/skills/unif-design)**

---

装了之后,在你的项目里让 AI 写 `@unif/react-native-design` 代码会更准。

## 常见问题

*Source: `docs/troubleshooting.md` · Slug: `/troubleshooting`*

# 常见问题

按**症状 → 原因 → 解法**排查。多数问题集中在「peer 缺失」「颜色没走 token / 主题不切」「web 环境特性」三类。

---

## Web / 文档站 {#web--文档站}

### 症状:LiveDemo 里 Button / Cell 点击无响应 {#rngh-pressable-web-点击无响应}

**原因。** `react-native-gesture-handler` 的 `Pressable` 在 `react-native-web` 运行时不触发 `onPress` —— RNGH 依赖原生手势驱动,浏览器里不存在。

**解法。** 文档站 webpack 插件(`website/src/plugins/docusaurus-rnw/index.js`)用 `NormalModuleReplacementPlugin` 把 RNGH 的 `Pressable` 替换成 `react-native-web` 原生 `Pressable`。如果你改了插件或引入新的 Pressable 来源,确保替换规则覆盖到新路径。

> 业务侧(真机)恰恰相反:可点区域要用 **RNGH 的 `Pressable`**,RN 原生 `Pressable` 在 web 上才不触发 `onPress`。

---

### 症状:含动画的页面在文档站崩溃 / 白屏 {#useanimatedstyle--layout-动画在文档站崩溃}

**原因。** `react-native-reanimated` 的 worklet 转换在 web 运行时不完整,`useAnimatedStyle` 等 API 在 `react-native-web` 下无法正常运行。

**解法。** 所有脉冲 / 渐入 / Layout 动画通过 design 包内的 web 特化实现(`usePulse.web` + `Reveal`)统一处理。消费方**不要在文档站 MDX 里直接用 `useAnimatedStyle`** —— 用 `<Pulse>` / `usePulse` / `<Reveal>` 这些已收口的封装(见[动效](/docs/design/tokens/motion#进出过渡))。

---

## 样式 / 主题 {#样式--主题}

### 症状:主题切换后样式没变 / `useThemedStyles` 每次都重算 {#usethemedstyles-缓存不生效}

**原因。** `makeStyles` 函数写在了组件函数体内(内联),每次渲染都是新引用,打穿 `useMemo([colors, shadow, maker])` 缓存。

**解法。** `makeStyles` 定义在**模块顶层**(通常从 `styles.ts` 导出):

```tsx
// ❌ Incorrect:makeStyles 内联在组件里 —— 每次渲染新引用,缓存失效
function MyComponent() {
  const makeStyles = (c: ColorTokens) => StyleSheet.create({ /* ... */ });
  const styles = useThemedStyles(makeStyles);
}

// ✅ Correct:makeStyles 在模块顶层
const makeStyles = (c: ColorTokens) => StyleSheet.create({ /* ... */ });

function MyComponent() {
  const styles = useThemedStyles(makeStyles);
}
```

---

### 症状:暗色模式下颜色不对,与设计稿不符 {#暗色颜色错乱}

**原因。** 颜色硬编码成 hex / rgba,只有亮色值,不随主题切换。

**解法。** 用 `useColors()` 返回的 role token(`c.primary` / `c.surface` / `c.foreground`…),不要内联 `#EB6E00` 或 `rgba(...)`。仅视觉锁定(QR 白卡 / 固定商标色)时允许硬编码,且必须加注释说明锁定理由。取色规则见[颜色 → 取色优先级链](/docs/design/tokens/colors#取色优先级链)。

---

### 症状:缺 ThemeProvider 时颜色还能出(但不切暗色) {#缺-themeprovider}

✅ **这是预期兜底,不是 bug。** `useTheme()` 在没有 `ThemeProvider` 时 fallback 到亮色(`lightColors` / `lightShadow`),保证组件不崩。但这样**不会跟随系统暗色**。正确做法是按[快速开始 → 根挂 ThemeProvider](/docs/getting-started#根挂-themeprovider) 在 App 根挂一次。

---

## Peer Dependencies {#peer-dependencies}

### 症状:启动 Metro / 构建报 `Unable to resolve module ...` / `Cannot find module ...` {#peer-缺失}

**原因。** peerDeps **缺一即崩**,本库不打包它们。

**解法。** 按[快速开始 → 安装依赖](/docs/getting-started#安装依赖)逐一装齐:

```sh
yarn add react-native-svg \
  react-native-gesture-handler \
  react-native-reanimated \
  react-native-worklets \
  react-native-safe-area-context \
  react-native-reanimated-carousel \
  @sbaiahmed1/react-native-blur
```

iOS 装完还需 `cd ios && bundle exec pod install`。

---

### 症状:iOS 构建失败 `Undefined symbols for architecture arm64` {#ios-链接错误}

**原因。** 装 / 升级原生包后没重新 `pod install`,或 peer 没装齐。

**解法。** 确认 peer 全部安装,然后重装 pods 并 clean build:

```sh
cd ios && bundle exec pod install --repo-update
# 再 Xcode → Product → Clean Build Folder 后重新构建
```

---

> 没覆盖到的问题:对照[设计令牌](/docs/design/tokens/colors)核对 token 名,或按需 fetch 远程 [llms.txt](https://unif-design.github.io/react-native-design/llms.txt) 查逐组件 API。