docs: add mobile settings homepage redesign spec

Author: pallyoung

docs/superpowers/specs/2026-05-17-mobile-settings-homepage-redesign-design.md

@@ -0,0 +1,362 @@
+# 移动端设置首页重做 · 设计文档
+
+> **版本：** 1.0
+> **日期：** 2026-05-17
+> **状态：** Draft（待评审）
+> **作者：** Codex
+
+---
+
+## 0. 文档说明
+
+### 0.1 目标
+
+重做移动端设置首页，修复当前首页混入旧版大圆角卡片语言、版心挤压和层级失衡的问题，让移动端首页重新回到与 PC 端一致的产品语气。
+
+本轮重点不是扩展设置能力，而是把移动端首页从“带说明区的独立大卡片列表”改成“紧凑分组式设置目录页”。
+
+### 0.2 本轮范围
+
+本轮只覆盖移动端设置首页根页面，即用户进入 `/settings` 且尚未进入任何具体分区时的界面。
+
+包含：
+
+- 首页信息重排
+- 首页 DOM 结构调整
+- 首页视觉语言重做
+- 首页回归测试与 UI preview 调整
+
+不包含：
+
+- 任意设置详情页的结构重做
+- 设置项业务逻辑变更
+- 桌面端设置页结构改动
+- 主题 token 体系重构
+
+### 0.3 现状与问题
+
+当前移动端首页主要由以下结构组成：
+
+- `packages/web/src/features/settings/components/settings-page.tsx`
+  - `renderMobileRoot()` 由 `settings-mobile-root-hero + settings-mobile-list + settings-mobile-item` 组成
+- `packages/web/src/styles/components.css`
+  - 移动端首页使用独立大卡片条目、说明型 hero 和较重的圆角/渐变
+
+当前问题集中在四点：
+
+1. 首页视觉语言与 PC 端设置页脱节
+2. 每个入口都是独立大卡片，移动端出现旧样式的“泡泡感”
+3. 说明型 hero 占用首屏空间，但没有提供真正必要的信息
+4. 条目和页边距的组合让页面产生“左窄右挤”的压缩观感
+
+---
+
+## 1. 设计目标与非目标
+
+### 1.1 设计目标
+
+- 去掉移动端首页的旧版大圆角卡片感
+- 首页风格向用户确认的 `B` 方向收敛，即更接近原生设置目录页的阅读节奏
+- 同时保留当前产品的工具型克制语气，而不是复制系统设置样式
+- 通过更紧凑的分组和连续行结构，让移动端与 PC 端设置页共享同一套层级逻辑
+- 保持现有导航状态机和设置分区能力不变，降低改动风险
+
+### 1.2 非目标
+
+- 不在本轮引入新的设置分区
+- 不在首页增加展开、折叠、搜索、筛选等额外交互
+- 不处理详情页的大规模视觉统一
+- 不重构 `settings-page.tsx` 的整体导航模型
+
+---
+
+## 2. 方案选择
+
+### 2.1 方案 A：工具面板式扁平入口列表
+
+去掉 hero，把所有入口做成一组扁平行，强调工具页感。
+
+优点：
+
+- 与桌面端语言最接近
+- 改造成本较低
+
+缺点：
+
+- 更像压缩版 PC 面板，不够贴近移动端浏览节奏
+- 容易做得过于硬朗
+
+### 2.2 方案 B：紧凑分组式目录页
+
+使用移动端原生设置页式的分组目录结构，但控制圆角、边框和密度，使其仍属于当前产品语言。
+
+优点：
+
+- 最符合用户选定方向
+- 可读性最好，能直接解决首页挤压和层级混乱
+- 便于后续将详情页逐步统一到同一语言
+
+缺点：
+
+- 需要重新组织信息层级
+- 需要调整现有测试和 preview 捕获点
+
+### 2.3 方案 C：混合式首页
+
+保留一个高频入口区，再加分组目录列表。
+
+优点：
+
+- 便于突出高频项
+
+缺点：
+
+- 首页会出现双层规则，体系复杂度上升
+- 当前只有四个主分区，收益有限
+
+### 2.4 结论
+
+本轮采用 **方案 B：紧凑分组式目录页**。
+
+原因：
+
+- 用户已明确选择 `B`
+- 当前问题本质是首页被旧卡片样式劫持，而不是缺少视觉强调
+- 首页信息量不大，最适合用简洁分组目录承载，而不是继续堆入口卡片
+
+---
+
+## 3. 信息架构
+
+### 3.1 首页层级
+
+移动端设置首页保留三层结构：
+
+1. 系统已有移动端页头
+2. 分组标题
+3. 分组内连续入口行
+
+移除内容：
+
+- `settings-mobile-root-hero`
+- 首页说明型文案区域
+- 首页强调型首屏模块
+
+### 3.2 分组与排序
+
+首页分为两个分组：
+
+1. `工作区与运行`
+   - `通用`
+   - `Providers`
+
+2. `界面与交互`
+   - `外观`
+   - `快捷键`
+
+排序原则：
+
+- 先放功能配置，再放偏个性化和习惯类设置
+- 让用户进入设置后的第一屏更偏“操作/运行相关”
+
+### 3.3 文案策略
+
+- 首页条目以主标签为主
+- 副文案从“默认展示所有项”调整为“仅在确有必要时显示”
+- 本轮默认保留轻量提示，但允许只对信息量更高的项显示副文案
+
+实现上不要求新增文案 key；优先复用现有 `getMobileSectionHintKey()` 返回的提示文案，并根据新布局决定是否对全部分区渲染提示
+
+---
+
+## 4. 视觉与交互设计
+
+### 4.1 页面框架
+
+- 保留现有 `MobilePageHeader`
+- 内容区直接进入分组列表
+- 内容区左右 gutter 使用统一移动端页面基线，不再额外制造首页专属挤压
+
+结果应表现为：
+
+- 页面外部留白稳定
+- 分组之间有呼吸感
+- 分组内部连续、紧凑
+
+### 4.2 分组容器
+
+每个分组使用单一连续容器承载，不再把条目渲染成彼此分离的大卡片。
+
+容器规范：
+
+- 轻量底色
+- 1 层弱边框
+- 中小圆角，建议落在 `10px - 12px`
+- 不使用明显浮起阴影
+
+设计意图：
+
+- 保留可识别的“分组块”
+- 去掉旧版独立卡片的鼓起感
+- 让移动端更接近 PC 的克制面板语言
+
+### 4.3 入口行
+
+每个入口为连续列表中的一行，而不是一张独立卡片。
+
+行项规范：
+
+- 行高建议 `56px - 64px`
+- 组内行与行之间使用分隔线
+- 行本体不单独描边、不单独做渐变卡面、不单独做阴影
+- 点击整行进入详情页
+
+这会替代现有 `.settings-mobile-item` 的大卡片结构。
+
+### 4.4 图标与箭头
+
+- 图标保留，但缩到辅助层级
+- 图标底板建议 `32px - 36px`
+- 图标底板使用中小圆角，不得回到大软胶囊样式
+- 右箭头保留为导航暗示，但视觉权重弱于标题
+
+### 4.5 文本层级
+
+- 标题为主，一行解决
+- 副文案弱化为辅助信息
+- 如果某项副文案对首页贡献低，可在实现中省略，以保持目录页紧凑度
+
+### 4.6 交互状态
+
+首页只承担目录跳转职责，不新增复杂交互。
+
+状态规范：
+
+- `hover/press` 使用轻量底色或边框变化
+- 不使用浮起动画表达按压
+- 分组标题不参与交互
+- 进入详情页的现有导航行为保持不变
+
+### 4.7 与 PC 对齐的规则
+
+移动端首页需要与 PC 端共享以下语气：
+
+- 不使用说明型 hero
+- 不使用旧版大圆角独立卡片
+- 不使用重渐变和过强的材质感
+- 保留清晰分组、克制边框和明确导航性
+
+这不是把 PC 缩放到手机上，而是让两端在“信息层级和面板语气”上属于同一产品。
+
+---
+
+## 5. 实现设计
+
+### 5.1 涉及文件
+
+- `packages/web/src/features/settings/components/settings-page.tsx`
+- `packages/web/src/styles/components.css`
+- `packages/web/src/features/settings/components/settings-page.test.tsx`
+- `packages/web/src/ui-preview/scenes/page-scenes.tsx`
+- `packages/web/src/ui-preview/scene-metadata.ts`
+
+### 5.2 JSX 调整策略
+
+保留当前状态机和跳转逻辑：
+
+- `navigationState`
+- `shouldShowMobileRoot`
+- `setNavigationState({ kind: "detail", section: id })`
+
+只重写移动端首页根结构：
+
+- 移除 `settings-mobile-root-hero`
+- 将单一列表改为带分组的结构
+- 继续复用 `availableSections` / section metadata / icon semantic
+
+必要时新增轻量的首页分组映射，但不改变 `SettingsSection` 模型本身。
+
+### 5.3 CSS 调整策略
+
+移除或废弃旧移动端首页视觉规则：
+
+- `.settings-mobile-root-hero`
+- `.settings-mobile-root-hero__eyebrow`
+- `.settings-mobile-root-hero__body`
+- 现有以独立大卡片为核心的 `.settings-mobile-item` 规则
+
+新增规则目标：
+
+- 首页分组容器
+- 分组标题
+- 连续行列表
+- 行项图标、文本和箭头布局
+- 更克制的移动端圆角和边框密度
+
+### 5.4 兼容性要求
+
+- 不破坏现有移动端详情页展示
+- 不影响桌面端设置页
+- 不改变 section id、翻译 key 和跳转逻辑
+- 不依赖新的设计 token 才能完成本轮
+
+---
+
+## 6. 测试与回归保护
+
+### 6.1 单元/组件测试
+
+更新或补充 `settings-page.test.tsx`，覆盖以下行为：
+
+- 移动端首页仍渲染全部设置入口
+- 首页入口顺序与新分组设计一致
+- 点击入口后仍能进入对应详情页
+- 旧 hero 结构不再存在
+- 新分组结构存在
+
+### 6.2 UI Preview
+
+保留 `settings-mobile-root` scene，用于移动端首页截图回归。
+
+需要同步检查：
+
+- `page-scenes.tsx` 中 scene 是否仍能稳定渲染首页态
+- `scene-metadata.ts` 中 capture selector 是否仍指向稳定的首页主体
+
+如果旧 selector 依赖 `.settings-mobile-list`，则应改为新首页根容器或更稳定的分组列表容器。
+
+### 6.3 手工验证重点
+
+- 中文环境下首页文案是否拥挤
+- 移动端首页左右 gutter 是否恢复正常
+- 分组外层和组内行项的圆角层级是否明显小于当前大卡片风格
+- 从首页进入详情页、再返回首页时状态是否正常
+
+---
+
+## 7. 风险与约束
+
+### 7.1 主要风险
+
+- DOM 结构变更可能导致现有测试选择器和 preview 捕获点失效
+- 如果副文案保留过多，首页仍可能显得松散
+- 如果分组容器和行项圆角没有拉开层级，仍会残留卡片感
+
+### 7.2 风险控制
+
+- 优先保持状态逻辑不变，只改首页结构与样式
+- 让“组容器圆角”和“行项自身无卡片化边界”形成明确区分
+- 用 scene capture 和组件测试双重保护首页回归
+
+---
+
+## 8. 验收标准
+
+完成后应满足以下标准：
+
+- 移动端设置首页不再出现说明型 hero
+- 首页入口不再是独立大圆角大卡片
+- 首页视觉密度明显收紧，消除“左窄右挤”的观感
+- 首页风格更接近原生设置目录页，但仍与 PC 端工具面板语言一致
+- 现有进入详情页和返回逻辑保持正常
+- 自动化测试和 UI preview 回归链路完成更新