CSS暗色主题必须在:root定义语义化变量，用@media(prefers-color-scheme:dark)或[data-theme="dark"]双路径覆盖，禁用硬编码颜色、纯黑背景及组件内重复定义，确保OLED防烧屏与全元素样式一致性。
暗色主题颜色不能靠“猜”或“调色板截图”，必须用 CSS 变量统一定义、按优先级分层覆盖，否则换肤时漏掉一个 border-color 就会让按钮边缘发白，OLED 屏上还可能烧屏。
怎么定义基础颜色变量才不翻车
CSS 变量必须在 :root 里先写亮色默认值，再用媒体查询覆盖暗色值。反着写会导致未匹配系统偏好时变量为 unset，var(--bg) 渲染成透明或继承色，页面直接“消失”。
-
:root中定义：--bg: #ffffff、--text: #333333、--border: #e0e0e0 -
@media (prefers-color-scheme: dark)内只覆盖：--bg: #121212、--text: #e0e0e0、--border: #3a3a3a - 所有样式都用
background: var(--bg)，禁用硬编码如background: #121212 - OLED 屏要避开纯黑
#000000，改用#121212或#1a1a1a防烧屏
data-theme="dark" 为什么必须挂 <html> 上
挂错位置是暗色模式失效的高频原因。挂到 <body> 或某个容器里，会导致 <pre>、<textarea>、滚动条、<select> 下拉箭头等原生元素颜色不一致——因为它们的样式默认继承自 html 或根上下文。
- 正确写法：
document.documentElement.setAttribute('data-theme', 'dark') - CSS 选择器必须用
[data-theme="dark"]开头，例如[data-theme="dark"] code { color: #bb8eff; } - 别用
.dark-theme这类 class 名，易与第三方库冲突（比如 Tailwind 的dark:前缀）
哪些颜色值最容易被忽略
除了背景和文字，以下几类值不显式声明就会在暗色下“突兀”：
Article To Html
下载
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
立即学习“前端免费学习笔记（深入）”；
-
box-shadow：亮色下rgba(0,0,0,0.1)在暗色里太重，应改为rgba(255,255,255,0.05)或rgba(0,0,0,0.15) -
svg图标：别写死fill="#333"，改用fill="currentColor"，靠父级color控制 -
<mark>高亮：需单独配色，@media (prefers-color-scheme: dark) { mark { background-color: #3b82f620; color: #f9fafb; } } - 表单控件：加
<meta name="color-scheme" content="light dark">让浏览器自动适配<input>边框、焦点环
用户手动切换后，系统变色还会触发吗
会，但必须加守卫逻辑，否则用户点完“亮色”，系统切到暗色，页面又变黑——这是背叛，不是响应。
- 监听系统变化时，只在
localStorage.getItem('theme')为空时才执行切换 - 监听代码必须带判断：
if (!localStorage.getItem('theme')) { setTheme(e.matches ? 'dark' : 'light'); } - 初始化顺序不能错：先读
localStorage→ 有值就设data-theme→ 无值才查window.matchMedia('(prefers-color-scheme: dark)').matches并立即写入localStorage - 别漏掉
localStorage.setItem('theme', 'light')—— 用户选亮色也得存，否则下次刷新 fallback 到系统偏好
最易被忽略的其实是变量作用域：在组件内部重复定义 --bg，媒体查询就覆盖不了；<style scoped> 里写的变量，根本进不了 :root。主题系统不是加个 class 就完事，是整套颜色从根上收口、每一处取值都可追溯。
