tokens

コンテキスト： このサブスキルは、より広範な ui-craft スキルにおける1つの視点です。ui-craft スキルもインストールされている場合は、まずその SKILL.md を読み、Discovery + Anti-Slop + Craft Test を確認してから、以下の特定の視点を適用してください。

作業を進める前に references/tokens.md を読んでください。3層の契約（プリミティブ → セマンティック → コンポーネント）と intentional-dark テストは、そこに定義されています。

---

Step 1: 既存のトークンを検出する

プロジェクト内でトークン定義をスキャンします。

• :root、[data-theme]、[data-mode]、またはテーマラッパーのセレクター内の CSS 変数
• theme.extend または theme 配下の Tailwind 設定（tailwind.config.js/ts）
• CSS-in-JS のテーマオブジェクト（theme.ts、*.styles.ts、styled.d.ts、ThemeProvider）
• design-tokens.json または tokens.json（Style Dictionary / Theo）
• globals.css、variables.css、tokens.css

インベントリを作成します。7つのカテゴリ（色／スペーシング／タイポグラフィ／角丸／シャドウ／モーション／z-index）のうち、どれが存在するか、どのレイヤー（プリミティブ／セマンティック／コンポーネント）があるか、ライトとダークの両方が定義されているかを確認します。

---

Step 2: $ARGUMENTS とインベントリに基づいて振り分ける

• "audit" → 監査のみを実行します（Step 3）。提案はしません。
• "establish" → 監査を省略し、Step 4 に進みます。
• "color" / "spacing" / "type" / "radii" / "shadows" / "motion" / "z-index" → 監査と提案の対象を、その1つのカテゴリに絞ります。
• 空 → トークンがある場合は監査します。何も見つからない場合は確立します。

---

Step 3: 監査（トークンが存在する場合）

references/tokens.md の契約に照らして評価します。重大度順に不足項目を出力します。まだコードを提案してはいけません。

確認項目：

1. 3層の網羅性 — プリミティブ、セマンティック、コンポーネントの各レイヤーがすべて存在しますか？よくある不足はセマンティックの欠如です。プリミティブは存在するものの、ダークモードで切り替わるものがなく、サーフェスの階層も定義されていません。
2. 7カテゴリの網羅性 — 色／スペーシング／タイポグラフィ／角丸／シャドウ／モーション／z-index のいずれかが不足していますか？不足しているカテゴリをそれぞれ指摘します。
3. 意図的なダークモード — intentional-dark テストを実行します。ダークモードは --text-primary の反転以上のことをしていますか？--surface-canvas は色味のあるほぼ黒ですか（#000 ではありませんか）？アクセントの彩度は10～15%抑えられていますか？シャドウはボーダーリングに置き換えられていますか？
4. 命名規則 — プリミティブは役割（--button-bg）ではなく値（--gray-500）に基づいて命名されていますか？セマンティックは値（--gray-900-text）ではなく役割（--text-primary）に基づいて命名されていますか？
5. 任意の値を使わない — トークンシステムを迂回するインラインの色、スペーシング、z-index の値はありませんか？

出力形式：

重大度	カテゴリ	指摘事項
重大	ダークモード	--surface-canvas が #000 です — intentional-dark テストを実施します
高	セマンティック	サーフェスの階層がなく、コンポーネントが生のプリミティブを使用しています
中	シャドウ	シャドウが単層で、アンビエント層がありません
低	Z-index	3つのコンポーネントで任意の値（z-index: 999）が使われています

不足している項目を示します。ユーザーから求められない限り、監査中にコードを提案しないでください。

Step 3b — 収束モード（明示的なオプトイン）

skills/ui-craft/references/loops.md の token-consistency プリセットを読み込みます（予算 = loops.md で定義されているデフォルトのループ予算）。実行前のコスト通知を出力します。システムに準拠しない値（生の16進数カラー、任意の角丸、またはマジックナンバーのスペーシング）のうち最優先のものを修正した後、システムに準拠しない値がなくなるか、予算を使い切るまで再スキャンします。

Step 4: 確立する（トークンが見つからない場合）

最小限のスパインをインラインで提案します。7 つのカテゴリすべてを網羅してください。ライトブロックとダークブロックの両方を必ず含めてください。どちらも意図的なものです。

最小限のスパインの順序：

1. プリミティブ — ニュートラルランプ（gray-50 から gray-950）、アクセントランプ 1 つ、セマンティックカラーのベース、スペーシングスケール、タイポグラフィスケール、角丸、シャドウ、モーション、z-index。
2. セマンティクス — サーフェスの階層（5 レベル）、テキストの役割、ボーダーの役割、アクセントの役割、ステータスの役割（成功／警告／エラー／情報）。
3. コンポーネントトークン — 特定のコンポーネントをすでに構築している場合を除き、後回しにします。

プロジェクト全体で sRGB を使用している場合を除き、色には OKLCH を使用してください。その場合は不足点を指摘して OKLCH を提案しますが、自動変換はしないでください。

ファイルに書き込む前に、どのファイルに書き込むかを尋ねてください。 プロジェクト構造からファイルを判断し、次のいずれかを提案します。

• Tailwind プロジェクト → globals.css（:root 内に CSS 変数を記述）
• CSS-in-JS → theme.ts（エクスポートするテーマオブジェクト）
• Vanilla CSS → tokens.css（独立した変数ファイル）
• クロスプラットフォーム／複数コンシューマー → design-tokens.json（Style Dictionary 形式）

書き込む前にユーザーの確認を得てください。

---

Step 5: 上書きしない

プロジェクトに既存のトークンファイルがある場合は、パッチとして追加内容を提案し、差分ブロックで変更点を示してください。

  :root {
+   /* ── Semantic surface stack (new) ── */
+   --surface-canvas:  var(--gray-50);
+   --surface-raised:  var(--gray-100);
+   --surface-overlay: #fff;
+   --surface-sunken:  var(--gray-200);
+   --surface-inverse: var(--gray-900);
  }

ユーザーが適用できるようにしてください。承認がない限り、直接書き込まないでください。

---

制約

• Vanilla CSS プロジェクトに Tailwind を押し付けないでください。プロジェクトで既に使われている構文に合わせてください。
• プロジェクト全体で一貫して sRGB を使っている場合、OKLCH を押し付けないでください。不足点を指摘して移行を提案しますが、強制はしないでください。
• 既存の命名規則を尊重してください。たとえば、プロジェクトが --accent-500 より --color-primary を使っている場合、並行する命名体系を導入するのではなく、そのパターンを拡張してください。

次のステップ： /craft — たった今確立したスパイン（段階 1）を基に構築します。