直接用--shadow-offset和--shadow-color拼接易失效，因CSS不支持运行时字符串解析；应拆为--shadow-x、--shadow-y、--shadow-blur、--shadow-color四个语义变量，确保合法语法、主题可控、调试直观。
直接用 --shadow-offset 和 --shadow-color 拼接，看似省事，实则极易失效——CSS 不支持运行时字符串解析，var(--shadow-offset) 展开后若不是合法的阴影片段，整条 box-shadow 声明会被浏览器静默丢弃。
为什么拆成 offset + color 两个变量容易翻车
因为 box-shadow 要求前四个参数（水平、垂直、模糊、扩散）必须是独立数值，不能靠空格“自动拆分”。比如设 --shadow-offset: 4px，浏览器展开后得到 box-shadow: 4px rgba(0,0,0,.1)，这根本不是合法语法，整条规则作废。
常见错误现象：
-
--shadow-offset: 0 4px看似可行，但一旦想改成--shadow-offset: -2px 6px 12px（含模糊），就超出语义范围，后续维护混乱 - 在深色模式下只重设
--shadow-color，阴影在暗背景上发灰糊成一片，实际需要同步调小--shadow-blur - 多层阴影用单个变量存整串字符串，逗号前后空格不一致时，拼接后出现
box-shadow: 0 2px 4px rgba() , 0 4px 8px rgba()这类非法格式
推荐拆解为四个语义化变量
每个变量只管一个职责，组合自由、调试直观、主题切换可控：
立即学习“前端免费学习笔记（深入）”；
-
--shadow-x：水平偏移（如0或2px） -
--shadow-y：垂直偏移（如4px） -
--shadow-blur：模糊半径（如8px） -
--shadow-color：带 alpha 的颜色（如rgba(0,0,0,.1)）
使用时写成：box-shadow: var(--shadow-x) var(--shadow-y) var(--shadow-blur) var(--shadow-color);
这样改任意一项都不会影响其他，也方便用 JS 动态控制，比如悬停时只放大 --shadow-blur。
Less/Sass 中封装阴影 mixin 的关键点
别把变量逻辑塞进预处理器——CSS 变量才是运行时动态的根基；预处理器 mixin 只负责生成初始值或语义档位。
- Less 中定义：
.shadow(@x: 0, @y: 4px, @blur: 8px, @color: fade(#000, 10%)) { box-shadow: @x @y @blur @color; } - 调用时仍应基于 CSS 变量传参：
.card { .shadow(var(--shadow-x), var(--shadow-y), var(--shadow-blur), var(--shadow-color)); } - 避免在 mixin 内硬写
rgba(0,0,0,.1)，否则主题切换时无法响应
真正要复用的不是“某组数值”，而是“如何组织这些数值的结构”。
深色模式下重定义整组变量，而非只换颜色
在 @media (prefers-color-scheme: dark) 或 [data-theme="dark"] 中，必须重设全部相关变量：
- 浅色模式：
--shadow-y: 4px; --shadow-blur: 8px; --shadow-color: rgba(0,0,0,.1); - 深色模式：
--shadow-y: 2px; --shadow-blur: 4px; --shadow-color: rgba(255,255,255,.06);
注意：不要试图用 calc() 在 rgba() 里动态算 alpha 值——CSS 不允许嵌套函数，rgba(0,0,0,calc(.1 * 0.8)) 会直接报错。
最易被忽略的是测试方式：关掉浏览器开发者工具里的“模拟深色模式”，改用系统级深色设置，否则 @media (prefers-color-scheme: dark) 根本不触发。
