新增文档说明

spec_kit/Card UI/spec.md

@@ -0,0 +1,110 @@
+# Card UI（高层规范）
+
+## 1. 背景与目标
+
+当前卡片页（Home/情绪卡片滑动页）右上角需要提供两个入口：
+
+- **切换主题**：在「风景」与「颜色」两种主题间切换
+- **个人主页**：以弹窗形式打开个人主页（样式与主题弹窗一致的弹窗体系）
+
+本需求聚焦 **UI 视觉统一** 与 **交互逻辑收敛**，让用户在卡片页可以快速切换主题、进入个人主页设置与通用入口。
+
+### 目标
+
+- **右上角双按钮**：两个圆形图标按钮常驻卡片页右上角
+- **主题弹窗**：可选择「风景 / 颜色」两种主题，并即时生效
+- **个人主页弹窗**：点击进入个人主页弹窗（与主题弹窗同一套弹窗/遮罩/圆角规范）
+- **资源统一**：图标资源使用 `client/assets/images/home/`（`theme.svg`、`my.svg`）
+
+### 非目标（本阶段不做）
+
+- 不引入复杂的主题系统（如多套配色、动态主题下载、远端配置等）
+- 不做账号体系/登录注册（个人主页弹窗仅作为本地个人中心入口与设置集合）
+- 不做完整的卡片滑动动效重构（仅限卡片页头部与相关弹窗/局部逻辑优化）
+
+## 2. 范围与交付物
+
+### 范围
+
+- 卡片页（Home）头部 UI：右上角两个圆形 icon 按钮
+- 主题弹窗：展示两种主题选项（风景/颜色）并支持选择
+- 个人主页弹窗：展示个人信息与快捷入口（以弹窗呈现）
+- 主题状态：本地持久化 + 启动后读取 + 在卡片页即时反映
+
+### 交付物
+
+- 卡片页头部 UI 更新（两按钮替换/补齐）
+- 主题弹窗与个人主页弹窗的 UI 与交互逻辑（共用弹窗规范）
+- 主题选择的本地存储 key 约定与读写逻辑
+- （可选）补充 i18n key（按钮无文本，但弹窗标题/选项文案需多语言）
+
+## 3. 视觉与交互需求
+
+### 3.1 右上角按钮（主题 / 我的）
+
+- **位置**：卡片页右上角，两个按钮水平排列，间距 8–12（按视觉微调）
+- **形状**：圆形按钮，背景为浅色圆底（与现有 UI 风格一致），点击区域需足够大（建议 `hitSlop >= 10`）
+- **图标**：
+  - 主题：`client/assets/images/home/theme.svg`
+  - 我的：`client/assets/images/home/my.svg`
+- **点击反馈**：按平台规范（透明度/水波纹）即可
+
+### 3.2 主题弹窗
+
+- **打开方式**：点击右上角「主题」按钮打开
+- **样式**：与现有弹窗体系一致（遮罩 + 圆角容器），可做底部弹窗或中间弹窗，需与设计稿一致
+- **内容**：
+  - 标题：主题
+  - 选项：
+    - 风景（预览图/缩略图）
+    - 颜色（预览图/缩略图）
+  - 当前选中项需有明显高亮（描边/勾选/阴影等，按设计稿）
+- **交互**：
+  - 点击选项即切换主题并立即生效
+  - 点击遮罩或关闭按钮关闭弹窗
+
+### 3.3 个人主页弹窗（我的）
+
+- **打开方式**：点击右上角「我的」按钮打开
+- **样式**：与主题弹窗同一套弹窗规范（遮罩、圆角、关闭按钮/手势）
+- **内容建议（以现有设计为准）**：
+  - 顶部区域：头像/插画 + 用户昵称（本地默认名或 onboarding 的 name）
+  - 快捷卡片：我的喜欢、小组件（或其他产品定义入口）
+  - 通用列表：每日提醒、隐私政策、使用条款、语言
+- **交互**：
+  - 列表项点击进入对应页面/二级弹窗（实现阶段在 plan/tasks 中细化）
+  - 关闭方式同主题弹窗
+
+## 4. 主题逻辑与状态管理
+
+### 4.1 主题类型
+
+- `scenery`：风景主题（以图片/风景背景为主）
+- `color`：颜色主题（以纯色/渐变色块为主）
+
+### 4.2 持久化 Key（建议）
+
+- `ui.theme.mode`: `'scenery' | 'color'`
+
+### 4.3 生效范围（建议）
+
+- 最低要求：卡片页背景/卡片背景/主题弹窗预览在切换后 **立即更新**
+- 可扩展：全局统一（如 Settings/我的页）在后续版本做全局 Theme Provider
+
+## 5. 验收标准
+
+- 卡片页右上角展示两个圆形图标按钮，点击热区合理
+- 点击主题按钮：
+  - 打开主题弹窗，显示「风景/颜色」两项
+  - 切换后立即生效并持久化，重新进入 App 仍保持上次选择
+- 点击我的按钮：
+  - 打开个人主页弹窗
+  - 弹窗样式（遮罩/圆角/关闭）与主题弹窗一致
+- 图标资源从 `client/assets/images/home/` 加载，显示清晰无拉伸
+
+## 6. 风险与注意事项
+
+- **SVG 兼容**：需要确认当前项目 SVG 渲染方案（如 `react-native-svg` / `expo` 方案），避免不同平台显示差异
+- **路由与弹窗体系**：若使用 `expo-router` 的 `Stack` modal，需要统一交互（遮罩、圆角、返回手势）以匹配设计
+- **多语言**：弹窗标题、列表项文案需走 i18n（`zh-CN/en/es/pt/zh-TW`）
+