暗色模式应通过:root定义语义化CSS变量，同时用@media(prefers-color-scheme:dark)和html.dark类双路径覆盖，配合localStorage持久化与hsl()控制明暗，避免透明度叠加发灰及filter失真。
如何用 :root 声明暗色系 CSS 变量
核心是把颜色值抽成变量，统一在 :root 里定义两套（亮/暗），再靠媒体查询或类名切换。别直接写死 background: #121212 —— 那样改一次要搜全项目。
实操建议：
- 所有颜色变量名带语义，比如
--color-bg-primary、--color-text-secondary，别用--dark-blue-500这种命名，后期根本不知道哪用在哪 - 暗色变量默认不生效，只在
html.dark或@media (prefers-color-scheme: dark)下覆盖 - 避免在变量里写透明度（如
rgba(0,0,0,0.8)），改用hsl()或独立的--opacity变量控制，否则暗色下透明叠加容易发灰
:root {
--color-bg-primary: #ffffff;
--color-text-primary: #1a1a1a;
}
html.dark :root,
@media (prefers-color-scheme: dark) {
--color-bg-primary: #121212;
--color-text-primary: #e0e0e0;
}
prefers-color-scheme 和 html.dark 怎么选
系统级自动适配靠 prefers-color-scheme，用户手动切换必须用 html.dark 类。两者不是二选一，而是共存关系 —— 否则用户点了「深色模式开关」却没反应。
常见错误现象：
立即学习“前端免费学习笔记（深入）”；
- 只用
@media (prefers-color-scheme: dark)，但用户主动切主题时样式不动 - 给
html加dark类后，没在 CSS 里写html.dark :root覆盖变量，导致变量还是亮色的 - JS 切换主题后没同步 localStorage，刷新就回退，体验断层
正确做法是：CSS 里同时写媒体查询和类选择器；JS 切主题时，改 document.documentElement.classList + 存 localStorage.theme。
暗色模式下 border 和 shadow 容易发糊的原因
不是颜色不对，是对比度崩了。亮色下 #e0e0e0 边框看着清晰，到暗色里变成 #333 对比 #121212，差值只剩 ~20，人眼几乎分辨不出。
实操建议：
- 暗色下的
border-color别直接用--color-bg-primary的同类变体，改用更明确的中间灰，比如--color-border: #333→--color-border: #444 - 阴影用
hsl()写，方便统一调整亮度。例如box-shadow: 0 2px 4px hsl(0 0% 0% / 0.15)，暗色下只需改hsl(0 0% 20% / 0.15)，不用重算十六进制 - 慎用
filter: brightness()整体压暗，它会吃掉细节，尤其对图标和文字描边
组件内如何安全读取当前主题色
别在组件 CSS 里硬写 color: var(--color-text-primary) 就完事。如果这个变量在某个局部作用域被意外覆盖（比如第三方 UI 库的 :host 样式），就会失效。
可靠方式：
- 所有组件根元素加
html:not(.dark) &和html.dark &前缀，双重保险 - 需要动态计算的颜色（比如按钮悬停态），用
color-mix()（Chrome 111+）或hwb()替代手算lighten()，避免暗色下越混越脏 - SSR 场景下，服务端无法读
prefers-color-scheme，首次渲染必须依赖客户端 JS 补一层html类，否则闪屏
最常被忽略的一点：CSS 变量本身不触发重排，但大量嵌套 var() + calc() 在低端设备上可能拖慢渲染，关键动效组件建议预计算好几组常用值。
