ドキュメント基盤を刷新：サイドバー再設計・インストールタブ同期・バックドロップフィルター対応
Web Awesomeのドキュメントサイト全体にわたる大規模なUI/UX改善が実施された。サイドバーの情報設計を整理し、インストール手順タブの選択状態をlocalStorageで横断同期する仕組みを新設し、<wa-dialog>と<wa-drawer>に--backdrop-filterプロパティを追加している。
背景
このPRは「サイドバーの整理」という小さな目的で始まったが、ドキュメント全体の情報構造上の問題が連鎖的に発見された結果、広範な変更へと拡張された。具体的には以下の問題が積み重なっていた。
- Style Utilities と Layout Utilities が別ページに分離しており、リンク先が
/docs/layoutと/docs/utilitiesに散在していた - コンポーネントの説明文が front matter の
descriptionフィールドとソースコードの JSDoc に二重管理されていた - インストール手順タブ（CDN / npm / Self-Hosted）の選択状態がページをまたぐと毎回リセットされていた
- パターンページでアウトラインが強制
trueになっており、レイアウトの柔軟性がなかった
これらが組み合わさり、ドキュメントの閲覧体験を断片的なものにしていた。
技術的な変更
インストールタブの横断同期（install-tabs.js）
最も実装面で注目すべき変更は、新設された install-tabs.js による <wa-tab-group> の同期機構だ。従来は各ページごとにタブ選択状態がリセットされていたが、このスクリプトはページロード時に localStorage から前回の選択を読み出し、同一ページ内の全 [data-install-tabs] グループに反映する。
const STORAGE_KEY = 'wa-install-tab';
const KNOWN_PANELS = ['cdn', 'npm', 'self-hosted', 'hosted', 'react'];
const FALLBACKS = { react: 'npm' };
フォールバック機構も備わっており、react タブが存在しないページでは自動的に npm にフォールバックする。WeakMap を使った suppressed マップにより、プログラムによる group.active 変更とユーザー操作を区別し、プログラム変更がさらにストレージ書き込みを起こすイベントループを防いでいる。また、従来の sidebar.js（26行）は不要になり削除された。
コンポーネント説明文の一元化
component.njk レイアウトで description front matter の参照が廃止され、代わりにソースコードの @summary JSDoc タグ から取得した component.summary を使う形に統一された。
{% set component = getComponent('wa-' + page.fileSlug) %}
+{% set description = component.summary %}
これに伴い、51以上のコンポーネントの .md ファイルから description: front matter が削除されている。単一の真実のソース（SSoT）として JSDoc を選択したことで、ソースコードとドキュメントの乖離リスクが解消される。
--backdrop-filter カスタムプロパティの追加
<wa-dialog> と <wa-drawer> に --backdrop-filter CSS カスタムプロパティが追加された。検索ダイアログはこれを利用して blur(6px) のバックドロップブラーを適用している。
#site-search {
--backdrop-filter: blur(6px);
width: 38rem;
コンポーネント側にプロパティを露出させることで、ドキュメントの特定ニーズのためにコンポーネント本体を改変せず、CSS変数の注入だけで視覚効果を実現している。
レイアウト・テンプレートの hasOutline 対応
docs.njk と pattern.njk の両レイアウトで、hasOutline の扱いが「常に true」から「front matter で制御可能」に変更された。
変更前:
{% set hasOutline = true %}
変更後:
{% if hasOutline == undefined %}{% set hasOutline = true %}{% endif %}
pattern.njk はデフォルトを false に設定し、パターン一覧系のページではアウトライン（目次）を非表示とした。
Markdownコールアウトの <wa-callout> 移行
markdown.js のコンテナプラグインが、独自クラスの <div> から <wa-callout Web Component を使うよう書き直された。これにより info / warning / pro の3種のコールアウトがすべてデザインシステムのコンポーネントで統一される。
// 変更前
return `
<div class="callout callout-${variant}">
<wa-icon class="callout-icon" name="${icon}"></wa-icon>
<div class="callout-content">
`;
// 変更後
return `
<wa-callout variant="${variant}">
<wa-icon slot="icon" name="${icon}" variant="regular"></wa-icon>
`;
pro コールアウト用の新しいコンテナも追加され、Pro限定コンテンツをマークアップする標準的な手段が整備された。
プラットフォーム検出によるキーボードショートカット表示
base.njk のインライン <script> に macOS / iOS 検出ロジックが追加され、navigator.platform を見て is-mac クラスを <html> 要素に付与する。これにより検索トリガーのツールチップが macOS では ⌘K、その他では Ctrl+K と表示される。
document.documentElement.classList.toggle('is-mac', /Mac|iPhone|iPad/.test(navigator.platform));
CSS側では .is-mac .non-mac と html:not(.is-mac) .mac-only を display: none にすることで、JavaScriptクラスに応じて表示を切り替えている。
設計判断
description front matter を廃止して @summary JSDoc に一本化した判断は、コンテンツとコードを同じファイルで管理することでズレを防ぐという原則に基づいている。front matter でコンポーネント説明を管理していた場合、ソース側の変更が反映されない状態が生まれやすく、51ページ以上に分散していた重複を解消している。
install-tabs.js での WeakMap 活用は、DOM要素のライフサイクルに紐付いたフラグ管理として適切な選択だ。ページ遷移で要素がGCされれば自動的にエントリも消えるため、明示的なクリーンアップが不要になる。
hasOutline をデフォルト値で制御する方式は、既存ページへの影響を最小化しつつ新しいページタイプ（パターンページ）に異なるデフォルトを設定できる。undefined チェックによる条件設定は、テンプレート継承の仕組みを壊さずに柔軟性を得る実用的な手法だ。
まとめ
このPRはドキュメントの情報設計・コンポーネントAPI・JavaScriptインフラの三層にまたがった整合性向上の変更だ。特に @summary JSDocへの一元化と install-tabs.js によるセッション状態の永続化は、ドキュメントサイトの保守性と利用者体験の両方に継続的に効いてくる設計判断といえる。