design-tokens-sync

デザイントークンの同期

信頼できる唯一の情報源を、常に信頼できる状態に保ちます。どのデザインシステムも同じように劣化していきます。急いでいるときに16進数のカラーコードがハードコードされ、Figmaではトークンの名前が変更されたのにTailwindではそのままになり、使い捨てのCSSファイルにパレットのコピーがもう1つ作られます。このスキルは差異を見つけ、ユーザーと同期の方向を決めて、整合性を回復します。

ワークフロー

1. 信頼できる情報源を特定します。 トークンが定義されている場所をすべて探します。tokens.json／*.tokens.json（W3C形式）、Figma変数のエクスポート、tailwind.config.* のテーマ、CSSカスタムプロパティ、TSのテーマオブジェクト、SCSS変数ファイルなどです。正規の情報源を名乗るものが複数ある場合は、何かに手を加える前に、どれを優先するか確認します。同期の方向は人が決める必要があります。
2. グラフを作成します。 各トークンについて、正規の値、下流で定義されているすべての値、利用されているすべての箇所を調べます。コード内の生の値（hex、px、rem、ms、cubic-bezier）については、それに対応するトークンが存在するかを確認します。
3. 差異レポートを作成します。 token-drift-report.md に、以下の4つの分類で結果を出力します。
   • STALE COPIES -- 正規の値と一致しなくなった下流の定義（両方の値を記載）
   • HARDCODED -- 一致するトークンが存在するコンポーネント内の生の値（完全一致を確認し、次に色については知覚的距離の近い値を確認）
   • ORPHANS -- 定義されているものの、どこからも利用されていないトークン
   • UNTOKENIZED -- トークンがなく、3回以上出現する生の値。名前を付けるべきトークンです。
4. 承認後に整合性を回復します。 古いコピーは、正規の情報源から下流の定義を再生成します。ハードコードされた値は、トークン参照に置き換えます。完全一致する値は自動で置き換え、近似値はケースごとに確認してから置き換えます。少し違う青色は、意図的な選択かもしれません。トークン化されていない値については、既存の命名規則に沿った名前を提案し、正規の情報源に追加します。孤立トークンは削除候補として一覧にします。自動では削除しません。
5. 防止策を講じます。 安価な検出策として、差異の検出を再実行するスクリプト（npm run tokens:check）の追加を提案します。新たな古いコピーや、近似値のハードコードが見つかった場合にCIを失敗させ、作業を離れた後も同期状態を保てるようにします。

ルール

• 1回の実行で両方向に同期しないでください。正規の情報源を優先します。コード側の新しい値をデザイナーが採用したい場合など、逆方向に同期する値は、まず正規の情報源を明示的に編集してください。
• 近似値の置換はケースごとに判断し、一括で行わないでください。#0B1121 と #0b1220 の違いは、差異かもしれませんし、意図的な選択かもしれません。
• セマンティックレイヤーを維持してください。システムが color.blue.500 -> color.accent -> button.bg という構造なら、すべてをプリミティブに平坦化するのではなく、適切なレイヤーの参照を修正してください。
• 名前の変更はすべてに反映するか、どこにも反映しないでください。名前が一部だけ変更されたトークンは、元の名前のままよりも厄介です。
• 生成ファイルに配慮してください。theme.css が tokens.json から生成される場合は、ソースを修正して再生成します。出力ファイルを直接編集しないでください。
• レポートでは健全性を数値化します。リリースごとに改善すべき指標は、トークン適用率（コンポーネント内の生の値に対するトークン化された値の割合）です。

クイックコマンド

• 「トークンを監査して」 -- 手順1〜3を実行し、レポートのみを出力
• 「[source]から同期して」 -- 指定された正規の情報源から、整合性を全面的に回復
• 「何がハードコードされている？」 -- HARDCODED のみを出力
• 「CIガードを追加して」 -- 手順5のみを実行