主题色明度判断必须用 if() 函数而非 @if 指令；CSS 变量需用 #{$var} 插值；多主题切换应通过 @each 遍历 map 自动生成；组件样式须用 var(--x) 而非 Sass 变量，以支持运行时切换。
主题色明度判断必须用 if() 函数，不是 @if 指令
很多人想让按钮文字在深色背景上自动变白、浅色背景上变黑，结果写了 @if lightness($primary) > 150，发现编译失败——@if 是控制代码块是否输出的指令，不能返回值；真正该用的是三元函数 if()。
正确写法是把判断结果赋给变量：
$primary: #2563eb;
$light-threshold: 150;
$text-on-primary: if(lightness($primary) > $light-threshold, #1e293b, #f1f5f9);
.primary-btn {
background-color: $primary;
color: $text-on-primary;
}
注意：lightness() 返回 0–100 的整数，别传小数；if() 第二、三个参数必须是合法 CSS 值（如颜色、长度），不能是未定义变量。
:root 里插值生成 --color-x 必须用 #{$var}，不能直接写 $var
Sass 变量和 CSS 变量生命周期不同，Sass 编译时不会自动把 $primary 转成 --primary-color 的值。写 --primary-color: $primary; 会原样输出，浏览器解析为无效声明。
立即学习“前端免费学习笔记（深入）”；
必须显式插值：
$primary-color: #3498db;:root { --primary-color: #{$primary-color}; }
如果颜色来自 map，得用 map-get() + 插值组合：
$theme: ("primary": #007bff, "bg": #f9fafb);
:root {
--primary-color: #{map-get($theme, "primary")};
--bg-color: #{map-get($theme, "bg")};
}
键名用字符串（带引号）没问题，但插值后不会带引号，所以 --primary-color 是合法的，而 --"primary"-color 是非法的。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
多主题切换靠 @each 遍历 map，别手动写 data-theme="dark" 规则
手写两套 :root[data-theme="light"] 和 :root[data-theme="dark"] 容易漏变量、难维护。Sass 的 @each 是批量生成的唯一可靠方式。
结构要清晰：
- 主题配置用 map，键名为字符串（
"light"、"dark"） - 每个主题内部再嵌套 color map
-
@each外层遍历主题名，内层再遍历颜色键值对
$themes: (
"light": ("primary": #3b82f6, "bg": #ffffff),
"dark": ("primary": #60a5fa, "bg": #111827)
);
@each $theme-name, $theme-map in $themes {
:root[data-theme="#{$theme-name}"] {
@each $key, $value in $theme-map {
--#{$key}: #{$value};
}
}
}
这样增删主题或颜色字段，CSS 变量自动同步；JS 只需改 document.documentElement.dataset.theme，无需操作单个变量。
组件样式里只用 var(--x)，禁用 $x 直接赋值
这是最容易被忽略的边界问题：一旦你在按钮里写 background: $primary;，编译后就是死值，JS 切换 data-theme 完全无效。
所有运行时可变的样式，必须走 CSS 变量通道：
- 错误：
.btn { background: $primary; }→ 编译后固定为#3b82f6 - 正确：
.btn { background: var(--primary); }→ 运行时取当前data-theme下的值
连 fallback 都要提前设计好：color: var(--text-primary, #1f2937);，否则没设主题时会继承不到值。
真正麻烦的地方在于：Sass 里 var(--x) 是纯字符串，无法参与颜色计算（比如 lighten(var(--primary), 10%) 会报错），所以明暗变体必须在 Sass 编译期生成好，再暴露为独立 CSS 变量（如 --primary-light）。
