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

目のアイコンを切り替えて、トークンを使用している DOM 要素を調査する

トークン使用要素のハイライト機能を使うと、ホストページ内のどの DOM 要素が特定のデザイントークンを使用しているかを視覚的に調査できます。トークン行の横にある目のアイコンを切り替えると、一致するすべての要素にアウトラインが表示されます。歯車の設定を開けば、各ハイライトスロットの色と共通のアウトライン幅をカスタマイズできます。一致数は表示中の全行に対してではなく、必要になった時点で計算されます。

概要

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

歯車アイコン — パネルヘッダーの設定ポップオーバーを開きます。ここで、利用可能な 10 個の各ハイライトスロットの色を変更し、共通のアウトライン幅を設定し、スロットのパレットをリセットできます。

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

クイックスタート

1. パネルを開きます。

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

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

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

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

オンデマンドの一致数

無効な行では、単に数値を表示するためだけにページを走査しません。トークンのチェーンポップオーバーを開くと、パネルがそのトークンをプローブし、結果をキャッシュして、ポップオーバー内に一致数を表示します。有効なハイライトは、オーバーレイを描画する必要に応じてプローブされるため、現在の一致数が自動的に表示されます。新しいスタイルシート、テーマやクラスの変更、ナビゲーションによってキャッシュは無効化され、次の要求時に再びプローブされます。一致数は宣言数ではなく要素数であり、対応している場合は ::before と ::after 疑似要素も走査対象です。

予約シートのセマンティクス

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

スロット割り当ての規則:

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 個すべてのスロットが 2 列のグリッドに表示され、共通のアウトライン幅入力が 1 つ用意されています。

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

幅の変更: 数値入力を編集します（最小 1px、最大 20px）。リングスウォッチと有効なすべてのアウトラインがリアルタイムで更新されます。

デフォルトへリセット

設定ポップオーバーのフッターにある Reset to defaults ボタンを押すと、10 個すべてのスロット色と共通のアウトライン幅（2px）が組み込みのデフォルトに戻ります。

すべてのハイライトを無効化

設定ポップオーバーのフッターにある Disable all highlights ボタンを押すと、有効な調査対象の集合全体がワンクリックでクリアされ、すべてのアウトラインオーバーレイが即座に削除されます。スロットの色とアウトライン幅は保持され、有効なマップだけがクリアされます。確認ダイアログはありません。元に戻したい場合は、各トークンの目のアイコンをクリックして個別に再有効化できます。

永続化モデル

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

この分離により、好みのスロット色は一度設定すれば永続的に維持できる一方、現在調査中の項目一覧は再読み込み時に自動的にリセットされます。そのため、前のセッションのデバッグ状態が新しいページ読み込みに残ることを防げます。

仕組み

トークンを有効にしたとき、または無効な行やトークンチェーンポップオーバーから一致数が要求されたとき、パネルはセンチネル置換プローブを実行します。結果はスタイルシートまたはホストテーマが変更されるまでキャッシュされます。

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

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

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

4. 同じブラウザーティック内で、元のトークン値を即座に復元します。目に見えるちらつきはありません。

CSS 関数を通るトークン — color・length・number・自動検出された値について、パネルは2 プローブ差分方式を使用します。2 つの異なるセンチネル値を順に適用し、プローブ間で計算済みプロパティが異なる要素をマークします。これにより、calc() や color-mix() でラップされた使用箇所も検出できます。文字列専用のマニフェスト kind では、このような変換を文法上適用できないため、1 回の等価性プローブを使用します。

トークン型に基づくプロパティ調査 — パネルは、どの CSS プロパティを調べるべきか把握する必要があります。型ヒントは、パネルマニフェストにあるトークンの type.kind フィールドから与えられます。公開 kind は color、length、number、text、select、cursor、content、mask-image です。text と select の値には、documentElement 上で解決された値に基づく内部的な自動検出が使われます。型によって、センチネルと比較する計算済みのロングハンドおよび複合プロパティの一覧が決まります。

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

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

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

• text — カスタム識別子のプロパティ（font-family、animation-name、transition-property、will-change）を調べます。

• 自動検出されるイージング／時間値 — text または select のアイテムは、解決済みの値から自動検出されます。値が内部のプローブ分類に一致すると、タイミング関数や duration／delay のプロパティも対象に含まれます。公開 TierValueKind ユニオンに easing や time という値はありません。

文字列プロパティの 3 つの kind（cursor、content、mask-image）には、重要なプローブ特性があります:

• 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 — エントロピーの高い識別文字列を含む url() センチネルを使用します。Chrome は cursor と異なり、mask-image の getComputedStyle では url() を保持します。Chrome が url() 内の一重引用符を二重引用符へ正規化する場合もありますが、識別文字列は引用符の形式に依存しないデータ URI の部分文字列です。解決済みの url() 値の自動検出は曖昧です。url() 値は cursor、mask-image、background-image のいずれにもなり得るため、自動検出では警告を出して text にフォールスルーします。曖昧さをなくすには、マニフェストで kind: 'mask-image' を明示してください。

文書化された制限事項

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

adoptedStyleSheets — adoptedStyleSheets API で document に関連付けられた Constructable Stylesheet は document.styleSheets に含まれず、アルゴリズムの調査対象になりません。

Shadow DOM — DOM の走査は shadow root の内部に入りません。Web Components の内部にある使用要素は、open／closed のどちらの shadow root でも検出されません。

::before と ::after 以外の疑似要素 — ::placeholder、::marker、::selection、::backdrop など、その他の疑似要素は調査されません。

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

CSS-in-JS フレームワーク — adoptedStyleSheets または Shadow DOM でスタイルを注入するフレームワークには、上記の制限が適用されます。通常の <style> タグを注入するフレームワークは完全にサポートされます。

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

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