Design Nits and Docs Polish: Rounded Hero Overlays, Search UI Tweaks, SSR Docs Refactor, and Icon Mapping

この PR では、コンポーネントドキュメントと UI の細部にわたるデザイン調整を行い、ヒーロー領域のオーバーレイが角丸に追従するようにしたほか、検索 UI の間隔・アイコン表示・空結果表示を改善し、SSR に関するドキュメント構造を統一しました。また、スタイル・スクリプトの小規模修正と、コンポーネントの JSDoc に SSR に関する表現統一を導入しています。

背景

ヒーロー領域や検索ポップオーバーで見られる UI の微細なずれは、ページ全体のビジュアル一貫性を損ねるため、早急な修正が求められていました。特に .background-grid 系のオーバーレイが丸角の wa-card 内で四角くはみ出す問題は、ユーザーがカードの形状を正しく認識できない原因となっていました。また、検索結果のリスト間隔や空結果のアイコンが他コンポーネントとスタイルが合っていない点も指摘されていました。さらに、SSR に関する情報が wa-callout 内に埋め込まれ、目次 (TOC) からのアクセスが不自然であったため、ドキュメント構造の統一が必要でした。これらの課題に対処することで、デザインの一貫性とドキュメントの可読性を向上させます。

技術的な変更

ヒーローオーバーレイの角丸追従: packages/webawesome/docs/assets/styles/utils.css に border-radius: inherit; を追加し、.background-grid、.background-dot-grid、.background-wa-pattern がホスト要素の border-radius を継承するようにしました。これにより、wa-card の丸角内部でもオーバーレイが正しくクリップされます。元の四角いオーバーレイが残るケースはなくなり、デザインがカードと一致します。

コードチップ背景の除去: packages/webawesome/docs/assets/styles/docs.css の code セレクタに background: transparent; と padding-inline: 0; を追加し、API テーブル内の <code> 要素が背景色なしで表示されるようにしました。これにより、スロットや属性などのコードチップが「ゴーストピル」のように見える問題が解消されます。

SSR ドキュメントの構造統一: packages/webawesome/docs/_layouts/component.njk で従来の wa-callout を削除し、代わりに見出し <h2>SSR</h2> と簡潔なリンクテキストへ置き換えました。これにより、目次に実際の「SSR」エントリが生成され、他ページと同様のドキュメント構造が実現します。wa-callout の冗長な見出しは排除され、情報の重複が無くなります。

検索 UI の間隔とボタン配置: packages/webawesome/docs/_includes/search.njk でリストの wa-gap-2xs を wa-gap-3xs に変更し、項目間隔を統一しました。また、空結果状態のボタン群を wa-button-group から wa-cluster wa-gap-s wa-justify-content-center に差し替え、個別の CTA として表示されるようにしました。これにより、UI がセグメント化されず、視覚的に自然な配置になります。

空結果アイコンのスタイル統一: 同ファイルで face-monocle アイコンにクラス duotone-illustrated を付与し、packages/webawesome/docs/assets/styles/utils.css にスタイル定義を追加しました。duotone-illustrated は暗色一次色とブランド系二次色で全体不透明に描画し、ホバー時に色が変化する演出を提供します。これにより、アイコンが他コンポーネントと同様のビジュアル言語を共有します。

検索結果アイコンのカテゴリ駆動マッピング: packages/webawesome/docs/_plugins/search.js に category フィールドをインデックスへ追加し、search.js 側で iconByCategory マップを導入しました。packages/webawesome/docs/assets/scripts/search.js では、ページ URL がコンポーネントパスでかつ category が設定されている場合に対応アイコンを取得し、従来のプレフィックスベースのハードコードを削除しました。これにより、カテゴリ情報だけで適切なアイコンが自動選択され、メンテナンス負荷が低減します。

ハートアイコンのアニメーション拡張: フッターといくつかのドキュメントで wa-icon に animation="beat" とクラス heart-affection を付与し、utils.css にホバーで無限ビートとブランドオレンジ色に変化するスタイルを追加しました。これにより、感謝や愛情を示すアイコンがインタラクティブに演出されます。

JSDoc の SSR 記述統一: 複数コンポーネント (animated-image, animation, card, carousel, include, markdown, tab-group) の TypeScript ファイルで @ssr コメントを更新し、SSR の制限や属性要件を明確に記述しました。これにより、開発者が SSR 時の挙動を正確に把握でき、ドキュメントの一貫性が向上します。

設計判断

オーバーレイの角丸対応は、border-radius: inherit を用いることで既存のユーティリティクラスを変更せずにホスト要素のスタイルに追従させ、後方互換性を保ちました。コードチップ背景の除去は、CSS で直接上書き するだけでテンプレート変更を不要にし、最小の侵入性で見た目を改善しています。SSR ドキュメントのリファクタリングは、見出しレベルを統一 し、目次生成ロジックに依存しない明示的な構造に変更した点が評価されます。検索 UI の間隔変更は、wa-gap-3xs に統一することでデザインシステム全体の間隔基準に合わせ、余計なクラス追加を避けました。検索結果アイコンのカテゴリ駆動マッピングは、データ駆動 アプローチに転換し、ハードコードされたプレフィックスリストを除去したことで拡張性が向上します。ハートアイコンのアニメーションは、クラスベースの制御 を導入し、既存の animation 属性と組み合わせて柔軟な演出を実現しました。最後に、JSDoc の SSR コメント統一は、ドキュメントの一貫性 と開発者体験の向上を目的とした設計判断と言えます。

まとめ

本 PR は、UI の細部調整とドキュメント構造の統一を通じて、Web Awesome のビジュアル一貫性と開発者向け情報の正確性を高めました。カテゴリベースの検索アイコンや SSR 記述統一といった設計選択は、保守性と拡張性を意識した実装となっており、今後の機能追加やデザイン刷新でも同様のアプローチが活用できるでしょう。