docs: add comprehensive UI design principles document

docs/DESIGN_PRINCIPLES.md

@@ -0,0 +1,105 @@
+# 天书 TianShu — UI 设计原则
+
+> "画面为王，UI 为仆。让玩家忘记这是软件，记住这是故事。"
+
+---
+
+## 1. 内容优先（Content First）
+
+画面是主角，UI 是配角。
+
+| 规则 | 实践 | 反例 |
+|------|------|------|
+| **画面满铺** | 视频/流程图占屏幕 100%，UI 叠加不遮挡 | 在画面四周加边框或 logo |
+| **信息分区** | 核心内容 → 满铺；操作按钮 → 边角；统计数据 → 底栏 | 面板居中、内容四周留大片空白 |
+| **面积比** | 画面 : 底栏 : 边角按钮 ≈ 8 : 1.5 : 0.5 | 一个面板占 60% 屏幕面积 |
+
+---
+
+## 2. 最少 UI（Minimal UI）
+
+能删的按钮一定要删。
+
+| 规则 | 实践 | 反例 |
+|------|------|------|
+| **一个操作一个入口** | 关闭弹窗只用 `← 返回` 或 Esc，不加 ✕ | 同时有返回按钮 + ✕ 按钮 + 点击遮罩关闭 |
+| **不对称优于对称** | `[← 返回] 标题______________` | `[返回]___标题居中___[✕]` |
+| **物理优先** | 用 Esc / 点击遮罩 / 滚轮操作，减少可见按钮 | 面板底部放一排操作按钮 |
+| **选项 ≤ 3 个** | 任何时刻最多 3 个选择（参考 Netflix Bandersnatch） | 满屏 6-8 个选项 |
+
+---
+
+## 3. 一致性（Consistency）
+
+同一件事，同一个地方，同一种颜色。
+
+| 规则 | 实践 |
+|------|------|
+| **同功能同位置** | 所有弹窗关闭方式统一为左上角 `← 返回` |
+| **同操作同交互** | 卡片 hover 缩放/发光效果全项目统一 |
+| **颜色语义统一** | `#c9a84c` 金色 = 已完成/已解锁/可交互；灰色 = 不可用/未解锁 |
+
+---
+
+## 4. 渐进展示（Progressive Disclosure）
+
+信息不是一次性堆满，而是层层展开。
+
+| 规则 | 实践 | 反例 |
+|------|------|------|
+| **先见森林后见树木** | 进入页面先看到核心（流程图），滚到底才现进度条，点击才展开详情 | StoryGallery 一屏展示全部信息 |
+| **折叠优先** | 次要数据收进折叠区域，点击展开 | 平铺所有统计数据 |
+| **面板宽度 ≤ 60%** | 除流程图满铺外，其他面板不超过屏幕 60% | 全宽半透明面板 |
+
+---
+
+## 5. 氛围不打断（Immersive）
+
+过渡要柔，打断要轻。
+
+| 规则 | 实践 | 反例 |
+|------|------|------|
+| **背景不空** | 弹窗背景用半透明模糊，让上一层内容微微可见 | 纯 `#000` 或 `rgba(0,0,0,0.9)` 遮罩 |
+| **过渡不硬切** | 面板显隐用 `opacity 0.2-0.3s` 淡出淡入 | `v-if` 瞬间闪现/消失 |
+| **光标不突兀** | 无操作 3s 后 `cursor: none`，动则恢复 | 播放全程显示鼠标指针 |
+
+---
+
+## 6. 反馈灵敏（Responsive）
+
+每个操作都要有响应，每个状态都要有表达。
+
+| 规则 | 实践 | 反例 |
+|------|------|------|
+| **点击三态** | hover（色变/缩放）→ active（按下）→ focus-visible（键盘焦点） | 只有 flat 按钮无 hover |
+| **加载有状态** | 异步操作（加载/存档）有转圈或进度条 | 静默等待无反馈 |
+| **错误有提示** | toast 短暂浮现提示，不阻断操作 | `alert()` 弹窗 |
+
+---
+
+## 设计检查清单
+
+每次新增 UI 或修改布局时，逐条自查：
+
+- [ ] 主要信息是否占据最大面积？（内容优先 #1）
+- [ ] 每个按钮都是必需的吗？有没有可以删的？（最少 UI #2）
+- [ ] 操作入口是否唯一？关闭方式是否与项目其他位置一致？（一致性 #3）
+- [ ] 信息是否分层展示而非一屏堆满？（渐进展示 #4）
+- [ ] 背景有没有透出底层内容？过渡是否柔和？（氛围 #5）
+- [ ] hover / active / focus-visible 三态是否齐全？加载失败有没有提示？（反馈 #6）
+
+---
+
+## 业界参考
+
+| 来源 | 精髓 |
+|------|------|
+| **Netflix Bandersnatch** | 选项 ≤3 个、10 秒自动选择、播放时零 HUD |
+| **Apple tvOS HIG** | Focus Engine、声音反馈、间接操控 |
+| **PlayStation UX** | Safe Area（95% 区域）、字体 ≥ 24px |
+| **Quantic Dream (Detroit)** | 叙境式 UI（毛玻璃 + 电影感）、Diegetic UI |
+| **Supergiant (Hades)** | 极简 HUD、对话面板 ≤ 40% 屏幕 |
+
+---
+
+> "在游戏里，每一个像素都是借来的。从画面借的，迟早要还。"  —— 佚名