コンポーネントステータスバッジをマクロで統一管理

2026年05月13日 03:31 JST shoelace-style/webawesome

https://github.com/shoelace-style/webawesome/pull/2391

ドキュメントの個別コンポーネントビューとコンポーネント一覧ページに散在していたバッジ描画ロジックを、共有マクロ componentStatusBadges に集約しました。これにより、バッジの見た目と振る舞いがサイト全体で一貫して保たれます。

背景

同じStable/Experimentalバッジと「Since X.X」バッジが、component.njk（個別ビュー）と index.njk（一覧ページ）の2か所に独立して実装されていました。両者は完全に同一ではなく、微妙な差異が生じていました。たとえばStableバッジの個別ビューでは variant="brand" が使われていましたが、一覧ページでは appearance 指定のない状態での描画になっており、「Since X.X」バッジの見た目も統一されていませんでした。

この重複した実装は、バッジのデザインや属性を変更する際に2か所を同期して修正しなければならないという保守上の課題を持っていました。今回の変更はその解消を目的としています。

技術的な変更

新たに作成された docs/_includes/macros/component-badges.njk が、ステータスバッジと「Since X.X」バッジのレンダリングを一手に担います。

追加されたマクロの実装は以下のとおりです：

{# Renders the status (Stable/Experimental) and "Since X.X" badges for a component.
   Used by the individual component view, the components index, and component cards. #}
{% macro componentStatusBadges(component) %}
{% if component.status == 'stable' %}
<wa-badge class="preview" variant="brand" pill>
  <wa-icon name="check" slot="start"></wa-icon>
  Stable
</wa-badge>
{% elif component.status == 'experimental' %}
<wa-badge variant="warning" appearance="filled" pill>
  <wa-icon name="flask" slot="start"></wa-icon>
  Experimental
</wa-badge>
{% endif %}
{% if component.since %}
<wa-badge class="since" variant="neutral" appearance="filled" pill>Since {{ component.since }}</wa-badge>
{% endif %}
{% endmacro %}

component.njk と index.njk 双方で、従来のインライン実装（計30行）が {{ componentStatusBadges(component) }} の1行に置き換えられています。

Stableバッジには class="preview" が付与されました。これはサイトパレットによるオレンジ色のブランドカラーテーマ（wa-theme-site）の適用から外れるためのクラスで、ページのテーマに関わらず常にデフォルトのブランドカラー（青）で表示されます。

「Since X.X」バッジには class="since" が付与され、対応するCSSルールが docs/assets/styles/utils.css に追加されました：

/* "Since X.X" badge: subtler than the default filled neutral */
wa-badge.since {
  background-color: var(--wa-color-surface-lowered);
}

--wa-color-surface-lowered を背景色に使うことで、Stable/Experimentalバッジよりも視覚的に控えめな表示となり、重要度の差が色で伝わるようになります。この .since ルールは既存の .pro・.free・.planned ルールと並んで定義されています。

設計判断

Nunjucksマクロによる抽象化が選ばれた点は、テンプレートエンジンの機能を活かした自然な判断です。マクロはコンポーネントオブジェクトを引数として受け取るため、呼び出し側はデータをそのまま渡せば済み、ステータスの種類や条件分岐をマクロ内に完全にカプセル化できています。

Stableバッジのスタイル統一にあたっては、一覧ページ側ではなく個別ビュー側の実装（variant="brand" + チェックアイコン）が基準として採用されています。これは視覚的に明確な表現を優先した判断と読み取れます。

「Since X.X」バッジは逆に、一覧ページ側の「控えめな表示」を基準とし、--wa-color-surface-lowered を使った新しいCSSクラスで実現しています。ステータスバッジとの視覚的な優先順位を明示しつつ、CSSトークンを使うことでテーマ変更への追従性も維持しています。

まとめ

この変更は、ドキュメントサイト内のバッジ描画ロジックを単一のマクロに集約することで、今後のデザイン変更や新たな呼び出し箇所（コンポーネントカードなど）への対応をシンプルにします。スタイルの不一致解消とコードの重複排除を同時に達成した、保守性向上を主眼とした整理といえます。