最稳的主题方案是直接在 :root[data-theme="xxx"] 中用语义化hsl变量定义整套调色板，并通过js同步设置dataset.theme激活预设；必须显式声明所有变量、避免setproperty、确保切换时机在html解析前，否则易引发颜色错乱与fouc。
直接在 :root 里用语义化变量名 + HSL 分量定义整套调色板，再通过 JS 切换 data-theme 属性来激活对应预设——不是靠 JS 批量 setProperty，也不是靠 class 覆盖，这是最稳、最易维护的路径。
为什么必须把整套变量写死在 :root[data-theme="xxx"] 里
浏览器解析 CSS 是单次层叠过程，var(--color-primary) 的值取决于当前匹配到的最高优先级声明。如果只在 JS 里动态改几个变量，其他变量没覆盖，就会 fallback 到上一个有效值（可能是 light 主题的旧值，也可能是 currentColor 或透明），导致边框消失、文字不可读等“颜色错乱”现象。
-
[data-theme="dark"] :root权重是 110，远高于普通 class（10），不会被业务组件或第三方库的.dark冲突 - 所有主题变量必须显式声明，哪怕和 light 模式值相同也要写出来，例如
--border-color: #e5e7eb在 dark 主题下也得是--border-color: #374151 - 不写全 = 留坑；漏一个变量 = 一处样式崩，且极难定位
data-theme 切换前必须同步设置 dataset.theme
FOUC（闪屏）几乎都源于这个时机错误：等 DOMContentLoaded 再执行 document.documentElement.dataset.theme = 'dark'，浏览器早已按默认主题渲染完首屏。
- 必须在
中放内联<script></script>，且不能包裹在函数里 - 正确写法：
<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script> - 服务端能判断初始主题（如从 Cookie 或 UA 解析），就优先服务端注入，比客户端 JS 更可靠
如何组织 HSL 分量变量让调色板可计算、可微调
把色相（--h-primary）、饱和度（--s-primary）、明度（--l-primary）拆成独立变量，再用 hsl(var(--h-primary), var(--s-primary), calc(var(--l-primary) - 15%)) 派生深浅色，比手写一串 HEX 健壮得多。
- Safari 15.4 之前不支持
hsl()里嵌套calc()，需降级 fallback：--l-primary-dark: 40%;，然后用hsl(var(--h-primary), var(--s-primary), var(--l-primary-dark)) - 避免用
rgba(var(--color-primary), 0.8)—— CSS 变量不能直接嵌套进函数参数，会报Invalid property value - 所有派生色统一用固定百分比（如
75%/30%），不用calc(var(--l) * 0.9)，防止小数精度抖动
切换主题时只动 data-theme，别碰 style.setProperty
手动 setProperty 看似灵活，实则破坏 CSS 层叠逻辑：你改了 --bg-base，但忘了 --shadow-sm；下次加新变量要翻 JS 代码；媒体查询（如 @media (prefers-color-scheme: dark)）也完全失效。
- JS 唯一职责是设置
document.documentElement.dataset.theme，其他全部交给 CSS 规则匹配 - 确保
localStorage.setItem('ui-theme', 'dark')和dataset.theme同步，否则刷新后回退到默认 - 不要在组件内部重复声明同名变量（如
.card { --bg-base: #f0f0f0; }），这会污染继承链，导致父级主题失效
真正难的不是写多少套变量，而是保证每套都覆盖同一组变量名、每个变量都显式赋值、每次切换都发生在 HTML 解析前——这些细节一旦松动，整个主题系统就会开始“漏色”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
