真正能长期维护的多套配色方案必须靠结构化声明、语义命名与层级隔离；所有主题变量须在 :root 显式声明，统一覆盖同一组变量名，通过 [data-theme] 切换并同步 dataset.theme，HSL 中 var() 需严格遵循单位规则。
直接在 :root 里塞一堆 --color-1、--color-2 变量，不出三个月就会失控。真正能长期维护的多套配色方案，必须靠结构化声明 + 语义命名 + 层级隔离，而不是靠数量堆砌。
所有主题变量必须在 :root 中完整显式声明
很多人只在 [data-theme="dark"] :root 里写暗色模式需要的几个变量，结果切换后某些边框、阴影或文字突然消失——因为 --border-color 或 --shadow-sm 根本没定义，浏览器 fallback 到 currentColor 或透明值。
- 每套主题（
light、dark、amber）都应覆盖同一组变量名，哪怕值和 light 模式相同也要写出来 - 变量顺序无关紧要，但结构必须一致，否则 JS 批量注入或设计系统导出时会漏项
- 禁止在组件内部重复声明同名变量（如
.card { --bg-base: #f0f0f0; }），这会污染全局继承链，且无法被主题切换逻辑识别
[data-theme] 是唯一可靠的主题切换载体
用 .dark 类或 body.dark 切换主题，权重低、易冲突、语义模糊，Safari 旧版对 @media (prefers-color-scheme) 支持也不稳。而 [data-theme="dark"] 权重是 110，全浏览器兼容，扩展性也强。
- 必须同步设置
document.documentElement.dataset.theme，且要在 HTML 解析前执行（不能等DOMContentLoaded） - 服务端渲染时，初始 HTML 的
要正确输出，否则首屏闪白 - 切换时只改
dataset.theme，别手动调style.setProperty()——它绕过 CSS 层叠，后续媒体查询或新主题扩展全乱
hsl() 中嵌套 var() 有硬性单位规则
想用 HSL 动态调色（比如暗色模式下统一降亮度），hsl(var(--primary-h), var(--primary-s), var(--primary-l)) 看似简洁，但稍错就整条声明失效。
立即学习“前端免费学习笔记（深入）”；
- 色相
h必须是无单位整数：hsl(var(--primary-h), ...)✅；hsl(calc(var(--primary-h) + 30deg), ...)❌ - 饱和度
s和亮度l必须带%单位：calc(var(--primary-s) * 0.9)✅；calc(var(--primary-s) * 0.9%)❌（单位重复） - 不能跨类型运算：
calc(var(--primary-h) + var(--primary-s))会失败，因为--primary-s是字符串"70%"，无法与数字相加
模块级配色靠选择器作用域 + 命名前缀隔离
CSS 变量没有“局部”概念，作用域由声明位置决定。想让某个卡片自带配色逻辑又不影响其他模块，关键不在变量本身，而在声明位置和命名方式。
- 在
.card-promo选择器里重设变量：.card-promo { --color-primary: #6a5acd; }，后代自动继承 - 命名加模块前缀：
--card-promo-bg而不是--bg，防止和.modal的--bg冲突 - Shadow DOM 里变量不会自动继承
:root值，必须显式在:host或组件根元素上声明
最常被忽略的一点：深色模式下直接把 --primary-l 从 60% 改成 20%，往往显脏。更稳妥的是先降 --primary-s 到 0% 去色，再微调 --primary-h 校正冷暖——这不是玄学，是 HSL 色彩空间的固有特性。
