推荐方式是通过 document.documentElement.dataset.theme = 'dark' 控制主题，CSS 使用 html[data-theme="dark"] 响应；禁止在 body 或容器上直接加 app--theme-dark 类，避免 SSR 白屏、变量未注入及 PurgeCSS 误删等问题。
主题类必须挂载在 html 上，用 data-theme 属性控制
直接给 body 或顶层容器加 app--theme-dark 类是错的——它既不是 BEM 的 Block，也不支持系统偏好自动同步。真正可控的方式是操作 document.documentElement.dataset.theme = 'dark'，让 CSS 通过 html[data-theme="dark"] 响应。
常见错误现象：切暗色后部分组件没变、select 下拉框文字看不清、SSR 首屏白屏。根本原因是用了 body--dark 或 :root.dark 这类非法写法，导致变量未注入、原生控件样式被强制覆盖、构建时样式被 PurgeCSS 误删。
-
html[data-theme="dark"]是唯一推荐的根级控制方式，浏览器能正确响应window.matchMedia('(prefers-color-scheme: dark)') - 服务端渲染时，需提前根据 Cookie / User-Agent 写入
data-theme，否则 JS 加载前变量无值 - 所有 CSS 变量必须带 fallback：
color: var(--text-primary, #333);，否则 SSR 或 JS 失败时直接白屏
app--theme-dark 这类修饰符只在 Block 级别有意义，且必须显式声明
如果你确实需要一个顶层 Block（比如包裹整个应用的容器），它的主题修饰符必须显式声明为 app--theme-dark，而不是 app--dark 或 dark-app。前者语义清晰、可被 PostCSS 插件静态分析；后两者要么被识别为新 Block，要么破坏 BEM 主语结构。
-
app--theme-dark合法，app--dark非法：BEM 要求主题修饰符必须含--theme-前缀，以区分状态类（如button--disabled） - 多个主题共存时（如深色 + 高对比度），应叠加修饰符：
app app--theme-dark app--theme-high-contrast，而不是拼成app--theme-dark-high-contrast—— 修饰符不可嵌套，也不可连写 - 禁止在组件内部硬写主题逻辑，比如
.button--primary.button--dark—— 这把环境状态和组件角色耦合，破坏正交性
CSS 变量名必须带 Block 前缀，且声明位置要对齐 DOM 结构
BEM 不是自动作用域隔离机制，--color-primary 这种裸名变量必然冲突。--card-color-primary 才符合 BEM 语义，变量须声明在对应 Block 的选择器内，避免提级至 :root。
立即学习“前端免费学习笔记（深入）”；
- 块级变量：以块名为根，如
--card-padding、--card-border-radius - 元素级变量：可选，仅当该元素样式高度定制且复用性低时才定义，如
--card__title-font-size - 修饰符级变量：不单独定义，直接在修饰符规则中覆盖块/元素变量，如
.card--compact { --card-padding: 8px; } - 变量作用域必须和 BEM Block 节点对齐：
.user-card { --user-card-padding: 1rem; }，这样它只会继承到.user-card及其后代，不会泄露
组件内响应主题靠变量，不是靠新增修饰符
别写 button--dark、card--high-contrast 这类类名。BEM 修饰符只表达组件自身角色或状态（button--primary、button--loading），不承担“当前主题是什么”的职责。主题响应应全部交给 CSS 自定义属性驱动。
- 组件内响应主题变化，靠的是变量值切换，不是靠类名增删。例如按钮在深色主题下调整边框透明度，应写：
.button { border-color: var(--button-border-color); }，然后在html[data-theme="dark"]下覆盖该变量 - 若用 Sass，可用
@at-root .app--theme-dark { .button { } }提升作用域，比嵌套更可控且不生成后代选择器 - 全局变量只放在
:root或[data-theme]下，用于主题色、间距基数等跨 Block 共享值；业务变量优先挂载到组件根节点
data-theme 当作普通修饰符去写 CSS 规则——它不是 BEM 的一部分，而是根级环境信号，必须严格与 HTML 结构绑定。 
