angular-css-bem-best-practices

Angular + BEM CSS のベストプラクティス

Angular のコンポーネントアーキテクチャと BEM（Block Element Modifier）CSS 命名規則を組み合わせ、再利用可能なコンポーネントを作成し、フロントエンド開発におけるコード共有を可能にするための方法論ガイドです。CSS、SCSS、SASS の誤った例と正しい例を含む 6 つのルールを紹介します。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• Angular コンポーネント用の CSS／SCSS／SASS を記述する場合
• Angular テンプレート内の CSS クラスに名前を付ける場合
• 一貫性を保つためにコンポーネントのスタイルをレビューする場合
• スタイルの複雑さに基づいてコンポーネントを分割するかどうかを判断する場合
• 新しい Angular プロジェクトの CSS アーキテクチャを設定する場合
• 既存のスタイルをリファクタリングして BEM 方法論に従わせる場合

基本原則

• 1 コンポーネント = 1 BEM ブロック — ブロック名はコンポーネントセレクターと一致させます
• 最大 2 階層 — Block と Block__Element のみを使用し、Block__Element__SubElement は使用しません
• 階層が深くなったら分割 — 3 階層目が必要な場合は、子コンポーネントとして抽出します
• フラットなセレクター — 子孫セレクター、子セレクター、タグ修飾セレクターは使用しません
• 意味のある名前 — 要素名は「どのようなものか」を表し、「どのように」や「どこに」は表しません
• バリエーションにはモディファイアを使用 — 状態やバリエーションには --modifier を使用し、常にベースクラスと併用します

優先度別ルールカテゴリ

優先度	ルール	影響度	ファイル
1	ブロック = コンポーネントセレクター	CRITICAL	bem-block-selector
2	ネストは最大 2 階層	CRITICAL	bem-max-nesting
3	子コンポーネントを分割	CRITICAL	bem-split-components
4	要素の命名規則	HIGH	bem-element-naming
5	モディファイアのパターン	HIGH	bem-modifier-patterns
6	カスケードセレクターを使用しない	HIGH	bem-no-cascading

クイックリファレンス

1. ブロック = コンポーネントセレクター（CRITICAL）

• bem-block-selector - BEM ブロック名は Angular コンポーネントセレクターと一致させます（プレフィックスを除く）

2. 最大 2 階層（CRITICAL）

• bem-max-nesting - .block__element より深くネストしないでください。.block__element__subelement は使用しません

3. 子コンポーネントを分割（CRITICAL）

• bem-split-components - BEM の階層が 2 階層を超える場合は、子コンポーネントを抽出します

4. 要素の命名（HIGH）

• bem-element-naming - BEM 要素には、意味が明確で説明的な kebab-case の名前を使用します

5. モディファイアのパターン（HIGH）

• bem-modifier-patterns - Angular のクラスバインディングを使い、状態やバリエーションに --modifier を正しく使用します

6. カスケードを避ける（HIGH）

• bem-no-cascading - 子孫セレクター、子セレクター、タグ修飾セレクターを避け、BEM の構造をフラットに保ちます

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)

使用方法

詳しい説明とコード例については、個別のルールファイルをお読みください。

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 コンポーネントへの統合パターン
• まとめの表と参考資料

コンパイル済み完全版ドキュメント

すべてのルールを詳しく解説した完全版ガイド：AGENTS.md