angular-css-bem-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Angular + BEM CSS Best Practices

Angular + BEM CSS 最佳实践

A methodology guide for combining Angular's component architecture with BEM (Block Element Modifier) CSS naming convention to create reusable components and enable code sharing in front-end development. Contains 6 rules with bad/good examples in CSS, SCSS, and SASS.

本指南介绍了如何将Angular的组件架构与BEM（块元素修饰符）CSS命名规范相结合，以在前端开发中创建可复用组件、实现代码共享。包含6条规则，附带CSS、SCSS、SASS的正反示例。

When to Apply

适用场景

Reference these guidelines when:

Writing CSS/SCSS/SASS for Angular components
Naming CSS classes in Angular templates
Reviewing component styles for consistency
Deciding whether to split a component based on styling complexity
Setting up CSS architecture for a new Angular project
Refactoring existing styles to follow BEM methodology

在以下场景可参考这些规范：

为Angular组件编写CSS/SCSS/SASS代码
在Angular模板中命名CSS类
评审组件样式的一致性
根据样式复杂度判断是否需要拆分组件
为新的Angular项目搭建CSS架构
重构现有样式以遵循BEM方法

Core Principles

核心原则

1 Component = 1 BEM Block — The block name matches the component selector

Max 2 Levels — Only

Block

and

Block__Element

, never

Block__Element__SubElement

Split When Deep — If you need a third level, extract a child component
Flat Selectors — No descendant, child, or tag-qualified selectors
Semantic Names — Element names describe what, not how or where
Modifiers for Variants — Use
```
--modifier
```
for states and variants, always with the base class

1个组件 = 1个BEM块 —— 块名称与组件选择器保持一致
最多2级嵌套 —— 仅允许
```
Block
```
和
```
Block__Element
```
，禁止使用
```
Block__Element__SubElement
```
层级过深时拆分 —— 如果需要第三级嵌套，请抽离出子组件
扁平选择器 —— 不使用后代、子元素或标签限定选择器
语义化命名 —— 元素名称描述「是什么」，而非「样式如何」或「位置在哪」
变体使用修饰符 —— 使用
```
--modifier
```
表示状态和变体，始终搭配基类使用

Rule Categories by Priority

按优先级划分的规则分类


bem-block-selector
bem-max-nesting
bem-split-components
bem-element-naming
bem-modifier-patterns
bem-no-cascading

Priority	Rule	Impact	File
1	Block = Component Selector	CRITICAL	`bem-block-selector`
2	Max 2 Levels of Nesting	CRITICAL	`bem-max-nesting`
3	Split Child Components	CRITICAL	`bem-split-components`
4	Element Naming Conventions	HIGH	`bem-element-naming`
5	Modifier Patterns	HIGH	`bem-modifier-patterns`
6	No Cascading Selectors	HIGH	`bem-no-cascading`


bem-block-selector
bem-max-nesting
bem-split-components
bem-element-naming
bem-modifier-patterns
bem-no-cascading

优先级	规则	影响程度	文件
1	块 = 组件选择器	严重	`bem-block-selector`
2	最多2级嵌套	严重	`bem-max-nesting`
3	拆分子组件	严重	`bem-split-components`
4	元素命名规范	高	`bem-element-naming`
5	修饰符模式	高	`bem-modifier-patterns`
6	禁止级联选择器	高	`bem-no-cascading`

Quick Reference

快速参考

1. Block = Component Selector (CRITICAL)

1. 块 = 组件选择器（严重）

```
bem-block-selector
```
- BEM block name must match the Angular component selector (minus prefix)

```
bem-block-selector
```
- BEM块名称必须与Angular组件选择器（去掉前缀后）一致

2. Maximum 2 Levels (CRITICAL)

2. 最多2级嵌套（严重）

bem-max-nesting

- Never nest beyond

.block__element

— no

.block__element__subelement

bem-max-nesting

- 嵌套层级永远不要超过

.block__element

—— 禁止使用

.block__element__subelement

3. Split Child Components (CRITICAL)

3. 拆分子组件（严重）

```
bem-split-components
```
- Extract child components when BEM depth would exceed 2 levels

```
bem-split-components
```
- 当BEM嵌套深度即将超过2级时，抽离子组件

4. Element Naming (HIGH)

4. 元素命名（高优先级）

```
bem-element-naming
```
- Use semantic, descriptive kebab-case names for BEM elements

```
bem-element-naming
```
- 为BEM元素使用语义化、描述性的短横线命名

5. Modifier Patterns (HIGH)

5. 修饰符模式（高优先级）

```
bem-modifier-patterns
```
- Use
```
--modifier
```
correctly for states and variants with Angular class bindings

```
bem-modifier-patterns
```
- 结合Angular类绑定，正确使用
```
--modifier
```
表示状态和变体

6. No Cascading (HIGH)

6. 禁止级联（高优先级）

```
bem-no-cascading
```
- Avoid descendant, child, and tag-qualified selectors — keep BEM flat

```
bem-no-cascading
```
- 避免使用后代、子元素和标签限定选择器 —— 保持BEM结构扁平

BEM Cheat Sheet

BEM速查表

.block                    → Component root (matches selector)
.block__element           → Child part of the component
.block--modifier          → Variant of the entire block
.block__element--modifier → Variant of a single element

✅ .user-card
✅ .user-card__avatar
✅ .user-card--featured
✅ .user-card__name--highlighted

❌ .user-card__header__title       (3 levels)
❌ .user-card .user-card__avatar   (descendant selector)
❌ div.user-card                   (tag-qualified)

.block                    → 组件根元素（与选择器匹配）
.block__element           → 组件的子部分
.block--modifier          → 整个块的变体
.block__element--modifier → 单个元素的变体

✅ .user-card
✅ .user-card__avatar
✅ .user-card--featured
✅ .user-card__name--highlighted

❌ .user-card__header__title       (3级嵌套)
❌ .user-card .user-card__avatar   (后代选择器)
❌ div.user-card                   (标签限定)

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/bem-block-selector.md
rules/bem-max-nesting.md
rules/bem-split-components.md
rules/bem-element-naming.md
rules/bem-modifier-patterns.md
rules/bem-no-cascading.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code examples (CSS, SCSS, SASS)
Correct code examples (CSS, SCSS, SASS)
Angular component integration patterns
Summary table and references

阅读各规则文件获取详细说明和代码示例：

rules/bem-block-selector.md
rules/bem-max-nesting.md
rules/bem-split-components.md
rules/bem-element-naming.md
rules/bem-modifier-patterns.md
rules/bem-no-cascading.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例（CSS、SCSS、SASS）
正确代码示例（CSS、SCSS、SASS）
Angular组件集成模式
汇总表格和参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看所有规则展开的完整指南，请查阅：

AGENTS.md