Design Token Panel
スペーシング、フォント、サイズ、カラーの各デザイントークンをタブ分けしたパネルでライブ編集し、JSONでエクスポート・AIを介して読み込めるワークフローを提供します。
Design Token Panelは、テーマが提供するすべてのデザイントークンをページ上で編集できるインタラクティブなエディタです。以前のColor Tweak Panel（カラー専用）を置き換え、Spacing・Font・Size・Colorの4つのトークン種別をタブ構成でカバーします。さらに統一されたJSONエクスポート／インポート機能を備えており、デザインをまとめてAIアシスタントに渡し、返ってきた結果を読み込むラウンドトリップ運用が可能です。
パネルを有効にする
src/ で designTokenPanel を true に設定します:
export const settings = {
designTokenPanel: true,
// ...
};有効になると、ヘッダーに（検索アイコンの左側に）パレットアイコンが表示されます。クリックするとパネルが開閉し、以前のColor Tweak Panelと同じキーボードショートカットも引き続き利用できます。
Note
設定キーは designTokenPanel です。true に設定するとパネルが有効になります。
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タブの他のセマンティック上書きと並んで配置され、検索ウィジェット（pages/）が検索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-v3 に永続化されます。v3エンベロープは各タブの状態（カラー・スペーシング・タイポグラフィ・サイズ、および任意の汎用タブ）を横並びにした単一オブジェクトなので、1回の読み込みでパネル全体が復元されます。
以前のプロジェクトで保存されていた古い形式 — zudo-doc-tweak-state-v2（v2）や zudo-doc-tweak-state（v1、カラーのみ） — は、自動的にマイグレーションされます:
パネルは読み込み時にまずv3を参照します。v3が無ければ、v2エンベロープ、続いてv1のカラーのみの状態へとフォールバックし、見つかったものをv3エンベロープへ昇格させ、v3キーを書き込み、レガシーキーを削除します。
doc レイアウト（
@takazudo/）がzudo- doc/ doclayout <head>に注入するFOUC防止スクリプトも同じ順で参照します。これにより、古いデバイスでも最初のペイント前に保存済みのトークンが適用されます。ヘッダーの Reset all をクリックすると、v3エンベロープ（および残存するレガシーキー）がクリアされ、
src/で宣言されたカラースキームに戻ります。config/ settings. ts
ライト/ダークの切り替えで保存済みの編集が消えることはありません。テーマトグルは color-scheme-changed イベントをディスパッチし、パネルはそれに応じて、新しくアクティブになったスキームからカラーパレットを再シードします（新しいスキームの色が反映されます）。一方で、スペーシング・タイポグラフィ・サイズの編集を含む永続化済みエンベロープはそのまま保持されます。
ストレージプレフィックスの継続性保証
ストレージプレフィックス zudo-doc-tweak は src/ に固定されており、変わりません。古いバージョンのキーで保存されたトークンも自動的に読み込まれ、初回ロード時に現在の zudo-doc-tweak-state-v3 エンベロープへとマイグレーションされるため、手動のマイグレーション作業は不要です。
実装
パネルUIは @takazudo/zdtp（zdtp）npmパッケージが提供します。zudo-docは src/ 内で configurePanel(designTokenPanelConfig) を呼び出してzdtpを組み込んでいます。パネルはこの呼び出しのサイドエフェクトとして自己マウントされるため、Preactアイランドの登録は不要です。
ヘッダーのトリガーボタンは window に toggle-design-token-panel カスタムイベントをディスパッチします。zdtpはこのイベントをネイティブに受け取るため、settings.headerRightItems でトリガーをカスタマイズしても追加の配線は必要ありません。
設定リファレンス
| 設定 | 型 | 説明 |
|---|---|---|
designTokenPanel | boolean | パネルを有効にします。デフォルトは false。 |
トークンそのもの（スペーシングスケール・フォントスケール・アイコンサイズ・パレット）は、引き続き src/ の @theme と src/ で設定します。パネルはブラウザ内のコピーを編集するだけで、ソースファイルに書き戻すことはありません。
Tip
気に入った組み合わせが見つかったら、差分をエクスポートしてコミットメッセージやデザインドキュメントに貼り付けてみてください — いま行った変更を再現するもっとも小さな説明になります。