直接修改 :root 的 HSL 变量即可切换暗黑模式，但必须用 JS 调用 document.documentElement.style.setProperty() 动态更新 --bg-h/--bg-s/--bg-l 等分量，浏览器会自动重绘；无需手动触发回流，也不应拼接完整 hsl() 字符串赋值。
直接改 :root 里的 HSL 变量就能切换黑夜模式，但必须用 JS 触发重绘
纯 CSS 无法响应用户操作（比如点击按钮）来动态修改自定义属性值，:root 中的 --bg-h、--bg-s、--bg-l 这类 HSL 分量必须由 JS 修改，浏览器才会重新计算依赖它们的 background-color: hsl(var(--bg-h), var(--bg-s), var(--bg-l))。
常见错误是只改变量值却不触发样式重绘——其实只要修改了 :root 上的自定义属性，CSS 引擎会自动更新所有引用该变量的地方，无需手动 force reflow 或操作 class。
- 推荐在
document.documentElement上用style.setProperty()设置变量，比操作className更精准、无副作用 - 不要在 JS 里拼接完整
hsl()字符串再赋给单个变量（如--bg: "210 10% 95%"），这样会失去 HSL 分量的独立控制能力 - 初始值建议写在 CSS 中（非内联），方便 SSR 或首屏渲染；JS 只负责后续状态变更
用三组 HSL 变量分别控制色相、饱和度、明度，避免硬编码颜色值
HSL 比 HEX/RGB 更适合主题切换：明度（--bg-l）可从 95%（白天）降到 10%（深黑），饱和度（--bg-s）从 0% 微调到 5% 避免死灰感，色相（--bg-h）一般保持不变（如 210 对应冷灰），但可为“暖夜模式”预留调节空间。
示例 CSS：
立即学习“前端免费学习笔记（深入）”；
body {
background-color: hsl(var(--bg-h), var(--bg-s), var(--bg-l));
color: hsl(var(--text-h), var(--text-s), var(--text-l));
}
:root {
--bg-h: 210;
--bg-s: 0%;
--bg-l: 95%;
--text-h: 210;
--text-s: 10%;
--text-l: 20%;
}
- 每类颜色（背景、文字、边框、强调色）都拆成独立的 HSL 三元组，便于局部微调
- 明度值用百分比（
95%）而非数字（95），否则hsl()函数会解析失败 - 避免把
--bg-l设为0%，纯黑（hsl(0,0%,0%)）易造成视觉疲劳，推荐4%–8%
切换时同步更新 prefers-color-scheme 不匹配的用户状态
系统级暗色偏好（prefers-color-scheme: dark）和用户手动切换可能冲突。比如用户系统设为浅色，却点了页面上的「黑夜模式」按钮——此时不能只靠媒体查询，得用 JS 主动覆盖。
做法是：首次加载时读取 window.matchMedia('(prefers-color-scheme: dark)').matches，存入 localStorage；后续所有切换都以 localStorage 为准，同时设置 document.documentElement.setAttribute('data-theme', 'dark') 供 CSS 回退使用。
- 务必监听
storage事件，实现多标签页同步（否则 A 标签切了暗色，B 标签仍是亮色） - 不要在 CSS 里用
@media (prefers-color-scheme: dark)直接覆盖 JS 设置的变量，它优先级低于内联 style，会导致闪烁或失效 - 如果用户未手动切换过，才按系统偏好初始化变量；一旦手动触发，就完全交由 JS 控制
hsl() 在低饱和度下对明度变化更敏感，调试时先调 --*-l 再微调 --*-s
当 --bg-s ≤ 5% 时，--bg-l 每变动 1% 都会明显改变灰阶，而 --bg-s 从 0% 到 3% 几乎看不出差别。实际调试顺序应该是：先定好白天/黑夜两套明度值，再拉饱和度滑块找“有质感但不突兀”的临界点。
- Chrome DevTools 的颜色拾取器支持 HSL 拖拽，但仅显示最终色值，看不到变量来源——建议在 Elements 面板中右键
:root→ “Break on attribute modification” 跟踪变量变更 - 部分旧版 Safari 对
hsl(var(--h), var(--s), var(--l))解析不稳定，若遇 fallback 失败，可在:root中加一层color-scheme: light dark声明 - 动画
transition: background-color 0.3s有效，但别对hsl()中的单个变量加 transition——CSS 不支持变量插值动画
8% 还是 12% 这种像素级感知差异，以及多端同步时 storage 事件漏处理。 
