用途：在 Tailwind 项目中添加、调试或迁移暗色模式支持，先选定策略，再一致地实现配置、标记、切换脚本与可选的主题令牌替换。
三种策略：media（默认，跟随系统 prefers-color-scheme，无需手动切换）；class/selector（在 <html> 上切换 .dark 类，适合需要用户开关）；attribute（自定义 data 属性，如 data-theme="dark"，适合已有属性主题系统）。
配置差异：v3 在 tailwind.config.js 中设置 darkMode（'media'、'selector'、['selector', '[data-theme="dark"]'] 或 ['variant', ...]）；v4 在 CSS 中用 @custom-variant dark (&:where(.dark, .dark *)); 等指令。不可在同一项目混用 v3 配置语法与 v4 指令语法，v4 会静默忽略 v3 的 darkMode 字段。
主要能力：提供决策树判断策略、暗色样式放置位置与切换脚本位置；给出媒体、类、属性、主题令牌替换、原生 JS 切换等模式；覆盖 Next.js、Vite、Astro、SvelteKit、Remix、纯 HTML 的脚本放置位置。
必要用法：切换脚本须在页面绘制前运行，通常内联于 <head> 且位于样式表链接之前；先读 localStorage.theme，再回退到 prefers-color-scheme；类切换作用于 <html> 而非 <body>。
限制：不可在 useEffect、onMount 等生命周期钩子中切换，否则首屏闪烁；不可在 v4 项目保留 v3 的 darkMode: 'class'；不可先判断系统偏好再判断 localStorage。具体框架细节与完整示例见其 references 文件。