主题色必须用 $theme-colors map 定义，禁用独立变量；通过 @each 生成 CSS 自定义属性和多主题样式；lighten()/darken() 参数为百分比，浅色宜用 mix(white)、透明度用 rgba；JS 仅切换 data-theme，依赖 CSS 变量继承。
主题色映射必须用 $theme-colors 这样的 map 变量，不能用普通变量列表
直接写 $primary: #007bff 无法批量切换或遍历，Sass 的 @each 和 map-get() 依赖 map 结构。常见错误是把颜色定义成独立变量后试图“动态拼接变量名”，这在 Sass 中不可行（没有变量反射）。
正确做法是统一收口到一个 map：
$theme-colors: ( "primary": #007bff, "success": #28a745, "warning": #ffc107, "danger": #dc3545 );
后续所有颜色引用、生成类名、生成 CSS 自定义属性都基于这个 map 展开。别想着“先定义变量再塞进 map”，那样多写一遍还容易不同步。
用 map-loop + lighten()/darken() 生成明暗变体时，注意参数单位和边界值
Sass 的 lighten($color, $amount) 中 $amount 是百分比值（如 10%），不是小数（0.1 会报错）。更关键的是：对极亮色（如 #fff）调用 lighten() 无效果，对极暗色（如 #000）调用 darken() 同样无效——函数内部会 clamp 到合法范围，但结果可能不符合预期。
立即学习“前端免费学习笔记（深入）”；
生成常用变体的推荐写法：
- 只对基础色做 ±10%、±20% 调整，避免过度失真
- 用
mix($color, white, 10%)替代lighten()对浅色更可控 - 用
rgba($color, 0.1)做透明度降级，比单纯变暗更安全
输出 CSS 自定义属性时，--color-primary 必须对应 map key，不能硬编码字符串
很多人手写 --color-primary: #007bff，导致换主题时要改两处：map 和 CSS 变量。正确方式是用 @each 驱动：
:root {
@each $name, $color in $theme-colors {
--color-#{$name}: #{$color};
}
}
这样 map 里增删颜色，CSS 变量自动同步。注意：#{$name} 插值后生成的是 --color-primary，不是 --color-"primary" —— 引号不会被插进去，所以 map key 本身别带引号（写 "primary" 没问题，但插值时它就是字符串 primary）。
如果需要支持深色模式，可额外加一层嵌套 map：
$themes: (
"light": $theme-colors,
"dark": ("primary": #0056b3, "success": #1e7e34, ...)
);
再用 @each $theme-name, $colors in $themes 分别输出 [data-theme="light"] 和 [data-theme="dark"] 下的变量。
JavaScript 切换主题时，只改 document.documentElement.dataset.theme，不重载 CSS
很多人用 JS 动态加载不同 CSS 文件，这是反模式：破坏缓存、增加请求、无法利用 CSS 变量继承。正确姿势是 Sass 编译出一份含多主题的 CSS，JS 只控制根节点的 data 属性：
document.documentElement.dataset.theme = 'dark';
对应 CSS 写成：
[data-theme="dark"] .btn {
background-color: var(--color-primary);
}
这样切换毫秒级完成，且所有组件自动响应。唯一要注意的是：确保所有用到颜色的地方都通过 var(--color-xxx) 引用，而不是写死 HEX 值——这点必须靠团队规范或 PostCSS 检查，Sass 本身管不了运行时。
真正容易被忽略的点是：CSS 变量作用域和继承链。比如 button 内部的 span 想用主题色，得确保父级没用 color: black 硬覆盖，否则 var(--color-primary) 不会生效。这不是 Sass 的问题，但主题切换失败十次有八次栽在这儿。
