Sass 变量优于 CSS 自定义属性，因其支持编译时计算、条件逻辑、作用域隔离与 IDE 识别；设计系统需语义分层（原子/语义/组件）、统一单位、map 主题切换及严格变量引用管控。
为什么直接写 CSS 变量不如用 Sass 变量管设计系统
因为原生 CSS custom properties 不支持计算、条件、作用域嵌套和编译时校验，而设计系统需要在构建阶段就锁定色值比例、间距阶梯、断点逻辑——这些靠运行时 CSS 变量根本做不到。Sass 的 $color-primary、$spacing-xs 等变量能在编译期参与运算，也能被 IDE 识别跳转，还能配合 @if 做主题开关。
常见错误是把 Sass 当成“带变量的 CSS”来用：只定义颜色和字体，不拆分语义层级。结果改个主色要翻 17 个文件手动替换 color: #007bff，而不是改一行 $color-primary: #2563eb 全局重编译。
- 基础变量必须按语义分层：原子层（
$blue-50）、语义层（$color-primary）、组件层（$button-bg-default） - 所有数值类变量（间距、圆角、阴影）必须用统一单位（推荐
rem或无单位数字），避免混用px/em导致缩放异常 - 禁止在样式规则里硬编码值，例如
padding: 16px→ 必须写成padding: $spacing-md
如何组织 Sass 变量文件结构避免后期混乱
单个 _variables.scss 文件撑过 300 行后，搜索、维护、交接成本会指数上升。真正可扩展的设计系统变量目录必须物理隔离关注点。
推荐结构：
立即学习“前端免费学习笔记（深入）”；
@use 'base/colors'; @use 'base/spacing'; @use 'base/typography'; @use 'base/breakpoints'; // 语义变量层（依赖 base 层） @use 'semantic/colors' as semantic-color; @use 'semantic/spacing' as semantic-spacing;
关键约束：
-
base/下只存原始值（如$blue-50: #f0f9ff），不出现任何primary、success等业务语义 -
semantic/层才做映射（$color-primary: $blue-600），且每个变量必须带注释说明使用场景，例如// 用于按钮默认背景、导航高亮等强调操作入口 - 所有
@use必须显式指定as别名，防止不同模块同名变量冲突（比如两个$radius）
Sass map 配合 @each 实现主题切换不是噱头
纯变量无法表达“深色模式下所有间距放大 10%”这种动态规则，但 map + @each 可以。真正的主题切换不是换几组颜色，而是整套视觉节奏的响应式重排。
示例：生成多主题间距类
$spacing-scale: (
xs: 0.25rem,
sm: 0.5rem,
md: 0.75rem,
lg: 1rem,
);
@mixin generate-spacing-utility($prefix, $scale-map) {
@each $key, $value in $scale-map {
.#{$prefix}-#{$key} {
margin: $value;
}
}
}
@include generate-spacing-utility('m', $spacing-scale);
这样生成的 .m-md 类，背后是可被主题覆盖的 map，而非死值。后续加暗色模式只需定义新 map：$spacing-scale-dark: map-merge($spacing-scale, (md: 0.875rem))，再重新 @include 即可。
- 不要用
@for循环生成数字索引类（如mt-1到mt-10），人类记不住数字对应关系，应坚持语义键名（sm/md） - map 的 key 名必须小写短横线风格（
font-weight-bold），与最终生成的 CSS 类名完全一致，减少记忆负担 - 对 color map 做透明度叠加时，用
mix()或rgba()函数，别手写#00000080—— 这种写法无法被主题系统接管
编译后 CSS 体积暴增？检查变量是否被实际引用
Sass 不会自动 tree-shake 未使用的变量，$z-index-drawer 定义了但全项目没调用，它依然会参与编译，更糟的是可能触发不必要的 CSS 规则输出（尤其配合 @extend 时）。
验证方式很简单：临时把某个变量改成明显异常值（如 $color-error: #f00），然后全局搜索编译后的 CSS 是否出现该色值。没出现，说明它没被消费，该删。
- 用
@debug在关键变量后打印日志：@debug 'Loaded spacing vars';，确认文件确实被加载 - VS Code 中装 Sass IntelliSense 插件，未被引用的变量会显示灰色，比肉眼排查快 10 倍
- 禁止在
_variables.scss里写@import，全部改用@use，否则变量作用域失控，导致同名变量覆盖或静默失效
最常被忽略的是断点变量的冗余定义：一个 $breakpoint-sm: 576px 被 3 个不同组件文件重复 @use，却没人检查是否真有组件在 @media (min-width: $breakpoint-sm) 里用了它。
