platforms/docs/13-移动端Design-System.md

移动端 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 与布局/状态组件。