バックグラウンドユーティリティのCSSアーキテクチャ整理：`::after`への統合とCSS変数の名前空間化
utils.cssのバックグラウンドスタイリングユーティリティが大幅に整理され、共通スタイルの一元管理とCSS変数の名前空間化が実現しました。#2298で始まった抽象化作業の続きとして、3つのバックグラウンドクラスが統一されたアーキテクチャを持つようになりました。
背景
前PR #2298 では、utils.cssのバックグラウンドユーティリティに対してwa-mask-fade-belowクラスの追加や.background-wa-patternへのCSS変数対応などの改善が行われました。しかし、.background-gridと.background-dot-gridの2つのクラスは、.background-wa-patternとは異なるレンダリングモデルを持ち続けており、実装の不統一が残っていました。
具体的には、.background-wa-patternが::after疑似要素でパターンを描画するのに対し、.background-gridと.background-dot-gridは要素自身のbackground-imageプロパティで描画していました。また、position: relativeやz-indexによるコンテンツのリフトアップなど、3クラスに共通するボイラープレートが各クラスに個別に記述されていました。加えて、--grid-line-colorのようなグローバルスコープに近いCSS変数名が使われており、名前衝突のリスクがありました。
これらの問題を解消するため、本PRでは共通スタイルの集約と::afterレイヤーへの統一が行われています。
技術的な変更
アーキテクチャの中核となる変更は、3つのバックグラウンドクラスに共通するグループセレクターの導入です。position: relativeによるスタッキングコンテキストの確立、子要素のz-index: 1へのリフトアップ、そして装飾レイヤーとなる::afterの基本スタイルが、ひとつのセレクターブロックにまとめられました。
/* Background utilities share an ::after decoration layer; content children are lifted above it. */
.background-grid,
.background-dot-grid,
.background-wa-pattern {
position: relative;
& > * {
position: relative;
z-index: 1;
}
&::after {
content: '';
position: absolute;
inset: 0;
z-index: 0;
pointer-events: none;
}
}
この共通ベースの上に、.background-gridのbackground-imageは::after疑似要素へと移管されました。これにより.background-wa-patternと同じレンダリングモデルに揃い、3クラスすべてが「本体要素はスタッキングコンテキストのみを担当し、視覚装飾は::afterが担当する」という一貫した構造を持ちます。
CSS変数はすべてbackground-プレフィックスで名前空間化されました。変更前後の対比は以下の通りです：
| 変更前 | 変更後 |
|---|---|
--grid-spacing |
--background-grid-spacing |
--grid-line-color |
--background-grid-line-color |
--grid-line-width |
--background-grid-line-width |
--subgrid-spacing |
--background-subgrid-spacing |
--subgrid-line-color |
--background-subgrid-line-color |
--subgrid-line-width |
--background-subgrid-line-width |
この変数リネームはutils.cssだけでなくdocs/503.mdにも波及しており、同ファイル内での変数参照も新しい名前に更新されています。
さらに、wa-mask-fade-belowセレクターが修正され、3つのバックグラウンドクラスすべての::after疑似要素を正しく扱えるようになりました。
設計判断
::after疑似要素への統一という方針が採用された点が、本PRの核心的な設計判断です。視覚装飾を疑似要素に分離することで、コンテンツのz-index制御が明確になります。本体要素の直下に& > * { z-index: 1 }を設定するだけで、すべてのコンテンツが装飾レイヤーの上に確実に配置される構造です。
CSS変数の名前空間化については、プレフィックスを付けることで他のスタイルとの名前衝突リスクを排除しつつ、変数の所属クラスを名前から自明にする効果があります。--grid-line-colorという汎用的な名前は他の文脈でも使われる可能性がありますが、--background-grid-line-colorであれば.background-grid専用の変数であることが明確です。
pointer-events: noneを::afterに付与している点も重要で、装飾レイヤーがマウスイベントをキャプチャしないことを明示的に保証しています。
まとめ
本PRは、3つのバックグラウンドユーティリティが「共通の::after装飾レイヤー」というひとつのメンタルモデルで理解できるよう整理したリファクタリングです。コードの重複除去とCSS変数の名前空間化により、utils.cssの保守性が向上し、今後wa-mask-fade-belowのような横断的なユーティリティを追加する際の基盤が整備されました。