nex/openspec/specs/theme-toggle/spec.md

主题切换

Purpose

管理主题状态与应用，使用 React Context 提供全局主题配置，支持多主题切换和持久化。

Requirements

Requirement: 持久化主题偏好

前端 SHALL 使用 localStorage 持久化用户的主题偏好。

Scenario: 保存主题偏好

• WHEN 用户选择主题或切换跟随系统开关
• THEN 前端 SHALL 将主题 ID 保存到 localStorage 键 nex-theme-id
• THEN 前端 SHALL 将跟随系统偏好保存到 localStorage 键 nex-follow-system

Scenario: 恢复主题偏好

• WHEN 用户重新访问前端应用
• THEN 前端 SHALL 从 localStorage 读取 nex-theme-id
• THEN 前端 SHALL 从 localStorage 读取 nex-follow-system
• THEN 如果 nex-theme-id 不存在或无效，SHALL 使用 'default'
• THEN 如果 nex-follow-system 不存在，SHALL 使用 false

Scenario: 刷新页面保持设置

• WHEN 用户在任意主题和跟随系统设置下刷新浏览器
• THEN 前端 SHALL 保持用户的选择

Requirement: 使用 React Context 管理主题状态

前端 SHALL 使用 React Context 提供全局主题状态。

Scenario: 主题 Context 提供

• WHEN 应用初始化
• THEN ThemeContext SHALL 提供 themeId（当前选择的主题 ID）
• THEN ThemeContext SHALL 提供 followSystem（跟随系统开关状态）
• THEN ThemeContext SHALL 提供 systemIsDark（OS 暗色模式状态）
• THEN ThemeContext SHALL 提供 effectiveThemeId（计算后的实际主题 ID）
• THEN ThemeContext SHALL 提供 setThemeId（设置主题方法）
• THEN ThemeContext SHALL 提供 setFollowSystem（设置跟随系统方法）

Scenario: 主题 Context 使用

• WHEN 组件需要访问或修改主题
• THEN 组件 SHALL 使用 useTheme hook
• THEN useTheme SHALL 返回当前主题状态和操作方法
• THEN 在 ThemeProvider 外使用 useTheme SHALL 抛出错误

Scenario: 计算有效主题

• WHEN followSystem 为 true 且 systemIsDark 为 true
• THEN effectiveThemeId SHALL 为 'dark'
• WHEN followSystem 为 true 且 systemIsDark 为 false
• THEN effectiveThemeId SHALL 为 themeId
• WHEN followSystem 为 false
• THEN effectiveThemeId SHALL 为 themeId

Requirement: 集成 Ant Design ConfigProvider

前端 SHALL 使用 ConfigProvider 应用主题到 Ant Design 组件，包括侧边栏。

Scenario: ConfigProvider 主题配置

• WHEN 渲染应用
• THEN 前端 SHALL 使用 ConfigProvider 包裹应用
• THEN ConfigProvider 的 theme 属性 SHALL 由当前 effectiveThemeId 对应的主题配置决定
• THEN 配置 SHALL 包含完整的 algorithm、token 和组件样式覆盖

Scenario: 组件自动应用主题

• WHEN 主题切换
• THEN 所有 Ant Design 组件 SHALL 自动应用新主题
• THEN 主题切换 SHALL 平滑过渡，无闪烁

Scenario: 侧边栏响应主题切换

• WHEN effectiveThemeId 发生变化
• THEN 侧边栏的 Menu theme SHALL 同步切换为 'light' 或 'dark'
• THEN 侧边栏 Sider 背景颜色 SHALL 同步切换为对应的亮色或暗色
• THEN Logo 文字颜色 SHALL 同步适配侧边栏主题