# Unif Design

> Unif Design 文档索引。每个链接是该页的纯 Markdown 版(供 LLM 抓取);需要完整全文一次性喂入时用 /llms-full.txt。

## 概览

- [完整规范](/md/UNIF-DESIGN.md) — Unif Design 单文件设计宪法：品牌 / voice / 5 原则 / role-based token（颜色·字体·间距·圆角·阴影·动效）/ 图标 / 组件库 / Don'ts / RN 落地图。所有 token 值取自 src/theme，是 llms-full 的全量锚点。
- [快速开始](/md/getting-started.md) — 5 分钟上手 @unif/react-native-design：装 peerDeps、根挂 ThemeProvider、用 useColors / useThemedStyles 写第一个主题化组件。面向 RN 0.85 新架构。
- [升级 / 迁移](/md/migration.md) — @unif/react-native-design 迁移指南：旧顶层 colors / shadow 静态导出 → 运行期 useColors() / useThemedStyles() hook（含旧 token → 新 role grep 对照），reanimated 4 升级，以及 0.6.0 移除 BottomSheet / Confirm。
- [AI Skill](/md/skills.md) — unif-design 是一个 Agent Skill,教 AI 编码助手正确调用 @unif/react-native-design 的 API、避免常见幻觉。
- [常见问题](/md/troubleshooting.md) — @unif/react-native-design 排障决策树（症状 → 因 → 解）：Web / 文档站点击无响应与动画崩溃、主题样式不切换 / useThemedStyles 缓存失效、peerDeps 缺失与 iOS 链接错误。

## components

- [AvatarWithRing 圆环头像](/md/components/avatar-with-ring.md) — 个人名片 hero 头像 —— 品牌橙渐变底 + 外圈 ring + 品牌橙 shadow，默认 64 直径，size / ringColor 可调。
- [Avatar 头像](/md/components/avatar.md) — 圆形 monogram 头像 —— brand / info / soft / neutral 四配色 × xs/sm/md/lg/xl 五档(18/28/32/40/56),支持图片 source 与加载失败回退 label。
- [BlurLayer 玻璃模糊层](/md/components/blur-layer.md) — BlurView + 颜色 tint 双层玻璃层 —— intensity soft(blur 10)/ strong(blur 40)，blurType 随亮 / 暗主题自动切换，纯装饰 pointerEvents='none'。
- [Button 按钮](/md/components/button.md) — 文本按钮 —— 7 variant(primary/secondary/ghost/neutral/outline/danger/text)× 3 size(sm/md/lg，高 28/36/44)，支持 block 块级、loading、leftIcon / rightIcon。
- [Card 卡片](/md/components/card.md) — 通用内容卡片 —— default(白底 + 卡片阴影)/ plain(仅圆角无阴影)，12px 圆角、14px padding，可加状态彩边 borderColor，bare 抑制内边距，fill 撑满 flex 父。
- [Carousel 轮播](/md/components/carousel.md) — 包装 react-native-reanimated-carousel 的薄壳轮播 —— 泛型 items、autoPlay、loop、内置 dot indicator(bottom / overlay-bottom-right)，条件性 a11y。
- [Cell · List 列表行](/md/components/cell.md) — 列表行 + List 容器 —— grouped(独立白卡 + 8px gap)/ flush(透明底 + 行间 hairline)两模式，leading / title / desc / extra / arrow 插槽，可点 onPress、danger 危险态。
- [Checkbox 复选框](/md/components/checkbox.md) — 受控多选框 —— 20×20 盒子，square / circle 两种形状，未选透明描边 / 已选主橙实心 + 白勾 / 禁用半透明，可选 label。
- [Chip 标签](/md/components/chip.md) — 胶囊形可点击 / 可选中 pill —— 默认白底细边 / 选中主橙边 + 浅橙底 / 按下半透明，支持 leading / trailing 插槽，Suggestion 与多选筛选的底层组件。
- [Confirm 确认对话框](/md/components/confirm.md) — 命令式 await confirm() → Promise<boolean> —— 高风险操作二次确认，ConfirmHost 裸 RN Modal 底部弹层（不依赖 @gorhom），destructive 红确认按钮，同一时间仅 1 个。
- [Decorations 装饰图元](/md/components/decorations.md) — 沉浸式屏 / hero 装饰原子(react-native-svg)—— GradientWash 线性渐变带、RadialHalo 径向光晕、ScreenBackdrop 整屏渐变 + halo 预设(warmOrange)，全 absolute 纯装饰不接管 hit area。
- [Empty 空态](/md/components/empty.md) — 空态 / 占位 —— 56×56 浅橙圆盘 + icon 插画(默认 spark)+ 大字标题 + 小字描述，icon 可换强语义图标(camera-off / permission-denied 等)。
- [EntryCard 入口卡](/md/components/entry-card.md) — 横向入口小卡 —— 左 30×30 灰底 icon tile + 右 title/sub，独立 surface 视觉(无 arrow / extra)，适合 grid 双列等宽入口，可点带按压态。
- [Form 表单](/md/components/form.md) — 表单容器三件套 Form / FormGroup / FormRow —— 白卡分组 + 行（label + 控件）+ 行间 hairline 分隔（表单不用 gap 的例外）。
- [GlassStats 玻璃数据条](/md/components/glass-stats.md) — 横向多列数据条，每格一个数字 + 标签；玻璃质感（BlurLayer backdrop + 半透白纱），数据用 [count, label] 元组、count 需预先格式化好再传入。
- [Grid 九宫格](/md/components/grid.md) — 图标入口宫格 —— 1..6 列（默认 4），每格 icon + label（+ 可选 badge 角标）；首页 / 分类落地页用，每格渲染为 accessibilityRole=\"button\"。
- [IconButton 图标按钮](/md/components/icon-button.md) — icon-only 方形按钮 —— size sm/md/lg（28/36/44）、variant 走 Button 同套 palette（默认 ghost）、accessibilityLabel TypeScript 强制必填。
- [图标](/md/components/icons.md) — 手绘 24×24 描边 SVG 图标系统 —— 统一绘制规则、IconName 字面量联合类型自动补全；<Icon> 刻意对屏幕阅读器隐藏，语义由承载它的可交互父组件提供。
- [Input 输入框](/md/components/input.md) — 单行文本输入框 —— 高 44（control.lg）、圆角 8、灰底无边框，4 视觉态 idle/focus/filled/error；InputProps = Omit<TextInputProps, style|multiline|numberOfLines> + leading/trailing/error/height/disabled/containerStyle。
- [Loading 加载](/md/components/loading.md) — 旋转加载指示器 Spinner —— size（默认 18，< 8 钳到 8）/ color（默认 c.primary）/ thickness（默认 2）；900ms 线性一圈，native 走 reanimated 4、web 走 CSS keyframes，刻意对屏幕阅读器隐藏。
- [Logo 主标](/md/components/logo.md) — 品牌主标容器组件 —— 标准化尺寸（默认 64）/ 圆角（默认 size/4 squircle）/ a11y（label 默认 'Logo'）；source 由 consumer 必传，组件本身不持有品牌资产。
- [NavBar 导航栏](/md/components/navbar.md) — 顶部导航栏 —— 44px 高、居中标题 + 可选副标题、左右槽（传 config 自动用 IconButton 渲染）；3 variant default（白底 hairline）/ brand（橙底白字）/ transparent（透明 + 深字，浮在浅色 hero 上）。
- [组件概览](/md/components/overview.md) — @unif/react-native-design 组件索引（40+ 组件，按场景分组：品牌 / 通用 / 表单 / 导航 / 反馈 / 数据展示 / 业务复合）。每个组件一页，逐组件 API 见各页与远程 llms.txt。
- [PasswordInput 密码输入框](/md/components/password-input.md) — 密码输入框 —— 内置 leading 锁图标 + trailing 眼睛切换明文/密文，showPw 内部 useState 自管，caller 只关心 value/onChangeText；不要传 secureTextEntry（组件自管会被覆盖）。
- [Pulse · PulseDot · usePulse](/md/components/pulse.md) — reanimated 4 worklet 通用脉冲原语 —— usePulse(opacity 循环 hook) + <Pulse>(包装组件) + <PulseDot>(默认 6×6 主橙圆点)；UI 线程驱动、不占 JS 桥，纯视觉对屏幕阅读器隐藏。
- [Radio 单选](/md/components/radio.md) — 单选控件 —— <Radio.Group value onChange> 包裹若干 <Radio value label>，同组只能选一个；20×20 圆，已选主橙描边 + 中心 8×8 主橙点，每项 accessibilityRole=\"radio\"。
- [Reveal](/md/components/reveal.md) — 内容入/出场淡入淡出容器 —— native 走 reanimated FadeIn/FadeOut layout 动画,web 自动切到 CSS transition 特化(RN-Web 上 reanimated layout 动画运行时会崩)。共享代码做进出过渡一律用它,不要直接写 FadeIn/FadeOut。
- [Search 搜索栏](/md/components/search.md) — Input 的搜索预设 —— 内置 leading search 图标 + 输入后 trailing 清除按钮、高 36、返回键为「搜索」；SearchProps = Omit<TextInputProps, style> + onSubmit / placeholder。
- [Skeleton 骨架屏](/md/components/skeleton.md) — 页面级加载占位骨架 —— shape='line'/'rect'/'circle' 三形态(默认 rect),width/height/size/radius 可覆盖；共享 usePulse opacity 脉冲(0.5↔1,半周期 700ms),对 SR 隐藏。
- [StatusDot 状态点](/md/components/status-dot.md) — status='pending'/'active'/'done'/'error' 状态圆点 —— done=success 底+白勾、error=error 底+白叉、active=primary 边框+内嵌 PulseDot、pending=outline 描边；tone='flat'(默认,透明底)/'soft'(柔色底),size 默认 16。
- [Stepper 步进器](/md/components/stepper.md) — 数字步进器 [−][N][+] —— 受控 value/onChange,自动夹到 [min,max](默认 0–99),step 默认 1,size='sm'(28px)/'md'(32px,默认),disabled;到达边界自动禁用对应按钮。
- [Switch 开关](/md/components/switch.md) — 布尔开关 —— 受控 value/onChange,32×20 轨道 + 16×16 白色把手,关 surfaceContainerHighest 底 / 开 primary 橙底,200ms 缓动;accessibilityRole='switch' + checked 上报,可选 disabled / accessibilityLabel。
- [TabBar 底部 tab 栏](/md/components/tabbar.md) — 固定底部主导航 tab 栏 —— 50px 高 + 顶部 hairline,各 tab icon+文字垂直居中,激活 c.primary;受控 active/onChange,items 含 id/icon/label/可选 badge,role='tab' + selected。
- [Tabs 标签页](/md/components/tabs.md) — 页面内分类切换 —— 下划线 Tabs(页面级,44px 高 + 2px 主色下划线)与分段控件 Segmented(局部灰底胶囊,size sm/md;md 默认 44px 触控达标 / sm 28px 紧凑);均受控 value/onChange + items(id/label),role='tab' + selected。
- [Tag 标签](/md/components/tag.md) — 纯展示状态标签 —— variant='neutral'(默认)/'brand'/'success'/'error'/'info'/'outline' 六种配色,size='md'(22h,默认)/'lg'(26h),label 必填,numberOfLines 默认 1 超长省略。
- [TextField 输入框 base(internal)](/md/components/text-field.md) — Input / Textarea / PasswordInput / Search 共享的内部 base(TextFieldBaseProps extends TextInputProps)—— 处理 4 态视觉、leading/trailing slot、error、disabled、单/多行;不在 barrel 导出,业务层请用 Input / Textarea / PasswordInput / Search。
- [Textarea 多行输入](/md/components/textarea.md) — 多行文本输入框 —— TextareaProps = Omit<TextInputProps,'style'|'multiline'|'numberOfLines'> + leading/trailing/error/minHeight(默认96)/maxHeight/disabled/containerStyle;内置 multiline + 顶对齐,复用 Input 的 idle/focus/filled/error/disabled 视觉。
- [Thumbnail 缩略图](/md/components/thumbnail.md) — 列表 / 卡片 / chat 通用 16:9.5 小图 —— size='sm'(64×40)/'md'(113×67,默认)/'lg'(160×96),uri 或 source 二选一(优先 uri),selected 加 2pt 品牌色 ring,无图返回 null;a11y 走可选 accessibilityLabel。
- [Toast 轻提示](/md/components/toast.md) — 命令式全局轻提示 —— toast(msg) / toast.success / .error / .info,或 {message,kind,duration};配根部挂一次 <ToastHost />,inverseSurface 底胶囊 + 可选状态点,默认 3000ms 后 fade+slide 自动消失,同时最多 1 条。
- [VersionPill 版本号药丸](/md/components/version-pill.md) — 版本徽章胶囊 —— 状态点 + 「版本 {version}」+ 可选「· build {build}」mono 后缀,hairline 描边圆角(radius.pill)胶囊;version 必填,statusColor 默认 c.success,可传 style。

## design

- [全局 Don'ts](/md/design/donts.md) — Unif Design 硬性禁忌清单：不引入新渐变 / 蓝色装饰 / 装饰 emoji / 英文 UI / 新字体；不破坏气泡内角方；不用 border-bottom；不硬编码 token；动效仅 fade + layout。
- [设计系统](/md/design/intro.md) — Unif Design 设计系统总览：品牌理念（中文优先、橙色克制、无装饰）、role-based token、组件视觉契约的入口；面向 React Native 0.85 新架构。
- [设计原则](/md/design/principles.md) — Unif Design 5 条不可违背的规则：中文优先、橙色克制、无装饰、列表用 gap 不用 border、气泡内角方。新增组件 / 改样式前必读。
- [颜色](/md/design/tokens/colors.md) — Unif Design 颜色 token：role-based 角色 token（c.primary / c.surface / c.foreground…），亮/暗各一套 hex，跟随系统切换；含取色优先级链与代码用法。
- [动效](/md/design/tokens/motion.md) — Unif Design 的 motion 时长 token（fast/base/slow/pulse）与动效约定：仅 fade + layout，走 reanimated 4 worklet，复用 usePulse / Pulse / Reveal。值取自 src/theme/tokens.ts。
- [间距 · 圆角 · 阴影](/md/design/tokens/spacing-radii-shadows.md) — Unif Design 的 space（4px 网格）/ radius（含气泡非对称圆角）/ shadow（themed，brandLg 等品牌光晕，暗色趋零）token，值取自 src/theme。
- [字体](/md/design/tokens/typography.md) — Unif Design 字体 token：type 字号阶梯 + fw 字重 + fontMono 等宽栈；仅系统字体（CJK 走 PingFang SC），不引入 webfont。值取自 src/theme/tokens.ts。
- [语调与文案](/md/design/voice.md) — Unif Design 文案规范：品牌大小写（Unif）、人称（AI / 我）、状态文案速查、建议 chip 语气、全角标点、禁用装饰 emoji。