# 可乐工具 · PC 端 → App 端设计规范文档

> 来源：基于 PC 端（React + Ant Design）实际代码提取
> 用途：App（Android/Compose）UI 落地依据
> 主题品牌：可乐（星空紫蓝渐变体系）

---

## 1. 色彩系统

### 1.1 主色 / 品牌色

| 名称 | HEX | 用途 |
|---|---|---|
| 主色 Primary | `#667EEA` | 品牌主色：导航选中、主按钮、链接、焦点态 |
| 主渐变 Primary Gradient | `#667EEA → #764BA2` (135°) | Hero 区、页头、主 CTA、选中态背景 |
| 次渐变 Secondary Gradient | `#F093FB → #F5576C` (135°) | 功能入口、工具类卡片点缀 |
| 成功渐变 Success Gradient | `#4FACFE → #00F2FE` (135°) | 文章/学习入口、成功态 |
| 警告渐变 Warning Gradient | `#FA709A → #FEE140` (135°) | 提醒、任务/活动入口 |

### 1.2 辅助色（分类语义色，PC 与 App 共用）

| 名称 | HEX | 用途 |
|---|---|---|
| 技术 Tech | `#667EEA` | 技术教程分类徽章 |
| 设计 Design | `#F093FB` | 设计前沿分类徽章 |
| 效率 Productivity | `#4FACFE` | 效率方法分类徽章 |
| 行业 Industry | `#43E97B` | 行业洞察分类徽章 |
| 热门 Hot | `#FF5B6E` | "热门"标签（App 端已用） |
| 新 New | `#43E97B` | "新"标签 |
| 金币/等级 Gold | `#FFD54F` | 等级徽章（App 端已用） |

### 1.3 中性色

| 名称 | HEX | 用途 |
|---|---|---|
| 页面背景 Background | `#F8FAFC` | 全局页面底色 |
| 卡片背景 Card | `#FFFFFF` | 卡片、面板、弹窗 |
| 主文字 Text Primary | `#1E293B` | 标题、正文主体 |
| 次文字 Text Secondary | `#64748B` | 描述、辅助信息 |
| 弱文字 Text Muted | `#94A3B8` | 占位符、时间戳、禁用态 |
| 边框 Border | `#E2E8F0` | 卡片描边、分割线、输入框 |

### 1.4 阴影与圆角

| 层级 | 值 | 用途 |
|---|---|---|
| shadow-sm | `0 1px 2px rgba(0,0,0,0.05)` | 常规卡片 |
| shadow-md | `0 4px 6px -1px rgba(0,0,0,0.1)` | 浮起卡片、下拉 |
| shadow-lg | `0 10px 15px -3px rgba(0,0,0,0.1)` | 弹窗、抽屉 |
| shadow-xl | `0 20px 25px -5px rgba(0,0,0,0.1)` | 全屏浮层 |
| radius-sm / md / lg | `6 / 12 / 20 px` | 小元素 / 卡片 / Hero |

> App 端映射：Material 主题已按此落地（浅色 primary `#6D5EF2` 对应 PC `#667EEA`，深色星空 `#141321` 背景），分类色与标签色完全复用 PC 端色板。

---

## 2. 字体层级

PC 端基准字号 14px，通过 `--font-scale` 缩放。移动端按 **逻辑像素（dp/sp）** 适配：

| 层级 | PC 端 (px) | App 端 (sp) | 字重 | 用途 |
|---|---|---|---|---|
| Display / Headline | 28 | 24 | Bold(700) | Hero 大标题（首页/文章/学习横幅） |
| Headline-2 | 24 | 20–22 | Bold | 页面大标题 |
| Title | 20 / 18 | 18 | Bold | 页面标题（TopBar）、卡片主标题 |
| Title-2 | 16 | 16 | SemiBold(600)/Bold | 卡片标题、区块标题 |
| Body | 15 / 14 | 14 | Regular(400) | 正文、列表内容 |
| Body-2 | 13 | 13 | Regular | 卡片摘要、描述 |
| Caption | 12 | 11–12 | Regular/Medium | 时间戳、标签、统计数字、徽章 |

行高建议：标题 1.3–1.4，正文 1.6（PC 端 body line-height 1.6）。

> 注意：App 不依赖系统默认字号，所有层级显式指定 sp 值。

---

## 3. 间距系统

### 3.1 栅格与基数

- PC 端间距遵循 **8px 栅格**（padding/margin 均为 8 的倍数，含 4 半基数）。
- App 端统一使用 **8 / 12 / 16 / 24 / 32** 基数：

| 基数 | App 端使用场景 |
|---|---|
| 4 | 图标与文字间隙、标签内边距 |
| 8 | 行内元素间距、小按钮内边距 |
| 12 | 卡片间距、元素组间距 |
| 16 | 页面水平安全边距（contentPadding）、卡片内边距 |
| 24 | 区块间距、底部留白 |
| 32 | 大区块分隔、登录引导页留白 |

### 3.2 关键间距约定

| 场景 | 值 |
|---|---|
| 页面水平边距 | 16dp（统一） |
| 卡片圆角 | 12–16dp（列表卡片 16，组内元素 12） |
| 卡片间垂直间距 | 8–12dp |
| 分类 Chips 间距 | 8dp |
| 分区标题距上 / 距下 | 24 / 8dp |
| 列表底部留白 | 24dp |

---

## 4. 核心组件（PC → App 形态映射）

| PC 端组件 | App 端对应形态 | 说明 |
|---|---|---|
| 左侧/顶部导航菜单 | **底部 Tab（4 项）** | 首页 / 学习 / 文章 / 我的（已落地） |
| 页面 Hero 横幅 | **渐变 Hero 卡片** | 可乐渐变 + 星光装饰（已落地于首页/学习/文章） |
| 分类标签 Tabs | **横向滚动 FilterChip** | 选中态 = 分类色实底 + 白字（已落地） |
| 文章卡片（封面+徽章+标签+统计） | **列表卡片（左图右文）** | 封面 110dp 宽，含 热门/新 徽章、分类色徽章、标签行、浏览/点赞/评论/阅读时间（已落地） |
| 课程卡片 | **横向渐变封面卡** | 课程色渐变 + 图标 + 等级徽章 + 章节数/学员数（已落地） |
| 表格 / 数据列表 | **卡片化列表** | 分组 MenuCard + 图标底色块 + 右箭头（已落地于"我的"页） |
| 分页 Pagination | **下拉加载 / 无限滚动** | 触底加载下一页 |
| 弹窗 Modal | **Dialog / 底部弹层** | 确认类用 AlertDialog，选择类用 ModalBottomSheet |
| 面包屑 | **返回键 + 页面标题** | TopAppBar 导航图标 |
| 搜索框 | **搜索页 / 搜索栏** | 全局搜索独立页（已有 SearchScreen） |
| 表单 | **分组表单页** | 邮箱/手机/密码设置均为独立二级页 |
| 登录（弹窗） | **登录页 + 扫码页** | 邮箱登录、扫码登录（Web 确认） |

---

## 5. 页面层级（信息架构）

### 5.1 一级导航（底部 Tab，App 已精简为 4 项）

| Tab | 对应 PC 路由 | App 页面 |
|---|---|---|
| 首页 | `/` | HomeScreen（Hero + 快捷入口 + 工具分类） |
| 学习 | `/learn` | CourseListScreen（课程列表） |
| 文章 | `/articles` | ArticlesScreen（文章列表） |
| 我的 | `/profile` | ProfileScreen（个人中心，未登录为引导页） |

> 说明：PC 端工具（/utility）、API 目录（/api）、消息（/messages）、聊天（/chat）在 App 一期**降级为二级入口**（首页快捷入口），不占一级 Tab。

### 5.2 二级页面（必须保留）

| 模块 | 二级页面 | 来源 PC 路由 |
|---|---|---|
| 学习 | 课程详情、章节阅读、学习进度 | `/learn`、`/course-learn` |
| 文章 | 文章详情、评论列表 | `/article/:id` |
| 我的 | 个人资料、邮箱绑定、手机绑定、修改密码、我的收藏、浏览历史、系统设置 | `/profile/*`、`/favorites`、`/history`、`/settings` |
| 通用 | 登录、扫码登录、搜索、关于/协议/隐私 | `/api-docs`、`/search`、`/agreement`、`/privacy`、`/manual` |

### 5.3 页面层级规范

```
一级（Tab，4 个）
 └─ 二级（详情/表单/设置，TopBar + 返回）
     └─ 三级（阅读/预览/确认类，全屏沉浸）
```

- 一级：底部 Tab 切换，无返回
- 二级：TopAppBar + 返回键，进入后保留 Tab 栏（保持导航连续性）
- 三级：沉浸式全屏（如章节阅读、文章正文），隐藏 Tab 栏

---

## 附：App 端已落地对照表

| 规范项 | App 落地状态 |
|---|---|
| 主色/渐变/分类色 | ✅ 可乐紫主题 + 分类色板 |
| 字体层级 | ✅ 显式 sp 层级 |
| 8px 栅格间距 | ✅ 8/12/16/24 基数 |
| 底部 4 Tab | ✅ |
| 学习中心 Hero + 分类 Chips + 渐变课程卡 | ✅ |
| 文章 Hero + 分类 Chips + 封面卡片 | ✅ |
| 我的页 渐变头像卡 + 统计行 + 分组菜单 | ✅ |