ダイアログのユーティリティスタイルをクラスセレクタでスコープ化

ドキュメントサイトのグローバルスタイルが <wa-dialog> コンポーネントのサンプル表示に意図せず適用されていた問題を、.app-dialog クラスによるスコープ化で解消しました。

背景

utils.css に定義されたダイアログ向けのユーティリティスタイルが、ドキュメントページ上の <wa-dialog> 使用例にも漏れ込むという問題が発生していました。具体的には、フッター付きダイアログに対して [slot='footer'] へのスタイル（ボーダーやパディング）が、ドキュメントのサンプルコンポーネントにも適用されてしまっていました。PRに添付されたスクリーンショットで、修正前は <wa-dialog> のサンプル表示が崩れており、修正後に正常なレイアウトに戻っていることが確認できます。

このスタイルはドキュメントサイト自身のアプリケーションUI（Build Awesome プロモーションダイアログなど）向けに定義されたものであり、コンポーネントの使用例とは明確に区別する必要がありました。

技術的な変更

変更の核心は、utils.css のCSSセレクタを要素タイプ全体から特定クラスを持つ要素に絞り込むことです。

変更前:

wa-dialog:has([slot='footer']) [slot='footer'] {
  border-block-start: var(--wa-border-width-s) solid var(--wa-color-surface-border);
  flex-grow: 1;
  padding-block-start: var(--wa-space-l);
}

変更後:

wa-dialog.app-dialog [slot='footer'] {
  border-block-start: var(--wa-border-width-s) solid var(--wa-color-surface-border);
  flex-grow: 1;
  padding-block-start: var(--wa-space-l);
}

変更前のセレクタ wa-dialog:has([slot='footer']) は、フッタースロットを持つすべての <wa-dialog> を対象としていました。変更後の wa-dialog.app-dialog は .app-dialog クラスを持つ要素のみに適用範囲を限定しています。あわせて :has([slot='footer']) の条件も削除され、セレクタがよりシンプルになっています。

スタイルの適用先であるサイト固有ダイアログには、対応するクラスが追加されました。

<wa-dialog
  id="dialog-site"
  class="dialog-ba-kickstarter brand-build-awesome app-dialog"
  light-dismiss
  without-header>

設計判断

既存のコンポーネント要素型セレクタを廃止し、アプリケーション固有クラスで意図を明示する方針 が採用されました。

wa-dialog はドキュメントサイトがコンポーネントの使用例を示すために多数埋め込んでいる要素です。要素型に対してグローバルなスタイルを当てると、ドキュメントが増えるたびにスタイルが漏れ込むリスクが継続的に存在します。.app-dialog という命名は、そのスタイルがアプリケーション自身のUIにのみ属することをコード上で明示しており、今後ダイアログが追加された際にも意図しない適用を防ぐ役割を果たします。

また、変更前に使用されていた :has() 疑似クラスは条件の表現力は高いものの、セレクタの意図が読み取りにくい面があります。.app-dialog クラスの付与という明示的な宣言に置き換えることで、スタイルの適用対象を開発者が一目で把握できるようになっています。

まとめ

2行の変更で、ドキュメントサイトのアプリケーションUIとコンポーネントサンプルのスタイルを明確に分離しました。クラスによるスコープの明示はCSS設計の基本原則ですが、このPRはドキュメントサイトというコンポーネントと利用例が共存する特殊な文脈において、その重要性を端的に示しています。