検索UIのアイコン体系を統一

Web Awesomeのドキュメント検索機能が、サイドバーナビゲーションと同じアイコン体系を採用し、デザイントークンによる一貫したスタイル管理を実現しました。ハードコードされたCSS値をCSS変数に置き換えることで、保守性と視覚的な統一感が向上しています。

背景

#2019でサイドバーのセクション見出しに新しいアイコンが追加されましたが、検索結果のアイコンは旧来の仕組みのままでした。「Components」セクションにはtrowel-bricks、「Frameworks」にはpuzzleといった新しいアイコンがサイドバーで使われる一方、検索結果ではpuzzle-pieceやcodeなどの異なるアイコンが表示されていました。

サイドバーと検索結果で異なるアイコン体系を使用することは、ユーザーの認知負荷を高め、インターフェース全体の一貫性を損ないます。また、検索UIのスタイル定義には1.75remや0.875remといったハードコードされた値が使われており、デザイントークンによる統一的なスタイル管理が行われていませんでした。

技術的な変更

search.jsに包括的なアイコンマッピングシステムが実装されました。iconByPrefix配列は、URLプレフィックスとアイコン名のペアを保持し、パス長の降順でソートされています。

const iconByPrefix = [
  ['/license', 'file-contract'],
  ['/tos', 'file-contract'],
  ['/privacy', 'file-contract'],
  // ...
  ['/docs/components', 'trowel-bricks'],
  ['/docs/patterns', 'block-brick'],
  ['/docs/frameworks', 'puzzle'],
  ['/docs/tokens', 'coin-front'],
  ['/docs/resources/agent-skills', 'sparkles'],
  // ...
].sort((a, b) => b[0].length - a[0].length);

長いパスから順に評価することで、/docs/utilities/nativeのような詳細なパスが/docs/utilitiesよりも優先的にマッチします。これにより、セクション階層に応じた正確なアイコン割り当てが可能になります。

検索結果の生成処理では、ホームページと/docsページに特別な処理を施した後、iconByPrefix配列を順に評価してアイコンを決定します。

if (page.url === '/') icon = 'home';
else if (page.url === '/docs') icon = 'rocket-launch';
else {
  for (const [prefix, prefixIcon] of iconByPrefix) {
    if (page.url.startsWith(prefix)) {
      icon = prefixIcon;
      break;
    }
  }
}

search.cssでは、ハードコードされたフォントサイズとスペーシング値がデザイントークンに置き換えられました。

/* 変更前 */
font-size: 1.75rem;
font-size: 1.25rem;
font-size: 0.875rem;
padding: 3rem 2rem;

/* 変更後 */
font-size: var(--wa-font-size-xl);
font-size: var(--wa-font-size-l);
font-size: var(--wa-font-size-s);
padding: var(--wa-space-3xl) var(--wa-space-2xl);

フッターレイアウトは、個別のFlexboxプロパティ定義からユーティリティクラスに移行しました。

<!-- 変更前 -->
<footer>

<!-- 変更後 -->
<footer class="wa-cluster wa-justify-content-center wa-gap-xl">

wa-clusterクラスはFlexboxレイアウトを提供し、wa-justify-content-centerとwa-gap-xlで中央揃えと要素間隔を指定します。CSSファイルからは対応するFlexboxプロパティ定義が削除されています。

設計判断

URLプレフィックスによるアイコンマッピング方式が採用されました。検索結果の各ページに明示的にアイコン情報を持たせるのではなく、URLパターンからアイコンを推論する仕組みです。

このアプローチには2つの利点があります。第一に、サイドバーナビゲーションのアイコン定義と検索結果のアイコン割り当てを一元的に管理できます。sidebar.njkでセクションアイコンを変更した際、search.jsのiconByPrefix配列を更新するだけで検索結果にも反映されます。第二に、各ページのメタデータにアイコン情報を追加する必要がなく、既存のコンテンツ構造を変更せずに実装できます。

配列を降順ソートする設計により、/docs/utilities/nativeのような詳細パスが/docs/utilitiesよりも優先されます。これは最長一致の原則に基づいており、階層的なURL構造に対して自然なアイコン解決を実現しています。

PR本文では「more refactor work to do」と述べられており、f3f7bc2で行われた変更が出発点に過ぎないことが示されています。デザイントークンへの移行は段階的に進められる方針です。

まとめ

本PRは、検索UIとサイドバーナビゲーションのアイコン体系を統一し、ハードコードされたスタイル値をデザイントークンに置き換えた変更です。URLプレフィックスベースのマッピング方式により、サイトナビゲーション全体で一貫したビジュアル言語が確立され、今後のアイコン変更に対する保守性も向上しています。