CSS自定义属性（如--color-bg）支持运行时切换，而Less变量（如@bg-color）仅编译期生效；正确做法是Less定义语义变量（如@color-bg: var(--color-bg, #fff)），由JS动态设置:root上的CSS变量值，实现暗黑模式切换。
暗黑模式切换必须用 CSS 自定义属性（--color-bg）而非 Less 变量
Less 编译期变量（如 @bg-color: #fff）在编译后就固化成静态值，无法运行时切换。真正可行的路径是：用 Less 管理颜色语义体系 + 输出含 CSS 自定义属性的 CSS，再由 JS 控制 :root 上的属性值。
常见错误是把 @dark-bg 和 @light-bg 直接塞进 body 类里做条件编译——这会导致两套 CSS 同时存在、体积翻倍、维护困难。
- Less 里只定义语义 token 映射，例如：
@color-bg: var(--color-bg, #ffffff); - 所有组件样式用
@color-bg等变量书写，最终编译为含var(--color-bg)的 CSS - 暗黑/亮色主题的 actual 值由外部 JS 注入
:root，不参与 Less 编译流程
Less 中如何组织主题 token 文件（tokens.less）
把颜色、间距、圆角等可变值抽成独立文件，用 @import 统一引入，避免散落在各处。关键不是“写多少变量”，而是让每个变量名表达设计意图，比如 @color-surface-primary 比 @bg-1 更可靠。
示例 tokens.less 片段：
立即学习“前端免费学习笔记（深入）”；
@color-surface-primary: var(--color-surface-primary, #ffffff);
@color-surface-secondary: var(--color-surface-secondary, #f8f9fa);
@color-text-primary: var(--color-text-primary, #1a1a1a);
@color-text-secondary: var(--color-text-secondary, #6c757d);
<p>// 所有组件样式基于这些变量，例如：
.card {
background-color: @color-surface-primary;
color: @color-text-primary;
}注意：var(--xxx, #fff) 中的 fallback 值仅用于无 JS 或 CSS 自定义属性不支持的降级场景（IE 不支持，现代浏览器都 OK）。
如何避免 calc() 与自定义属性混合时的 Less 编译错误
Less 会尝试解析 calc(var(--size) * 2) 中的 var()，但早期版本（Unrecognised input。根本原因是 Less 解析器把 var(--x) 当作未定义函数。
- 解决方案：用字符串拼接绕过解析，例如：
width: ~"calc(var(--size) * 2)"; - 更稳妥做法：把带
calc()的规则单独提取到纯 CSS 文件，或升级 Less 到 4.0+（它原生支持var()） - 不要写
calc(@size * 2)再试图替换为变量——这又回到编译期固化问题，失去运行时灵活性
JS 切换主题时，为什么 document.documentElement.style.setProperty 要批量设置
逐个调用 setProperty 触发多次重排，尤其在移动端可能卡顿。更糟的是，如果先设 --color-bg 再设 --color-text，中间状态可能短暂出现对比度极低的组合（比如白底+浅灰字）。
- 正确做法：构造完整主题对象，一次性注入：
Object.assign(document.documentElement.style, themeDark) - 主题对象 key 必须带
--前缀，且值为字符串（"#121212"，不能是数字或布尔） - 切换前加
document.documentElement.classList.add('theme-dark')可用于媒体查询兜底或动画控制，但不能依赖 class 控制颜色值本身
真正麻烦的是第三方组件库（比如 antd）的暗黑适配——它们往往用 Less 变量生成静态 CSS，除非你重编译其样式，否则 JS 切主题对它们无效。这种情况下，得靠 CSS 层叠覆盖或插件式注入，不是 Less 能解决的。
