优先使用语义化Sass变量（如$shadow-md）定义阴影，因其轻量、可控、易理解；避免过早引入函数或map，变量天然支持全局生效、编译快、调试直观；命名应按视觉角色（如$shadow-card）而非像素值；值须带单位，禁用inset/!important；深色模式通过主题切换实现；仅在需动态切阴影、运行时换主题或导出CSS变量时才升级为map+函数；多层阴影需unquote()确保合法，且注意渲染性能约束。
直接用语义化 Sass 变量（如 $shadow-sm、$shadow-md）定义阴影值，是最轻量、最可控、也最容易被团队理解的方案。别一上来就写函数或 map——90% 的项目根本不需要那么复杂。
为什么优先选变量而不是函数或 map
变量天然支持“一处修改、全局生效”，编译快、调试直观、IDE 补全友好。而函数容易误用成字符串拼接，map 则多一层间接引用，增加出错概率。实际协作中，设计师说“卡片用中等阴影”，开发直接写 box-shadow: $shadow-md 就完事，没人想查文档看函数怎么调。
- 硬编码
box-shadow: 0 4px 8px rgba(0,0,0,0.1)：改一次得全局搜索替换，漏一个就风格断裂 - 用
@function shadow($key)：必须确保$key存在，否则编译报错；还容易忘记加!global导致颜色变量访问失败 - 用
$shadows: ("sm": (...))+map-get()：调用时多写一串，比如box-shadow: map-get($shadows, "sm")，可读性反而下降
变量命名与分档逻辑要对齐设计语义
别按像素值分档（如 $shadow-2、$shadow-4），而应按视觉角色分档：$shadow-card、$shadow-button-hover、$shadow-modal-backdrop。这样即使设计调整了 md 对应的偏移量，你也不用改所有用到它的组件，只需更新变量定义。
- 所有变量值必须带单位（
0px 4px 6px -1px），不能混用0和0px，否则 Sass 编译报错Incompatible units - 避免在变量里塞
inset或!important——这些属于使用场景逻辑，应留在选择器里控制 - 深色模式适配不靠变量名区分，而是靠主题切换机制：同一变量在不同主题文件中指向不同值
需要扩展时再升级为 map + 函数
当出现以下情况，才考虑把变量升级为 $shadows map 和 shadow() 函数：
- 同一组件需根据状态动态切阴影（如
.btn:active用shadow("sm-strong")） - 设计系统要求支持运行时 JS 切换主题，且阴影颜色需随背景动态计算（此时函数内可用
if($is-dark, ...)） - 需要生成 CSS 自定义属性供 JS 读取（
--shadow-md: #{$shadow-md}）
升级时注意：函数返回值必须是 Sass list（不是字符串），否则 box-shadow: #{shadow("lg")} 会编译失败；map 中每个字段（offset-x、spread）都要做空值判断，尤其 spread 经常为 null 或 0px，漏判会导致拼接出 0 2px 4px null #000 这种非法值。
多层阴影必须用 unquote() 或 join()
无论用变量、函数还是循环生成多层阴影（比如 0 2px 4px #000, 0 4px 8px #000），最终塞进 box-shadow 属性前，必须确保它是无引号的纯 CSS 字符串。Sass 默认把拼接结果当字符串字面量处理，直接写 box-shadow: $shadow-lg 没问题，但若中间经过 append() 或 list.join()，就得用 unquote($shadow-list) 解包，否则浏览器忽略整条声明。
真正容易被忽略的是：多层阴影叠加本身有渲染开销，尤其在滚动区域或动画中。4 层以上、总模糊面积超 200px² 时，部分低端 Android 设备会出现掉帧。这不是语法问题，是设计约束——得和设计师对齐“哪几处真需要多层”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
