应优先使用 CSS 媒体查询 @media (prefers-color-scheme: dark) 作为深色模式基础适配层，避免 JS 主观判断；CSS 变量需分层定义、按作用域就近设置；第三方组件库需手动适配自定义内容；图标、阴影、边框等须用变量或语义化方式响应主题变化。
用 prefers-color-scheme 检测系统主题，别自己写 JS 判断
浏览器原生支持 prefers-color-scheme 媒体查询，它比任何 JS 检测都可靠——包括用户手动切换系统主题、浏览器强制深色、甚至某些 macOS/iOS 的自动日出日落切换。自己用 window.matchMedia 包一层没问题，但千万别监听 localStorage 或读取 class 名来“猜”主题。
常见错误现象：document.body.classList.add('dark') 硬编码后，系统切回浅色，页面卡在深色不动；或者 JS 加载延迟导致闪屏（先亮后暗）。
- 始终把
@media (prefers-color-scheme: dark)作为基础适配层，CSS 优先级高于 JS 注入的 class - 如果必须用 JS 控制（比如需要兼容老浏览器），只在
DOMContentLoaded后读一次matchMedia('(prefers-color-scheme: dark)')，不监听 change 事件——除非你真需要响应式切换且已处理好样式重绘抖动 - 避免在 CSS-in-JS 库里用
theme === 'dark'这类运行时判断，容易漏掉媒体查询变化
CSS 变量定义要分层，别全塞进 :root
把所有颜色变量堆在 :root 里，看似整洁，实际会让深色模式切换变脆弱：一旦某个组件单独覆盖了某个变量（比如 .card { --bg: #fff; }），它在深色下就完全失控，且难以追踪。
正确做法是按语义分作用域，让变量“就近生效”：
立即学习“前端免费学习笔记（深入）”；
- 基础色板放
:root，如--color-primary、--color-border - 组件级变量放组件选择器内，如
.button { --button-bg: var(--color-primary); }，再在@media (prefers-color-scheme: dark)里重置该组件的变量 - 慎用
!important覆盖变量值——它会破坏变量继承链，后续任何局部调整都会失效
性能影响：变量本身无渲染开销，但过度嵌套 var(--a, var(--b, ...)) 在低端设备上可能触发计算延迟，建议层级不超过 3 层。
第三方组件库的深色模式不是开个开关就完事
像 Ant Design、Chakra UI、Mantine 都提供 colorScheme="dark" 或类似配置，但它们默认只管自己组件，不管你的自定义卡片、表格、图标颜色。
使用场景：你用了 ChakraProvider 并设了 colorModeManager，但自己写的 .stat-card 仍用 background: #f8fafc，结果深色下变成灰白块。
- 务必检查文档里是否要求你额外引入深色主题 CSS 文件（如
@chakra-ui/react的css-reset可能需配合dark-mode样式补丁） - 禁用组件库的自动检测（如
useColorMode({ disableTransition: true })），改用统一的prefers-color-scheme媒体查询控制——避免 JS 和 CSS 两套逻辑打架 - 图标颜色别写死
fill="#333，改用fill: currentColor或变量，让它随文本色自动适应
图片和阴影在深色下容易糊成一片
浅色模式下看着清爽的 box-shadow: 0 1px 3px rgba(0,0,0,0.1)，到深色背景上几乎看不见；而一张白底 PNG 图标，在深色区域边缘会因抗锯齿残留灰边，显得脏。
容易踩的坑：直接给所有图片加 filter: brightness(0.8) 试图“压暗”，结果导致彩色图表失真、图标变灰不可读。
- 阴影用变量控制透明度和色值，例如
--shadow: 0 1px 3px rgba(var(--shadow-rgb), 0.15)，并在深色媒体查询中改--shadow-rgb: 255, 255, 255 - 图标优先用 SVG 内联或
<svg fill="currentColor"></svg>，避免 PNG/JPG；必须用位图时，导出深色专用版本并用picture+source media切换 - 表单控件的
border别依赖#d1d5db这类固定灰，改用border-color: var(--border)，并在变量中为深色定义更清晰的对比度（如--border: 226 232 240 / 0.3→148 163 184 / 0.4）
最麻烦的其实是设计系统没对齐：开发按 CSS 变量写了深色逻辑，设计师给的深色稿却用了另一套灰阶。这种问题没法靠代码解决，得提前拉齐变量命名和色值定义。
