# 移动端 Design System

## 1. 目标与边界

本规范是 `apps/user_app` 与 `apps/service_app` 的移动端视觉单一事实来源。目标是让新增页面默认满足 Material 3、iOS/Android 适配、暗色模式、无障碍和安全业务表达要求，同时避免两端复制主题后独立漂移。

Design System 负责：

- 品牌色、中性色、安全语义色、字体、间距、圆角、尺寸、动效和断点。
- Material 3 主题与无业务状态的展示组件。
- 页面层级、列表、表单、反馈、导航和安全提示的视觉规则。

Design System 不负责：

- 权限判断、任务状态机、金额计算、设备控制结果或风险等级判定。
- API DTO、领域模型、Repository、缓存或离线补传。
- 将尚未落地的业务能力包装成静态成功页面。

实现源位于 `apps/heqi_design_system`。业务 App 的 `ui/core` 仅保留兼容适配或业务专用组件，不得复制公共主题实现。

## 2. 设计原则

1. **安全可信**：红色只用于危险、失败、阻断和破坏性操作；请求成功不能伪装成设备执行成功。
2. **内容优先**：通过字号、留白和对比建立层级，避免依靠 Card 堆叠。
3. **平台原生**：优先使用 Material/Cupertino 可访问控件，支持系统返回、字体缩放和 Safe Area。
4. **语义驱动**：页面使用 `ColorScheme`、TextTheme 和公共组件，不读取裸色值。
5. **渐进披露**：现场作业、注册和退款等复杂流程分组展示，错误紧邻问题并提供恢复入口。
6. **双端一致、品牌有别**：中性色、安全色和组件行为共享；用户端使用安全蓝，服务端使用作业靛蓝。

## 3. Tokens

### 3.1 Color

| Token | Light | 用途 |
| --- | --- | --- |
| `consumerPrimary` | `#2563EB` | 用户端品牌、主要操作 |
| `servicePrimary` | `#4F46E5` | 服务端品牌、主要操作 |
| `success` | `#16875D` | 已通过、已确认、完成 |
| `warning` | `#B86400` | 待处理、未配置、临近风险 |
| `danger` | `#C7352A` | 危险、失败、阻断、删除 |
| `lightBackground` | `#F7F8FA` | 亮色页面背景 |
| `darkBackground` | `#0B1220` | 暗色页面背景 |
| `darkSurface` | `#111827` | 暗色内容表面 |

业务页面不得使用 `Colors.red/green/orange` 或裸 `Color(0x...)` 表达状态。状态必须同时包含文字或图标，不能只依赖颜色。

### 3.2 Typography

不绑定网络字体，使用 iOS/Android 系统中文字体回退。所有页面使用 Material 3 类型角色：

| Role | Size/Line height | Weight | 用途 |
| --- | --- | --- | --- |
| `displaySmall` | 32/40 | 700 | 关键金额与核心结果 |
| `headlineMedium` | 28/36 | 700 | 页面主标题 |
| `headlineSmall` | 24/32 | 700 | 重要状态标题 |
| `titleLarge` | 22/28 | 600 | 区块标题 |
| `titleMedium` | 16/24 | 600 | 列表标题 |
| `bodyLarge` | 16/24 | 400 | 主要正文与表单 |
| `bodyMedium` | 14/22 | 400 | 辅助正文 |
| `labelLarge` | 14/20 | 600 | 按钮与主要标签 |
| `labelSmall` | 12/16 | 500 | 状态与非关键说明 |

必须支持系统字体放大；正文不低于 14sp，12sp 仅用于非关键说明。

### 3.3 Spacing、Radius、Size

- 间距：`4 / 8 / 12 / 16 / 20 / 24 / 28 / 32 / 40 / 48dp`。
- 圆角：`10 / 12 / 16 / 20 / 24dp`。
- 页面横向边距：紧凑屏 20dp，宽屏 28dp。
- 内容最大宽度：720dp。
- 主要按钮高度：52dp。
- 最小触控区：48×48dp，满足 Android 48dp 与 iOS 44pt 下限。
- 底部导航高度：72dp，并保留系统安全区。

### 3.4 Motion

- `fast 150ms`：按压、焦点、轻量状态。
- `standard 220ms`：展开、切换、内容替换。
- `emphasized 300ms`：页面级重要状态变化。
- 动效只表达因果和层级，不使用装饰性无限动画。
- 必须尊重系统 Reduced Motion，加载动画除外。

## 4. 组件规则

### 4.1 Layout

- `HeqiGutter`：统一页面宽度和自适应边距。
- `HeqiSectionHeader`：区块标题、说明与可选尾部操作。
- `HeqiSurfaceSection`：同组内容容器；普通设置项放入同一个 Section，不得每行单独 Card。
- 独立可点击业务实体可以使用 Card，但同一屏不宜连续出现超过三个同权重 Card。

### 4.2 Status and feedback

- `HeqiStatusPill`：短状态标签，必须使用语义 tone。
- `HeqiMessageState`：空、错、不可用状态；错误应提供恢复动作。
- 高风险事件、自动关阀和禁止作业应使用独立 Safety Banner，包含原因、影响、状态和下一步。
- 超过 300ms 的操作显示加载反馈；提交期间按钮禁用并保持尺寸稳定。

### 4.3 Forms

- 每个字段必须有可见 Label，复杂字段提供 Helper Text。
- 错误显示在对应字段附近，说明原因与修复方法。
- 密码字段提供显示/隐藏；手机号、验证码、密码使用对应系统键盘和 Autofill。
- 长表单应保存草稿，离开前确认未保存内容。

### 4.4 Navigation and actions

- Bottom Navigation 只承载 3–5 个顶层目的地，图标和文字同时存在。
- 每屏只设置一个主要 FilledButton；次要操作用 OutlinedButton；低权重操作用 TextButton。
- 破坏性操作使用 error 语义色，并与主操作保持至少 20dp 间距。
- 深层页面不得重复创建顶层 AppBar 或 Bottom Navigation。

## 5. 页面模式

### 用户端

- 登录/注册：品牌区 → 表单 → 单一主操作 → 协议与辅助入口。
- 首页：页面介绍 → 当前服务/安全概览 → 内容区块。
- 商城：商品列表为同组 Surface，商品是独立 Row；价格和购买操作优先于装饰。
- 订单：顶层 Tab 管理分类，子列表使用 embedded 模式，不嵌套 AppBar。
- 我的：身份概览 → 资产概览 → 账户与服务列表 → 独立退出操作。

### 服务端

- 作业前检查：准入总结果 → 检查项列表 → 单一进入/打卡操作。
- 任务列表：岗位概览 → 任务数量 → 可扫描的任务 Row。
- 任务详情：任务状态 → 服务信息 → 主流程操作 → 独立异常操作。
- 现场取证：安全暂存说明 → 完成进度 → 取证项 → 结论 → 提交。
- 我的工作台：人员/在岗状态 → 钱包与草稿 → 作业检查 → 独立退出操作。

## 6. 版本与贡献流程

1. 在设计评审中说明新增 Token/组件解决的跨页面问题，避免为单页创建公共 API。
2. 先修改 `apps/heqi_design_system`，再在两个 App 中验证兼容性。
3. 新组件必须提供亮色、暗色、禁用、加载、错误和大字体状态。
4. 公共组件不接收数据库 ID，不包含业务状态机，不直接访问网络或存储。
5. 每次变更更新包版本与本规范的“变更记录”。

版本规则：

- MAJOR：删除或重命名 Token/组件、改变公共行为。
- MINOR：新增兼容 Token、组件或品牌主题。
- PATCH：不改变 API 的对比度、布局、语义或缺陷修复。

## 7. 验收清单

- `flutter analyze` 和 `flutter test` 在共享包及两个 App 均通过。
- Android、iOS、Web 至少执行对应构建验证；受环境限制未执行的平台必须说明。
- 375px 小屏、横屏、平板宽度均无横向溢出。
- 亮色和暗色分别检查文字、边框、状态和弹层对比度。
- 大字体下无关键文本截断，读屏顺序与视觉顺序一致。
- 所有触控目标至少 48dp，固定操作不被系统安全区遮挡。
- 页面中不存在裸状态色、重复主题实现或无解释的禁用操作。

## 8. 变更记录

| 版本 | 日期 | 内容 |
| --- | --- | --- |
| 0.1.0 | 2026-08-10 | 建立共享 Flutter 包、双品牌 Material 3 主题、基础 Token 与布局/状态组件。 |