# 暗色模式模块

## 概述
追光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 暗色变量
```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