# RUNDA ToC 组件库规范
> 配套文档：`DESIGN.md`（设计原则与令牌）、`design-tokens.json`（机器可读令牌）
> 本文档定义所有可复用组件的视觉、状态、尺寸、交互行为
---
## 0. 开发规范（必读）
**⚠️ 使用本组件库前必须遵循以下规则：**
1. **禁止重复造轮**
开发前先查阅本文档组件索引，确认是否有现成组件。已有组件禁止自定义实现。
2. **严格参考 Origin 视觉风格**
`design-system/Origin/` 包含 42 张 APP 实际截图，组件参数调整必须与截图保持一致。
3. **遵循组件规范**
组件的圆角、阴影、颜色、字体、间距已在本文档定义，禁止随意修改。
4. **完整开发流程与验收标准**
详见 **[`DEVELOPMENT-RULES.md`](./DEVELOPMENT-RULES.md)** — 包含组件选型流程、禁止行为清单、视觉验收流程。
---
## 组件库索引
| 分类 | 组件 |
|------|------|
| **基础** | Button、IconButton、Link、Tag/Chip、Badge、Divider、Avatar、AvatarGroup |
| **表单** | TextField、TextArea、SearchBar、Switch、Checkbox、RadioGroup、SegmentedControl、Slider、Stepper、Rate、FilterBar |
| **导航** | NavigationBar、TabBar、TabGroup、BackButton、Breadcrumb、Steps（水平步骤条）、Tabs Pill |
| **数据展示** | Card、ListItem、ChatBubble、Table、KeyValuePair、Timeline、CodeBlock、ProgressBar、ProgressRing、Accordion、SegmentedProgress、SwipeActions |
| **反馈** | Toast、Alert、ActionSheet、Modal、BottomSheet、Skeleton、Spinner、EmptyState、ErrorState、Tooltip、NotificationBanner、ContextMenu |
| **业务** | TaskCard、AgentMessage、StepIndicator、ToolCallCard、UploadCard、PlanCard、PricingCard |
| **信息展示** (v1.2) | MetricCard、GroupKPI、StatusBadge、InfoTable、AdviceTip、InfoCapsule、ShareCard、SectionTitle |
| **图表** (v1.3, ECharts; v1.4 移动端纯色) | LineChart、AreaChart、BarChart、RingProgress、StackedBar、MultiLine |
---
## 1. 基础组件
### 1.1 Button 按钮
#### 1.1.1 类型与视觉
| 类型 | 背景 | 文字 | 边框 | 用途 |
|------|------|------|------|------|
| **Primary** | `#2A7F8B` | `#FFFFFF` | 无 | 主 CTA（每屏最多 1 个） |
| **Secondary** | `#27272A` | `#FFFFFF` | 无 | 次要操作 |
| **Outline** | 透明 | `#FFFFFF` | `rgba(255,255,255,0.16)` 1pt | 三级操作 |
| **Ghost** | 透明 | `rgba(255,255,255,0.7)` | 无 | 文字按钮 |
| **Danger** | `#D83226` | `#FFFFFF` | 无 | 危险操作（删除） |
| **Gradient** | `linear-gradient(#2A7F8B, #37A0AE)` | `#FFFFFF` | 无 | 高级功能/订阅 |
#### 1.1.2 尺寸
| 尺寸 | 高度 | 内边距 | 字号 | 圆角 | 图标 |
|------|------|--------|------|------|------|
| **xs** | 28pt | 12pt × 4pt | 12pt | 8pt | 12pt |
| **sm** | 36pt | 16pt × 8pt | 14pt | 10pt | 16pt |
| **md** | 44pt | 24pt × 12pt | 16pt | 12pt | 20pt |
| **lg** | 52pt | 24pt × 14pt | 17pt | 12pt | 20pt |
| **xl** | 60pt | 32pt × 18pt | 18pt | 16pt | 24pt |
| **pill** | 40pt | 20pt × 10pt | 14pt | 9999pt | 16pt |
#### 1.1.3 状态
```
Default → Hover → Pressed → Loading → Disabled
```
| 状态 | Primary 表现 | 通用规则 |
|------|-------------|---------|
| Default | `#2A7F8B` 实色 | — |
| Hover (iPad) | 亮度 +8% | 透明度 +0.08 蒙层 |
| Pressed | 亮度 -10%，缩放 0.96 | 100ms 反馈 |
| Loading | 显示 Spinner，禁用点击 | 文字隐藏，三星脉冲动画（参见 5.7 Spinner） |
| Disabled | 透明度 0.38，不可交互 | — |
#### 1.1.4 排列规则
- **图标 + 文字**：图标在左
- **多按钮组**：水平间距 12pt；满宽场景用「次要 / 主」从左到右
- **垂直堆叠**：主按钮在上，次按钮在下，间距 8pt
- **底部固定按钮**：高度 52pt，距底部 16pt + 安全区 34pt
---
### 1.2 IconButton 图标按钮
| 尺寸 | 触摸区 | 图标 | 圆角 | 用途 |
|------|--------|------|------|------|
| sm | 32×32pt | 16pt | 8pt | 内嵌操作 |
| md | 44×44pt | 20pt | 12pt | 导航栏、卡片操作 |
| lg | 56×56pt | 24pt | full | 浮动操作按钮 (FAB) |
- **背景**：默认透明，按压时 `rgba(0,0,0,0.04)`
- **FAB**：蓝色实底 + glow 阴影，置于右下 16pt+34pt 安全区上方
---
### 1.3 Tag / Chip 标签
| 类型 | 背景 | 文字 | 用途 |
|------|------|------|------|
| Default | `rgba(0,0,0,0.05)` | `rgba(26,26,26,0.65)` | 普通标签 |
| Accent | `rgba(42,127,139,0.10)` | `#1D6770` | 选中/活跃 |
| Success | `rgba(40,138,92,0.10)` | `#288A5C` | 成功状态 |
| Warning | `rgba(242,173,12,0.12)` | `#C68F10` | 警告状态 |
| Error | `rgba(216,50,38,0.08)` | `#D83226` | 错误状态 |
- **尺寸**：高度 24pt 或 28pt，内边距 12pt × 6pt
- **圆角**：full（胶囊）
- **字号**：12pt（caption1）
- **可关闭**：右侧加 12pt × 关闭图标，间距 4pt
- **可选中**：选中时背景变 Accent 类型，未选保持 Default
---
### 1.4 Badge 徽章
| 类型 | 表现 |
|------|------|
| **Dot** | 8×8pt 红色圆点，无文字 |
| **Number** | 高度 16pt，最小宽度 16pt，背景 `#D83226`，白字 11pt，圆角 full |
| **Text** | 高度 18pt，背景按状态色，圆角 full，padding 6pt |
- **位置**：相对于父元素右上角偏移 -4pt × -4pt
- **数字超过 99 显示 99+**
---
### 1.5 Avatar 头像
| 尺寸 | 直径 | 字号 | 用途 |
|------|------|------|------|
| xs | 24pt | 10pt | 列表内嵌 |
| sm | 32pt | 12pt | 评论 |
| md | 40pt | 14pt | 默认 |
| lg | 56pt | 20pt | 个人主页 |
| xl | 80pt | 28pt | 资料页 |
- **形状**：始终圆形（border-radius full）
- **图片**：使用 cover 裁剪
- **占位**：首字母大写 + 随机颜色（从 8 色色板取）
- **边框**：在线状态 2pt 白边 + 右下绿点
---
### 1.6 Divider 分割线
| 类型 | 表现 | 用途 |
|------|------|------|
| Hairline | 0.5pt `rgba(0,0,0,0.08)` | 列表项之间 |
| Regular | 1pt `rgba(0,0,0,0.08)` | 区块之间 |
| Strong | 1pt `rgba(0,0,0,0.16)` | 强分隔 |
| Section Gap | 8pt 无线 + 8pt | 视觉分组 |
---
## 2. 表单组件
### 2.1 TextField 单行输入
```
┌────────────────────────────────────┐
│ Label (可选, 13pt, 次要色) │
│ ┌──────────────────────────────┐ │
│ │ [icon] Placeholder... [×] │ │ ← 高度 48pt
│ └──────────────────────────────┘ │
│ Helper text (可选, 12pt) │
└────────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 高度 | 48pt（标准）/ 56pt（大） |
| 内边距 | 16pt × 12pt |
| 圆角 | 12pt |
| 背景 | `#F4F4F5`（在白色页面）/ `#FFFFFF`（在灰色卡片内） |
| 边框 | 默认 1pt `rgba(0,0,0,0.08)`；focus 时 `#2A7F8B` 1.5pt |
| 字号 | 16pt（防 iOS 缩放） |
| 占位文字 | `#A1A1AA` |
| 图标 | 左侧前缀 20pt，右侧清除按钮 16pt |
#### 状态
| 状态 | 边框 | 文字 |
|------|------|------|
| Default | 无 | — |
| Focus | 1.5pt `#2A7F8B` | — |
| Filled | 无 | `#18181B` |
| Error | 1.5pt `#D83226` | helper 变红 |
| Disabled | 无，背景 `rgba(0,0,0,0.03)` | 透明度 0.38 |
| Read-only | 无 | 文字 `rgba(26,26,26,0.65)` |
---
### 2.2 TextArea 多行输入
- 同 TextField，但**最小高度 96pt**，**最大高度 240pt**（超出滚动）
- **自动增高**：随内容增长，超过最大值后内部滚动
- **字数计数**：右下角 `当前/最大`，超限变红
---
### 2.3 SearchBar 搜索框
```
┌──────────────────────────────────┐
│ 🔍 搜索... [×] │ ← 40pt 高，圆角 full
└──────────────────────────────────┘
```
- **高度** 40pt，**圆角 full**，背景 `rgba(0,0,0,0.05)`
- **左侧图标** 16pt 搜索图标，间距 12pt
- **取消按钮**（聚焦后出现）：右侧出现「取消」文字按钮，蓝色，12pt 间距
- **历史记录**：聚焦时下拉显示最近 5 条
---
### 2.4 Switch 开关
| 属性 | 值 |
|------|-----|
| 尺寸 | 51 × 31pt（iOS 标准） |
| 圆角 | full |
| 关：背景 | `rgba(0,0,0,0.12)` |
| 开：背景 | `#2A7F8B` |
| 滑块 | 27pt 圆，白色，阴影 sm |
| 切换时长 | 200ms easeInOut |
| 触觉 | 切换时 `selection` haptic |
---
### 2.5 Checkbox 复选框
| 状态 | 表现 |
|------|------|
| 未选 | 1.5pt `rgba(0,0,0,0.25)` 描边，背景透明 |
| 选中 | `#2A7F8B` 实底 + 白色 ✓ 图标 |
| 半选 | `#2A7F8B` 实底 + 白色横线 |
| 禁用 | 透明度 0.38 |
- **尺寸**：20×20pt，圆角 4pt
- **触摸区**：扩展至 44×44pt
- **与文字间距** 12pt
---
### 2.6 RadioGroup 单选组
- **单个圆点**：20pt 直径，1.5pt 描边
- **选中**：外圈蓝色描边 + 内部 10pt 实心蓝圆
- **垂直排列**：项间距 12pt
- **水平排列**（少于 4 项）：使用 SegmentedControl 替代
---
### 2.7 SegmentedControl 分段控制器
```
┌──────────────────────────────────┐
│ ┌───────┐ │
│ │ 选项A │ 选项B 选项C 选项D │ ← 高度 32pt
│ └───────┘ │
└──────────────────────────────────┘
```
- **容器**：背景 `rgba(0,0,0,0.05)`，圆角 9pt
- **选中段**：背景 `#FFFFFF`，圆角 7pt，阴影 sm
- **文字**：13pt 中性；选中后 600 字重
- **切换动画**：滑块 250ms easeInOut
---
### 2.8 Slider 滑块
- **轨道**：高度 4pt，背景 `rgba(0,0,0,0.10)`，已选部分 `#2A7F8B`
- **滑块**：24pt 直径，白色实心，阴影 md
- **拖动区**：扩展至 44pt 高度
- **气泡提示**（拖动中）：滑块上方显示当前值，背景 `#18181B`（深色），白字，箭头朝下
---
## 3. 导航组件
### 3.1 NavigationBar 导航栏
```
┌──────────────────────────────────┐
│ ← Back 标题 Action │ ← 44pt
└──────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 高度 | 44pt（不含状态栏） |
| 背景 | 滚动前透明；滚动后 `#FFFFFF` + 1pt 底边 `rgba(0,0,0,0.08)` |
| 标题字号 | 17pt Semibold（小）/ 28pt Bold（大标题） |
| 返回按钮 | 28pt 触摸区，箭头 16pt + 文字（可选） |
| 右侧操作 | 最多 2 个 IconButton 或 1 个文字按钮 |
#### Large Title 模式（iOS 11+）
- **未滚动时**：标题 28pt，紧贴左边 16pt，下方占据 52pt 高
- **滚动时**：渐隐变为 17pt 居中，导航栏出现底边
---
### 3.2 TabBar 标签栏
```
┌──────────────────────────────────┐
│ ▢ ▢ ● ▢ │ ← 49pt
│ 首页 任务 创建 设置 │
└──────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 高度 | 49pt + 安全区 34pt |
| 背景 | `rgba(255,255,255,0.95)` 模糊背景（毛玻璃） |
| 顶部边框 | 0.5pt `rgba(0,0,0,0.08)` |
| 图标 | 24pt 线性（默认）/ 实心（选中） |
| 文字 | 10pt，距图标 4pt |
| 默认色 | `rgba(26,26,26,0.45)` |
| 选中色 | `#2A7F8B` |
| 中央创建按钮 | 56pt 圆形，蓝色实心，glow 阴影，居中向上偏移 4pt |
| 切换 | 无动画，立即响应 + 触觉反馈 |
---
### 3.3 TabGroup 顶部 Tab 组
```
┌──────────────────────────────────┐
│ 全部 进行中 已完成 草稿 │
│ ─── │ ← 选中下划线 2pt 蓝色
└──────────────────────────────────┘
```
- **高度** 44pt
- **下划线** 2pt `#2A7F8B`，宽度 = 文字宽度
- **文字**：默认 15pt 次要色，选中 15pt 600 主色
- **滑动指示器**切换：250ms easeOut
- **横向滚动**：超过 4 项时可横向滚动
---
## 4. 数据展示组件
### 4.1 Card 卡片
| 属性 | 值 |
|------|-----|
| 背景 | `#FFFFFF` |
| 圆角 | 16pt |
| 内边距 | 16pt 四周 |
| 边框 | 1pt `rgba(0,0,0,0.06)` + 阴影 sm |
| 卡片间距 | 12pt（垂直） |
| 标题 | 17pt Semibold |
| 副标题 | 13pt 次要色 |
#### 卡片变体
| 变体 | 特性 |
|------|------|
| **Default** | 标准卡片 |
| **Selectable** | 可点击，按压时缩放 0.98 |
| **Outlined** | 透明背景 + 1pt 边框 |
| **Highlighted** | 左侧 3pt 蓝色装饰条 |
| **Image Header** | 顶部 16:9 封面图，图与内容圆角连续 |
---
### 4.2 ListItem 列表项
```
┌──────────────────────────────────┐
│ [图标] 主标题 [操作] │
│ 副标题/描述 │ ← 高度 56-72pt
└──────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 最小高度 | 56pt |
| 双行高度 | 72pt |
| 内边距 | 16pt × 12pt |
| 左侧图标 | 24pt，距文字 12pt |
| 主标题 | 17pt Regular |
| 副标题 | 13pt 次要色，距主标题 2pt |
| 右侧 | 文字（次要色 15pt）/ Switch / 箭头 ›（16pt） |
| 分隔线 | 左 56pt 起 0.5pt |
| 按压态 | 背景 `rgba(0,0,0,0.03)` |
---
### 4.3 ChatBubble 聊天气泡
> 参考豆包/元宝等主流 AI 对话产品：用户消息用卡片模块包裹，模型回复直接显示在背景上（无气泡包裹、无头像）。
#### 对话区域容器
| 属性 | 值 |
|------|-----|
| 背景 | `#FAFAFA` + 点状纹理（与全局背景一致） |
| 纹理 | `radial-gradient(rgba(0,0,0,0.018) 1px, transparent 1px)` 3px×3px |
| 消息间距 | 16pt |
| 内边距 | 16pt |
#### 用户消息（右对齐，卡片包裹）
| 属性 | 值 |
|------|-----|
| 背景 | `#FFFFFF` |
| 文字 | `#18181B` 15pt |
| 圆角 | 16pt |
| 内边距 | 12pt × 16pt |
| 边框 | 1pt `rgba(0,0,0,0.08)` |
| 阴影 | sm |
| 最大宽度 | 屏宽的 80% |
| 对齐 | 右对齐 |
#### Agent 消息（左对齐，无气泡包裹）
| 属性 | 值 |
|------|-----|
| 背景 | 无（透明，直接显示在对话区域纹理背景上） |
| 文字 | `#18181B` 15pt，行高 1.6 |
| 内边距 | 4pt × 0 |
| 最大宽度 | 屏宽的 90% |
| 头像 | 无 |
#### 时间戳与状态
- 时间戳 11pt 次要色，居中显示在消息组之上，间隔超过 5 分钟才显示
- 已读/已发状态在用户消息右下角 11pt
- 流式输出：底部显示「⋯」三点闪烁动画（500ms 间隔）
---
### 4.4 CodeBlock 代码块
```
┌──────────────────────────────────┐
│ python [复制] │ ← 头部 32pt
├──────────────────────────────────┤
│ def hello(): │
│ print("hi") │ ← 内容区
└──────────────────────────────────┘
```
- **背景**：`#F4F4F5`
- **圆角**：12pt
- **头部高 32pt**：左侧语言 12pt 次要色，右侧复制按钮
- **内容**：SF Mono 14pt，行高 20pt
- **横向滚动**：内容溢出时
- **语法高亮**：关键字 `#DC9418`、字符串 `#288A5C`、注释 `rgba(26,26,26,0.4)`
---
### 4.5 ProgressBar 进度条
| 属性 | 值 |
|------|-----|
| 高度 | 4pt（细）/ 8pt（粗） |
| 圆角 | full |
| 轨道 | `rgba(0,0,0,0.08)` |
| 进度 | `#2A7F8B` |
| 标签 | 上方 12pt 次要色 |
| 百分比 | 右侧 12pt 次要色 |
| 动画 | 600ms easeOut |
| 不确定态 | 30% 宽度蓝色块往复滑动 1500ms |
---
### 4.6 ProgressRing 进度环
- **尺寸**：32pt / 48pt / 64pt / 96pt
- **描边宽度**：尺寸 / 8（如 48pt 用 6pt 描边）
- **轨道色**：`rgba(0,0,0,0.08)`
- **进度色**：`#2A7F8B`
- **起点**：顶部 12 点钟方向
- **方向**：顺时针
- **中央内容**：百分比数字（Title 3）
---
### 4.7 Timeline 时间线
```
●─── 步骤 1：理解任务 (已完成 #288A5C)
│
●─── 步骤 2：搜索资料 ⋯ (进行中 #2A7F8B 脉冲)
│
○─── 步骤 3：生成报告 (待执行 灰色)
```
- **节点直径**：12pt
- **连接线**：2pt 居中对齐
- **节点状态**：完成（实心绿）/ 进行中（实心蓝 + 1.5x 放大脉冲）/ 待执行（空心灰）
- **节点与文字间距**：12pt
- **行高**：48pt
---
## 5. 反馈组件
### 5.1 Toast 通知
```
┌──────────────────────────────────┐
│ ✓ 操作成功 │ ← 距顶 16pt+59pt
└──────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 位置 | 顶部安全区下 16pt |
| 宽度 | 屏宽 - 32pt（左右各 16pt） |
| 高度 | 自适应，最小 48pt |
| 内边距 | 16pt × 12pt |
| 背景 | `#FFFFFF` |
| 圆角 | 12pt |
| 阴影 | md |
| 图标 | 20pt，左侧，按类型染色 |
| 文字 | 15pt 主色 |
| 持续时间 | 成功 2s / 错误 4s |
| 进入 | 250ms 从顶部滑入 + 淡入 |
| 退出 | 200ms 向上滑出 + 淡出 |
| 手势 | 上滑可主动关闭 |
#### 类型
| 类型 | 图标色 |
|------|--------|
| Success | `#288A5C` ✓ |
| Error | `#D83226` ⚠ |
| Warning | `#F2AD0C` ⚠ |
| Info | `#2272C3` ⓘ |
---
### 5.2 Alert 警告框
- **遮罩**：`rgba(0,0,0,0.6)`
- **容器**：宽 270pt，背景 `#FFFFFF`，圆角 14pt
- **结构**：标题（17pt 600） + 描述（13pt 次要） + 按钮组
- **按钮**：横向并排（最多 2 个）/ 纵向堆叠（3 个+）
- **分隔**：按钮间 0.5pt `rgba(0,0,0,0.12)`
- **危险按钮**：文字 `#D83226`
- **进入**：300ms spring，缩放 0.85→1
- **退出**：200ms easeIn，淡出
---
### 5.3 ActionSheet 操作菜单
- **从底部弹出**
- **背景** `#FFFFFF`，顶部圆角 24pt
- **每项**：高 56pt，居中文字 17pt
- **危险项**：红色文字
- **分组**：组间 8pt 间距 `#F4F4F5`
- **取消按钮**：分离的独立卡片，距上 8pt
- **底部安全区** 34pt
- **遮罩**：点击关闭
---
### 5.4 BottomSheet 底部抽屉
```
┌──────────────────────────────────┐
│ ▬▬▬▬ │ ← 把手 36×4pt
│ 标题 [×] │
│ ──────────────────────────── │
│ │
│ 内容区（可滚动） │
│ │
└──────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 顶部圆角 | 24pt |
| 把手 | 36×4pt 圆角 full，`rgba(0,0,0,0.15)`，距顶 8pt |
| 高度档位 | 25% / 50% / 90% |
| 拖动 | 支持上下拖动切换档位 |
| 关闭手势 | 下拉超过 100pt 关闭 |
| 遮罩 | `rgba(0,0,0,0.5)`，根据高度档位渐变 |
| 进入 | 350ms spring |
---
### 5.5 Modal 弹窗
- **居中显示**，宽度屏宽 - 64pt（最大 327pt）
- **结构**：关闭按钮（右上 IconButton） + 标题 + 内容 + 操作按钮组
- **内边距** 24pt
- **圆角** 24pt
- **背景** `#FFFFFF`
- **进入** 300ms spring，缩放 0.9→1 + 淡入
---
### 5.6 Skeleton 骨架屏
- **基础**：圆角 8pt 矩形/圆形
- **背景**：`#F4F4F5`
- **闪烁**：1500ms 周期，gradient 从 `rgba(255,255,255,0.6)` 扫过
- **形状**：
- 文字行：高 12pt，宽随机 60-100%
- 标题：高 20pt，宽 40-60%
- 头像：圆形对应 Avatar 尺寸
- 卡片：高度匹配真实卡片
- **使用规则**：仅在首次加载使用，刷新使用 Spinner
---
### 5.7 Spinner 加载指示器
> 采用三星脉冲动效（`Loading.svg`），紫蓝渐变三星错峰缩放与透明度循环，替代传统转圈样式。
| 尺寸 | 画布 | 用途 |
|------|------|------|
| sm | 24×24 | 按钮内、行内 |
| md | 40×40 | 列表/卡片加载（默认） |
| lg | 64×64 | 全屏/区块加载 |
- **造型**：三颗星形（大/中/小）按布局错位排列
- **配色**：`#5266C5`（大）/ `#A855F7`（中）/ `#EC4899`（小）
- **动效**：
- 大星：1.733s 线性循环，scale 0.26→0.38，opacity 0.5→1.0
- 中星：1.733s 线性循环，延迟 -0.24s，scale 0.2→0.36，opacity 0.3→0.9
- 小星：1.067s 线性循环，scale 0.22→0.32，opacity 0.2→0.8
- **使用规则**：所有需要 Loading 状态的位置统一使用此动效（按钮、列表、全屏覆盖等）
---
### 5.8 EmptyState 空状态
```
┌──────────────────────────────────┐
│ ○ │ ← 插图 96pt
│ │
│ 暂无内容 │ ← Title 3
│ 创建第一个任务开始 │ ← 13pt 次要
│ │
│ [创建任务] │ ← 主按钮
└──────────────────────────────────┘
```
- **垂直居中**于剩余空间
- **插图** 96pt，单色线性图标，色 `rgba(255,255,255,0.3)`
- **标题** 17pt 600
- **描述** 13pt 次要色，最多 2 行
- **CTA**（可选）距描述 24pt
---
### 5.9 ErrorState 错误状态
- 同 EmptyState 结构，插图替换为错误图标（`#D83226`）
- 提供「重试」按钮（Outline 类型）
- 描述文字给出失败原因（网络/权限/服务）
---
## 6. 业务组件
### 6.1 TaskCard 任务卡片
```
┌──────────────────────────────────┐
│ [icon] 任务标题 │
│ 描述文字... │
│ │
│ ●───●───○───○ │ ← 步骤指示
│ 研究 规划 执行 完成 │
│ │
│ [Tag] [Tag] ⋯ 进行中 12:34 │
└──────────────────────────────────┘
```
| 区域 | 规则 |
|------|------|
| 容器 | 背景 `#18181B`，圆角 16pt，padding 16pt |
| 头部 | 24pt 类型图标 + 17pt 600 标题 |
| 描述 | 13pt 次要色，最多 2 行截断 |
| 步骤指示 | Timeline 横向变体 |
| 底部 | Tags（左） + 状态（中） + 时间（右） |
| 状态色 | 进行中蓝 / 完成绿 / 失败红 / 暂停灰 |
| 按压 | 缩放 0.98，背景 +5% 亮度 |
---
### 6.2 AgentMessage Agent 消息块
```
┌──────────────────────────────────┐
│ ◉ RUNDA 12:34 · 思考中 │ ← 头部
├──────────────────────────────────┤
│ ◐ 正在搜索 "...." │ ← 工具调用
│ ✓ 已读取 3 个网页 │
│ ◑ 生成回答中... │
│ │
│ 根据搜索结果... │ ← Markdown 内容
└──────────────────────────────────┘
```
- **头部**：24pt 头像 + 名称 17pt 600 + 时间 11pt 次要 + 状态
- **工具调用列表**：每行 32pt，前缀状态图标 16pt + 描述
- **状态图标**：进行中（蓝色脉冲圆）、完成（绿勾）、失败（红叉）
- **Markdown 渲染**：
- 段落 17pt，间距 12pt
- 列表项缩进 16pt
- 引用左侧 3pt 蓝色边
- 内联代码：`#27272A` 背景，圆角 4pt，padding 2pt × 6pt
- **流式光标**：蓝色 2px × 16px 矩形闪烁（500ms）
---
### 6.3 StepIndicator 步骤指示器
```
●━━━━●━━━━●━━━━○
1.开始 2.进行 3.审核 4.完成
```
- **节点**：16pt 圆，已完成（蓝实心+✓）/ 当前（蓝实心+白心）/ 未来（灰空心）
- **连接线**：2pt 高，已完成段蓝色，未来段灰色
- **节点间距**：均分剩余宽度
- **标签**：节点下方 8pt，字号 11pt
- **当前步骤标签**：蓝色 600 字重
---
### 6.4 ToolCallCard 工具调用卡片
```
┌──────────────────────────────────┐
│ 🔍 执行搜索 [展开] │ ← 头部 48pt
├──────────────────────────────────┤
│ query: "AI 设计系统" │ ← 参数（折叠态隐藏）
│ 返回: 23 条结果 │
└──────────────────────────────────┘
```
- **头部**：图标 + 工具名 + 状态徽章 + 展开/收起按钮
- **参数区**：背景 `#0F0F0F`（更深）、SF Mono 13pt、padding 12pt
- **状态徽章**：运行中蓝、成功绿、失败红，胶囊形
- **可点击展开/收起**，箭头 200ms 旋转
---
### 6.5 PricingCard 订阅套餐卡片
```
┌────────────────────────────────────┐
│ 推荐 │ ← 角标
│ ┌────────────────────────────────┐ │
│ │ RUNDA Pro │ │
│ │ │ │
│ │ ¥99 /月 │ │ ← 大金额
│ │ ¥1188 /年（节省 ¥120） │ │
│ │ │ │
│ │ ✓ 无限任务 │ │ ← 特权列表
│ │ ✓ 优先响应 │ │
│ │ ✓ 高级模型 │ │
│ │ │ │
│ │ [立即升级] │ │ ← Gradient 按钮
│ └────────────────────────────────┘ │
└────────────────────────────────────┘
```
- **推荐角标**：右上角，蓝色背景，白字 11pt 600，圆角 4pt
- **套餐名**：22pt 700
- **金额**：34pt 700，单位 13pt 次要色，紧贴金额，**字族 `display`（Manrope · Bold 700）**
- **特权列表**：✓ `#288A5C` 16pt + 文字 15pt，行间 12pt
- **CTA**：满宽 Gradient 按钮，52pt 高，glow 阴影
---
### 6.6 UploadCard 文件上传卡片
```
┌──────────────────────────────────┐
│ [📄] document.pdf [×] │
│ 2.4 MB · ✓ 已上传 │
│ ━━━━━━━━━━━━━━━━━━━━ 100% │
└──────────────────────────────────┘
```
- 高 72pt，圆角 12pt，背景 `#18181B`
- 左侧 40pt 文件类型图标（带渐变背景圆角 8pt）
- 文件名 15pt，限 1 行；副信息 12pt 次要色
- 进度条 2pt 高，圆角 full
- 状态：上传中（百分比+蓝）/ 完成（绿勾+绿条）/ 失败（红叉+红条+重试按钮）
- 删除按钮：右上 IconButton 16pt
---
## 7. 状态规范总览
### 7.1 通用交互状态
| 状态 | 触发 | 视觉 | 反馈 |
|------|------|------|------|
| Default | 静止 | 基础样式 | — |
| Hover | 指针悬停（iPad） | 透明蒙层 +0.08 | 100ms |
| Pressed | 按下未释放 | 缩放 0.96 + 亮度 -10% | 触觉 light |
| Focused | 键盘聚焦 | 2pt 蓝色描边 + 4pt 偏移 | — |
| Selected | 已选中 | 蓝色描边/背景 | 触觉 selection |
| Disabled | 不可用 | 透明度 0.38，禁用事件 | — |
| Loading | 异步处理 | 替换内容为 Spinner | — |
| Error | 校验失败 | 红色描边 + 错误文案 | 触觉 error |
### 7.2 数据加载状态
| 状态 | 表现 |
|------|------|
| **Initial** | 骨架屏 |
| **Loaded** | 正常内容 |
| **Empty** | EmptyState 组件 |
| **Error** | ErrorState + 重试按钮 |
| **Loading More** | 列表底部 Spinner（24pt） |
| **Refreshing** | 顶部下拉刷新指示器 |
| **Offline** | 顶部黄色横幅「网络离线」 |
---
## 8. 触觉反馈规范（Haptic）
| 类型 | iOS API | 使用场景 |
|------|---------|---------|
| Light | `impactOccurred(.light)` | 轻按、Tab 切换 |
| Medium | `impactOccurred(.medium)` | 删除、长按菜单弹出 |
| Heavy | `impactOccurred(.heavy)` | 重要操作确认 |
| Success | `notificationOccurred(.success)` | 操作成功 |
| Warning | `notificationOccurred(.warning)` | 危险确认 |
| Error | `notificationOccurred(.error)` | 操作失败 |
| Selection | `selectionChanged()` | 滚轮选择、Switch 切换 |
---
## 9. 组件组合规则
1. **同级原则**：同级组件使用相同尺寸（如同一卡片内的所有按钮均为 sm）
2. **嵌套规则**：内层圆角 = 外层圆角 - 内边距（如卡片 16pt + padding 8pt → 内层用 8pt）
3. **强调单点**：每屏仅 1 个 Primary 按钮 / 1 处蓝色焦点
4. **密度匹配**：信息密度高的列表用紧凑尺寸（sm），低密度用宽松（md）
5. **状态一致**：同一组件在所有页面状态表现一致，不局部魔改
---
## 10. 实施检查清单
### 视觉一致性
- [ ] 所有色值来自令牌表，无硬编码 HEX
- [ ] 所有间距为 4 的倍数
- [ ] 所有圆角使用语义令牌（不出现 6/10/15 等中间值）
- [ ] 字号严格使用 11 阶字号梯度
- [ ] 同级元素圆角/字号统一
### 交互完整性
- [ ] 所有按钮覆盖 Default/Pressed/Disabled/Loading 四态
- [ ] 异步操作有 Loading 反馈
- [ ] 错误情况有 ErrorState 和重试
- [ ] 列表覆盖 Empty/Loading/Loaded/Error 四态
- [ ] 重要操作有 Haptic 反馈
### 无障碍
- [ ] 触摸目标 ≥ 44×44pt
- [ ] 文字对比度 ≥ 4.5:1
- [ ] 状态不仅靠颜色（图标+文字）
- [ ] 支持 Dynamic Type
- [ ] 提供 VoiceOver 标签
### 性能
- [ ] 列表使用懒加载/虚拟滚动
- [ ] 图片使用合适尺寸（@2x/@3x）
- [ ] 动画 ≤ 600ms
- [ ] 骨架屏在 100ms 内出现
---
*下一轮交付：`design-preview.html` 自包含交互预览页（可在浏览器直接打开查看所有组件）*
---
## 11. 信息展示组件（v1.2.0 新增）
> 基于 `/Users/ying/Downloads/组件模块/` 21 张截图逆向提取，专为健康/数据类 C 端 APP 场景设计。所有组件遵循 RUNDA ToC Design System 规范。
### 11.1 MetricCard 健康指标卡片
单一健康指标的标准展示卡，含标题、数值、单位、趋势和元数据。
```
┌──────────────────────────────────┐
│ ❤ 血压 查看 › │
│ │
│ 128 / 82 mmHg ↑ 2% │
│ │
│ 较昨日 今日 09:23 │
└──────────────────────────────────┘
```
| 属性 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `title` | string | — | 指标名称（必填） |
| `icon` | SVG | — | 标题前线性图标，accent 色 |
| `value` | string\|number | — | 主数值（必填） |
| `unit` | string | — | 单位文字 |
| `trend` | `'up'\|'down'\|'flat'` | `flat` | 趋势方向 |
| `trendValue` | string | — | 趋势百分比文字 |
| `meta` | `{left, right}` | — | 底部元数据 |
| `onClick` | function | — | 点击回调 |
**视觉规则：**
- 容器：`#fff` + 1pt `#E4E4E7` 边框 + `shadow-sm`，圆角 16pt
- 内边距 16pt，垂直间距 10pt
- 数值字号 32pt 700，等宽数字（tabular-nums），**字族 `display`（Manrope · Bold 700）**
- 趋势徽章 12pt 600，up=绿、down=红、flat=灰
**示例代码（HTML）：**
```html
```
---
### 11.2 GroupKPI 多指标对比卡片
一个容器内并列展示 3 个相关 KPI，用不同色背景区分类型。
| 属性 | 类型 | 说明 |
|------|------|------|
| `title` | string | 卡片标题 |
| `items` | `KPIItem[]` | 3 个指标项 |
| `KPIItem.color` | `'blue'\|'orange'\|'amber'` | 主题色 |
| `KPIItem.value` | string\|number | KPI 数值 |
| `KPIItem.label` | string | KPI 标签 |
**视觉规则：**
- 外层卡片同 MetricCard
- 内部 3 列等宽网格，间距 8pt
- 每个 KPI 单元：12pt 内边距，12pt 圆角，背景为 alpha=0.08~0.12 的对应主题色
- 数值 24pt 600，标签 11pt secondary，**数值字族 `display`（Manrope · SemiBold 600）**
**色彩方案（来源自截图实测）：**
- Blue 数据：背景 `rgba(67,136,255,.08)` / 文字 `#4388FF`
- Orange 趋势：背景 `rgba(255,153,70,.10)` / 文字 `#FF9946`
- Amber 摄入：背景 `rgba(254,188,65,.12)` / 文字 `#E59100`
---
### 11.3 StatusBadge 健康状态徽章组
胶囊状的状态标识，含彩色圆点和文字。
| 状态 | 圆点色 | 背景色 | 文字色 | 用途 |
|------|--------|--------|--------|------|
| **excellent** | `#02955F` | `rgba(2,196,86,.10)` | `#02955F` | 优秀（健康指标达标） |
| **normal** | `#2D6CD9` | `rgba(67,136,255,.10)` | `#2D6CD9` | 正常（在范围内） |
| **attention** | `#B27800` | `rgba(254,188,65,.14)` | `#B27800` | 关注（轻微偏离） |
| **danger** | `#D83226` | `rgba(216,50,38,.10)` | `#D83226` | 异常（需就医） |
**尺寸：** 高度自动 ~22pt，内边距 5pt × 10pt，圆角 full，字号 12pt 600
```html
优秀
```
---
### 11.4 InfoTable 数据表格
紧凑型多列数据展示，表头浅蓝底，数据行交替背景。
| 属性 | 类型 | 说明 |
|------|------|------|
| `columns` | string[] | 列名数组 |
| `rows` | (string\|number)[][] | 数据行数组 |
| `accentCol` | number | 高亮列索引（蓝色加粗） |
**视觉规则：**
- 表头：背景 `rgba(67,136,255,.04)`，11pt 600，字间距 0.04em
- 单元格：12pt 内边距，13pt 字号，等宽数字
- 行交替：偶数行 `#FAFAFA`
- 高亮列：`#4388FF` 文字 + 600 字重
---
### 11.5 AdviceTip 策略提示带
绿色背景的健康建议提示带，含成功图标 + 标题 + 描述。
| 属性 | 类型 | 说明 |
|------|------|------|
| `title` | string | 建议标题（绿色 600） |
| `text` | string | 建议正文（最多 3 行） |
| `tone` | `'success'\|'info'\|'warning'` | 色调（默认 success） |
**视觉规则：**
- 容器：背景 `#EEFFF5` + 1pt `rgba(2,196,86,.20)` 边框，圆角 16pt
- 图标：28×28 圆形，`#02C456` 实底 + 白色勾
- 内边距 14pt × 16pt，gap 12pt
---
### 11.6 InfoCapsule 信息胶囊
行内嵌入的强调信息标签，通常带数值高亮。
```html
已连续记录 7 天
```
| 属性 | 值 |
|------|-----|
| 高度 | 自动（约 26pt） |
| 内边距 | 6pt × 12pt |
| 背景 | `#F5FAFF` |
| 边框 | 1pt `rgba(67,136,255,.20)` |
| 圆角 | full |
| 字号 | 12pt 文字 / 12pt 600 数值 |
| 颜色 | 文字 `#2D6CD9` / 数值 `#4388FF` |
---
### 11.7 ShareCard 分享卡片
横向布局的功能入口卡，左侧黑色图标 + 标题描述 + 右侧动作。
| 属性 | 类型 | 说明 |
|------|------|------|
| `icon` | SVG | 左侧 20pt 图标 |
| `title` | string | 主标题 14pt 600 |
| `subtitle` | string | 副标题 12pt tertiary |
| `action` | string | 右侧动作文字（accent 色） |
| `onClick` | function | 点击整卡触发 |
**视觉规则：**
- 容器：白底 + 1pt 边框 + `shadow-sm`，圆角 16pt
- 图标容器：40×40 黑底 `#18181B` + 白色图标，圆角 12pt
- 内边距 16pt，gap 12pt
---
### 11.8 SectionTitle 区块标题条
页面内分组的标题行，含 3pt 主色装饰条 + 标题 + 右侧动作。
| 属性 | 类型 | 说明 |
|------|------|------|
| `text` | string | 区块标题 |
| `action` | string | 右侧动作文字（可选） |
**视觉规则：**
- 高度 38pt（含上下 12pt padding）
- 装饰条：3×14pt 主色 `#2A7F8B` + 圆角 4pt
- 底部 1pt `#E4E4E7` 分隔线
- 标题 15pt 600
---
## 12. 信息展示组件 — 响应式规则
| 断点 | 行为 |
|------|------|
| `< 360pt` | MetricCard 单列堆叠；GroupKPI 改为竖向 1 列 |
| `360 - 480pt` | MetricCard 2 列网格；GroupKPI 3 列保持 |
| `> 480pt` | 全部组件保持设计稿原始布局 |
| 横屏/iPad | 容器最大宽度 600pt，居中显示 |
## 13. 视觉一致性测试清单
- [ ] 所有色值来自 `design-tokens.json`，零硬编码
- [ ] 中性色阶与 B 端 RUNDA ToB ink 色阶一致
- [ ] 主色 #2A7F8B 仅用于强调（CTA / 装饰条 / 选中）
- [ ] 状态色（绿/蓝/橙/红）使用 alpha=0.08~0.14 的弱背景
- [ ] 圆角统一：胶囊 full / 卡片 16pt / 单元格 12pt / 标签 4pt
- [ ] 阴影统一：卡片 `shadow-sm`，无自定义 shadow
- [ ] 等宽数字：所有 KPI/数值使用 `font-variant-numeric: tabular-nums`
- [ ] 触摸目标 ≥ 44×44pt（卡片整体可点击）
## 14. 功能完整性测试清单
- [ ] MetricCard：默认 / 含图标 / 含趋势上下平 / 含底部元数据 4 种状态
- [ ] GroupKPI：3 种主题色（blue/orange/amber）单元正常显示
- [ ] StatusBadge：4 种状态（excellent/normal/attention/danger）独立可用
- [ ] InfoTable：表头 + 多行 + 行交替 + 高亮列 4 项可控
- [ ] AdviceTip：3 种 tone（success/info/warning）独立切换
- [ ] InfoCapsule：含/不含数值高亮两种模式
- [ ] ShareCard：图标 + 标题 + 副标题 + 动作 4 项可见
- [ ] SectionTitle：含/不含右侧 action 两种模式
---
## 15. 图表组件（v1.4.0 · 移动端适配 · 基于 ECharts 5）
> 所有图表组件统一使用 `design-tokens.json` 中 `color.primitive.chart` 节点的色板，禁止自定义色值。引入方式：CDN 或本地 `import echarts from 'echarts'`。
### 15.0 图表通用规则（v1.4 强制约束）
1. **禁用任何渐变**：line/area/bar/ring 全部使用纯色。`echarts.graphic.LinearGradient` / `RadialGradient` 在图表中禁止使用，所有 token 也不再提供 `areaGradient`。
2. **面积/轨道用低饱和纯色**：面积图填充用 `chart.seriesAlpha.*`（16% 透明的纯色叠加，不是渐变）；环形进度轨道用 `chart.seriesSoft.track` (`#F0F0F2`)。
3. **跟随移动端 app 视觉**：紧凑 grid、10–11px 字号、`chart-canvas` 默认高度 200px、点尺寸 5px、柱宽 ≥ 56%、tooltip `confine: true` 防止溢出。
4. **同一图表只用一个主色**：单系列严格单色；多系列按 §15.7 顺序取色。
5. **Tooltip 始终深色** `rgba(24,24,27,0.92)`：保证浮层对比度。
### 15.1 通用基础配置
所有图表共享以下基础设置（**不可覆盖**）：
```js
const dsTokens = {
primary: '#2A7F8B', primarySoft: '#E6F1F3',
blue: '#4388FF', blueSoft: '#E8F0FF',
amber: '#FEBC41', orange: '#FF9946',
green: '#02C456', greenSoft: '#E1F8EB',
red: '#D83226', track: '#F0F0F2',
axisLine: '#E4E4E7', splitLine: '#F4F4F5',
axisLabel: '#71717A', tickLabel: '#A1A1AA',
tooltipBg: 'rgba(24, 24, 27, 0.92)',
fontFamily: '-apple-system, "PingFang SC", sans-serif'
};
// 移动端紧凑 grid（px 单位，避免百分比在小屏下边距过大）
const commonGrid = { left: 4, right: 12, top: 24, bottom: 8, containLabel: true };
const commonAxisStyle = {
axisLine: { lineStyle: { color: dsTokens.axisLine } },
axisLabel: { color: dsTokens.axisLabel, fontSize: 10, fontFamily: dsTokens.fontFamily, margin: 8 },
splitLine: { lineStyle: { color: dsTokens.splitLine, type: 'dashed' } },
axisTick: { show: false }
};
const commonTooltip = {
backgroundColor: dsTokens.tooltipBg,
borderColor: 'transparent',
textStyle: { color: '#FFFFFF', fontSize: 11, fontFamily: dsTokens.fontFamily },
padding: [6, 10],
confine: true
};
```
### 15.2 LineChart 折线图
| 属性 | 类型 | 说明 |
|------|------|------|
| `data` | `number[]` | Y 轴数据 |
| `xAxis` | `string[]` | X 轴分类 |
| `color` | `chart token` | 默认 `primary`，**仅纯色** |
| `smooth` | boolean | 默认 `true`（曲线平滑） |
| `symbolSize` | number | 默认 5（移动端，原 6） |
**视觉规则：**
- 容器：白底 chart-card，圆角 16pt + `shadow-sm`
- 折线：2pt 描边 + 圆形数据点（白色 1.5pt 边）
- 不显示坐标轴线（仅 X 轴底线）+ 虚线网格
### 15.3 AreaChart 面积图
折线图的扩展，区域用**纯色低透明度填充**（不再使用渐变）：
```js
series: [{
type: 'line', smooth: true, symbol: 'none',
lineStyle: { color: dsTokens.blue, width: 2 },
areaStyle: { color: 'rgba(67,136,255,0.16)' }, // = chart.seriesAlpha.blue
data: [...]
}]
```
### 15.4 BarChart 柱状图
| 属性 | 默认值 |
|------|--------|
| 柱宽 | 56%（移动端，原 50%） |
| 圆角 | `[6, 6, 0, 0]`（仅顶部） |
| 填充 | **纯色主色**，禁止渐变 |
```js
itemStyle: { color: dsTokens.primary, borderRadius: [6, 6, 0, 0] }
```
### 15.5 RingProgress 环形进度
通过 ECharts pie 的 doughnut 模式实现，**单色 + 灰色轨道**：
```js
type: 'pie',
radius: ['74%', '90%'], // 环宽（v1.4 微调）
center: ['50%', '50%'],
data: [
{ value: 85, itemStyle: { color: dsTokens.primary, borderRadius: 8, borderColor: '#fff', borderWidth: 2 } },
{ value: 15, itemStyle: { color: dsTokens.track } } // #F0F0F2 轨道
]
```
| 属性 | 类型 | 说明 |
|------|------|------|
| `value` | number | 当前值 |
| `max` | number | 总值（默认 100） |
| `color` | string | 主色，**仅纯色**（不再支持渐变） |
| `centerSlot` | HTMLElement | 圆心自定义内容 |
### 15.6 StackedBar 多色叠加进度条
纯 CSS 实现（不依赖 ECharts），三段式胶囊条：
```html
```
### 15.7 MultiLine 多系列折线图
同 LineChart，但支持 `legend` 和多 `series`。规则：
- 系列 ≤ 4 条
- 颜色顺序：`primary → amber → blue → green`（全部纯色）
- Legend 位置：右上 `top:0, right:0`，icon `roundRect`，itemWidth 10 / itemHeight 6
---
## 16. 图表色板（chart token）使用规则
| 用途 | Token 路径 | 推荐色 |
|------|-----------|--------|
| 单系列折线/柱状 | `chart.series.primary` | `#2A7F8B` |
| 多系列对比（≤2） | `primary` + `amber` | 高对比 |
| 多系列对比（3-4） | `primary, amber, blue, green` | 防混淆 |
| 多系列对比（>4） | 加入 `purple, pink, teal, rose` | 注意可读性 |
| 面积填充 | `chart.seriesAlpha.{color}` | 16% 纯色叠加（非渐变） |
| 环形/空状态轨道 | `chart.seriesSoft.track` 或 `chart.seriesSoft.{color}` | 纯色低饱和 |
| 趋势涨/跌 | `chart.series.green / red` | 仅在「上升=好」语义下用 |
| **多分类饼/环图** | **`chart.categorical.*`** | **6 色，按顺序分配** |
### 16.0 chart.categorical 分类色板（v1.5 新增）
专用于多分类饼图/环图，来源：APP 截图逆向提取，ΔE76 去重（阈值 10），主色 `#2A7F8B` 不变。
| 顺序 | Token | HEX | 色相 |
|------|-------|-----|------|
| 1 | `chart.categorical.ochre` | `#BC932F` | 赭石金 |
| 2 | `chart.categorical.coral` | `#FD7548` | 鲜橙珊瑚 |
| 3 | `chart.categorical.olive` | `#2A5B00` | 深橄榄绿 |
| 4 | `chart.categorical.sky` | `#88CDFE` | 浅天蓝 |
| 5 | `chart.categorical.amberLight` | `#F9B868` | 浅琥珀 |
| 6 | `chart.categorical.violet` | `#847DFF` | 紫罗兰 |
```js
// ECharts 饼图使用示例
const CATEGORICAL = ['#BC932F','#FD7548','#2A5B00','#88CDFE','#F9B868','#847DFF'];
option = {
series: [{
type: 'pie',
radius: ['40%', '70%'],
color: CATEGORICAL,
data: [...]
}]
};
```
### 16.1 数据可视化禁忌
1. **禁用渐变**：series/area/ring/bar 全部纯色。需要"层次感"时用透明度而非线性渐变。
2. **不用主色 #2A7F8B 作为大面积背景**：仅用于线条/柱体本身
3. **不用 emoji 作为数据点**：违反图标系统线性 SVG 规则
4. **不超过 4 条系列**：>4 改用堆叠柱图或分组小倍数
5. **Tooltip 永远用深色背景** `rgba(24,24,27,0.92)`：保证浮层对比度
### 16.2 ECharts 主题导入（推荐做法）
将上述 `dsTokens` 抽取为独立主题：
```js
echarts.registerTheme('runda-toc', {
color: ['#2A7F8B', '#FEBC41', '#4388FF', '#02C456', '#A855F7', '#EC4899', '#14B8A6', '#F43F5E'],
textStyle: { fontFamily: '-apple-system, "PingFang SC", sans-serif' },
// ... 其他配置
});
const chart = echarts.init(dom, 'runda-toc');
```
## 17. 图表响应式与无障碍
- **响应式**：所有图表 `width: 100%`，监听 `window.resize` 调用 `chart.resize()`
- **移动端默认**（v1.4）：`chart-canvas` 高度 200px、`chart-canvas-sm` 160px；axisLabel 10px / tooltip 11px / 数据点 5px / 柱宽 56%；grid 边距 `{left:4, right:12, top:24, bottom:8}`
- **无障碍**：每张图标注 `aria-label="<图表说明>"`；悬停 tooltip 提供完整数值；tooltip `confine: true`
- **打印友好**：本规范本身已是纯色，打印无需切换
---
## 18. v1.6.0 补充组件（系统性审查新增）
> 对标 Apple HIG、Material Design 3、Ant Design Mobile、Airbnb DLS 审查后补充的缺失组件。
---
### 18.1 Tooltip 气泡提示
**场景**：图标按钮说明、表单字段帮助、数据点标注。
| 属性 | 值 |
|------|-----|
| 背景 | `rgba(24,24,27,0.92)` |
| 文字 | `#FFFFFF` 12pt |
| 圆角 | 12pt |
| 内边距 | 6pt × 10pt |
| 最大宽度 | 200pt |
| 箭头 | 5×5pt 三角，指向触发元素 |
| 出现动效 | 淡入 + 上移 4pt，150ms ease-out |
| 消失动效 | 淡出 100ms |
**方向优先级**：上 → 下 → 左 → 右（自动避边）。
```
触发元素
↑
┌──────────────┐
│ 提示文字内容 │ ← 深色背景，白字
└──────────────┘
```
**规则**：
- 移动端仅在长按时触发，不用 hover
- 不嵌套交互元素（链接/按钮）
- 超过 2 行改用 Popover
---
### 18.2 Popover 气泡弹出层
**场景**：筛选面板、快捷操作菜单、富文本提示。
| 属性 | 值 |
|------|-----|
| 背景 | `#FFFFFF` |
| 阴影 | `shadow-lg` |
| 圆角 | 16pt |
| 内边距 | 16pt |
| 最大宽度 | 280pt |
| 遮罩 | 无（点击外部关闭） |
| 出现动效 | 弹性弹出 350ms `cubic-bezier(0.34,1.56,0.64,1)` |
**与 Tooltip 区别**：Popover 可含交互元素（按钮、列表、表单）。
---
### 18.3 DatePicker 日期选择器
**场景**：日期范围筛选、预约时间、生日录入。
#### 18.3.1 滚轮选择器（iOS 原生风格）
```
┌─────────────────────────────┐
│ 2026 05 28 │
│ ──── ── ── │ ← 选中行高亮背景
│ 2025 04 27 │
└─────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 行高 | 44pt |
| 选中背景 | `rgba(42,127,139,0.08)` |
| 选中文字 | `#18181B` 17pt Semibold |
| 非选中文字 | `#A1A1AA` 15pt |
| 渐隐遮罩 | 上下各 80pt 线性透明 |
#### 18.3.2 日历网格（月视图）
```
一 二 三 四 五 六 日
27 28 29 30 1 2 3
4 5 6 7 8 9 10
...
```
| 状态 | 样式 |
|------|------|
| 今日 | 文字 `#2A7F8B`，无背景 |
| 选中 | 背景 `#2A7F8B`，白字，圆角 full |
| 范围内 | 背景 `rgba(42,127,139,0.10)` |
| 范围端点 | 半圆背景 + 实心圆 |
| 禁用 | 文字 `#A1A1AA`，不可点 |
**交互**：单选 / 范围选（两次点击）/ 快捷选（本周、本月）。
---
### 18.4 TimePicker 时间选择器
同 DatePicker 滚轮风格，列为「时 / 分」或「时 / 分 / 秒」。AM/PM 模式可选。
---
### 18.5 Stepper 数量步进器
**场景**：购物车数量、剂量调整、人数选择。
```
┌───┐ ┌─────┐ ┌───┐
│ − │ │ 3 │ │ + │
└───┘ └─────┘ └───┘
44pt 56pt 44pt
```
| 属性 | 值 |
|------|-----|
| 按钮尺寸 | 44×44pt，圆角 12pt |
| 按钮背景 | `#F4F4F5` |
| 按钮图标 | 20pt，`#18181B` |
| 数值框 | 56pt 宽，居中，17pt Semibold |
| 禁用态 | 按钮透明度 0.38 |
| 长按 | 500ms 后连续步进，间隔 100ms |
---
### 18.6 Rate 评分组件
**场景**：服务评价、内容评分。
- **图标**：星形，线性风格，描边 1.5pt
- **尺寸**：24pt（默认）/ 32pt（大）
- **选中色**：`#F2AD0C`（gold.500）
- **未选色**：`#E4E4E7`
- **半星**：支持，左半填充
- **间距**：8pt
- **动效**：选中时缩放 1.2 → 1.0，150ms
---
### 18.7 Swipe Actions 滑动操作
**场景**：列表项左滑删除/归档，右滑标记已读。
```
← 左滑
┌──────────────────────────────┬──────┬──────┐
│ 列表项内容 │ 归档 │ 删除 │
└──────────────────────────────┴──────┴──────┘
64pt 64pt
```
| 操作 | 背景 | 图标 | 文字 |
|------|------|------|------|
| 归档 | `#F2AD0C` | archive | `#FFFFFF` |
| 删除 | `#D83226` | trash | `#FFFFFF` |
| 标记已读 | `#2A7F8B` | check | `#FFFFFF` |
**规则**：
- 滑动超过 50% 宽度自动触发第一个操作
- 操作区宽度 64pt，图标 18pt + 文字 12pt 垂直排列，间距 8pt
- 弹回动效 300ms spring
---
### 18.8 Pull-to-Refresh 下拉刷新
**场景**：列表页、Feed 流顶部刷新。
| 阶段 | 表现 |
|------|------|
| 拉动中 | 显示箭头图标，随拉动距离旋转 0→180° |
| 触发阈值（64pt） | 箭头变为 Spinner，触觉反馈 |
| 刷新中 | Spinner 持续旋转，文字「刷新中...」 |
| 完成 | 文字「已更新」，300ms 后收起 |
- **触发距离**：64pt
- **最大拉伸**：96pt（弹性阻尼）
- **Spinner 色**：`#2A7F8B`
---
### 18.9 Tabs 顶部标签页（增强版）
在现有 TabGroup（§3.3）基础上补充：
| 变体 | 说明 |
|------|------|
| **Scrollable** | 超过 4 个 tab 时横向滚动，左右渐隐提示 |
| **Pill** | 胶囊形选中态，背景 `#2A7F8B`，白字 |
| **Underline** | 下划线 2pt `#2A7F8B`，文字选中加粗 |
| **Icon+Text** | 图标 16pt + 文字 12pt 垂直排列 |
**Badge 支持**：Tab 标题右上角可叠加 Badge 组件。
---
### 18.10 Accordion 折叠面板
**场景**：FAQ、设置分组、详情展开。
```
┌─────────────────────────────────┐
│ 标题文字 ▼ │ ← 44pt 触摸区
├─────────────────────────────────┤
│ 展开内容区域 │
│ 可包含任意子组件 │
└─────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 标题高度 | 44pt（最小触摸目标） |
| 标题字号 | 15pt Semibold |
| 箭头图标 | 16pt，展开时旋转 180°，200ms ease |
| 内容区 | 高度动画展开，300ms ease-out |
| 分割线 | Hairline `rgba(0,0,0,0.08)` |
**规则**：默认单开（关闭其他），可配置多开。
---
### 18.11 Carousel 轮播图
**场景**：Banner 广告、图片浏览、引导页。
| 属性 | 值 |
|------|-----|
| 高度 | 160pt（Banner）/ 全屏（引导页） |
| 圆角 | 16pt |
| 指示点 | 6pt 圆，选中 `#2A7F8B`，未选 `rgba(0,0,0,0.2)` |
| 指示点间距 | 6pt |
| 自动播放 | 3000ms，用户交互后暂停 |
| 切换动效 | 水平滑动 300ms ease-in-out |
| 边缘预览 | 左右各露出 16pt 下一张（peek） |
---
### 18.12 ImageViewer 图片查看器
**场景**：聊天图片全屏查看、相册浏览。
| 交互 | 行为 |
|------|------|
| 双击 | 放大 2× / 还原 |
| 捏合 | 自由缩放（0.5× ~ 4×） |
| 单击 | 切换工具栏显示/隐藏 |
| 下滑 | 关闭（背景渐透明） |
| 左右滑 | 切换图片 |
- **背景**：`#000000`，进入时渐变 300ms
- **工具栏**：底部，含分享/保存/删除，背景 `rgba(0,0,0,0.6)`
- **关闭按钮**：右上角，白色 × 图标
---
### 18.13 Notification Banner 通知横幅
**场景**：系统级通知、消息推送预览（区别于 Toast）。
```
┌─────────────────────────────────────┐
│ [图标] 标题文字 │ ← 64pt 高
│ 副标题/内容预览 │
└─────────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 位置 | 顶部，状态栏下方 |
| 背景 | `#FFFFFF`，`shadow-lg` |
| 圆角 | 16pt |
| 内边距 | 12pt × 16pt |
| 图标 | 40×40pt，圆角 10pt |
| 标题 | 14pt Semibold |
| 副标题 | 12pt，`#71717A` |
| 出现 | 从顶部滑入，350ms spring |
| 消失 | 4s 后自动，或上滑关闭 |
**与 Toast 区别**：Banner 含应用图标、标题+副标题，可点击跳转；Toast 仅单行文字反馈。
---
### 18.14 FloatingActionButton 浮动操作按钮（扩展）
在现有 FAB（§1.2）基础上补充 **SpeedDial** 变体：
```
┌──────┐
│ 📷 │ ← 子按钮（展开后）
├──────┤
│ 📎 │
├──────┤
│ 📝 │
└──────┘
↑
┌──────┐
│ + │ ← 主 FAB（点击展开/收起）
└──────┘
```
| 属性 | 值 |
|------|-----|
| 主按钮 | 56pt，`#2A7F8B`，`shadow-glow` |
| 子按钮 | 40pt，`#FFFFFF`，`shadow-md`，文字标签在左 |
| 展开动效 | 子按钮逐个上移 + 淡入，stagger 50ms |
| 主按钮旋转 | + → × 旋转 45°，200ms |
| 遮罩 | `rgba(0,0,0,0.3)`，点击关闭 |
---
### 18.15 Segmented Progress 分段进度
**场景**：故事/Stories 进度、多步骤完成度。
```
┌────┐ ┌────┐ ┌────┐ ┌────┐
│████│ │████│ │▓▓░░│ │░░░░│
└────┘ └────┘ └────┘ └────┘
完成 完成 进行中 未开始
```
| 属性 | 值 |
|------|-----|
| 高度 | 3pt |
| 圆角 | full |
| 完成色 | `#2A7F8B` |
| 进行中 | `#2A7F8B`（动态填充） |
| 未开始 | `rgba(0,0,0,0.12)` |
| 段间距 | 8pt |
---
### 18.16 CountdownTimer 倒计时
**场景**：限时活动、验证码倒计时、任务截止。
| 变体 | 样式 |
|------|------|
| **Inline** | `05:30` 文字，Manrope Numeric Medium 24pt，`#2A7F8B` |
| **Ring** | 环形进度 + 中心数字，RingProgress 组件复用 |
| **Block** | 分块显示「时 : 分 : 秒」，每块独立卡片 |
- **数字字族**：`typography.scale.numericMedium`（Manrope 700）
- **颜色变化**：剩余 < 10% 时切换为 `#D83226`（red.500）
---
### 18.17 Breadcrumb 面包屑导航
**场景**：多级内容导航、设置路径。
```
首页 / 健康 / 睡眠报告
```
| 属性 | 值 |
|------|-----|
| 字号 | 13pt |
| 当前页 | `#18181B` Semibold |
| 父级 | `#2A7F8B`，可点击 |
| 分隔符 | `/` 或 `›`，`#A1A1AA` |
| 超出截断 | 中间层折叠为 `...`，点击展开 |
---
### 18.18 Stepper 步骤条（水平）
> 区别于 §6.3 StepIndicator（垂直时间线风格），本组件为水平步骤条。
```
① 基本信息 ──── ② 健康数据 ──── ③ 确认
完成 进行中 待完成
```
| 状态 | 节点 | 连线 |
|------|------|------|
| 完成 | `#2A7F8B` 实心 + ✓ | `#2A7F8B` |
| 进行中 | `#2A7F8B` 实心 + 序号 | `#E4E4E7` |
| 待完成 | `#E4E4E7` 空心 + 序号 | `#E4E4E7` |
- **节点直径**：24pt
- **字号**：节点内 12pt，标题 12pt，副标题 12pt `#71717A`
---
### 18.19 FilterBar 筛选栏
**场景**：列表页顶部筛选、搜索结果过滤。
```
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ 全部 ▾│ │ 时间 ▾│ │ 类型 ▾│ │ ⋮ 更多│
└──────┘ └──────┘ └──────┘ └──────┘
```
| 属性 | 值 |
|------|-----|
| 高度 | 44pt |
| 圆角 | full |
| 默认背景 | `#F4F4F5` |
| 激活背景 | `rgba(42,127,139,0.10)` |
| 激活文字 | `#1D6770` |
| 激活边框 | 1pt `#2A7F8B` |
| 字号 | 13pt |
| 内边距 | 0 × 16pt |
| 图标 | 12pt SVG 图标（下箭头/更多），间距 8pt，描边 2pt，圆角端点 |
| 横向滚动 | 超出时可滚动，左右渐隐 |
**图标规范**：
- 下拉箭头：``（12×12pt viewBox 24×24）
- 更多菜单：三点竖排 ``
**激活态**：选中后显示已选值，右侧 × 可清除。
---
### 18.20 KeyValuePair 键值对
**场景**：详情页信息展示、订单信息、个人资料。
```
┌─────────────────────────────────┐
│ 姓名 张三 │
│ 手机号 138****8888 │
│ 注册时间 2026-01-15 │
└─────────────────────────────────┘
```
| 属性 | 值 |
|------|-----|
| 行高 | 44pt |
| Key 字号 | 15pt，`#71717A` |
| Value 字号 | 15pt，`#18181B` |
| 分割线 | Hairline，仅行间 |
| Value 对齐 | 右对齐 |
| 可复制 | 长按 Value 弹出复制菜单 |
**变体**：
- **Vertical**：Key 在上，Value 在下，用于宽值（地址、备注）
- **Highlight**：Value 用 `#2A7F8B` 强调色（链接、金额）
---
### 18.21 AvatarGroup 头像组
**场景**：群组成员、协作者列表。
```
[A][B][C][D] +12
```
| 属性 | 值 |
|------|-----|
| 头像尺寸 | 32pt（默认）/ 24pt（紧凑） |
| 重叠偏移 | -8pt（每个向左偏移） |
| 边框 | 2pt `#FFFFFF`（防重叠） |
| 溢出显示 | `+N` 灰色圆，同尺寸，字号 12pt |
| 最大显示 | 5 个（超出折叠） |
---
### 18.22 Skeleton 增强（内容感知型）
在现有 §5.6 基础上补充内容感知变体：
| 变体 | 结构 |
|------|------|
| **Card** | 图片占位 + 2 行文字 + 1 行短文字 |
| **ListItem** | 圆形头像 + 2 行文字 |
| **Chart** | 矩形占位 + 底部 3 个标签 |
| **Profile** | 大圆 + 居中 2 行文字 |
所有变体使用统一 shimmer 动效：`linear-gradient(90deg, #E4E4E7 25%, #F4F4F5 50%, #E4E4E7 75%)`，`background-size: 400% 100%`，2.8s linear infinite。
---
### 18.23 ContextMenu 上下文菜单
**场景**：长按触发的快捷操作（iOS 原生 Context Menu 风格）。
```
┌──────────────────┐
│ 📋 复制 │
│ ✏️ 编辑 │
│ 🔗 分享 │
├──────────────────┤
│ 🗑 删除 │ ← 危险操作分组
└──────────────────┘
```
| 属性 | 值 |
|------|-----|
| 背景 | `rgba(255,255,255,0.95)` + 毛玻璃 |
| 圆角 | 14pt |
| 阴影 | `shadow-xl` |
| 行高 | 44pt |
| 图标 | 20pt，`#18181B` |
| 文字 | 15pt，`#18181B` |
| 危险项文字 | `#D83226` |
| 分割线 | Hairline |
| 出现动效 | 缩放 0.8→1.0 + 淡入，200ms spring |
---
### 18.24 组件补充索引
| 新增组件 | 分类 | 对标参考 |
|---------|------|---------|
| Tooltip | 反馈 | Apple HIG Tooltip |
| Popover | 反馈 | Material Popover |
| DatePicker | 表单 | Apple UIDatePicker |
| TimePicker | 表单 | Apple UIDatePicker |
| Stepper | 表单 | Ant Design Mobile Stepper |
| Rate | 表单 | Ant Design Rate |
| Swipe Actions | 数据展示 | Apple Mail 左滑 |
| Pull-to-Refresh | 交互模式 | iOS UIRefreshControl |
| Tabs (增强) | 导航 | Material Tabs |
| Accordion | 数据展示 | Ant Design Collapse |
| Carousel | 数据展示 | Airbnb 图片轮播 |
| ImageViewer | 数据展示 | iOS Photos |
| Notification Banner | 反馈 | iOS 通知横幅 |
| FAB SpeedDial | 基础 | Material SpeedDial |
| Segmented Progress | 数据展示 | Instagram Stories |
| CountdownTimer | 业务 | 电商倒计时 |
| Breadcrumb | 导航 | Apple HIG |
| Stepper 水平步骤条 | 导航 | Ant Design Steps |
| FilterBar | 导航 | Airbnb 筛选栏 |
| KeyValuePair | 数据展示 | Apple Settings |
| AvatarGroup | 基础 | GitHub Contributors |
| Skeleton 增强 | 反馈 | Facebook Content Loader |
| ContextMenu | 反馈 | iOS Context Menu |