design-foundation

デザイン基盤

このコードベース向けに、実際に使えるトークンファイルを作成してください。トークンについての文書ではありません。トークンとは、名前を付けたデザイン上の決定事項（--color-text-primary、--space-4 など）です。これらを一元管理することで、以降のあらゆるデザインスキル（レイアウト、タイポグラフィ、色、コンポーネント）に一貫性が生まれます。基本原則は、新しく作る前に抽出することです。既存のコードベースでは、トークンシステムによって既存の優れた要素を体系化し、再設計ではなく名前の変更によって移行できるようにします。

使用するタイミング／引き継ぎ先

• トークンを一から作成する場合、または既存のコードベースから抽出する場合に使用します。
• ユーザーが特に色（パレット、コントラスト、ダークモードの奥行き）に困っている場合 → トークンの骨格ができた後に skills/frontend-design/color-system を使用します。
• 特にタイポグラフィ（スケール、フォント、読みやすさ）に困っている場合 → skills/frontend-design/typography-system を使用します。
• トークンを使ったコンポーネントの構築を希望する場合 → 次に skills/frontend-design/component-architecture を使用します。
• 「何から始めればいいか」という幅広い相談の場合 → skills/frontend-design/frontend-orchestrator を使用します。

ステップ 1 — コードベースを調査する

何かを尋ねる前に、根拠を集めます。

1. 現在のスタイル設定のエントリポイントを見つけます。 tailwind.config.{js,ts,cjs,mjs}、**/globals.css、**/index.css、**/app.css、**/*theme*、**/tokens* を Glob で検索し、内容を読みます。
2. スタックを特定します。 Tailwind v4（CSS 内の @import "tailwindcss" と @theme）、v3（theme オブジェクトを含む設定ファイル）、CSS Modules／styled-components／vanilla CSS のどれかを確認します。package.json で tailwindcss のバージョンも確認します。
3. ばらつきを測定します。 ソースコードで #[0-9a-fA-F]{3,8}\b、rgba?\(、hsla?\( を Grep し、異なる色の数を数えます。\d+px と Tailwind の任意値 \[(\d+px|#) を Grep し、規則外の余白・サイズ値の数を数えます。これらの数を根拠に含めます。
4. 実質的なシステムを特定します。 見つかった値を使用頻度順に並べます。最も多く使われているフォントサイズ、余白の段階、色がトークン候補です。
5. ダークモードを確認します（dark:、prefers-color-scheme）。これにより、セマンティックレイヤーを今すぐ 2 つのモードで提供する必要があるか判断します。

ステップ 2 — 要件の確認

不足している項目だけを、一度にまとめて尋ねます。ブランドカラー（または「選んでください」）、プロダクトの印象（データを密に扱うツールか、ゆとりのあるマーケティング／コンシューマー向けか）、ダークモードを今導入するか後にするかです。それ以外は推測します。作業を停滞させないでください。 コードベースから答えが明らかな場合（明確なブランドブルー、既存の dark: の使用など）は、前提を示して作業を進めます。

ステップ 3 — トークンシステムを構築する

最低 2 層、コンポーネントライブラリがある場合は 3 層にします。

1. グローバルトークン — 生の値：ニュートラルカラーの段階（50〜950。純粋なグレーではなく、ブランドの色相を帯びた色）、ブランドカラーの段階、セマンティックなステータスカラー（成功／警告／エラー／情報）、4px を基準にしたスペーシングスケール（4、8、12、16、24、32、48、64）、フォントサイズ、角丸、シャドウ、z-index の段階、トランジション時間。
2. セマンティックトークン — グローバルトークンを参照する意味ベースの値：bg-primary/secondary、text-primary/secondary/tertiary/inverse、border-primary、interactive-primary/hover/active/disabled。ダークモードで切り替わるのはこのレイヤーです。 コンポーネントが使用するのはセマンティックトークンのみです。
3. コンポーネントトークン — コンポーネントライブラリが存在する、または次に導入する場合のみ作成します（--button-primary-bg: var(--color-interactive-primary)）。

判断ルール：

• Tailwind v4 → メインの CSS ファイル内の @theme で、トークンを CSS 変数として定義します。Tailwind v3 → 設定ファイルの theme.extend を使い、設定ファイルから参照する CSS 変数としてセマンティックレイヤーを定義します。Tailwind なし → :root（および .dark またはメディアクエリのブロック）にプレーンな CSS カスタムプロパティを定義します。
• 抽出ルール： 既存の値が集中している場合（15px、16px、17px など）、最も使用頻度の高い値に最も近いスケール値にまとめます。まとめた項目はすべて移行マップに記載します。
• 命名： kebab-case とし、カテゴリを先頭に置きます（--color-text-primary、--space-4、--radius-md）。Tailwind がある場合は Tailwind の名前に合わせ、ユーティリティを引き続き使えるようにします。

標準的な構成（CSS 変数。検出されたスタックに合わせて調整してください）

:root {
  /* global */
  --gray-50: #F8FAFC;  --gray-500: #64748B;  --gray-900: #0F172A; /* full 50–950 ramp, brand-tinted */
  --brand-500: #3B82F6; --brand-600: #2563EB; /* full ramp */
  --space-1: 0.25rem; --space-2: 0.5rem; --space-4: 1rem; --space-8: 2rem;
  --radius-md: 0.375rem; --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.10);

  /* semantic — the only layer components touch */
  --color-bg-primary: var(--gray-50);
  --color-text-primary: var(--gray-900);
  --color-text-secondary: var(--gray-600);
  --color-border-primary: var(--gray-200);
  --color-interactive-primary: var(--brand-600);
  --color-interactive-hover: var(--brand-700);
}
.dark {
  --color-bg-primary: var(--gray-950);   /* dark gray, never #000 */
  --color-text-primary: var(--gray-50);
  --color-text-secondary: var(--gray-300);
  --color-border-primary: var(--gray-700);
}

3 層構成の完全な分類、Tailwind v3/v4 の設定、バリアント／レスポンシブトークンのパターンについては、完全なファイルを作成する際に references/token-architecture.md を参照してください。

ステップ 4 — ファイルを作成し、問題の大きい箇所を移行する

1. トークンを検出されたエントリーポイントに記述します（既存のシステムの隣に別のシステムを作らず、既存のものを拡張してください）。
2. 最も利用頻度の高いファイルのうち 1～3 個を移行します（grep の結果、最もばらつきが大きかったもの）。生の値をトークンに置き換え、移行例として示してください。
3. 残りの移行マップを作成します。

必須の出力形式

コードと、次の概要を提出してください。

## Tokens file
[path written, e.g. src/app/globals.css or tailwind.config.ts — full contents]

## Decisions
| Decision | Choice | Why |
| Stack wiring | Tailwind v4 @theme / v3 config / CSS vars | [detected how] |
| Neutral tint | [hue] | matches brand [color] |
| Spacing base | 4px | [most existing values already multiples / default] |
| Dark mode | now via .dark class / deferred | [user answer or inference] |

## Migration map (worst drift first)
| Found in code | Count | Replace with |
| #3c82f7, #3B82F6, #3a80f0 | 23 | var(--color-interactive-primary) |
| padding: 13px / p-[13px] | 9 | var(--space-3) (12px) |
| ... |

## Migrated now
[files actually edited as demonstration]

## Next step
[Which skill consumes this — typically skills/frontend-design/typography-system or color-system]

品質基準（提出前に確認）

• ダークモードが実装されている場合、意味上のテキスト／背景の組み合わせが両方のモードで WCAG AA（通常のテキストは 4.5:1、大きなテキストは 3:1）を満たしている
• 余白スケールは、単一の基準に基づく、ほぼ幾何級数的な進行になっており、孤立した段階がない
• ニュートラルカラーにはブランドの色味が付いている（彩度が 0 ではない）。#808080 や純粋な #000 は使用しない
• コンポーネント／サンプルはセマンティックトークンのみを参照し、グローバルトークンを直接参照していない
• トークン名が既存の名前と衝突せず、Tailwind のユーティリティが引き続き解決される
• 移行マップがステップ 1 で見つかったすべての値のまとまりを網羅し、それぞれがちょうど 1 つのトークンに対応している
• 2 つ目の並行したトークンシステムを導入していない

統合

• 入力：skills/frontend-design/frontend-orchestrator の成熟度診断とばらつきの件数（実行された場合）。
• 出力：次の要素で使用するトークンファイル。skills/frontend-design/typography-system（タイポグラフィトークンを拡張）、skills/frontend-design/color-system（カラースケールとダークモードを拡張）、skills/frontend-design/layout-system（余白とブレークポイント）、skills/frontend-design/visual-hierarchy-refactoring（画面をリファクタリングしてトークンを適用）、skills/frontend-design/component-architecture（コンポーネントレイヤー）。

参考資料

• references/token-architecture.md — 完全な一覧を含む 3 層構成のトークン分類、Tailwind v3 と v4 の設定、ダークモード、コンポーネントバリアント、レスポンシブトークンのパターンを説明しています。完全なトークンファイルを作成する場合や、使い慣れていないスタックを設定する場合に参照してください。