brainwave/docs/ux-design.md

UX 与东方视觉规范

状态：MVP 设计基线 适用范围：Android 手机优先，兼顾横屏、平板和系统无障碍设置 当前实现：Compose 已覆盖方法说明、回访首页、起念、六轮手录、卦名/动爻结果和保存设置；问卦簿列表、「解」与授权卦辞仍未进入应用，不能把本文件尚未实现的页面当成已上线功能

1. 体验定位

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

产品体验不是：

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

产品体验是：

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

2. 信息架构

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

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

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

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

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

3. 场景与页面契约

3.1 欢迎与方法说明

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

必须说明：

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

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

3.2 回访首页与功能扩展

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

首页层级固定为：

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

扩展规则：

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

3.3 起念

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

交互规则：

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

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 与 Compose 无障碍的最新官方指南。