Docs サイト検索ダイアログの UI 改善

Docs サイトの検索ダイアログがデザインと操作性の両面で刷新され、ユーザーが検索結果や操作ヒントに素早くアクセスできるようになりました。主な変更点はダイアログ全体のレイアウト見直し、空結果時のビジュアル統一、最近の検索履歴の永続化、そしてキーボードショートカットの可視化です。これにより、検索体験が一貫したブランドイメージとアクセシビリティ基準を満たす形で向上します。

背景

検索ダイアログは従来、視覚的に目立つオレンジのフルブリードデザインと限られたインタラクションしか提供していませんでした。その結果、空結果時の案内が不十分であり、ユーザーが次のアクションを取るまでに迷うケースが散見されました。今回の PR は UI の一貫性と操作フローの明確化を目的に、デザインガイドラインに沿ったリファクタリングを行いました。

ダイアログの UI を全面的に見直すことで、検索入力欄と結果リストのサイズ感を統一し、アクセシビリティ属性を強化しました。また、最近の検索語句をローカルストレージに保存し、再利用できるようにしたことで検索回数の削減とユーザーエクスペリエンスの向上が期待されます。

この変更は単なるビジュアル調整に留まらず、検索フロー全体を“提案 → 結果 → 最近検索”という明確なステートマシンに再構築した点が大きなポイントです。

技術的な変更

マークアップとアクセシビリティ属性の拡張

wa-dialog に aria-label="Site Search" を付与し、スクリーンリーダー向けのラベル付与を行いました。wa-input の属性は行単位で折りたたまれ、未使用の属性は削除しつつ aria-controls が動的に site-search-suggested-list へ切り替わるようにしました。また、開始アイコンを magnifying-glass、クリアアイコンを xmark に変更し、カラートーンもデエモファイズしました。

@@ -1,59 +1,145 @@
-<wa-dialog id="site-search" without-header light-dismiss>
+<wa-dialog id="site-search" without-header light-dismiss aria-label="Site Search">
@@
-        <wa-input
-          id="site-search-input"
-          type="search"
-          with-clear
-          placeholder="Search for&hellip;"
-          autofocus
-          autocomplete="off"
-          autocorrect="off"
-          autocapitalize="off"
-          enterkeyhint="go"
-          spellcheck="false"
-          maxlength="100"
-          role="combobox"
-          aria-autocomplete="list"
-          aria-expanded="true"
-          aria-controls="site-search-listbox"
-          aria-haspopup="listbox"
-          aria-activedescendant
-        >
-          <wa-icon slot="start" name="search"></wa-icon>
+        <wa-input id="site-search-input" type="search" with-clear placeholder="Search for&hellip;" autofocus
+          autocomplete="off" autocorrect="off" autocapitalize="off" enterkeyhint="go" spellcheck="false" maxlength="100"
+          role="combobox" aria-autocomplete="list" aria-expanded="true" aria-controls="site-search-suggested-list"
+          aria-haspopup="listbox" aria-activedescendant>
+          <wa-icon slot="start" name="magnifying-glass" class="de-emphasize"></wa-icon>
+          <wa-icon slot="clear-icon" name="xmark" variant="regular"></wa-icon>
         </wa-input>

最近検索の永続化ロジック

localStorage を利用して最大 5 件までの検索語句を保存し、重複排除と XSS 対策を行うユーティリティが search.js に追加されました。検索結果が表示されない場合でも、site-search-default コンテナに Recent セクションが挿入され、クリックや Enter キーで再検索が可能です。さらに、ARIA の aria-controls 入れ替えに合わせて、結果があるときは has-results クラスが付与され、getActiveList が適切なリストボックスを返すようになりました。

@@ -64,6 +64,7 @@ const iconByPrefix = [
   ['/docs/ai/llms', 'sparkles'],
+  ['/docs/resources/support', 'life-ring'],
   ['/docs/resources', 'book-spine'],
 ].sort((a, b) => b[0].length - a[0].length);
@@
   recentContainer: document.getElementById('site-search-recent-list'),
   recentListbox: document.getElementById('site-search-recent-listbox'),
   recentDivider: document.querySelector('[data-recent-divider]'),
@@
+// Recent searches — persisted in localStorage, capped at 5
+const recentSearchesKey = 'wa-search-recent';
+const recentSearchesMax = 5;
+
+function loadRecentSearches() {
+  try {
+    const raw = localStorage.getItem(recentSearchesKey);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter(q => typeof q === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function saveRecentSearch(query) {
+  const trimmed = (query || '').trim();
+  if (!trimmed) return;
+  try {
+    const current = loadRecentSearches();
+    const next = [trimmed, ...current.filter(q => q !== trimmed)].slice(0, recentSearchesMax);
+    localStorage.setItem(recentSearchesKey, JSON.stringify(next));
+  } catch {}
+}

スタイルとユーティリティの追加

CSS ではヘッダーとフッターのパディング調整、モバイルでの最大高さ設定、そして新しいユーティリティ .kbd-modern が utils.css に導入されました。.kbd-modern はキーボードショートカットチップ用にデザインされ、背景色に半透明のサーフェスカラー、薄いボーダー、丸みを持たせた外観を提供します。フッターのチップはこのクラスで装飾され、トーンが統一された UI が実現されました。

@@ -590,6 +590,15 @@
     font-weight: var(--wa-font-weight-bold);
   }

+  .kbd-modern {
+    padding: var(--wa-space-2xs) var(--wa-space-xs);
+    line-height: 1;
+    background-color: color-mix(in oklab, var(--wa-color-surface-default), transparent 50%);
+    border: var(--wa-panel-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
+    border-radius: var(--wa-border-radius-s);
+    box-shadow: var(--wa-shadow-s);
+  }
+
   /* step icons for ordered instructions */
   .step-icon {
     --primary-color: var(--wa-color-neutral-20);

設計判断

ARIA 属性の動的切り替え と aria-controls の統一は、検索状態に応じたフォーカス移動とスクリーンリーダーの適切な把握を意図した設計です。結果がないときはデフォルトコンテナ（Suggested + Recent）にフォーカスが残り、結果が出た瞬間に has-results クラスが付与されて結果リストに遷移します。これにより、キーボードのみのユーザーでもシームレスに検索フローをたどれます。

最近検索の永続化 をローカルストレージに委ねたのは、サーバーサイドへの負荷増大を避けつつ、ユーザー側のブラウザで履歴を管理できるシンプルな実装を選択したためです。最大 5 件に制限し、重複排除とサニタイズを行うことでストレージ肥大化と XSS のリスクを低減しています。

.kbd-modern ユーティリティ の導入は、個別コンポーネントを増やさずにキーボードショートカットの表示を統一するためのトレードオフです。既存の .tag-ui と同様の設計哲学で、CSS カスタムプロパティに依存することでテーマ切り替えにも自然に追従します。

まとめ

本 PR は Docs サイトの検索ダイアログをビジュアル・アクセシビリティの両側面から刷新し、検索入力、結果表示、最近検索、ショートカットチップを一貫した UI パターンで提供します。localStorage による最近検索の永続化 と ARIA の状態管理 が中心的な設計決定であり、ユーザー体験の向上とコードベースの保守性向上を同時に実現しています。