zhuiguang-ai/.trae/specs/modules/theme.md

暗色模式模块

概述

追光AI支持浅色/暗色双主题模式，通过 ThemeProvider + CSS 变量驱动，用户偏好自动持久化到 localStorage，整体遵循 Tailwind CSS class 策略。

架构

ThemeProvider (Context)
    ├── 读取 localStorage 初始主题
    ├── 监听系统 prefers-color-scheme 变化
    ├── 在 <html> 上切换 "dark" class
    └── 提供 toggle/setTheme 方法给子孙组件

---

核心组件

ThemeProvider

• 文件: src/components/ThemeProvider.tsx
• 位置: 根 layout.tsx 包裹
• 功能:
  • theme state: "light" | "dark" | "system"
  • toggleTheme() — 在 light/dark 间切换
  • setTheme(mode) — 设置为指定模式
  • 自动监听 prefers-color-scheme 媒体查询（system 模式时）
  • 持久化到 localStorage("zhuiguang-theme")

Header 主题切换按钮

• 文件: src/components/layout/Header.tsx
• 太阳 ☀️ / 月亮 🌙 图标切换
• 点击调用 toggleTheme()
• 动画过渡效果

---

CSS 变量系统

globals.css 暗色变量

:root {
  /* 浅色主题变量 (默认) */
  --background: 0 0% 100%;
  --foreground: 222 47% 11%;
  /* ... */
}

.dark {
  /* 暗色主题变量覆盖 */
  --background: 222 47% 11%;
  --foreground: 210 40% 98%;
  /* ... */
}

• 使用 HSL 变量，Tailwind 通过 hsl(var(--xxx)) 引用
• shadcn/ui 组件自动适配暗色模式（基于 .dark class）

---

组件适配（14个文件已更新）

以下组件已适配暗色模式：

组件	适配内容
Header	主题切换按钮、导航栏背景色
Footer	页脚背景色、文字色、分隔线
HeroBanner	Canvas 粒子颜色随主题切换
HomePageClient	卡片背景、文字颜色
ToolsContent	搜索框、筛选侧边栏、卡片
SkillsPageClient	技能卡片、分类标签
社区相关组件	ForumBoard/ForumTopicCard/ForumEditor
通知组件	NotificationBell/NotificationCenter
用户中心	积分卡片、等级进度条
工具详情	信息面板、推荐列表
技能详情	评测卡片、详情面板
后台管理	管理面板所有表格/表单

---

设计规范

浅色主题

• 背景: bg-white / bg-muted/50
• 卡片: bg-white/80 (毛玻璃) / bg-white/60 (卡片)
• 边框: border-border/40
• 阴影: shadow-sm

暗色主题

• 背景: bg-background (HSL 222 47% 11%)
• 卡片: bg-card (HSL 222 47% 13-15%)
• 边框: border-border (HSL 215 20% 25%)
• 阴影: shadow-md (更明显的阴影)

颜色规范（双主题通用）

• 文字: 浅色 -600/-700 | 暗色 -300/-200
• 背景: 浅色 -50 | 暗色 -900/-950
• 边框: 浅色 -200/60 | 暗色 -700/60

---

技术实现要点

闪烁防护

• ThemeProvider 在 useEffect 中初始化，避免 SSR 时的主题闪烁
• <html> 上通过内联 script 在 hydration 前设置 class（防止白屏闪烁）

系统主题跟随

• matchMedia('(prefers-color-scheme: dark)') 监听
• 用户手动设置后覆盖系统偏好
• "system" 模式时动态跟随

持久化策略

• 存储键: zhuiguang-theme
• 值: "light" | "dark"
• 优先级: localStorage > 系统偏好 > 默认 light