应通过document.documentElement.dataset.theme切换主题，避免style.setProperty导致闪屏卡顿；CSS变量需定义在:root或data-theme选择器中并带fallback；首次加载须在DOM渲染前同步设置data-theme与localStorage值；过渡效果仅对color等可动画属性生效，且变量名须语义化。
直接改document.documentElement.dataset.theme，别碰style.setProperty
换肤闪屏或卡顿，90%是因为用了style.setProperty逐个写变量。CSS变量本身支持继承和级联，但直接操作style会绕过选择器权重机制，导致部分样式重排、动画中断、甚至 scoped 样式失效。
正确做法是用data-theme属性切换，让浏览器走原生 CSS 重计算流程：
-
data-theme="light"对应:root默认值，data-theme="dark"对应html[data-theme="dark"]块内覆盖 - 所有主题变量必须定义在
:root或带data-theme的选择器里，不能写在组件<style scoped>内部 - 避免用
body[data-theme]——body不是根元素，无法保证全局变量继承链完整
var(--color-bg, #fff)必须带 fallback，否则 SSR 或首次渲染会白屏
Vue服务端渲染（SSR）或首屏直出时，data-theme还没设置，var(--color-bg)若无 fallback，计算结果为invalid value，浏览器会回退到 inherited 值或初始值，造成背景/文字色错乱。
写法上必须显式声明 fallback：
立即学习“前端免费学习笔记（深入）”；
Vue Composition Analyzer
下载
分析 Vue 3 Composition API 使用情况——审计响应式模式、可组合函数设计、ref 与 reactive 的选择、计算属性、watcher 使用及组件……
- 错误：
background-color: var(--bg-surface); - 正确：
background-color: var(--bg-surface, #ffffff); - 颜色类变量 fallback 推荐用中性灰（如
#666），比纯黑/白更容错
首次加载时要同步设置data-theme和读取 localStorage，否则闪回亮色
用户上次选的是暗色，刷新页面后先看到亮色再跳成暗色——这不是动画问题，是执行顺序没对齐。
关键点在于：DOM 渲染前就要让document.documentElement带上正确的data-theme，否则浏览器按:root默认值渲染第一帧。
- 在
main.ts或App.vue的beforeMount钩子中读取localStorage.getItem('theme') - 立即调用
document.documentElement.dataset.theme = theme，**不要等 mounted** - 如果用
useTheme自定义 Hook，确保它在根组件 setup 阶段就执行初始化
加transition只对可动画属性生效，别乱写all 0.3s
CSS变量本身不可动画，但它的“下游属性”可以。比如--bg-color被用于background-color，那就在html或body上加transition: background-color 0.25s ease。
- 有效属性：color、background-color、border-color、opacity、transform 等
- 无效属性：font-size、padding、grid-template-columns —— 改了
--gap不会自动过渡 - 禁止写
transition: all 0.3s，会触发大量不必要的 layout 和 paint
最易被忽略的是：主题变量名一旦写死在组件样式里，后续新增主题（比如data-theme="high-contrast"）就无法复用。设计令牌要真正语义化，比如--text-primary而不是--dark-text——后者在高对比度主题里可能反而不是深色。
