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

トークンの目アイコンを切り替え、そのトークンを使用する DOM 要素を調べます

トークン使用要素のハイライト機能を使うと、ホストページ内で特定のデザイントークンを使用している DOM 要素を視覚的に確認できます。トークン行の横にある目アイコンを切り替えると、一致するすべての要素にアウトラインが付きます。歯車の設定を開けば、各ハイライトスロットの色とアウトライン幅をカスタマイズできます。

概要

目アイコン — 各トークン行の横にあるトグルボタンです。クリックすると、そのトークンの検査用ハイライトが有効になります。その CSS カスタムプロパティが算出スタイルへ影響しているすべての要素に、ホストページ上で色付きのアウトラインオーバーレイが表示されます。もう一度クリックするとハイライトが消えます。

歯車アイコン — パネルヘッダーの設定ポップオーバーを開きます。ここでは、利用可能な 10 個のハイライトスロットそれぞれについて色とアウトライン幅を変更したり、すべてのスロット色を鮮やかなデフォルトパレットへ戻したりできます。

表示結果 — 有効なハイライトは、ホストページのコンテンツ上に重ねられた色付きのアウトラインとして現れます。オーバーレイは、パネルの z-index スケール（--tokentweak-z-overlay）においてパネルシェルのすぐ下、一般的なホストコンテンツより上に配置されます。同時に最大 10 個のトークンをハイライトできます。

クイックスタート

1. パネルを開きます。

2. 調べたいトークンがあるタブへ移動します。

3. トークン行の横にある目アイコンをクリックします。

4. ホストページ内の要素に表示される色付きのアウトラインを確認します。

5. 目アイコンをもう一度クリックしてハイライトを消します。

予約表のセマンティクス

ハイライトは、固定された 10 スロットの「予約表」から割り当てられます。各スロットにはインデックス（0〜9）、色、アウトライン幅があります。常に空いている最小のインデックスが最初に確保されます。途中のスロットを解放しても、それより大きなインデックスのスロットは現在の位置に留まります。

スロット割り当てのルール:

1. トークンを有効にすると、ハイライトシステムは空いている最小のスロットインデックスを見つけて確保します。

2. そのスロットの色とアウトライン幅が、トークンのアウトラインに適用されます。

3. トークンを無効にすると、そのスロットが解放されます。ほかのスロットはすべてそのままです。

4. 次に有効にしたトークンが、空いている最小のスロットを再び確保します（以前解放された小さいインデックスの場合もあります）。

動作例:

• トークン A を切り替える → スロット 0 を確保。

• トークン B を切り替える → スロット 1 を確保。

• トークン C を切り替える → スロット 2 を確保。

• A を無効にする → スロット 0 が解放される。B はスロット 1、C はスロット 2 のまま。

• トークン D を切り替える → スロット 0（空いている最小のインデックス）を確保。

結果: D はスロット 0、B はスロット 1、C はスロット 2 に配置されます。

設定ポップオーバー

パネルヘッダーの歯車アイコンをクリックすると、ハイライト設定ポップオーバーが開きます。10 個のスロットが 4 列のグリッドに表示されます。

色を変更する: リングの色見本をクリックすると、そのスロット用のカラーピッカーが開きます。現在ハイライトされているすべての要素のアウトラインがリアルタイムに更新されます。

幅を変更する: スライダーをドラッグしてアウトライン幅を変更します。リングの色見本の枠線と、ハイライトされたすべての要素のアウトラインがリアルタイムに更新されます。

デフォルトへリセット

設定ポップオーバーのフッターにある Reset to defaults ボタンは、10 個すべてのスロット色を、組み込みの鮮やかなデフォルトパレット（赤、ピンク、スカイブルーなど）へ戻します。

すべてのハイライトを無効にする

設定ポップオーバーのフッターにある Disable all highlights ボタンは、有効な検査対象を 1 回のクリックですべてクリアし、すべてのアウトラインオーバーレイを即座に削除します。スロットの色とアウトライン幅は保持され、有効なマップだけがクリアされます。確認ダイアログはありません。取り消したい場合は、それぞれの目アイコンをもう一度クリックして個々のトークンを再度有効にできます。

永続化モデル

この機能は 2 つの異なるストレージ層を使用します。

この分離により、好みのスロット色を一度設定して永続的に保ちながら、現在検査している対象のリストは再読み込み時に自動的にリセットできます。前のセッションのデバッグ状態が、新しく読み込んだページへ残ることを防ぎます。

仕組み

トークンの横にある目アイコンをクリックすると、パネルはセンチネル置換プローブを実行します。

1. パネルは一意なマーカー値（「センチネル」）をトークンの CSS カスタムプロパティへ一時的に書き込みます。:root と、スタイルシートのルールがそのトークンを直接定義しているほかのすべての要素を上書きします。これにより、:root だけでなく [data-theme="dark"] ブロックのようなカスケードスコープのオーバーライドも対象になります。

2. スタイルの再計算を同期的に強制します。

3. ページ body 内のすべての要素と、その ::before および ::after 疑似要素について、算出済み CSS 値を取得します。算出値にセンチネルを含む要素が、そのトークンの使用要素です。

4. 同じブラウザーティック内ですぐに元のトークン値へ戻します。画面上のちらつきはありません。

CSS 関数を通るトークン — トークンの値が calc()、min()、max()、clamp()、color-mix()、または同様の CSS 関数を通る場合、単一センチネルによる等価性チェックは信頼できません（関数がセンチネルを認識できない形に変換することがあるためです）。この場合、パネルは自動的に二重プローブ方式へフォールバックします。異なる 2 つのセンチネル値を順に適用し、2 回のプローブ間で算出プロパティが異なる要素をマークします。この低速なフォールバックにより、高速な等価性チェックでは見落とす、変換処理に包まれた使用要素も検出できます。

トークン型によるプロパティ検査 — パネルは、どの CSS プロパティを調べるか把握する必要があります。型ヒントは、パネルマニフェストにあるトークンの type.kind フィールドから渡されます。対応する kind は color、length、number、text、easing、time、cursor、content、mask-image です。マニフェストにないトークンについては、documentElement 上で解決されたトークン値から型を自動検出します。型によって、センチネルと比較する算出済みロングハンドプロパティと複合プロパティのリストが決まります。

• color — 色のプロパティ（color、background-color、border-color など）と、box-shadow のような複合プロパティを検査します。

• length — 寸法のプロパティ（padding、margin、width、font-size など）と、transform のような複合プロパティを検査します。

• number — 単位なしの数値プロパティ（opacity、line-height、z-index など）を検査します。

• text — custom-ident プロパティ（font-family、animation-name、transition-property、will-change）を検査します。

• easing — タイミング関数のプロパティ（transition-timing-function、animation-timing-function）を検査します。

• time — 継続時間と遅延のプロパティ（transition-duration、transition-delay、animation-duration、animation-delay）を検査します。0.3s や 150ms のようなトークン値は、自動的にこの kind へ分類されます。

#285 で追加された 3 つの新しい文字列プロパティ kind には、重要なプローブ特性があります:

• cursor — 裸の cursor キーワードをセンチネル（crosshair / move）として使用します。Chrome の getComputedStyle は cursor 値から url() 部分を取り除きます（画像を読み込めない場合はフォールバックキーワードも破棄され、auto を返します）。そのため、url() ベースの cursor センチネルは使用できません。キーワードのセンチネルは正しく往復します。トレードオフとして、CSS 変数を使用せずリテラルで cursor: crosshair または cursor: move を指定した要素は偽陽性として報告されます。自動検出は cursor へ振り分けません。マニフェストで kind: 'cursor' を明示する必要があります。

• content — 二重引用符付き文字列のセンチネルを使用します。引用符付きの文字列値は、Chrome の算出スタイルのシリアライズ後もそのまま維持されます。トークンの解決値が "..."（:root 上の引用符付き文字列）というパターンに一致する場合、自動検出は content へ振り分けます。

• mask-image — 高エントロピーの needle を含む url() センチネルを使用します。Chrome は（cursor と異なり）mask-image の getComputedStyle で url() を維持します。Chrome が url() 内の一重引用符を二重引用符へ正規化することがありますが、needle はデータ URI の部分文字列なので引用符の形式に依存しません。解決値が url() の場合の自動検出は曖昧です。url() 値は cursor、mask-image、background-image のいずれかである可能性があります。自動検出は警告を出しながら text へフォールスルーします。曖昧さを解消するには、マニフェストで kind: 'mask-image' を明示してください。

既知の制限

クロスオリジンのスタイルシート — CORS ヘッダーなしで異なるオリジンから配信されたスタイルシートについて、ブラウザーは CSS ルールの読み取りをブロックします。そのようなシートだけで定義された使用要素は検出されません。クロスオリジンのシートをスキップすると、ブラウザーコンソールに警告が出力されます。

adoptedStyleSheets — adoptedStyleSheets API を通じて document に接続された構築済みスタイルシートは document.styleSheets に含まれないため、アルゴリズムの検査対象になりません。

Shadow DOM — DOM の走査は shadow root 内へ入りません。Web Components 内の使用要素は、open / closed いずれの shadow root でも検出されません。

::before と ::after 以外の疑似要素 — ::placeholder、::marker、::selection、::backdrop、およびその他の疑似要素は検査されません。

ブラウザーの「最小フォントサイズ」設定 — ユーザーがブラウザーの最小フォントサイズをアルゴリズムの length センチネル（通常は約 7.13px）より大きく設定している場合、高速な等価性プローブでは font-size の使用要素を見落とす可能性があります。通常は二重プローブの差分フォールバックで検出できます。

CSS-in-JS フレームワーク — adoptedStyleSheets や shadow DOM を通じてスタイルを挿入するフレームワークには、上記の制限が適用されます。通常の <style> タグを挿入するフレームワークには完全に対応しています。

ホストの非常に高い z-index — オーバーレイは、パネルの z-index スケールにある --tokentweak-z-overlay に配置されます。このオーバーレイ値より高い z-index を持つホスト要素は、アウトラインを視覚的に覆います。パネルシェルとオーバーレイは、ほとんどのホスト側の chrome より手前になるよう、デフォルトで INT32 の高い値域を使用します。ホストはパネルスコープの --tokentweak-z-* をオーバーライドして上限を調整できます。

動的に挿入された要素は自動更新されない — DOM の走査は、目アイコンをクリックした時点で存在する要素に対して一度だけ実行されます。ハイライトを有効にした後で新しい要素が DOM に挿入されても、自動的にオーバーレイは付きません。目アイコンをもう一度クリックしてプローブを再実行してください。