SCSS变量编译后即固化为静态值，无法运行时切换；动态主题必须依赖CSS自定义属性（如--primary），由SCSS仅负责生成:root声明，JS通过切换data-theme或class控制，所有样式须用var(--x)引用。
SCSS变量和CSS自定义属性不能混用
SCSS变量在编译时就被替换成固定值，比如 $primary: #2f80ed 编译后就是 color: #2f80ed，它无法在运行时响应主题切换。而暗黑模式需要的是运行时动态更新的样式，必须依赖 CSS 自定义属性（--primary）——它们能被 JS 修改、能在 @media (prefers-color-scheme: dark) 中重写、还能参与 transition 动画。
常见错误是试图在 SCSS 里直接赋值给 CSS 变量：--bg: #{$dark-bg-color}。这看似可行，但一旦你后续想用 JS 切换主题，就会发现变量值早已固化，无法更新。
- SCSS 只适合做“构建期配置”，比如生成多套主题 CSS 文件（light.css / dark.css）
- CSS 自定义属性才是“运行时主题引擎”的唯一载体
- 两者可以共存，但职责必须清晰：SCSS 生成初始变量声明，不参与切换逻辑
:root 中声明变量必须用纯 CSS，不能用 SCSS 插值
所有主题变量必须写在 :root 选择器下，且必须是原生 CSS 语法。即使你用 SCSS 编写，最终输出也得是类似这样的结构：
:root {
--text-color: #000;
--bg-color: #fff;
}
:root.dark {
--text-color: #fff;
--bg-color: #121212;
}
body {
color: var(--text-color);
background-color: var(--bg-color);
}
如果你在 SCSS 里这样写：:root { --text-color: #{$light-text}; }，虽然能编译通过，但会丢失运行时灵活性——JS 无法再通过 document.documentElement.style.setProperty('--text-color', ...) 安全覆盖它，因为该声明已被 SCSS “冻结”为静态值。
立即学习“前端免费学习笔记（深入）”；
- 所有
:root和:root.dark块必须保持纯 CSS 输出 - SCSS 可用于组织变量源（如
_colors.scss），但只用来生成默认值字符串，不参与运行时逻辑 - 避免在
:root内使用@if或@each控制变量输出，那会让 CSS 变得不可预测
SCSS 可以安全用于生成主题类名和媒体查询结构
SCSS 的真正价值在于提升开发效率和可维护性，而不是替代 CSS 自定义属性。你可以用它批量生成主题类、媒体查询块或 fallback 样式：
// _themes.scss
$themes: (
light: (
text: #000,
bg: #fff,
),
dark: (
text: #fff,
bg: #121212,
)
);
@each $theme, $map in $themes {
:root.#{$theme} {
@each $prop, $val in $map {
--#{$prop}: #{$val};
}
}
}
这段 SCSS 会输出干净的 CSS，且完全兼容运行时切换逻辑。关键点在于：它只生成声明，不干预变量求值时机。
- 用 SCSS 管理颜色映射表、生成
.light/.dark类、拼接@media规则都安全 - 不要用 SCSS 控制“是否启用某个变量”，那会导致 CSS 输出缺失或错乱
- 生成的 CSS 必须能被 DevTools → Elements →
:root节点直接看到并修改
切换时只操作 class，别碰 style.setProperty()
用户点击按钮后，JS 应该只做一件事：document.documentElement.classList.toggle('dark')。这是最轻量、最可靠、与媒体查询兼容的方式。
如果你用 SCSS 配合 JS 做了额外封装（比如一个 setTheme(theme) 函数），务必确保它内部没调用 style.setProperty() —— 那会绕过 :root.dark 的级联机制，导致 @media (prefers-color-scheme: dark) 失效，也破坏 Shadow DOM 内部继承。
- class 切换触发 CSS 重计算，变量自动更新，所有
var(--x)实时响应 - localStorage 存储的必须是 class 名（如
'dark'），不是变量值 - 初始化时，从 localStorage 读取后立即设置 class，早于首屏渲染（不要等
DOMContentLoaded）
最易被忽略的一点：SCSS 生成的 CSS 必须保证 :root.dark 的声明顺序在 :root 默认声明之后，否则旧版 Safari 会直接忽略整个块。这不是 SCSS 的 bug，而是你输出的 CSS 是否符合规范的问题。
