Design Token Panel

作成2026年4月27日Takeshi Takatsudo

スペーシング、フォント、サイズ、カラーの各デザイントークンをタブ分けしたパネルでライブ編集し、JSONでエクスポート・AIを介して読み込めるワークフローを提供します。

Design Token Panelは、テーマが提供するすべてのデザイントークンをページ上で編集できるインタラクティブなエディタです。以前のColor Tweak Panel（カラー専用）を置き換え、Spacing・Font・Size・Colorの4つのトークン種別をタブ構成でカバーします。さらに統一されたJSONエクスポート／インポート機能を備えており、デザインをまとめてAIアシスタントに渡し、返ってきた結果を読み込むラウンドトリップ運用が可能です。

パネルを有効にする

src/config/settings.ts で designTokenPanel を true に設定します:

export const settings = {
  designTokenPanel: true,
  // ...
};

有効になると、ヘッダーに（検索アイコンの左側に）パレットアイコンが表示されます。クリックするとパネルが開閉し、以前のColor Tweak Panelと同じキーボードショートカットも引き続き利用できます。

📝 Note

designTokenPanel は従来の colorTweakPanel 設定を置き換えます。既存プロジェクトの互換性のため、colorTweakPanel は1リリースのあいだエイリアスとして受け付けます — どちらかが true であればパネルは有効になります。新規プロジェクトでは designTokenPanel を使ってください。

4つのタブ

パネルは4つのタブに分かれており、それぞれ単一のトークン種別に集中しています。各タブには担当するトークン以外は表示されないため、色の下までスクロールしてスペーシングにたどり着く必要はありません。

Spacing

水平（hsp-*）と垂直（vsp-*）のスペーシングスケールを編集するスライダーです。3xs から 2xl までの各ステップに対応するスライダーがあり、ドラッグに応じて縮んだり伸びたりするライブプレビューを表示します。値はレイアウトが潰れないよう、妥当な最小値にクランプされます。

Font

タイポグラフィスケール用のコントロール:

フォントファミリー選択（プリセットまたはカスタム）
数値テキスト入力による抽象スケールトークン（2xs → 2xl）。CSS値のサニタイズあり
セマンティックロール（caption・body・heading など）のマッピング設定

フォントファミリー入力は、複数スタックのフォールバックを含む任意の有効な font-family 値を受け付けます。無効な値（引用符の不一致、生のJavaScriptなど）は入力確定時に拒否されるため、貼り付けたスニペットによってページが壊れることはありません。

Size

セマンティックなアイコンサイズトークン（icon-xs → icon-lg）や、任意値からセマンティックトークンに昇格したコンポーネント寸法に対応する、ピル型スライダーです。各スライダーは、2階層サイズ戦略で想定されるpx値にスナップします。

Color

Colorタブは、以前のColor Tweak Panelがタブの1つに収まった形です。以下を含みます:

16色パレット（p0〜p15）
ベーステーマカラー（bg・fg・cursor・sel-bg・sel-fg）
セマンティックトークンの上書き（accent・code-bg・success・danger など）
50種類以上のバンドル済みプリセットから読み込める Scheme… ドロップダウン

マッチキーワード用トークン

検索結果でマッチしたキーワードのハイライト色を制御する2つのセマンティックカラートークンがあります。Colorタブの他のセマンティック上書きと並んで配置され、src/components/search.astro が検索UIのヒット箇所のスタイリングで参照します。

matchedKeywordBg — マッチしたキーワードの背景に塗られる色。
matchedKeywordFg — その背景の上に重なる、マッチしたキーワードの文字色。

キーボードアクセシビリティ

タブの切り替えは標準的なWAI-ARIA Tabsパターンを実装しています:

キー	動作
`←` / `→`	前／次のタブにフォーカスを移動
`Home`	最初のタブにフォーカス
`End`	最後のタブにフォーカス
`Enter` / `Space`	フォーカス中のタブをアクティブ化

タブは自動アクティブ化方式で、矢印キーでフォーカスを移動するとパネルの表示も切り替わります。各タブ内のすべてのスライダー・セレクト・テキスト入力は Tab で辿れ、すべてのコントロールに可視のフォーカスリングが用意されています。

JSONエクスポート — 既定では差分のみ

パネルヘッダーの Export をクリックすると、エクスポートモーダルが開きます。モーダルには、各タブの現在の状態を表す単一のJSONドキュメントが表示されます。

既定のエクスポートはデフォルトとの差分です — 実際に変更したトークンだけが含まれます。まったく触っていないトークン種別は丸ごと省略され、変更があった種別のなかでも編集したトークンだけが残ります。差分は小さく、diffしやすく、コミットに貼り付けても安定した出力になります。

{
  "version": 2,
  "spacing": {
    "hsp": { "md": "1.25rem" }
  },
  "color": {
    "palette": {
      "6": "#7aa2f7"
    },
    "semanticMappings": {
      "accent": 6
    }
  }
}

モーダルヘッダーの Show defaults too トグルを有効にすると、未変更のデフォルトを含む完全なトークンツリーを出力できます。テーマの全容を知らないデザイナーやAIに渡すスナップショットが必要な場合は、この形式を使ってください。

JSONから読み込み

Load… ボタンを押すとインポートモーダルが開きます。以前のエクスポートやAIが生成したJSONドキュメントを貼り付けると、パネルは次の処理を行います:

形状を検証（バージョン・既知のキー・値の妥当性）。
不明なキーや不正な値を致命的でない警告として報告。
ドキュメントを現在のデフォルトにマージ。未指定のトークンはデフォルトのまま、明示されたトークンだけが上書きされます。
結果を localStorage に永続化し、すべてのCSSカスタムプロパティを即時に再適用。

不正なJSONは具体的なエラーメッセージとともに拒否されます。spacing.hsp.md だけを変更するような部分的なインポートも、正規のユースケースとしてサポートされます。

AIワークフロー

差分のみのエクスポートとJSONロードを組み合わせると、チャット型AIとの単純なラウンドトリップが実現できます:

渡したいトークンを編集（触らなくてもOK）。
差分をエクスポートしてJSONをコピー。
AIチャットに貼り付け、自然言語でリクエストを添える。例:

これは現在のデザイントークンの差分です。カラーパレットはそのままに、より温かみがあり、コントラストの強いタイポグラフィスケールに書き換え、JSONだけを返してください。
AIが返したJSONを Load… に貼り付け。
パネルが検証・マージ・反映を即座に行います。結果が気に入らなければ、ヘッダーの Reset all で巻き戻せます。

既定のエクスポートが差分になっているため、AIは気にしているトークンだけを読むことになり、未変更のデフォルトを推理する必要がありません。AIに全体像が必要な場合（例: ゼロから新しいテーマを作らせるとき）にだけ Show defaults too をオンにしてください。

永続化とマイグレーション

状態は localStorage のキー zudo-doc-tweak-state-v2 に永続化されます。v2形式は各タブの状態を横並びにした単一オブジェクトなので、1回の読み込みでパネル全体が復元されます。

以前のプロジェクトで zudo-doc-tweak-state の下に保存されていたv1（カラーのみ）の状態は、自動的にマイグレーションされます:

パネルは読み込み時にまずv2を参照します。v2が無ければ、v1の状態（カラートークンのみ）を解釈し、v2のColorタブへ昇格させます。
doc-layout.astro が <head> に注入するFOUC防止スクリプトも、v2→v1の同じ順で参照します。これにより、古いデバイスでも最初のペイント前に保存済みのカラーが適用されます。
ヘッダーの Reset all をクリックすると両方のキーがクリアされ、src/config/settings.ts で宣言されたカラースキームに戻ります。

設定リファレンス

設定	型	説明
`designTokenPanel`	`boolean`	パネルを有効にします。デフォルトは `false`。
`colorTweakPanel`	`boolean \| undefined`	`designTokenPanel` の非推奨エイリアス。いずれかが truthy のときパネルは有効になります。将来のリリースで削除される予定です。

トークンそのもの（スペーシングスケール・フォントスケール・アイコンサイズ・パレット）は、引き続き src/styles/global.css の @theme と src/config/color-schemes.ts で設定します。パネルはブラウザ内のコピーを編集するだけで、ソースファイルに書き戻すことはありません。

💡 Tip

気に入った組み合わせが見つかったら、差分をエクスポートしてコミットメッセージやデザインドキュメントに貼り付けてみてください — いま行った変更を再現するもっとも小さな説明になります。