Prompt Perfector 是你的专属技术项目经理，只…

# 深色模式切换功能 · 完整技术方案Prompt

你可以直接把下面内容作为需求文档/Prompt交给开发者或AI编码助手使用。

---

一、需求背景与目标

• 技术栈：React（建议 React 18+）+ Tailwind CSS（建议 3.x）
• 目标：为官网增加深色/浅色模式切换按钮，支持手动切换 + 跟随系统偏好，刷新后保持用户选择
• 约束：不引入大型状态管理库，尽量轻量；不产生页面闪烁（FOUC）

二、技术方案要求

1. 深色模式策略

• 采用 Tailwind 的 dark: 类名策略（darkMode: 'class'），通过在 <html> 根元素上切换 dark 类实现
• 不推荐 media 策略（无法支持手动切换）

2. 状态管理

• 使用 React Context（ThemeContext）封装主题状态，提供 theme 与 toggleTheme
• 主题值仅两种：light / dark

3. 持久化与初始化

• 使用 localStorage 存储用户选择（key 自定义，如 theme）
• 初始化优先级：localStorage 中的用户选择 > 系统偏好（prefers-color-scheme）> 默认浅色
• 在 index.html 中加入一段内联阻塞脚本，在页面渲染前读取存储并设置 dark 类，避免刷新时闪烁

4. UI 组件

• 切换按钮置于导航栏右侧，使用太阳/月亮图标切换（可用 lucide-react 等轻量图标库）
• 按钮需有 aria-label，支持键盘操作，切换时加过渡动画（transition）
• 可选：支持三态切换（浅色/深色/跟随系统），若实现需在按钮上明确区分状态

5. 样式适配要求

• 全站颜色使用 Tailwind 语义色板（如 bg-white dark:bg-slate-900、text-gray-900 dark:text-gray-100）
• 重点检查：导航栏、页脚、卡片、表单输入框、图片边框、代码块等区域
• 避免硬编码 hex 颜色；阴影和边框在深色下需降低对比或调整透明度

三、验收标准

• [ ] 切换后全站无遗漏的亮色区域或刺眼对比
• [ ] 刷新页面主题不丢失、无闪烁
• [ ] 首次访问能正确跟随系统偏好
• [ ] 按钮具备无障碍属性（aria-label、焦点样式）
• [ ] Lighthouse 无障碍评分不低于当前水平

四、交付物

1. ThemeContext + 自定义 Hook（如 useTheme）

2. ThemeToggle 按钮组件

3. tailwind.config.js 配置修改说明

4. index.html 内联初始化脚本

5. 简要接入文档（如何在其他组件中使用）

---

使用提示：将以上内容直接粘贴给你的开发者或AI工具，并附上你的Tailwind版本号，可获得更精准的实现代码。