应使用语义化BEM类名，如user-profile-card__avatar--compact，而非avatar或btn-primary；Block名须与设计系统组件名完全一致，并与文件路径对齐，确保Figma、代码、DevTools三方统一。
设计稿里的“用户头像区域”怎么变成可搜索的CSS类名
直接把设计师说的“大头像”“小头像”翻译成 big-avatar 或 small-avatar 是错的——这类命名没有上下文，搜不到、改不动、复用不了。真正能映射到代码的是视觉区块与业务语义的交集。
实操建议：
- 把设计稿中每个独立可交互/可复用的视觉单元，当场拆解为一个
Block：比如“用户资料卡片” →user-profile-card - 卡片内的“头像”不是独立 Block，而是它的
Element：写成user-profile-card__avatar，不是avatar也不是profile-avatar - 如果该头像在不同场景下有尺寸差异（如详情页 vs 列表项），用
Modifier表达状态，不是新 Block：user-profile-card__avatar--compact - 禁止跨组件复用元素名：不要让
user-profile-card__avatar和comment-item__avatar共享同一套 CSS 规则，它们语义不同、维护域不同
为什么 button--primary 能被前端和设计师同时理解，而 btn-primary 不行
button 是具象 Block 名，对应设计系统文档里的 “Button” 组件页；--primary 是明确的状态开关，设计师在 Figma 中标注“Primary 状态”时，前端立刻知道该挂哪个类名。而 btn 是缩写、是实现细节，既不唯一也不可索引。
常见错误现象：
立即学习“前端免费学习笔记（深入）”；
- 设计师问：“那个蓝色按钮的禁用态样式对不上”，开发翻遍
button.css找不到btn--disabled，因为实际类名是ui-button--disabled，命名断层了 - Figma 插件导出类名时生成
btn-lg，但项目里只认button__content--large，对接失败
关键点：Block 名必须与设计系统组件库的官方命名完全一致，大小写、连字符、单复数都不能差。例如 Ant Design 的 Button 组件，对应类名就该是 ant-button，而不是强行改成 button —— 这不是 BEM 教条，是协作契约。
将一个或多个 UI 原型图、线框图、产品截图或设计稿转换为标准化、可直接交付的 PRD 风格文档，供产品、设计、前端和测试共同使用。适用于 Codex 需要分析 PC 网页、桌面端、移动端、响应式页面、独立弹窗、表单、表格、看板、数据大屏或多页面流程截图，还原页面结构与交互，强制套用固定文档模板，抽取跨页面共享规则，或把一组原型沉淀为单页规范文档加整体业务流程文档的场景。不适用于纯视觉审美点评、代码实现、接口设计、埋点方案、竞品分析或无 UI 输入的业务需求创作。
如何让 Figma 标注、PR Review、DevTools 定位全部指向同一个文件
BEM 类名只有和文件路径对齐，才能实现真·语言统一。否则设计师在 Figma 里点“复制类名”，开发粘贴进搜索框却找不到对应 CSS 文件，协作就卡在第一步。
实操建议：
- 组件目录名 = Block 名：
/components/user-profile-card/→ 主类名必须是user-profile-card - 子元素和修饰符的 CSS 规则，全部写在
user-profile-card.css里，不分散、不跨文件引用 - 禁止在
global.css或layout.css里写任何__或--类名——那说明它本就不该是全局的 - 用 Chrome DevTools 点击 Styles 面板中的类名时，链接必须能跳转到
user-profile-card.css第 23 行，而不是index.css:1456
第三方组件库（如 Ant Design）要不要套 BEM
不要。Ant Design 的 ant-btn、Element Plus 的 el-button 本身就是成熟 Block，它们的命名、作用域、升级节奏已自成体系。硬套 button__icon 会破坏样式隔离，也让你无法响应上游的 patch 更新。
正确桥接方式：
- 把第三方组件当“原子 Block”使用，在它外部用 BEM 组织布局关系：
search-form__submit-btn包裹一个<button></button>，而不是重写 Button 内部结构 - 需要定制样式时，用 wrapper 类 + CSS 自定义属性，而非覆盖
.ant-btn原生选择器 - 如果团队内部封装了一层
MyButton，那它的类名才走 BEM：my-button、my-button__icon，且目录严格对应
最易被忽略的一点：BEM 的价值不在“写得漂亮”，而在“改得安心”。当你删掉一个 user-profile-card__avatar--compact 类名时，必须能确定它只影响用户资料卡片里的紧凑头像，不会顺手干掉评论列表里的头像尺寸——这种确定性，来自 Block 的边界感，而不是双下划线本身。
