Front-End-Checklist 实战指南CSS 命名规范BEM 与命名空间的落地与验证【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本指南以 Front-End-Checklist 仓库中的 naming-conventions 规则文档 为骨架系统讲解 CSS 类名命名的核心方法论BEMBlock__Element--Modifier的完整语法、组件/布局/工具/状态/JS 钩子五类命名的命名空间划分、常见命名反模式以及 Tailwind 风格工具类方案的命名逻辑并给出可执行的多视口验证流程。读完本文你将能为一套组件库制定统一的类名约定、识别并修复歧义与样式泄漏并用 DevTools 与多断点检查完成上线前的最终核验。规则定位一条中等优先级的 CSS 最佳实践在 Front-End-Checklist 的内容体系中这条规则被收录在 packages/content/rules/en/css/naming-conventions.mdx 中其元数据定义了它在整个清单中的定位分类categoriescss子分类为best-practices优先级prioritymedium难度difficultybeginner预计耗时15 分钟一句话 TL;DR采用一致的类名命名方法论BEM、CUBE CSS 或团队约定的模式让类名自解释self-documenting并防止样式冲突。配套的 SKILL.md 还给出了该规则面向 AI Agent 的使用场景在审查样式表、组件样式与响应式行为时先检查渲染布局在不同断点和交互状态下的表现再提出修复方案。这意味着命名规范不仅是人工编码习惯也被设计为可被 Agent 自动审查的检查项。为什么命名规范如此重要没有命名约定时类名会变成一场猜谜游戏——.active到底表示导航项被激活、按钮被按下还是表单字段获得焦点使用 BEM 或类似方法论后.button--active的含义就毫无歧义。一致的命名让 CSS 实现“自文档化”self-documenting不需要阅读样式定义仅凭类名就能推断元素在组件中的角色减少排查“这个样式是谁写的、改它会不会影响别处”所花费的时间防止类名碰撞导致的意外样式泄漏style leakage——即一个组件无意间被另一处的同名选择器影响。从源码结构看仓库中的规则之间存在明确关联specificity-management.mdx 将命名规范列为“保持选择器低平特异性”的关联规则理由是BEM 通过单一类选择器天然保持特异性平坦styles-lint.mdx 则与之配套——Stylelint 可以自动强制命名模式保证全团队一致。也就是说命名约定是“低特异性级联”这套整体最佳实践的入口。BEM 核心语法Block、Element 与 ModifierBEM 是目前最广泛采用的 CSS 命名方法论其分隔符约定非常明确块Block独立组件直接使用名词命名如.card元素Element块的组成部分使用双下划线__连接如.card__header修饰符Modifier变体或状态使用双连字符--连接如.card--featured元素修饰符__与--可以组合使用如.card__title--large。/* Block — 独立组件 */ .card { } /* Element — 块的组成部分使用 __ */ .card__header { } .card__body { } .card__footer { } .card__title { } .card__image { } /* Modifier — 变体或状态使用 -- */ .card--featured { } .card--dark { } .card--loading { } /* Element modifier */ .card__title--large { }配套的 HTML 示例展示了类名如何真实地映射到 DOM 结构article classcard card--featured div classcard__header img classcard__image src... alt... /div div classcard__body h2 classcard__title card__title--largeTitle/h2 p classcard__description.../p /div footer classcard__footer button classbutton button--primaryRead more/button /footer /article注意其中两个细节块与修饰符叠加article同时拥有card块和card--featured修饰符通过双类名组合出“精选卡片”语义跨块嵌套button--primary属于另一个块button嵌套在card__footer内部但命名上完全独立——BEM 不依赖 DOM 层级来表达归属这正是它能保持特异性平坦的原因。从仓库的 specificity-management 规则 可以看到这条最佳实践背后的原理类选择器的特异性是0,0,1,0而像.card .card__header .card__title span这样的 4 层嵌套选择器特异性会升到0,0,4,0。BEM 的扁平命名.card__title-text让每个选择器都保持0,0,1,0的低平特异性后续规则与更具体的选择器可以干净地覆盖级联按预期工作。命名空间区分不同类型的类除了 BEM 本身规则文档还给出了一套前缀命名空间方案用来区分功能不同的类避免它们互相污染/* 组件类 — BEM */ .c-card { } .c-button { } /* 布局类 */ .l-grid { } .l-container { } /* 工具类 */ .u-text-center { } .u-visually-hidden { } /* 状态类 — 通过 JavaScript 动态应用 */ .is-active { } .is-loading { } .is-open { } /* JavaScript 钩子 — 永远不要为它们写样式 */ .js-modal-trigger { } .js-form-submit { }这五类前缀各有明确职责边界前缀类型用途关键纪律c-组件类组件的结构样式使用 BEM 语法l-布局类页面骨架与网格与组件样式解耦u-工具类单一职责的通用工具可跨组件复用is-状态类由 JS 切换的状态激活、加载、展开与具体组件名配合使用js-JS 钩子仅供 JavaScript 选择元素严禁为其编写样式其中js-前缀的纪律最容易被忽视如果把 JS 钩子与样式选择器混用当样式调整导致 DOM 结构调整时会连带破坏脚本逻辑。将两者分离后样式表可以自由重构行为选择器保持稳定。常见命名错误与修正规则文档用正反对照的方式列出了三类高频反模式这也是代码审查时最值得优先排查的点/* ❌ 歧义 — active 的到底是什么 */ .active { } /* ✅ 明确表达是什么处于激活状态 */ .nav-item--active { } .tab--selected { } .accordion--open { } /* ❌ 外观化命名 — 颜色变了怎么办 */ .blue-button { } .big-text { } /* ✅ 语义化命名 — 描述用途而非外观 */ .button--primary { } .text--headline { } /* ❌ 过于通用 */ .container { } /* 什么的容器 */ .wrapper { } /* ✅ 限定上下文 */ .page-container { } .hero-wrapper { }这三组对照分别揭示了命名设计的三条原则状态必须指明对象--active、--selected、--open等修饰符要挂在具体的块/元素名上而不是孤立的.active语义优先于外观.blue-button在品牌色从蓝变成绿时就是谎言而.button--primary表达的“主操作”含义永远成立名称要携带上下文全局性的.container无法回答“什么内容的容器”前缀场景后的.page-container才具备自解释能力。在审查现有代码时可以按 SKILL.md 的 Check 提示操作审计一个 CSS 文件中的所有类名检查它们是否遵循一致约定、是否存在可能冲突的歧义名称修复阶段则将类名统一重命名为Block、Block__Element、Block--Modifier模式。Utility-FirstTailwind 风格下的命名逻辑如果采用工具类优先utility-first方案命名“约定”的主体从 CSS 转移到了 HTML 中——每个工具类只描述一件事!-- 工具类各自只描述一件事 -- div classflex items-center gap-4 p-6 rounded-lg shadow-md bg-white img classw-12 h-12 rounded-full ... div classflex-1 min-w-0 h3 classtext-lg font-semibold truncateTitle/h3 p classtext-sm text-gray-500Description/p /div /div工具类方案并非没有约定而是把约定转化为两条硬性纪律原子性一个类只负责一个视觉属性间距、对齐、字号、圆角、阴影组合关系全部由 HTML 表达组合即结构.flex-1 min-w-0、.text-sm text-gray-500这类组合是团队需要默契维护的“模式词汇表”仍然需要评审与一致性管理。这条规则在 Front-End-Checklist 仓库自身的 UI 代码中就有大量实践证据。例如 packages/design-system/src/custom/navigation/breadcrumb.tsx 中大量使用inline-flex items-center gap-1.5、flex h-9 w-9 items-center justify-center、font-medium text-foreground等工具类组合motion/community-orbit.tsx 中的absolute flex size-10 items-center justify-center rounded-full border-2 border-accent/40 bg-accent/20则是“定位 弹性 尺寸 圆角 边框 背景”的纯原子组合。同时组件库中仍保留copy-button、code-inline、code-surface-prompt等语义化的自定义类名见 custom/content/code-surface.tsx说明在实际工程中工具类与少量语义类可以共存——关键依然是语义类也要遵循命名约定。标准与参照规则文档明确了两种外部标准作为最终渲染行为的判定依据以MDN: CSS作为跨浏览器与断点下最终渲染行为的标准参照对应规则元数据中sources的role: reference以web.dev: Learn CSS作为实现层面的标准参照role: implementation。这两份标准在 naming-conventions.mdx 的 frontmatter 中均被标记为authority: primary的权威来源用于裁决“命名约定下的具体渲染效果是否符合预期”。验证流程上线前的四步核验命名规范最终要在渲染结果上兑现因此规则文档给出了可执行的验证步骤检查受影响断点与交互状态在规则所影响的断点breakpoints和交互状态hover、focus、active 等下检查渲染后的 UI核对计算样式在 DevTools 中确认计算后的样式computed styles与预期修复一致——这一步能验证选择器是否真的命中目标元素间接验证命名是否正确作用于样式多视口测试上线前至少在一个移动端和一个桌面端视口进行测试防止命名/布局问题只在特定宽度下暴露面向用户的结果验证如果规则影响动效motion、对比度contrast或布局稳定性layout stability直接验证这些用户可感知的结果。与相邻规则配合使用命名规范不是孤立的。在 naming-conventions.mdx 的relatedRules中它明确与四条相邻规则联动specificity-managementBEM 用单一类选择器将特异性保持在平坦水平是“保持低平特异性”的前提styles-lintStylelint 可以自动检查类名模式与选择器特异性把命名约定从“人工评审”升级为“机器强制”has-selector与reset-css同属css/best-practices区域常被放在一起审查。实际落地时推荐的组合路径是先约定命名方法论本文核心→ 用 Stylelint 规则强制类名格式 → 保持特异性平坦 → 在 CI 与代码审查中执行 SKILL.md 定义的审查提示Check / Fix / Explain / Code Review最后按验证流程在真实浏览器中确认渲染结果。对于新组件Block__Element--Modifier的单类选择器天然满足低特异性要求对于存量样式优先从歧义类名.active、.container与外观化类名.blue-button开始迁移因为它们的修复收益最高、风险最低。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Front-End-Checklist 实战指南：CSS 命名规范（BEM 与命名空间）的落地与验证
Front-End-Checklist 实战指南CSS 命名规范BEM 与命名空间的落地与验证【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本指南以 Front-End-Checklist 仓库中的 naming-conventions 规则文档 为骨架系统讲解 CSS 类名命名的核心方法论BEMBlock__Element--Modifier的完整语法、组件/布局/工具/状态/JS 钩子五类命名的命名空间划分、常见命名反模式以及 Tailwind 风格工具类方案的命名逻辑并给出可执行的多视口验证流程。读完本文你将能为一套组件库制定统一的类名约定、识别并修复歧义与样式泄漏并用 DevTools 与多断点检查完成上线前的最终核验。规则定位一条中等优先级的 CSS 最佳实践在 Front-End-Checklist 的内容体系中这条规则被收录在 packages/content/rules/en/css/naming-conventions.mdx 中其元数据定义了它在整个清单中的定位分类categoriescss子分类为best-practices优先级prioritymedium难度difficultybeginner预计耗时15 分钟一句话 TL;DR采用一致的类名命名方法论BEM、CUBE CSS 或团队约定的模式让类名自解释self-documenting并防止样式冲突。配套的 SKILL.md 还给出了该规则面向 AI Agent 的使用场景在审查样式表、组件样式与响应式行为时先检查渲染布局在不同断点和交互状态下的表现再提出修复方案。这意味着命名规范不仅是人工编码习惯也被设计为可被 Agent 自动审查的检查项。为什么命名规范如此重要没有命名约定时类名会变成一场猜谜游戏——.active到底表示导航项被激活、按钮被按下还是表单字段获得焦点使用 BEM 或类似方法论后.button--active的含义就毫无歧义。一致的命名让 CSS 实现“自文档化”self-documenting不需要阅读样式定义仅凭类名就能推断元素在组件中的角色减少排查“这个样式是谁写的、改它会不会影响别处”所花费的时间防止类名碰撞导致的意外样式泄漏style leakage——即一个组件无意间被另一处的同名选择器影响。从源码结构看仓库中的规则之间存在明确关联specificity-management.mdx 将命名规范列为“保持选择器低平特异性”的关联规则理由是BEM 通过单一类选择器天然保持特异性平坦styles-lint.mdx 则与之配套——Stylelint 可以自动强制命名模式保证全团队一致。也就是说命名约定是“低特异性级联”这套整体最佳实践的入口。BEM 核心语法Block、Element 与 ModifierBEM 是目前最广泛采用的 CSS 命名方法论其分隔符约定非常明确块Block独立组件直接使用名词命名如.card元素Element块的组成部分使用双下划线__连接如.card__header修饰符Modifier变体或状态使用双连字符--连接如.card--featured元素修饰符__与--可以组合使用如.card__title--large。/* Block — 独立组件 */ .card { } /* Element — 块的组成部分使用 __ */ .card__header { } .card__body { } .card__footer { } .card__title { } .card__image { } /* Modifier — 变体或状态使用 -- */ .card--featured { } .card--dark { } .card--loading { } /* Element modifier */ .card__title--large { }配套的 HTML 示例展示了类名如何真实地映射到 DOM 结构article classcard card--featured div classcard__header img classcard__image src... alt... /div div classcard__body h2 classcard__title card__title--largeTitle/h2 p classcard__description.../p /div footer classcard__footer button classbutton button--primaryRead more/button /footer /article注意其中两个细节块与修饰符叠加article同时拥有card块和card--featured修饰符通过双类名组合出“精选卡片”语义跨块嵌套button--primary属于另一个块button嵌套在card__footer内部但命名上完全独立——BEM 不依赖 DOM 层级来表达归属这正是它能保持特异性平坦的原因。从仓库的 specificity-management 规则 可以看到这条最佳实践背后的原理类选择器的特异性是0,0,1,0而像.card .card__header .card__title span这样的 4 层嵌套选择器特异性会升到0,0,4,0。BEM 的扁平命名.card__title-text让每个选择器都保持0,0,1,0的低平特异性后续规则与更具体的选择器可以干净地覆盖级联按预期工作。命名空间区分不同类型的类除了 BEM 本身规则文档还给出了一套前缀命名空间方案用来区分功能不同的类避免它们互相污染/* 组件类 — BEM */ .c-card { } .c-button { } /* 布局类 */ .l-grid { } .l-container { } /* 工具类 */ .u-text-center { } .u-visually-hidden { } /* 状态类 — 通过 JavaScript 动态应用 */ .is-active { } .is-loading { } .is-open { } /* JavaScript 钩子 — 永远不要为它们写样式 */ .js-modal-trigger { } .js-form-submit { }这五类前缀各有明确职责边界前缀类型用途关键纪律c-组件类组件的结构样式使用 BEM 语法l-布局类页面骨架与网格与组件样式解耦u-工具类单一职责的通用工具可跨组件复用is-状态类由 JS 切换的状态激活、加载、展开与具体组件名配合使用js-JS 钩子仅供 JavaScript 选择元素严禁为其编写样式其中js-前缀的纪律最容易被忽视如果把 JS 钩子与样式选择器混用当样式调整导致 DOM 结构调整时会连带破坏脚本逻辑。将两者分离后样式表可以自由重构行为选择器保持稳定。常见命名错误与修正规则文档用正反对照的方式列出了三类高频反模式这也是代码审查时最值得优先排查的点/* ❌ 歧义 — active 的到底是什么 */ .active { } /* ✅ 明确表达是什么处于激活状态 */ .nav-item--active { } .tab--selected { } .accordion--open { } /* ❌ 外观化命名 — 颜色变了怎么办 */ .blue-button { } .big-text { } /* ✅ 语义化命名 — 描述用途而非外观 */ .button--primary { } .text--headline { } /* ❌ 过于通用 */ .container { } /* 什么的容器 */ .wrapper { } /* ✅ 限定上下文 */ .page-container { } .hero-wrapper { }这三组对照分别揭示了命名设计的三条原则状态必须指明对象--active、--selected、--open等修饰符要挂在具体的块/元素名上而不是孤立的.active语义优先于外观.blue-button在品牌色从蓝变成绿时就是谎言而.button--primary表达的“主操作”含义永远成立名称要携带上下文全局性的.container无法回答“什么内容的容器”前缀场景后的.page-container才具备自解释能力。在审查现有代码时可以按 SKILL.md 的 Check 提示操作审计一个 CSS 文件中的所有类名检查它们是否遵循一致约定、是否存在可能冲突的歧义名称修复阶段则将类名统一重命名为Block、Block__Element、Block--Modifier模式。Utility-FirstTailwind 风格下的命名逻辑如果采用工具类优先utility-first方案命名“约定”的主体从 CSS 转移到了 HTML 中——每个工具类只描述一件事!-- 工具类各自只描述一件事 -- div classflex items-center gap-4 p-6 rounded-lg shadow-md bg-white img classw-12 h-12 rounded-full ... div classflex-1 min-w-0 h3 classtext-lg font-semibold truncateTitle/h3 p classtext-sm text-gray-500Description/p /div /div工具类方案并非没有约定而是把约定转化为两条硬性纪律原子性一个类只负责一个视觉属性间距、对齐、字号、圆角、阴影组合关系全部由 HTML 表达组合即结构.flex-1 min-w-0、.text-sm text-gray-500这类组合是团队需要默契维护的“模式词汇表”仍然需要评审与一致性管理。这条规则在 Front-End-Checklist 仓库自身的 UI 代码中就有大量实践证据。例如 packages/design-system/src/custom/navigation/breadcrumb.tsx 中大量使用inline-flex items-center gap-1.5、flex h-9 w-9 items-center justify-center、font-medium text-foreground等工具类组合motion/community-orbit.tsx 中的absolute flex size-10 items-center justify-center rounded-full border-2 border-accent/40 bg-accent/20则是“定位 弹性 尺寸 圆角 边框 背景”的纯原子组合。同时组件库中仍保留copy-button、code-inline、code-surface-prompt等语义化的自定义类名见 custom/content/code-surface.tsx说明在实际工程中工具类与少量语义类可以共存——关键依然是语义类也要遵循命名约定。标准与参照规则文档明确了两种外部标准作为最终渲染行为的判定依据以MDN: CSS作为跨浏览器与断点下最终渲染行为的标准参照对应规则元数据中sources的role: reference以web.dev: Learn CSS作为实现层面的标准参照role: implementation。这两份标准在 naming-conventions.mdx 的 frontmatter 中均被标记为authority: primary的权威来源用于裁决“命名约定下的具体渲染效果是否符合预期”。验证流程上线前的四步核验命名规范最终要在渲染结果上兑现因此规则文档给出了可执行的验证步骤检查受影响断点与交互状态在规则所影响的断点breakpoints和交互状态hover、focus、active 等下检查渲染后的 UI核对计算样式在 DevTools 中确认计算后的样式computed styles与预期修复一致——这一步能验证选择器是否真的命中目标元素间接验证命名是否正确作用于样式多视口测试上线前至少在一个移动端和一个桌面端视口进行测试防止命名/布局问题只在特定宽度下暴露面向用户的结果验证如果规则影响动效motion、对比度contrast或布局稳定性layout stability直接验证这些用户可感知的结果。与相邻规则配合使用命名规范不是孤立的。在 naming-conventions.mdx 的relatedRules中它明确与四条相邻规则联动specificity-managementBEM 用单一类选择器将特异性保持在平坦水平是“保持低平特异性”的前提styles-lintStylelint 可以自动检查类名模式与选择器特异性把命名约定从“人工评审”升级为“机器强制”has-selector与reset-css同属css/best-practices区域常被放在一起审查。实际落地时推荐的组合路径是先约定命名方法论本文核心→ 用 Stylelint 规则强制类名格式 → 保持特异性平坦 → 在 CI 与代码审查中执行 SKILL.md 定义的审查提示Check / Fix / Explain / Code Review最后按验证流程在真实浏览器中确认渲染结果。对于新组件Block__Element--Modifier的单类选择器天然满足低特异性要求对于存量样式优先从歧义类名.active、.container与外观化类名.blue-button开始迁移因为它们的修复收益最高、风险最低。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考