团队文档必须可查、可校验、可同步，Block名需用TypeScript或JSON Schema强制约束，Element名须表语义非结构，Modifier需明确状态契约与兼容性，所有变更须自动触发清单更新、CI校验与文档生成。
团队文档不是写给机器看的，而是防止人脑在三个月后对着 .user-card__title--featured 发呆——它必须能被快速查、被强制校验、被低成本同步。
怎么定义 Block 名清单并让它真正生效
Block 名不能靠“大家自觉遵守”，否则很快会出现 usr-card、userCard、user-card-v2 并存。必须收口到可执行的约束源：
- 用 TypeScript interface 或 JSON Schema 明确声明所有公开 Block 名，例如
type BlockName = 'user-card' | 'date-picker' | 'filter-panel' - 所有 HTML 模板、CSS 类名、组件文件名（如
UserCard.vue）都必须与该清单对齐 - 禁止在文档里写“推荐使用
card”，而要写“仅允许使用以下 Block 名：card、teaser、stat-badge” - CI 阶段用
stylelint-selector-bem-pattern拦截非法类名，比如.card .header或.user-card__title-large
Element 命名为什么不能靠 DOM 结构推断
看到 HTML 里 <div class="user-card"><div><h3 class="title"></h3></div></div> 就写 .user-card__title 是错的——Element 名必须反映语义角色，不是 DOM 深度：
-
.user-card__name✅（这是用户姓名，和位置无关） -
.user-card__header-title❌（“header”是结构词，不是业务角色；且嵌套命名违反 BEM 扁平原则） -
.user-card__title❌（歧义：是卡片标题？还是用户姓名？需结合上下文猜） - 如果一个 Element 内还要分
value和unit，说明它已具备独立逻辑，应拆成新 Block：stat-value和stat-unit
Modifier 文档里最常漏掉的兼容性说明
修饰符不是样式开关，而是状态契约。文档若只写“加 --large 变大”，下游开发者就会在响应式场景里误用：
立即学习“前端免费学习笔记（深入）”；
-
button--large应注明：“仅用于桌面端固定尺寸变体；移动端请配合@media (max-width: 768px)使用button--compact” -
card--featured要明确：“触发此修饰符的 JS 逻辑必须同时设置aria-current="true"，否则无障碍失效” - 禁止出现纯视觉修饰符如
--blue、--small；文档中必须替换为业务语义，如--brand、--compact - 所有 Modifier 必须在 CSS 文件中与对应 Block/Element 同文件定义，不许跨文件拼接（例如
card.css里定义.card--featured，不许在theme.css里覆盖）
真正难的不是写清楚规则，而是让每次改名、加元素、新增修饰符时，都自动触发清单更新、CI 校验、文档生成三件事——否则文档半年后就只是个纪念品。
