テーマドキュメントの構造整理と動的スニペット変換の導入

今回の PR は、テーマ関連ドキュメントを統合し UI コンポーネントを再構成すると同時に、Eleventy ビルドパイプラインに dynamicSnippetsTransformer を組み込み、コードスニペットの動的置換を可能にした点が中心です。

背景

分散したテーマドキュメント が読者に認知コストを課していました。PR #2249 でテーマ概要ページが新設されたものの、theming-overview, color-palettes, tokens/color がそれぞれ同じ概念を別々に説明しており、どのページを参照すべきか判断が難しかった点が指摘されました。

この課題に対処するため、本 PR では各ドキュメントの役割を明確に分離し、リンク構造を統一することで、読者がトップダウンでテーマシステムを追えるようにしました。

技術的な変更

Eleventy ビルド設定の拡張 として packages/webawesome/docs/.eleventy.js に dynamicSnippetsTransformer のインポートと config.addTransform 呼び出しが追加され、ビルド時にスニペット置換が適用されるようになりました。

新規追加された packages/webawesome/docs/_transformers/dynamic-snippets.js は、Prism ハイライト後にプレースホルダー __NAME__ 系を <span data-dyn="name">…</span> に置換し、クライアント側スクリプトが動的に更新できる仕組みを提供します。

テンプレートのリファクタリング では、以下の主要変更が行われました。

color-scheme-selector.njk に 区切り要素 と URL へ遷移するロジックを追加し、Docs ページへ直接ジャンプできるようにしました。
pro-badge.njk のマクロを簡潔化し、デフォルト引数処理を一行にまとめました。
sidebar.njk のリンク順序を Built-in Themes、Design Tokens、Customizing & Theming と再編し、ページ構造を反映させました。
theme-selector.njk のアイコンを brush から palette に変更し、テーマ選択 UI の視覚的一貫性を向上させました。
ラジオグループからタブグループ への移行が theme-picker.njk と color-palette-picker.njk で実施され、アクセシビリティとインタラクションの統一が図られました。
instructions.njk のオプションリストをインライン化し、Pro テーマのマークアップを簡素化しました。
light-dark-example.njk が新規追加され、ライト／ダークモードの実例をカード形式で提示します。
theme-viewer.njk に zoom 属性が追加され、プレビュー画像のサイズ調整が可能になりました。

これらの変更はすべて HTML/NJK の構造調整であり、ランタイムロジック自体には影響を与えていません。

設計判断

単一情報源の確立 が本 PR の根幹です。theming-overview がレイヤー構造（テーマ → パレット → バリアント → カラースキーム）を一次的に示し、color-palettes がカタログとインストール手順を、tokens/color がトークンリファレンスを担うことで、同一概念が重複して記述されることを防ぎました。

再利用可能コンポーネント の導入として、pro-badge, color-palette-picker, theme-picker などをマクロやインクルード化し、複数ページで一貫した UI を提供できるようにしました。これにより将来の UI 変更が一箇所で完結し、保守コストが低減します。

動的スニペットの実装 は、ビルド時に静的ハイライトだけでなく、クライアント側でテーマ選択に合わせてコード例を即時更新できるようにする設計です。Transformer を追加しただけで既存のビルドフローに大きな変更を加えず、拡張性を保ちつつ UX を向上させました。

まとめ

本 PR は、テーマドキュメントの情報整理と UI コンポーネントの統一、そして dynamicSnippetsTransformer の導入という三本柱で、開発者がテーマシステムを理解しやすくし、実装例をインタラクティブに提示できるようにしました。今後は追加テーマやカラーパレットが増えても、共通コンポーネントと動的スニペットが一貫した体験を保証します。