类名中嵌入断点标识（如--mobile、@md）无效，断点逻辑必须由显式@media规则控制；修饰符仅表达状态意图，所有断点值须统一收口至变量并集中管理于_breakpoints.scss。
修饰符名里写 --mobile 或 @md 会失效
浏览器根本不识别 block--hidden@md 或 card--mobile 这类类名里的断点标识——它们只是字符串，不会触发任何媒体查询行为。CSS 引擎只认选择器匹配 + 外部 @media 规则，类名中塞断点等于加了无意义注释。
常见错误现象包括：header--fixed@sm 写了但小屏没固定；多个组件都用 --hidden@lg，结果一处写 min-width、另一处写 max-width，样式互相覆盖；重构时想改断点值，得满项目搜 @sm、@md，漏一处就出问题。
- 修饰符只表达状态意图（如
nav-menu--collapsed），不表达“何时生效” - 断点逻辑必须由
@media显式控制，不能靠类名“暗示” - 所有断点数值必须收口到统一变量（如
$bp-md: 768px），禁止硬编码在类名或 CSS 中
正确写法：语义化修饰符 + 外部媒体查询包裹
修饰符是钩子，@media 是开关。HTML 只需写 <div class="block block--hidden-below-md">，CSS 则用媒体查询限定它的作用范围：
<pre class="brush:php;toolbar:false;">.block {
display: block;
}
@media (max-width: 767px) {
.block--hidden-below-md {
display: none;
}
}</pre>
<p>命名要避免歧义：<code>block--sm-hidden 不明确 “sm” 指尺寸还是断点；block--mobile-only 暗示排他性但 CSS 无法自动清除其他断点样式。
- 推荐动词 + 范围结构：
nav-menu--hidden-below-md、card--stacked-above-lg - 前提：团队对
md、lg等缩写有统一定义（如 Sass 变量$breakpoint-md: 768px） - 所有
@media必须收口到_breakpoints.scss，禁止在组件样式文件里直接写
React + CSS Modules 场景下容易踩的坑
很多人以为组件自己管响应式更灵活，结果断点逻辑散落各处，后期无法全局调控。JS 层不该拼接断点类名，也不该监听 resize。
- 禁止字符串拼接类名：
className={`button button--${size}@${breakpoint}`❌ - 禁止硬编码修饰符：
className="button button--primary button--mobile"❌ - 正确做法：用状态控制语义化修饰符，如
clsx('card', isStacked && 'card--stacked')✅ - ESLint 必须启用自定义规则拦截非语义类名拼接
最容易被忽略的一点：媒体查询写法必须统一
混用 max-width 和 min-width 极易引发覆盖冲突。比如同时存在 @media (max-width: 768px) 和 @media (min-width: 768px)，在 768px 精确宽度下两者都匹配，最终生效的是源码顺序靠后的规则——这完全不可控。
推荐全项目统一用 min-width，断点设为 768px、992px、1200px 这类逻辑宽度，并确保 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 已声明。没有它，移动端永远按桌面宽度渲染，@media 形同虚设。
