直接硬编码 box-shadow 不适合 Elevation 系统，因其难以维护、不支持主题/响应式/规范迭代；应使用按整数索引的 $elevation-values map + @mixin elevation($level) 封装，并通过 CSS 自定义属性实现暗色模式适配。
为什么直接写 box-shadow 不适合做 Elevation 系统
硬编码 box-shadow: 0 2px 4px rgba(0,0,0,0.1) 看似简单，但会快速失控：不同组件需要的阴影深度不一致（卡片要 elevation-4，按钮可能只需 elevation-2），夜间模式需切换颜色值，响应式场景下还要动态缩放。更麻烦的是，一旦设计规范调整（比如所有 elevation-6 的模糊半径从 12px 改为 16px），你得全局搜索替换——而这类修改往往漏掉某些嵌套选择器或第三方组件覆盖样式。
$elevation-values 变量表必须按数字索引且不可跳号
Material Design 和 Vuetify 都采用整数层级（elevation-1 到 elevation-24），这不是随意定的。CSS 层级是离散的 Z 轴概念，跳号会导致语义断裂（比如没有 elevation-5，设计师和前端就无法对齐“这个弹窗应该比侧边栏高一级”这种需求）。Sass 中应定义为 map：
$elevation-values: ( 1: (0 1px 3px rgba(0, 0, 0, 0.12)), 2: (0 1px 5px rgba(0, 0, 0, 0.14)), 3: (0 1px 8px rgba(0, 0, 0, 0.16)), 4: (0 2px 12px rgba(0, 0, 0, 0.18)), 6: (0 3px 16px rgba(0, 0, 0, 0.2)), 8: (0 4px 20px rgba(0, 0, 0, 0.22)), 12: (0 6px 24px rgba(0, 0, 0, 0.24)), 16: (0 8px 32px rgba(0, 0, 0, 0.26)), 24: (0 12px 48px rgba(0, 0, 0, 0.28)) );
注意：3 和 4 之间没有 5，但 4 必须存在；6 是下一个关键档位——这是为了匹配 Material 规范中“高度差引发的视觉权重跃迁”。跳过 4 或把 6 写成 5.5 会让下游使用者困惑。
用 @mixin elevation($level) 封装，别用 @function
有人想用函数返回字符串再插进 box-shadow，这会导致无法被 CSS @layer 或后续 Sass 工具（如主题 token 注入）识别。正确做法是写 mixin：
立即学习“前端免费学习笔记（深入）”；
@mixin elevation($level) {
@if map-has-key($elevation-values, $level) {
box-shadow: map-get($elevation-values, $level);
} @else {
@warn "Unknown elevation level: #{$level}. Available: #{map-keys($elevation-values)}.";
box-shadow: none;
}
}
这样调用时才干净：
.v-card {
@include elevation(4);
}
.v-dialog__content {
@include elevation(12);
}
关键点：
- 必须检查
map-has-key，否则构建时不会报错，运行时阴影直接消失 - 警告信息里列出可用 key，比抛异常更友好，方便排查拼写错误（比如写了
elevation(04)） - 不要在 mixin 里加
!important——它破坏可覆盖性，违背 Vuetify 等框架的@layer('components')设计原则
暗色模式适配不能靠 JS 切换 class，得用 CSS 自定义属性
如果只在 Sass 里写两套 map（$elevation-light / $elevation-dark），编译后就是两套静态 CSS，无法响应系统偏好变化。真正可靠的方案是让 box-shadow 的颜色部分绑定 CSS 变量：
:root {
--elevation-color: rgba(0, 0, 0, 0.12);
}
@media (prefers-color-scheme: dark) {
:root {
--elevation-color: rgba(255, 255, 255, 0.08);
}
}
@mixin elevation($level) {
@if map-has-key($elevation-values, $level) {
$shadow: map-get($elevation-values, $level);
// 把颜色部分替换成 var(--elevation-color)
box-shadow: set-nth($shadow, 4, var(--elevation-color));
}
}
这里有个隐藏坑：set-nth 只能替换 tuple 中第 N 个值，而 box-shadow 值是 4 元组（x y blur color），所以必须确保 map 里每个值都严格是 4 项。少写一个 0（比如漏掉 x 偏移）会导致 set-nth 错位。
