brainwave/docs/ux-design.md

# UX 与东方视觉规范

> 状态：MVP 设计基线
> 适用范围：Android 手机优先，兼顾横屏、平板和系统无障碍设置

## 1. 体验定位

界面要让用户感到“安静、清楚、有分寸”。东方文化来自流程、文字、材料感和留白，不来自堆叠符号。

产品体验不是：

- 制造神秘权威的算命工具；
- 抽卡、开盲盒或“再测一次”的成瘾循环；
- 复刻古籍页面而牺牲现代触控和可读性。

产品体验是：

- 一段从起念、投币、观象到落事的缓慢反思流程；
- 原始文化材料与现代解释层次分明；
- 保留用户自主判断，随时可以退出、不保存或不调用 AI。

## 2. 信息架构

MVP 顶层不需要底部导航。首次欢迎与回访首页是不同状态；核心流程仍保持线性，并使用单 Activity 和清晰的返回行为：

```text
首次欢迎/方法说明
└── 回访首页
    ├── 开始一问 → 起念
    └── 最近一次 / 问卦簿

起念
    └── 投币（1/6…6/6）
        └── 结果
            ├── 本地解释
            └── AI 解释（需同意）

次级入口
├── 历史（启用后）
├── 方法说明
├── 内容来源
└── 设置与隐私
```

投币流程返回时保留已经确认的轮次；从结果页返回不能导致重新计算。预测性返回手势必须与系统导航兼容。

## 3. 场景与页面契约

### 3.1 欢迎与方法说明

目的：在第一次起卦前建立边界和方法。

必须说明：

- “你投币，应用记录；AI 不参与起卦。”
- “字为 2，背为 3；第一次是初爻，由下而上。”
- “结果用于整理想法，不替你做决定。”

主操作只有一个：“开始”。“查看方法”是次级文本操作，不制造必须完成的教程轮播。

### 3.2 回访首页与功能扩展

目的：让回访用户快速开始新的一问，同时能回看默认保存在本机、由自己控制的记录。

首页层级固定为：

1. 唯一主操作“开始一问”；
2. “你的观照”次级区域；
3. 存在记录时显示最近一次及“查看问卦簿”；无记录时显示简短空态和隐私说明。

扩展规则：

- 不展示“敬请期待”、禁用卡片或空宫格；只有已上线且用户可进入的功能才出现。
- MVP 只显示问卦簿，不为了预留而引入底部导航。
- 当出现至少 3 个长期、同级、需要频繁切换的顶层功能时，才评估带文字标签的底部导航；最多 5 项。
- “最近一次”由历史查询派生，不复制问题或解释正文；记录删除后首页同步显示下一条或空态。
- 最近卡片必须同时显示日期、卦名、动爻概况和解释来源；问题因设置或当次选择未保存时明确写“未保存问题原文”。
- 首页在主操作附近持续显示：“起卦与历史默认保存在本机，不主动上传。只有你选择 AI 解读时，本次所需内容才会发送。”末尾提供可点击的“管理保存设置”，但不能把设置做成开始流程的前置门。

### 3.3 起念

页面标题可使用“此刻，你在为何事迟疑？”。问题输入框有固定标签“正在纠结的事”，辅文提示尽量描述事实、选择和顾虑，不要求生日、性别等无关信息。

交互规则：

- 多行输入，支持系统输入法和字体缩放；
- 离开页面时在会话内保留草稿；
- 默认不把问题发送到网络；
- 用户可选择“不写具体内容，直接开始”，最终是否允许空值见[决策记录](decisions.md#未决问题)。

### 3.4 投币

页面始终显示：

- 当前轮次，如“第三爻 · 3/6”；
- 三个独立的铜币录入控件；
- “字 · 2 / 背 · 3”的当前约定；
- 已确认的爻从下向上累积显示；
- 一个主按钮“确认这一爻”。

铜币控件不得仅靠拟真图片表达正反面；图形旁必须有“字/背”文本和选中语义。三个控件触控区域均不小于 48×48dp。

每次确认可以有一次轻触觉反馈和 150–250ms 的爻线出现动画。不得使用持续摇晃、金币飞散、音效倒计时或强制等待。开启“减少动态效果”时直接更新状态。

### 3.5 成卦与观象

信息优先级：

1. 本卦卦象、编号和名称；
2. 动爻位置；
3. 之卦（若与本卦不同）；
4. 卦辞与实际动爻文本；
5. 「解」按钮。

卦象使用 Compose `Canvas` 或稳定的 Compose 图元绘制，不使用包含文字的位图。无障碍描述示例：“第 24 卦，复；初爻阳，其余为阴；初爻为动爻”。

原文、本地白话和 AI 解释必须有明确标签，不使用视觉相似但来源不明的段落混排。

### 3.6 解读与落事

「解」是结果页唯一主操作。点击后先选择或显示当前方式：

- “本地解读”：立即、离线，不发送问题；
- “AI 解读”：说明将发送问题、本卦、之卦和动爻文本，首次需要明确同意。

AI 加载超过 300ms 时显示内联进度；按钮在请求期间禁用，避免重复提交。超时后显示“保留当前结果，可重试或改用本地解读”，不能把结果页替换为空白错误页。

结尾固定使用“可以试的一小步”区域，包含时间范围和撤销方式；它是建议，不是判词。

### 3.7 保存与问卦簿

第六爻确认并生成结果后，默认在后台立即创建本机会话。结果页在不打断阅读的位置显示“已保存到本机问卦簿”，并提供次级操作“本次不保存/删除本次记录”；它们不能抢占结果页唯一主操作「解」。自动保存关闭时，同一位置显示“本次未保存”和“保存本次”。

设置页必须提供以下控制：

- “自动保存完整记录”，默认开启；
- “保存问题原文”，默认开启；
- “保存解读全文”，默认开启；
- “保存行动记录”，默认开启；
- “清空全部问卦记录”，使用危险操作样式并再次确认。

关闭总开关后，三个内容开关保持其值但在界面中同步停用，便于再次开启时恢复用户偏好。总开关不影响未完成草稿的进程恢复，也不能改变 AI 同意状态。

保存边界必须分层说明：

- 固定快照包含 18 枚币面、六爻结果、动爻、方法版本和内容版本；
- 问题原文、当次解读和行动记录由各自开关控制；
- 未完成问题与投币只用于当前流程恢复，不进入问卦簿；
- 存储范围是应用私有本机存储，默认不进入系统备份、设备迁移或云同步；
- 本地保存与 AI 发送是两个独立决定，自动保存绝不触发网络请求。

本地或 AI 解读在生成后应自动关联到当次会话，并给出轻量的“已加入本次记录”反馈。重新解读默认新增版本；若产品只保留一个版本，覆盖前必须让用户明确确认。

问卦簿要求：

- 列表按保存时间倒序，展示卦名、动爻概况、问题保存状态和解释来源；
- 空状态说明“完成起卦后会默认保存在本机；你可以在设置中关闭”，并提供“开始第一次记录”和“管理保存设置”；
- 详情展示保存时的卦象快照、问题状态、解释来源、方法/内容版本和可选行动；
- 删除使用明确确认对话框，并级联删除该会话关联的解释和行动记录；
- “清空全部”必须在设置或问卦簿菜单中二次确认，并清楚说明不可恢复范围；
- 返回列表后保留原滚动位置；从问卦簿开始新流程时，返回行为不得跳到首次欢迎页。

## 4. 视觉系统

### 4.1 风格关键词

内容优先、纸张感、墨色、高留白、细线、克制朱砂、现代中文排版。

避免：龙凤、满屏祥云、旋转太极、金色发光、仿古卷轴、低对比度水墨、正文毛笔字、伪造印章和无意义繁体字。

### 4.2 颜色令牌

以下是起始令牌，不允许在页面中散落硬编码颜色：

| 语义 | 浅色主题 | 用途 |
|---|---|---|
| `background` | `#F7F2E8` | 暖纸背景 |
| `surface` | `#FFFDF7` | 正文和卡片表面 |
| `onBackground` | `#1F1B16` | 墨色主文字 |
| `onSurfaceVariant` | `#655E55` | 次级说明 |
| `primary` | `#8C2F2B` | 朱砂主操作、动爻强调 |
| `onPrimary` | `#FFFFFF` | 主操作文字 |
| `secondary` | `#765D3E` | 旧铜色次级强调 |
| `outline` | `#B9AEA0` | 分隔线和输入边界 |
| `error` | Material 语义错误色 | 错误，不与朱砂强调混用 |

深色主题不是简单反色。建议使用近墨背景、暖白正文和降低饱和度的朱砂色，并独立验证所有对比度。最终令牌以无障碍测试结果为准。

### 4.3 字体与排版

- 标题、卦名、短卦辞可使用授权清晰的思源宋体/Noto Serif CJK 子集。
- 按钮、输入、长篇说明和系统信息使用系统中文无衬线或思源黑体。
- 毛笔字体只允许出现在经过审查的品牌字形中，不能用于正文和关键操作。
- 正文基准不小于 16sp，行高约 1.5–1.7；长文在平板上限制行宽。
- 所有字号通过 `MaterialTheme.typography` 语义令牌提供，不在 Composable 中硬编码。

字体资源必须评估 APK 体积、授权和字形覆盖；不能为了视觉一致性下载不明来源字体。

### 4.4 形状与材质

- 使用 4/8dp 间距体系，页面以 24dp 左右的宽松留白为主。
- 卡片圆角克制，避免所有内容都成为悬浮大圆角卡片。
- 阴阳爻线、分隔线和图标使用统一粗细。
- 纸纹若使用，透明度必须极低、可移除，且不得影响滚动性能与文字对比度。
- 图标使用同一套矢量图标；Emoji 不作为结构性图标。

## 5. 动画与触觉

动画必须表达因果：确认一轮后，对应爻线从下向上出现；从本卦到之卦时，仅动爻发生形态过渡。

- 触控反馈在 100ms 内出现。
- 微动画通常为 150–300ms，复杂过渡不超过 400ms。
- 一屏同时动画的重点元素不超过两个。
- 动画可中断，不阻止返回和触控。
- 系统减少动态效果时关闭非必要过渡。
- 触觉只用于确认单爻、完成六爻和显式错误，不对滚动或普通切换连续震动。

## 6. 无障碍验收

- 所有交互目标至少 48×48dp，邻近目标间距至少 8dp。
- 正文与背景对比度至少 4.5:1；大图形和非文字元素至少 3:1。
- 动爻同时使用颜色、形状/符号和文字说明。
- 读屏顺序与视觉顺序一致；卦象有完整语义描述，装饰纸纹不进入语义树。
- 最大系统字体下无关键文字截断，主按钮仍可见或可滚动到达。
- 横屏、小屏和大屏不产生水平滚动；长文在平板上限制阅读宽度。
- 错误信息靠近问题控件，包含原因和恢复动作。

## 7. 文案规范

推荐语气：平实、留有余地、说明来源。

| 避免 | 推荐 |
|---|---|
| “此卦预示你一定会成功” | “这段材料提醒你留意……” |
| “现在绝不能辞职” | “在不可逆决定前，可以先验证一个较小假设” |
| “AI 大师解卦” | “AI 解读” |
| “再算一次改变运势” | “重新开始一段记录” |
| “结果加载中”用于本地计算 | 本地结果即时展示 |

解释中的经典文本、编辑撰写的本地白话、AI 生成内容必须分别标注。

## 8. UI 完成检查表

- [ ] 每屏只有一个主操作。
- [ ] 投币进度和计值约定始终可见。
- [ ] 卦象不是包含文字的位图。
- [ ] 动爻不只靠颜色表达。
- [ ] 本地与 AI 内容来源可辨认。
- [ ] 加载、空、离线、超时和非法响应均有恢复路径。
- [ ] 浅色、深色、最大字体、读屏、减少动态效果均验证。
- [ ] 无龙凤祥云等与功能无关的“古风贴图”。

本规范采用内容优先、纸张阅读、低动态和宽松密度的移动端设计原则，并结合 Android 原生交互要求。工程实现仍应遵循 [Material 3](https://m3.material.io/) 与 [Compose 无障碍](https://developer.android.com/develop/ui/compose/accessibility)的最新官方指南。