最可控、最易维护的方案是用 @each 遍历颜色 map 并结合 HSL 基础变量与 calc() 派生；手写 HEX 或硬编码色阶难维护，独立变量无法遍历，Sass 不支持变量反射；应定义 $theme-colors map 生成语义化类名与 CSS 变量，用 HSL 分离 hue/saturation/lightness 后通过 calc() 派生明暗阶，并为旧 Safari 提供 fallback；主题切换应通过 data-theme 属性解耦，避免 prefers-color-scheme 硬编码；需控制 lightness 边界防止失真。
直接用 @each 遍历颜色 map，配合 HSL 基础变量 + calc() 派生，是最可控、最易维护的方案。手写 20 个 HEX 或硬编码色阶，后期换主色等于重写全部。
必须用 map 定义基础色，别用独立变量
独立变量如 $primary: #007bff 无法被 @each 遍历，也无法自动同步到 CSS 变量或工具类中。Sass 没有变量反射机制，拼接变量名（比如 $$name）会报错。
- 正确写法：
$theme-colors: ("primary": #007bff, "success": #28a745, "warning": #ffc107); - 所有后续操作——生成
--color-primary、.btn-primary、.tag-success——都基于这个 map 展开 - 增删颜色时只需改 map，其余自动更新，不会漏项或索引错位
用 HSL 分离 hue/saturation/lightness，再用 calc() 派生明暗阶
CSS 中 hsl(var(--h-primary), var(--s-primary), calc(var(--l-primary) - 10%)) 这种写法，比手列 HEX 更可靠。但注意 Safari 15.4 之前不支持 hsl() 内嵌 calc()，需 fallback。
- 在
:root定义三组基础变量：--h-primary、--s-primary、--l-primary-base - 派生色用
calc()调整lightness，例如：--color-primary-300: hsl(var(--h-primary), var(--s-primary), calc(var(--l-primary-base) + 20%)); - 为兼容旧 Safari，可提前算好 fallback 值：
--l-primary-300: 75%;，再写hsl(var(--h-primary), var(--s-primary), var(--l-primary-300))
@each 生成语义化类名，别用 @for 碰运气
@for $i from 1 through 10 只给数字，生成 .color-1、.color-2 这类类名毫无语义，协作和维护时完全不可读。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
立即学习“前端免费学习笔记（深入）”；
- 用
@each $name, $color in $theme-colors，直接产出.btn-primary、.bg-success - 若需变体（如
.btn-primary-hover），单独再套一层@each，避免在主循环里塞lighten()导致逻辑混乱 - 命名空间冲突？加前缀：
.my-btn-#{$name}，比硬改类名或加-base后缀更干净
主题切换只换 data-theme，别重复写两套变量
用 @media (prefers-color-scheme: dark) 写死一套深色值，看似省事，实则让 JS 切主题时失去控制权；而把深色值塞进另一个 map，再用 [data-theme="dark"] 覆盖，才能真正解耦。
- 定义
$themes: ("light": $light-colors, "dark": $dark-colors); - 用嵌套
@each $theme, $colors in $themes输出对应作用域样式 - JS 只需切换
document.documentElement.setAttribute('data-theme', 'dark')，CSS 自动响应 - 关键点：所有派生色（如
--color-primary-200）必须在对应 theme 下重新计算，不能复用 light 主色的 calc 表达式
最常被跳过的环节是 lightness 的边界控制——calc(var(--l-primary-base) - 30%) 可能算出负值或超 100%，浏览器虽会 clamp，但结果往往发灰或失真。建议明暗阶只做 ±10%、±20%、±30% 三档，再加一个 mix($color, white, 15%) 保底浅色变体。
