コンポーネントドキュメントでProバッジUIの表示を統一

Web Awesomeのコンポーネントドキュメントで、Pro機能を示すバッジ表示が統一され、説明付きツールチップを備えたproBadgeマクロに置き換えられました。これにより、ユーザーはProバッジにカーソルを合わせるだけで、そのコンポーネントがPro機能である理由を確認できるようになります。

背景

これまで、コンポーネントドキュメントのProバッジは <wa-badge class="pro">Pro</wa-badge> として直接記述されていました。この実装では、バッジ自体は表示されるものの、なぜそのコンポーネントがPro機能なのかという説明が不足していました。ユーザーがProコンポーネントの意味を理解するには、別途ドキュメントを参照する必要があり、UXの観点から改善の余地がありました。

本PRは、バッジ表示の実装をマクロ化することで、一貫した表示とツールチップによる説明機能を提供します。

技術的な変更

packages/webawesome/docs/_layouts/component.njk において、Proバッジの表示方法が変更されました。

変更前:

{% if isProComponent %}
  <wa-badge class="pro">Pro</wa-badge>
{% endif %}

変更後:

{% from "pro-badge.njk" import proBadge %}
...
{% if isProComponent %}
  {{ proBadge({ description: (component.tagName | stripPrefix) | capitalize ~ " requires access to Web Awesome Pro" }) }}
{% endif %}

proBadgeマクロ は、コンポーネント名から自動的に説明文を生成します。stripPrefixフィルタでプレフィックスを除去し、capitalizeで先頭を大文字化した後、"requires access to Web Awesome Pro"という定型文を付加します。例えば、wa-advanced-buttonというコンポーネントの場合、"Advanced Button requires access to Web Awesome Pro"というツールチップが表示されます。

この変更により、各コンポーネントのドキュメントで個別にバッジHTMLを記述する必要がなくなり、マクロの実装を更新するだけで全てのProバッジの表示を一括で変更できるようになりました。

設計判断

マクロベースの実装 が採用されました。直接HTMLを記述する方式から、Nunjucksのマクロシステムを活用した実装へ移行することで、DRY（Don't Repeat Yourself）原則に従った保守性の高いコードベースが実現されています。

ツールチップの説明文は、コンポーネント名から動的に生成される設計です。これにより、各コンポーネントのドキュメントでカスタムの説明文を記述する必要がなく、コンポーネント名さえ適切であれば自動的に意味のある説明が提供されます。この自動生成アプローチは、ドキュメント作成の負担を軽減しつつ、一貫性のある表現を保証します。

添付のスクリーンショットからは、ツールチップが視覚的に明確で、ユーザーが直感的に理解できるUIになっていることが確認できます。

本PRは、ドキュメントシステムの保守性とユーザビリティの両面を改善する、実装パターンの標準化を進めた変更です。Proバッジという頻出要素をマクロ化することで、将来的なデザイン変更への対応コストを削減し、コンポーネント固有の説明を自動生成する仕組みでドキュメント作成の効率を向上させています。