原子类与bem类必须严格分工:bem仅负责语义结构、js交互和测试定位,原子类全权接管视觉样式;禁止混用或用@apply耦合,状态修饰符必须用bem,纯视觉调整可用原子类配合css变量。

原子类和BEM类不能混在同一个元素上
常见错误是给一个按钮同时写 btn btn--primary u-p-4 u-text-center。这会导致样式控制权分裂:BEM类负责语义结构,原子类负责视觉细节,但两者对padding、text-align等属性的覆盖顺序不可预测,尤其在CSS优先级或构建工具压缩后容易失效。
真正可行的共存方式只有一种:用原子类“实现”BEM结构,而不是“补充”它。比如把.button__icon的尺寸、颜色、间距全部用u-w-6 u-h-6 u-text-gray-500 u-mr-2定义,而BEM类只保留语义锚点作用——class="button__icon"本身不带任何样式规则。
- 原子类必须接管全部布局与视觉属性,BEM类只用于JS选择、测试定位、可访问性标注(如
aria-labelledby) - 禁止在SCSS中用
@apply把原子类塞进BEM选择器里,那会破坏原子类的可组合性 - 构建时需确保原子类的CSS顺序早于BEM样式层,否则
.button__icon { display: flex }可能被u-flex覆盖却无提示
修饰符(--modifier)该用BEM还是原子类
修饰符描述的是组件状态或变体,比如button--disabled、card--loading,这类逻辑应由BEM承担。原子类适合处理静态、正交的视觉特征,比如u-bg-gray-100、u-border-2,但不适合表达“不可点击”“正在加载中”这种需联动JS的状态。
典型反例:button u-bg-gray-200 u-cursor-not-allowed代替button--disabled。问题在于:前者无法被JS统一监听(element.classList.contains('button--disabled')),也无法在自动化测试中作为状态断言依据;后者能直接映射到组件的disabled prop,形成闭环。
- 所有需要JS切换、测试断言、无障碍支持的状态,必须用BEM修饰符
- 纯视觉调整(如暗色模式下的背景色替换)可用CSS变量+原子类,但变量名要语义化,比如
--color-surface而非--bg-blue - 避免
button--disabled u-bg-gray-200这种混合写法——要么全BEM控制状态样式,要么用原子类配合主题系统自动注入
元素(__element)命名要不要保留
保留。哪怕你用UnoCSS或Tailwind,card__header、form__submit-button这类类名仍有必要存在。它们不是为了写样式,而是为DOM提供稳定、语义化的锚点。
例如在Vue中,你可能写<div :class="['card__header', themeClasses.header]">,这里的<code>card__header确保了无论主题如何切换,测试脚本总能通过document.querySelector('.card__header')准确定位到页头区域;而themeClasses.header才是实际决定背景、字体的原子类集合。
- 删除BEM类名等于放弃语义契约,后续加SSR hydration、做A/B测试、接入自动化E2E都会出问题
- 元素名不参与样式计算时,可以设为
display: contents或空规则,不影响渲染 - 禁止用原子类替代元素语义,比如把
card__title写成u-font-bold u-text-xl u-mb-2——你再也无法回答“这个标题属于哪个卡片”
最易被忽略的边界:JS操作className时的陷阱
很多人以为只要模板里写了class="button button--primary"就万事大吉,但JS动态添加类时极易踩坑。比如el.classList.add('u-p-6')看似无害,实则绕过了BEM的语义约束——这个u-p-6可能和button--large的内边距冲突,且无法被CSS Modules或Shadow DOM隔离。
正确做法是把所有原子类封装进BEM修饰符的映射表里,在JS中只操作BEM类:
const BUTTON_MODIFIERS = {
'button--large': ['u-p-6', 'u-text-lg'],
'button--ghost': ['u-bg-transparent', 'u-text-primary']
};
然后统一用applyModifier(el, 'button--large')来同步更新。这样既保住了BEM的语义层级,又没丢掉原子类的灵活性。
复杂点在于:这个映射表必须和构建工具联动,确保未使用的原子类能被PurgeCSS识别并剔除。否则,button--large明明只在登录页用,却把整套u-p-*间距类都打进生产包里。











