主题类必须挂载在顶层Block（如app）上并用--theme-前缀，禁止直接作用于body或用data-theme；正确写法是app--theme-dark，确保语义清晰、作用域可控、可静态分析，且组件只声明自身状态而非所处主题。
主题类必须挂载在根元素上，且命名需带--theme前缀
直接在 body 或最外层容器加 theme--dark 这类类名是错的——它破坏了 BEM 的 Block 边界，也导致后续所有组件无法通过选择器精准响应。正确做法是定义一个顶层 Block，比如 app，再用修饰符表达主题：app--theme-dark、app--theme-high-contrast。
这样做的关键好处是：CSS 里能写 .app--theme-dark .button--primary { ... }，语义清晰、作用域可控、可被 PostCSS 插件静态分析。如果写成 .theme-dark .button，就退化为普通 CSS 层级控制，和 BEM 无关，也容易被第三方样式污染。
- 禁止用
data-theme="dark"配合属性选择器替代修饰符——它绕过了 BEM 的状态语义，.button[data-theme="dark"]不表达“button 的 dark 变体”，而是“在 dark 主题下 button 应该长这样”，职责错位 - 主题修饰符必须和 Block 名紧耦合，
app--dark合法，但dark-app或app-dark都非法：前者不是 Block 为主语，后者单连字符被识别为新块名 - 多个主题共存时（如深色+高对比度），应叠加修饰符：
app app--theme-dark app--theme-high-contrast，而非拼接app--theme-dark-high-contrast（修饰符不可嵌套）
组件内如何响应主题变化：用嵌套修饰符而非全局变量
很多人以为主题切换靠 CSS 自定义变量（--color-primary）就够了，但 BEM 下更关键的是让每个组件「知道自己处在哪个主题里」。这意味着不能只改变量值，还要让组件类名结构能被主题修饰符命中。
例如按钮在深色主题下需要调整边框透明度和文字阴影，就不能只依赖 .button { color: var(--text-primary); }，而要显式写出：
立即学习“前端免费学习笔记（深入）”；
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
.button { background: var(--bg-default); }
.app--theme-dark .button { background: var(--bg-default-dark); }
.app--theme-dark .button--primary { color: var(--text-on-primary-dark); }
- 所有主题相关样式必须以
.app--theme-xxx为父选择器，避免泄漏到非主题区域 - 不推荐在组件内部用
:where(.app--theme-dark) .button——:where()会重置优先级，导致基础样式被意外覆盖 - 若使用 Sass，可用
@at-root提升主题块作用域：@at-root .app--theme-dark { .button { ... } }，比嵌套更易维护
为什么不能把主题修饰符写在组件 Block 上
像 .button--theme-dark 这种写法看似直观，实则埋下三处硬伤：
- 主题不是按钮自身的状态，而是应用上下文；
.button--disabled合理，因为禁用是按钮可编程的状态，而主题切换不归按钮管 - 一旦按钮出现在不同主题区域（比如弹窗用深色，主页面用浅色），就得动态增删
button--theme-dark，JS 逻辑爆炸，且无法 SSR 预判 - CSS 里无法区分「这个按钮当前是 dark 主题」和「这个按钮默认支持 dark 主题变体」——后者是设计意图，前者是运行时状态，BEM 要求修饰符表达的是设计意图
真正需要动态控制的，是根节点上的 app--theme-dark，其余全部靠 CSS 层级继承和组合选择器响应，这才是可预测、可测试、可 SSR 的路径。
主题与状态修饰符共存时的 class 顺序怎么排
当一个按钮既是深色主题下、又处于加载中、还是禁用态，HTML 类名写成 button button--loading button--disabled 是对的，但要不要加 app--theme-dark？答案是：不加在按钮上，只加在根节点。
所以最终结构是：
<div class="app app--theme-dark"> <button class="button button--loading button--disabled"></button> </div>
- 组件自身只声明它「是什么」和「当前什么状态」，不声明「在哪种主题下」——那是布局层的责任
- 如果项目用了
clsx或类似工具，主题类必须由 Layout 组件注入，而不是 Button 组件自己读取window.__THEME拼接 - 最容易被忽略的一点：服务端渲染时，
app--theme-dark必须和客户端首次 hydrate 时完全一致，否则 React/Vue 会触发样式抖动甚至 hydration error
