token-mapping

トークンのマッピング

生の値（16 進数、px、シャドウ）を、別の担当者が管理するトークンリストに照合する読み取り専用レポートです。クラス、正規化、許容範囲については references/mapping-rules.md に記載されています。「設定ページのトークンを確認して」という依頼で十分です。値とリストは自分で探してください。

手順

1. リストを見つける。 トークンファイル、テーマエントリー、:root のカスタムプロパティ、コンポーネントライブラリの変数のペアを探します。フレームワークのデフォルトテーマはチームのリストではなく、公開システムのリストも同様です（Geist の名前をチームの名前の代わりに使うことはできません）。名前、場所、読み取り方法を記録してください。読み取りに失敗した場合は、その旨を伝えて停止します。記憶を頼りにリストを埋めてはいけません。
2. 値を見つける。 指定された対象があればそれを、なければブランチの差分、さらにそれもなければプロダクトコードを確認します。それぞれについて、ファイル、行、プロパティ、用途を記録します。
3. 解決する。 各モードですべてのエイリアスをたどり、最終的な値を確認します。2 つのソース間で食い違いがあれば、すべて書き留めます。
4. 正規化する。 両側をコードで正規化します（長さは px に、色は OKLCH に変換して delta E OK で比較）。目視で判断してはいけません。
5. 分類する。 各モードで、各行を一度だけ分類します。まず用途、次に値を確認します。
   • 完全一致：トークンの用途がその行をカバーし、値も一致します。
   • セマンティック一致：用途がその行をカバーし、値が許容範囲内です。差を数値で示します。
   • 曖昧：2 つ以上のトークンが当てはまり、どれかを選ぶ根拠がありません。候補をすべて挙げます。
   • ギャップ：どのトークンの用途もその行をカバーしないか、当てはまる唯一のトークンが許容範囲外です。ギャップに新しい名前を付けてはいけません。
6. 集計して締めくくる。 ギャップが全行の 30% を超え、かつ 12 件以上ある場合、通常はリストが適切ではありません。その旨を伝えたうえで表を提出し、冒頭を Status: not actionable (gap threshold) とします。

レポート

Summary、Mapping、Do not use（値は一致していても用途が異なるトークン）、Ambiguous、Gaps、For a person to decide、Source の順に記載します。最終行は Coverage: とし、スキャンした対象とスキャンしなかった対象を記載します。単独で実行した場合、チャットの返信だけで数値を含む回答が得られ、次の手順に進むためにユーザーが貼り付けられるプロンプトが 1 つ提示されます。

ルール

• 用途より先に値で一致させるのは誤りです。誤り：16 進数が同じという理由で #6b7280 を color.border.default に割り当てる。正しい方法：これはテキストなので、候補はテキスト用トークンです。ボーダー用トークンは Do not use に記載します。
• セマンティックトークンは、それがエイリアスしているプリミティブより優先します。用途をカバーするセマンティックトークンがない場合に限り、プリミティブに割り当て、その旨を記載します。
• パレットクラス（text-gray-500）は値を示しますが、用途は示しません。独立した行として扱い、生の値とは分けて集計します。
• クラス名から用途を推測するなど、読み取った情報ではなく推論した情報には、推論であることを明記します。
• 集計値には単位を付けます：出現数、行数、またはマッピング行数。

停止条件

次の場合に限り、停止して報告します。リストが存在しない。同じモードで 1 つの名前に 2 つの値がある。2 つのソースが食い違い、どちらを優先するかを定めるプロジェクトのルールがない（両方を報告する）。停止の原因、ここまでに行った準備、作業を進めるために必要な最短のメッセージを返します。例：「tokens.json を貼り付けるか、パスを教えてください。」

完了

すべての行に用途、クラス、理由があります。曖昧な行には、2 つ以上の候補が記載されています。リポジトリは変更されていません（作業前後で git status が同じです）。最終行は Coverage: です。