ドキュメントサイトのパンくずリストをリファクタリング：クラス名変更とスタイルの汎用化

ドキュメントサイトのパンくずリストUIパターンを再設計し、クラス名を .docs-subpage-crumbs から .page-breadcrumbs へ改名するとともに、スタイル定義を docs.css から utils.css へ移動して再利用性を高めました。あわせて、任意の背景面に対応できる表現に視覚的な見直しも実施しています。

背景

このパンくずリストUIパターンは最近追加・スタイリングされたものでしたが、初期実装ではドキュメント固有のスタイルファイルにのみ定義されており、アプリ全体のUI/UXで再利用する手段がありませんでした。クラス名の .docs-subpage-crumbs も「ドキュメントのサブページ用」という具体的な文脈に縛られた命名で、パターンの本来の目的を正確に表していませんでした。

加えて、背景色が --wa-color-surface-lowered というデフォルトのサーフェス専用のトークンに固定されており、異なるサーフェスレベルの上に配置した場合にデザインが崩れる課題もありました。

技術的な変更

スタイル定義を docs.css から削除し、utils.css へ新規追加することで、このパターンをアプリ全体で利用可能なユーティリティとして昇格させました。

docs.css から削除された旧スタイルは以下の通りです：

/* 削除 */
.docs-subpage-crumbs {
  display: flex;
  inline-size: 100%;
  background-color: var(--wa-color-surface-lowered);
  border: var(--wa-panel-border-width) var(--wa-panel-border-style) var(--wa-color-surface-border);
  border-radius: var(--wa-border-radius-pill);
  font-size: var(--wa-font-size-s);
  padding: var(--wa-space-xs) var(--wa-space-m);
  margin-block-end: var(--wa-content-spacing);
}

utils.css に追加された新スタイルでは、いくつかの重要な変更が加えられています：

.page-breadcrumbs {
  display: flex;
  align-items: center;
  inline-size: 100%;
  /* translucent tint so the pill recedes on any surface */
  background-color: color-mix(in oklab, var(--wa-color-text-normal) 4.5%, transparent);
  border-radius: var(--wa-border-radius-pill);
  font-size: var(--wa-font-size-s);
  padding: var(--wa-space-xs) var(--wa-space-m);
  margin-block-end: var(--wa-content-spacing);

  /* fade past the component's text-quiet + optical-align nudge */
  wa-icon[slot='separator'] {
    color: color-mix(in oklab, var(--wa-color-text-quiet), transparent 50%);
    translate: 0 0.075em;
  }
}

変更点は大きく3つあります。第一に、背景色が固定値の --wa-color-surface-lowered から、color-mix(in oklab, var(--wa-color-text-normal) 4.5%, transparent) による半透明のティントへ変更されました。テキストカラーの4.5%という極小の混合比で、配置されたサーフェスの色に依存せずピルが自然に背景に馴染む設計です。第二に、ボーダーが削除され、セパレータアイコンのスタイルが新設されました。セパレータには color-mix で50%の透明度を付与し、translate: 0 0.075em のわずかな垂直オフセットで光学的なテキストとの位置合わせを行っています。第三に、align-items: center が追加されフレックスボックスの縦揃えも明示されました。

HTMLテンプレートとマークダウンファイルでは、base.njk・Angular・React・Svelte・Vue 2・Vue 3・migration-checklist の計7ファイルで、クラス名を docs-subpage-crumbs から page-breadcrumbs へ一括置換しています。

設計判断

color-mix(in oklab, ...) を用いた相対的な背景表現を採用したことが、このリファクタリングの核心にある設計判断です。絶対的なカラートークンへの依存を断ち切ることで、ライト・ダークテーマや異なるサーフェスレベルのいずれの上でも、コンテキストに応じた背景色を自動的に得られます。コード中のコメント「translucent tint so the pill recedes on any surface」が示すように、任意のサーフェスで機能することが意図された実装です。

また、スタイルを docs.css から utils.css へ移動した判断は、関心の分離という観点からも重要です。docs.css はドキュメントサイト固有の設定を持つファイルであり、アプリ全体で再利用可能なUIパターンを置く場所としては適切ではありませんでした。

まとめ

今回の変更は、既存のUIパターンに対して「命名の正確化」「スタイルの汎用化」「視覚的な改善」を同時に達成した凝縮度の高いリファクタリングです。特に color-mix() による相対的な背景表現の採用は、このパターンが様々なサーフェスで使われる場面でメンテナンスコストを削減する設計上の判断として注目されます。