Tailwind 的 dark 变体默认不生效，因它仅是条件前缀，需手动在 添加 dark 类或配置 darkMode: 'class'；须用 JavaScript 控制类切换并持久化至 localStorage，且注意 focus:ring 等样式在深色下的可见性。
dark变体为什么默认不生效
因为 Tailwind 默认不会自动监听系统深色偏好或手动切换状态，dark: 只是一个条件前缀，它本身不触发任何逻辑——你得自己提供 dark 类名到某个祖先元素上，它才生效。
常见错误是直接写 dark:bg-gray-800 却没在 或 上加 dark 类，结果样式完全不应用。
- 必须手动控制：比如用户点击按钮后给
添加/移除dark类 - 若想跟随系统偏好，需用
prefers-color-scheme: dark媒体查询配合class切换（Tailwind 3.3+ 支持darkMode: 'class'配置） - 确认
tailwind.config.js中已设darkMode: 'class'（不是'media'），否则dark:变体只响应媒体查询，不响应类名
如何用 JavaScript 切换 dark 类（最小可行代码）
不需要框架、不依赖 localStorage 初始化，一段脚本能跑通：
document.documentElement.classList.toggle('dark', localStorage.getItem('theme') === 'dark')
document.getElementById('theme-toggle').addEventListener('click', () => {
const isDark = document.documentElement.classList.contains('dark')
document.documentElement.classList.toggle('dark', !isDark)
localStorage.setItem('theme', !isDark ? 'dark' : 'light')
})
注意点：
立即学习“前端免费学习笔记（深入）”；
- 一定要操作
document.documentElement（即），不是，否则部分样式（如dark:bg-gray-900在根级背景）可能失效 - 首次加载时从
localStorage读取比用matchMedia更可控，避免闪屏（系统设置和用户选择冲突时以存储为准） - 按钮文案建议同步更新，比如用
textContent = isDark ? '亮色' : '深色'
dark 变体在组件中怎么写才不冗余
别每个元素都写两遍背景/文字色，优先用语义化工具类组合：
- 用
bg-surface text-content这类自定义颜色变量（通过theme.extend.colors定义），再配合dark:bg-surface-dark dark:text-content-dark，一处改，全局换 - 避免
dark:text-gray-200 dark:bg-gray-800 dark:border-gray-700连写——可抽成dark:prose-invert或自定义dark-card类 - 表单控件容易漏：比如
dark:checked:bg-blue-600要显式写，checked:和dark:可叠加，但顺序不能错（dark:checked:bg-✅，checked:dark:bg-❌）
深色模式下 focus-outline 发虚或看不见怎么办
Tailwind 的 focus:ring 在深色背景上常因对比度不足而“消失”，尤其 focus:ring-blue-500 在 dark:bg-gray-900 上几乎不可见。
- 强制为深色模式指定高对比 ring：
focus:ring-2 focus:ring-blue-400 dark:focus:ring-blue-300 - 更稳妥的是用
focus-visible替代focus，避免鼠标点击时也触发 outline（Tailwind 3.0+ 默认启用） - 别忽略
focus:outline-none的副作用——它会干掉原生 focus 样式，但深色模式下若没补focus:ring，键盘用户就彻底失去焦点指示
最易被忽略的其实是 CSS 变量过渡和图片适配：dark 模式切换时，纯色能立刻变，但 background-image: url(...) 不会自动换图，SVG fill 也不会自动反色，这些得单独处理。
