デザイントークンドキュメントの全面改訂：タブナビゲーション導入と「デフォルト値」列の廃止

Web Awesomeのデザイントークンドキュメントが大きく刷新され、サイドバーの整理・タブナビゲーションの追加・各トークンへの説明文の付与が行われました。また、保守上の問題があった「Default Value」列が全トークンテーブルから削除されています。

背景

これまで /docs/tokens/* 配下には、borders・color・shadows など各カテゴリのページがサイドバーに個別に並んでいました。この構成はサイドバーを肥大化させ、カテゴリをまたいでトークンを比較・探索する際に多くのコンテキストスイッチを強いていました。同時に、各トークンテーブルに設けられていた「Default Value」列は、CSS関数を多用した値の計算式が長くなりがちで視認性が悪く、カスタムテーマを使用するユーザーにとっては実態と乖離した情報となっていました。

PR本文では「Default Value を削除したのは正しい判断か」を著者自身が問いかけており、この判断がトレードオフを含む設計変更であることが示されています。関連する #2249 ではテーマ全体のドキュメント改訂が並行して進められており、本PRはその一部をなす変更です。

技術的な変更

/docs/tokens/index.njk のレイアウト変更が今回の構造改革の中心です。layout: docs から layout: page-outline に変更され、wide: true が追加されたことでページが横幅を広く使えるようになりました。あわせて <wa-divider> で区切りを設けた後、「Using Design Tokens」セクションが新設され、var() 関数での使い方をCSSとインラインスタイルの両方で示す具体的なコード例が追加されています。

トークン一覧テーブルの構造が Markdown のパイプテーブルから <wa-scroller> で包んだ HTML テーブルへと移行されました。各行には id="token-wa-*" 属性が付与され、特定トークンへの直接リンクが可能になっています。列構成は「Default Value」を廃し「Description」を追加する形に変わっています。

変更前の列構成:

| Custom Property       | Default Value                    | Preview |

変更後の列構成:

<tr><th>Custom Property</th><th>Description</th><th>Preview</th></tr>

docs/assets/styles/docs.css では、グローバルに定義されていた .swatch スタイルが削除され、各トークンページのスコープ内スタイルとして再定義されています。transitions.md では .swatch が .transition-swatch にリネームされ、overflow: hidden の追加と :focus 疑似クラスへの対応も加えられました。また focus.md 内のクロスリンクが /docs/tokens/color/#interactions から ?active_tab=color 形式に変更されており、タブナビゲーションによるページ内遷移への対応が見られます。

設計判断

「Default Value」列の廃止は、正確性と保守性を優先した判断です。Web Awesomeのトークン値には calc(var(--wa-space-scale) * 0.125rem) や round(calc(2 * var(--wa-form-control-padding-block) + 1em * var(--wa-form-control-value-line-height)), 1px) のようなCSS関数の連鎖が多く含まれており、テーブルセルに収めると可読性が著しく下がります。さらにカスタムテーマ利用者にはこれらの値が実態と一致しないため、情報として誤解を招くリスクがありました。

<wa-scroller> によるHTMLテーブルへの移行は、Markdownパイプテーブルでは困難だったセル内HTMLレンダリング（プレビューswatchやコード整形）とid属性付与の両立を実現するための選択です。各行に id="token-wa-*" を付与することで、ドキュメント間のディープリンクが可能になっています。

.swatch スタイルのグローバル定義廃止は、各トークンページが独自のプレビュー要件を持つことへの対応です。transitions.md がアニメーション専用の .transition-swatch を必要とするように、ページごとに異なるswatch定義が必要なケースに対して、グローバルスタイルでの一括管理よりもスコープ内定義を選んでいます。

まとめ

この変更は、デザイントークンドキュメントをサイドバーの散在ページから集約されたタブ型ページへと再編し、「Default Value」列をDescription列に置き換えることで正確性と可読性を両立させた刷新です。各トークン行へのid付与という細部の変更も含め、ドキュメントを参照用リファレンスとして機能させるための一貫した設計判断が反映されています。