パネル UX ツアー

実際に動作するデザイントークンパネルの機能とキーボード操作を順に紹介します。

パネルは、トークンを変更し、実際のページで結果を確認して、その変更を残すか 判断するための開発者ツールです。このツアーでは、日常的に使う編集コントロールから ページ全体を対象とする補助機能まで、現在のシェルを順に紹介します。パネル内の編集は 1 つのトランザクション経路に集約されているため、行単位の編集、一括操作、インポート、 スナップショット、要素インスペクトは、すべて同じ undo/redo 履歴に記録されます。

検索とコマンドパレット

インラインフィルターは、CSS 変数名、安定 ID、ラベル、現在値、ティアラベル、 タブラベルを対象に、ファジーな部分列一致で検索します。/ を押すとフィルターへ フォーカスします。パネルが閉じている場合は、代わりにコマンドパレットが開きます。 Cmd/Ctrl+K を押せば、いつでもコマンドパレットを直接開けます。パレットでは、 矢印キー、Home、End、Enter、Escape を使って操作できます。検索結果には タブごとの件数チップも表示されるため、すべてのタブを手作業で巡回しなくても トークンを見つけられます。

変更状態の表示

パネルは各値を正規のベースラインと比較し、変更された行にアクセントマーカーと レールを付けます。変更を含むタブにはバッジが付き、一時的な Changed only ビューでは、通常のタブナビゲーションを隠さずに、アクティブなタブだけを 絞り込めます。変更された各行には個別の Revert 操作があります。フッターには 全タブを通じた変更済みトークン数が表示され、Copy diff と Revert all を 実行できます。最後に適用した比較ベースラインは、現在のオーバーライドとは別に 永続化されます。ディスクへの適用が成功すると、実装はそのベースラインを {} に リセットし、実際に書き込まれたことが確認できた変数だけを整合させます。そのため、 保持されたオーバーライドやルーティング対象外のオーバーライドは、引き続き変更済み として表示されます。

タイプ見本とグリフプレビュー

ティアに対応するプレビューを表示するには、TierConfig.preview を設定します。 size は、解決後のピクセル値順にトークンごとの見本行を表示します。 line-height は、行送りガイド付きの段落を表示します。family と weight は フォント見本を、bar、radius、duration はコンパクトな視覚グリフを描画します。 ティアでは previewBase を指定して、見本の font-size または line-height の基準に 使う CSS 変数を選択できます。

見本ツールバーのテキスト、プリセット、オーバーライド状態、幅は ${storagePrefix}-specimen に保存されます。幅は 240〜720 ピクセルに制限されます。 Render on page は見本をホストドキュメントへポータルし、ホストの実際の フォントを使用します。その間は右ドックを一時的に確保し、無効化、クローズ、 アンマウント、またはドック確保の喪失時に、以前のドックモードを復元します。 ページ上の見本には data-zdtp-specimen が付き、トークンスキャンから除外され、 ページピッカーにも関与しません。

Undo、redo、A/B スナップショット

状態を変更するすべての操作は、次の順序でパネルのトランザクション経路を通ります。 メモリ内の状態と CSS 変数を適用し、永続化エンベロープを保存し、コンポーネント状態を 更新してから、履歴を記録します。Cmd/Ctrl+Z で undo、 Cmd/Ctrl+Shift+Z（または Ctrl+Y）で redo します。履歴レールからも、同じ メモリ内の履歴エントリーを操作できます。履歴自体は再読み込みをまたいで 永続化されません。

スナップショット A と B は永続化され、状態、identity、タイムスタンプ、 編集メタデータを含みます。修飾キーを押しておらず、編集可能なコントロールにも フォーカスしていない状態で \ を押すと、2 つのスナップショットを切り替えられます。 スナップショットの復元もトランザクションとして扱われ、undo できます。

ドック、ミニモード、ゴーストアイドル

シェルは float、right、bottom、mini の各モードに対応します。右ドックと 下ドックの寸法は ${storagePrefix}-dock-size に、モードは ${storagePrefix}-dock に永続化されます。Alt+1〜Alt+4 で 4 つのモードを 選択できます。ミニモードはコンパクトなピル表示で、展開すると直前のフルモードへ 戻ります。ゴーストアイドルは、操作がない状態が続くとパネルの chrome を薄くし、 設定を ${storagePrefix}-ghost に永続化します。

dock.reflow がデフォルトの body-margin の場合、右または下のドックを確保すると、 対応する body のマージンが更新され、--zdtp-dock-inset-right または --zdtp-dock-inset-bottom が公開されます。none では body のマージンを変更せず、 inset だけを公開します。確保はウィンドウ単位かつ辺単位です。競合するパネルは float にフォールバックし、確保を解除するとホストのインライン値と優先度が正確に 復元されます。

トークンの解決チェーンと使用箇所

チェーンポップオーバーには、トークンが参照ティアを通じて解決される過程と、 下流の依存先、ランプ内の兄弟、影響範囲が表示されます。Used on page の件数は、 マウント時に全行分を計算するのではなく、必要になった時点で計算します。件数は CSS 変数およびスタイルシート／テーマのバージョン別にキャッシュされ、ドキュメントの スタイルシートやテーマ／クラス入力が変わると無効化されます。ポップオーバーの ハイライト操作を使うと、トークンとページ内の使用要素を対応付けて確認できます。

適用プレビューとディスク書き込み

applyEndpoint と applyRouting が設定されている場合、Apply はまず { dryRun: true } を含む、デバウンスされた POST /apply プレビューを送信します。 プレビューは、ルーティングされた各ファイルについてダイジェストと 1 始まりの ハンクを返します。確定時の書き込みでは、選択したトークン値と expectDigests を 送信します。ファイルが変更されていれば、どのファイルにも書き込む前に 409（reason: 'stale-file'）で拒否されるため、パネルは安全にプレビューを 更新できます。

モーダルでは、変更済み変数の一部だけを選択して含められます。ルーティング対象外の 変数は現在の状態に残り、診断情報として報告されます。一部の適用が成功すると、 書き込みが確認された変数だけが整合され、永続化された last-applied ベースラインは {} にリセットされます。エンドポイントとルーティングの両方が揃っていなければ、 ディスク適用操作は無効になりますが、エクスポート／インポートは引き続き利用できます。

ランプの一括編集

ティア内で、書き込み可能な数値リテラル行を選択すると、一括操作バーが開きます。 参照行、読み取り専用行、ピルが有効な行、解析できない値は対象外です。利用できる 操作は、乗算、加算、ステップ丸め、全件同一値への設定です。クイック操作では 0.9 倍または 1.1 倍にできます。負の結果は 0 にクランプされ、Set all はほかの 操作より優先されます。Apply to selection を 1 回実行すると、選択範囲全体が 1 つのトランザクションとしてコミットされます。Clear は選択を解除するだけです。

要素インスペクト

ヘッダーのトグルを使うか I を押して要素インスペクトを起動し、ホストページの 要素をクリックします。予約済みの Inspect タブには、選択した要素にあるトークン由来の 宣言が一覧表示されます。継承された一致や、スキャン済みスタイルシートで確認できなかった 算出値も含まれます。行は通常のトランザクション経路で編集または復元できます。 インスペクト画面には Clear と、関連トークン向けの Color ジャンプもあります。

トークン使用要素のハイライト

ハイライト補助機能は、選択した CSS 変数を使用するページ要素に印を付けます。 ${storagePrefix}-highlight-slots に永続化される 10 個のカラースロット、 ${storagePrefix}-highlight-outline-width に保存される共通アウトライン幅、 セッション中に ${storagePrefix}-highlight-active に保存される CSS 変数から スロットへのアクティブな対応表を使用します。非アクティブな行については、ユーザーが 件数を要求するまでカウント／プローブのコストは発生しません。スタイルシートまたは テーマ入力が変わるとキャッシュは無効化されます。

要素パス

要素パスは、DOM Tweaker および要素インスペクトと 1 つの Alt+クリック コーディネーターを共有します。owner autoload またはパネルのトグルで有効にし、 Alt を押しながらホスト要素をクリックすると、注釈付きのセレクター／パスブロックが コピーされます。別のピッカーが要求されると、要素パスの起動状態は解除されます。 パネルが所有する画面とページ上の見本は対象外です。

DOM Tweaker

PanelConfig.domTweaker が存在する場合、DOM Tweaker を有効にして Alt を押しながら ホスト要素をクリックすると、設定済みの Tailwind クラスエディターとライブ ユーティリティプレビューが開きます。要素パスおよび要素インスペクトと排他的な コーディネーターを共有するため、最後に起動した機能がジェスチャーを受け取ります。 owner autoload が要素パスを起動していても、あとから DOM Tweaker を起動できます。

エクスポート、インポート、リセット

パネルは正規の JSON エンベロープをエクスポートし、互換性のあるスキーマを インポートできます。インポート、リセット、スナップショットの復元、通常の行編集は、 すべて同じトランザクション経路を使います。リセットすると、パネルインスタンスの CSS 変数一式（または設定済みの applySink）がクリアされ、永続化されたトークン状態が 削除されます。ドックの形状、ゴースト、見本、スナップショットなどの UI 設定は、 別に保持されます。

キーボードショートカット

検索とパレットのリストでは、さらに ArrowUp / ArrowDown、Home、End、 Enter、Escape も使用できます。