CSS变量不能直接动画，主题切换需统一在:root声明、用data-theme切换、预设localStorage防闪屏、过渡原生属性而非变量、全覆盖所有渲染路径。
CSS变量本身不能直接动画，主题切换“优雅”的关键不在变量怎么设，而在怎么切、怎么传、怎么稳——核心是避免闪屏、卡顿和样式断裂。
必须把所有主题变量声明在 :root 里
写在 .dark 或组件类里，var(--bg-color) 在子元素中会 fallback 到初始值或继承值，导致部分区域颜色错乱甚至变透明。只有 :root 是全局作用域起点，整个 DOM 都能稳定读取。
-
[data-theme="dark"] :root比.dark :root更可靠：权重更高（110 vs 10），不与业务 class 冲突，支持data-theme="amber"这类扩展 - SSR 场景下，务必在 HTML 的
<head>中内联 script 预设：document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light'，否则首屏必闪 - 漏掉一个变量（比如
--border-color没覆盖），暗色模式下边框就还是浅灰，视觉断层明显
用 dataset.theme 切换，别用 style.setProperty
逐个调用 document.documentElement.style.setProperty('--color', '#xxx') 不仅代码冗长，还会触发多次重排重绘，尤其在 Safari 上输入中切换主题会明显卡顿。
- 正确做法是只改
document.documentElement.dataset.theme = 'dark'，让 CSS 规则批量生效，浏览器自动合并样式计算 - 切换后必须同步存
localStorage.setItem('ui-theme', 'dark')，否则刷新即回退 - 如果用了第三方编辑器（如 Tiptap），它的内部
<span>或<pre>往往硬编码颜色，得用!important或更高权重选择器覆盖，比如[data-theme="dark"] .tiptap p
动画要加在使用变量的元素上，不是 :root
transition: --bg-color 0.3s 完全无效——浏览器不支持对自定义属性插值。var(--bg-color) 只是取值占位符，真正要过渡的是 background-color 这类原生属性。
立即学习“前端免费学习笔记（深入）”；
- 例如：
.card { background-color: var(--card-bg); transition: background-color 0.25s ease; } - 所有颜色值必须格式统一：亮色用
hsl(210, 10%, 95%)，暗色就用hsl(210, 10%, 10%)；混用#fff和rgb(10,10,10)会导致动画跳变 - contenteditable 元素默认不继承
color和background，必须显式写：color: var(--text-primary); background: var(--bg-editor); caret-color: var(--text-primary);
真正难的不是定义变量，而是确保每一条渲染路径都接入变量体系：从 <img> 的外边框、<table> 的分隔线，到 SVG 图标的 fill 和表单控件的 ::placeholder 颜色——漏掉任意一环，主题切换就只是“看起来动了”，实际体验仍是割裂的。
