SCSS主题变量必须用$themes map配合@each生成data-theme选择器，禁用硬写多套:root；themeify需含&和#{$name}插值，themed()须加map-has-key安全检查并以light为fallback。
SCSS主题变量必须用 map + @each 构建，不能硬写多套 :root
直接在 :root 里写 --primary-color: #1890ff 再覆盖成 --primary-color: #722ed1 是错的——它破坏作用域隔离，多个主题包同时加载时会相互污染。正确做法是把所有主题配置收进一个 SCSS $themes map，再用 @each 遍历生成带 data-theme 前缀的选择器。
常见错误现象：body[data-theme="dark"] 下某些组件颜色没变，或切换后旧值残留；本质是变量没被正确作用域包裹，CSS 优先级失效。
-
$themes中每个子 map 的 key 必须完全一致（比如都含primary-color），否则themed("primary-color")查不到值 - 不要用
:root.theme-dark这种写法——浏览器不认这个选择器，var(--x)会 fallback 到:root默认值 - 所有主题样式必须通过
body[data-theme="xxx"]或html[data-theme="xxx"]触发，确保层级压得过全局:root
themeify mixin 必须配合插值 #{} 和 & 符号，否则无法嵌套生成有效选择器
很多人写 @mixin themeify { @each $name, $map in $themes { body[data-theme="#{$name}"] { ... } } }，但漏了 &，导致生成的 CSS 选择器脱离上下文，根本不会命中组件内部样式。
使用场景：你在 .card 里调用 @include themeify，期望输出的是 body[data-theme="dark"] .card { background-color: map-get($map, bg-color); }，而不是孤立的 body[data-theme="dark"] { ... }。
立即学习“前端免费学习笔记（深入）”；
-
&是父选择器占位符，必须出现在body[data-theme="#{$name}"] &中，才能把当前上下文（如.button）拼进去 -
#{$name}是必需的插值语法，写成body[data-theme="$name"]会被当字面量解析，生成无效属性值 - 如果组件用了
scoped，themeify必须定义在非 scoped 样式块里，否则编译后选择器带 data-v-xxx 后缀，和body[data-theme]不匹配
themed() 函数要加 map-has-key 安全检查，否则编译期报错会中断构建
当你传入 themed("border-radius-sm")，但某个主题 map 里没定义这个 key，Sass 编译直接抛 ArgumentError: map-get: $map is not a map，整个 CSS 构建失败。
性能影响：没有安全检查的 themed() 在大型项目中极易因拼写错误或遗漏字段导致 CI 失败；加一层判断虽增加少量编译耗时，但换来的是可维护性。
- 必须用
@if map-has-key($map, $key)包裹map-get()，否则 fallback 值无法生效 - fallback 值建议设为
map-get($themes[light], $key)，即强制以 light 主题为兜底，避免 undefined 导致样式崩溃 - 不要在
themed()里做颜色转换（如darken()），主题间色阶应由设计预先定义好，运行时计算会拖慢编译
HTML 根节点必须同步设置 data-theme，且需在 CSS 加载前完成
如果 JS 在 DOMContentLoaded 后才执行 document.documentElement.setAttribute('data-theme', 'dark')，而 CSS 已经按默认主题渲染完毕，用户会看到明显闪烁——这就是常说的“首屏闪白”或“主题跳变”。
容易踩的坑：用 localStorage 读取主题后异步 setAttribute；或者把设置逻辑放在 Vue/React 组件 mounted 里，此时页面早已绘制完成。
- 最佳实践是在 HTML 模板最顶部用内联 script 同步读取并设置：
<script>document.documentElement.setAttribute('data-theme', localStorage.getItem('theme') || 'light')</script> - 如果服务端能识别用户偏好（如通过 Cookie 或 UA），更推荐 SSR 直出正确
data-theme，彻底规避客户端闪动 - 切忌用
document.body.classList.add('theme-dark')替代data-theme——SCSS 里写的body[data-theme="dark"]选择器不会匹配到 class 变化
@mixin themeify，而是让所有业务组件都放弃写死 #1890ff，统一走 themed("primary-color")。一旦漏掉一个按钮、一个图标、一个边框，换肤就变成“看起来差不多，但总差那么一点”。这需要代码审查机制+自动化 lint 规则（比如禁止在 SCSS 里出现十六进制颜色字面量），而不是靠人肉检查。 
