# RUNDA ToC 移动端开发规范

> 版本 1.0.0 | 2026-05-28  
> 适用范围：所有新页面创建、新功能开发、UI 实现

---

## 1. 强制性开发规则

### 1.1 设计系统优先原则

**所有新页面和新功能开发必须严格遵循以下优先级：**

1. **优先使用设计系统组件**  
   - 查阅 `COMPONENTS.md` 确认是否有现成组件
   - 禁止重复造轮子，禁止自定义实现已有组件
   - 组件不满足需求时，先提出扩展需求，经评审后统一扩展

2. **严格参考 Origin 视觉风格**  
   - `design-system/Origin/` 目录包含 42 张 APP 实际截图
   - 所有 UI 实现必须与 Origin 截图保持视觉一致性
   - 间距、圆角、阴影、字体、颜色必须完全对齐

3. **遵循设计令牌（Design Tokens）**  
   - 所有样式值必须引用 `design-tokens.json` 或 `DESIGN.md` 中定义的令牌
   - 禁止硬编码颜色值、间距值、字号
   - 示例：使用 `var(--accent)` 而非 `#2A7F8B`

---

## 2. Origin 视觉风格参考规范

### 2.1 Origin 截图库说明

| 属性 | 说明 |
|------|------|
| 位置 | `design-system/Origin/` |
| 数量 | 42 张 PNG 截图 |
| 来源 | APP 实际运行截图（真实视觉标准） |
| 用途 | 视觉对齐基准、组件实现参考、UI 验收标准 |

### 2.2 视觉对齐检查清单

开发完成后，必须逐项对照 Origin 截图进行检查：

#### 2.2.1 布局与间距
- [ ] 屏幕水平内边距 = 16pt
- [ ] 卡片间距 = 12pt
- [ ] 区块间距 = 24pt
- [ ] 列表项间距 = 8pt
- [ ] 所有间距为 4 的倍数

#### 2.2.2 圆角系统
- [ ] 按钮圆角 = 12pt
- [ ] 卡片圆角 = 16pt
- [ ] 输入框圆角 = 12pt
- [ ] 弹窗/Sheet 圆角 = 24pt
- [ ] 胶囊按钮/头像 = full（正圆）

#### 2.2.3 色彩使用
- [ ] 主色仅用于 CTA、链接、进度、选中态
- [ ] 背景色使用 `#FAFAFA`（页面）/ `#FFFFFF`（卡片）
- [ ] 文字色使用 `#18181B`（主）/ `#52525B`（次）/ `#A1A1AA`（占位）
- [ ] 分割线使用 `#E4E4E7`
- [ ] 无自定义颜色值

#### 2.2.4 排版规范
- [ ] 标题使用 SF Pro Display Bold
- [ ] 正文使用 SF Pro Text Regular
- [ ] 大数字使用 Manrope（`typography.scale.numeric*`）
- [ ] 字号符合 `DESIGN.md` §3.2 字号阶梯
- [ ] 行高 = 字号 × 1.4

#### 2.2.5 阴影与层级
- [ ] 卡片使用 `shadow-sm`
- [ ] 弹窗使用 `shadow-lg`
- [ ] Toast 使用 `shadow-xl`
- [ ] 无自定义阴影值

#### 2.2.6 图标规范
- [ ] 所有图标为线性风格（Outlined）
- [ ] 描边宽度 = 1.5pt
- [ ] 端点/拐角 = 圆角（Round cap/join）
- [ ] 尺寸符合 `DESIGN.md` §8.2（12/16/20/24pt）
- [ ] 禁止使用 emoji

#### 2.2.7 触摸目标（移动端）
- [ ] 所有可点击元素 ≥ 44×44pt
- [ ] 按钮高度 ≥ 44pt
- [ ] 列表项高度 ≥ 44pt
- [ ] Tab 栏图标区域 ≥ 44pt

---

## 3. 组件使用规范

### 3.1 组件选型流程

```
用户需求
   ↓
查阅 COMPONENTS.md 组件索引
   ↓
找到匹配组件？
   ├─ 是 → 直接使用，参考 Origin 截图调整参数
   └─ 否 → 查找相似组件
           ↓
       找到相似组件？
           ├─ 是 → 提出扩展需求 → 评审 → 统一扩展
           └─ 否 → 提出新组件需求 → 评审 → 设计 → 开发
```

### 3.2 禁止行为

| 禁止行为 | 说明 | 正确做法 |
|---------|------|---------|
| 自定义实现已有组件 | 重复造轮子，破坏一致性 | 使用 `COMPONENTS.md` 中的标准组件 |
| 硬编码样式值 | 无法统一维护，破坏令牌系统 | 引用 `design-tokens.json` 令牌 |
| 使用 emoji 作为图标 | 跨平台渲染不一致 | 使用 SVG 线性图标 |
| 自定义颜色 | 破坏色彩系统 | 使用 `DESIGN.md` §2 色彩系统 |
| 自定义字体 | 破坏排版系统 | 使用 `DESIGN.md` §3 排版系统 |
| 小于 44pt 的触摸目标 | 违反移动端可用性 | 最小 44×44pt |
| 使用渐变背景 | 与扁平化原则冲突 | 使用纯色 + 透明度 |

### 3.3 组件参数调整原则

- **允许调整**：尺寸（sm/md/lg）、状态（default/active/disabled）、内容文字
- **禁止调整**：圆角值、阴影值、颜色值、字体族、描边宽度
- **灰色地带**：需要调整禁止项时，必须先在设计系统层面统一修改

---

## 4. 开发流程

### 4.1 开发前（必做）

1. **阅读设计文档**  
   - `DESIGN.md`：设计原则、色彩、排版、间距、圆角、阴影、动效
   - `COMPONENTS.md`：组件库完整清单、使用规范、状态定义

2. **查看 Origin 参考**  
   - 在 `design-system/Origin/` 中找到相似页面截图
   - 截图文件名为 UUID，需逐个查看
   - 记录关键视觉特征：布局、间距、圆角、阴影

3. **确认组件清单**  
   - 列出页面需要的所有组件
   - 在 `COMPONENTS.md` 中确认每个组件的章节编号
   - 记录组件参数（尺寸、状态、变体）

### 4.2 开发中（必做）

1. **使用设计令牌**  
   ```css
   /* ✓ 正确 */
   background: var(--bg-card);
   color: var(--text-1);
   border-radius: var(--r-lg);
   
   /* ✗ 错误 */
   background: #FFFFFF;
   color: #18181B;
   border-radius: 16px;
   ```

2. **引用组件样式**  
   - 复用 `design-preview.html` 中的 CSS 类
   - 不修改组件核心样式
   - 仅通过组合类实现变体

3. **对照 Origin 截图**  
   - 每完成一个模块，立即对照截图检查
   - 使用浏览器开发者工具测量间距、字号
   - 截图对比工具验证视觉一致性

### 4.3 开发后（必做）

#### 4.3.1 自检清单

- [ ] 所有颜色值来自设计令牌
- [ ] 所有间距为 4 的倍数
- [ ] 所有圆角值符合 `DESIGN.md` §5
- [ ] 所有字号符合 `DESIGN.md` §3.2
- [ ] 所有图标为 SVG 线性风格
- [ ] 所有触摸目标 ≥ 44×44pt
- [ ] 无硬编码样式值
- [ ] 无自定义组件（已有组件未使用）

#### 4.3.2 视觉验收流程

1. **截图对比**  
   - 在相同设备/分辨率下截图
   - 与 Origin 对应截图并排对比
   - 标注差异点（间距/颜色/圆角/阴影）

2. **测量验证**  
   - 使用开发者工具测量关键尺寸
   - 间距误差 ≤ 2pt
   - 字号必须完全一致
   - 颜色值必须完全一致

3. **交互验证**  
   - 所有按钮有按压态（缩放 0.96）
   - 所有输入框有焦点态
   - 所有列表项有高亮态
   - 动效时长符合 `DESIGN.md` §7.1

4. **无障碍验证**  
   - 触摸目标 ≥ 44×44pt
   - 文字对比度 ≥ 4.5:1
   - 所有交互元素有 aria-label
   - 支持 VoiceOver

#### 4.3.3 提交前检查

- [ ] 代码中无 `TODO` / `FIXME` 注释
- [ ] 无 console.log 调试代码
- [ ] 无未使用的 CSS 类
- [ ] 无内联样式（除动态计算值）
- [ ] 通过 ESLint / Stylelint 检查
- [ ] 通过视觉回归测试

---

## 5. 常见问题

### 5.1 找不到合适的组件怎么办？

1. 先查找相似组件，通过参数调整实现
2. 如无相似组件，提出新组件需求
3. 新组件需求必须包含：
   - Origin 截图参考
   - 使用场景说明
   - 与现有组件的差异
   - 复用性评估

### 5.2 Origin 截图与设计系统冲突怎么办？

**优先级**：Origin 截图 > DESIGN.md > COMPONENTS.md

- Origin 截图是真实视觉标准
- 如发现设计文档与截图不符，以截图为准
- 同时提出文档修正需求

### 5.3 需要微调样式怎么办？

**允许微调的情况**：
- 内容长度导致的自适应调整
- 不同设备尺寸的响应式适配
- 动态数据驱动的样式变化

**禁止微调的情况**：
- "感觉这个颜色更好看"
- "这个圆角太大了"
- "间距有点挤"

所有主观审美调整必须在设计系统层面统一修改。

---

## 6. 工具与资源

### 6.1 必备文档

| 文档 | 路径 | 用途 |
|------|------|------|
| 设计规范 | `design-system/DESIGN.md` | 色彩/排版/间距/圆角/阴影/动效 |
| 组件库 | `design-system/COMPONENTS.md` | 组件清单/使用规范/状态定义 |
| 设计令牌 | `design-system/design-tokens.json` | 机器可读的样式变量 |
| 交互预览 | `design-system/design-preview.html` | 组件实时预览/CSS 参考 |
| 视觉参考 | `design-system/Origin/*.png` | 42 张 APP 实际截图 |

### 6.2 推荐工具

- **截图对比**：[PixelSnap](https://getpixelsnap.com/)（macOS）
- **颜色提取**：浏览器开发者工具 Eyedropper
- **间距测量**：浏览器开发者工具 Ruler
- **无障碍检查**：[axe DevTools](https://www.deque.com/axe/devtools/)
- **视觉回归**：[Percy](https://percy.io/) / [Chromatic](https://www.chromatic.com/)

---

## 7. 违规处理

### 7.1 违规等级

| 等级 | 违规行为 | 处理方式 |
|------|---------|---------|
| **严重** | 自定义实现已有组件、硬编码颜色/字体、使用 emoji 图标 | 强制返工，代码审查不通过 |
| **中等** | 间距/圆角/阴影偏差 > 2pt、触摸目标 < 44pt | 必须修复后合并 |
| **轻微** | 注释不规范、CSS 类命名不一致 | 建议修复，可合并 |

### 7.2 审查流程

1. **自检**：开发者按本文档 §4.3 自检清单逐项检查
2. **同行评审**：另一位开发者进行代码审查
3. **设计验收**：设计师对照 Origin 截图验收
4. **QA 测试**：测试工程师进行功能和视觉测试

---

## 8. 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v1.0.0 | 2026-05-28 | 初始版本：强制性开发规则、Origin 视觉风格参考规范、组件使用规范、开发流程、视觉验收流程 |

---

**本文档为强制性开发规范，所有开发人员必须严格遵守。**