コンテンツにスキップ

デザイントークン・アーキテクチャ

アプリのすべての視覚的プロパティは、デザイントークン （CSS 変数）を介して制御されます。アプリの配色を変えたい、または 新しいテーマを作りたい場合は、単一の theme-*.css ファイルを 編集するだけで、コンポーネントには一切手を加えません。この規則は 単なる慣例ではなく、テストによって強制されています。完全な トークンリファレンスは docs/DESIGN-TOKENS.md にあります。

トークンのレイヤー

  1. テーマごとのトークン — 44 個の正規トークンのセットで、 テーマごとに 1 回ずつ frontend/src/styles/themes/theme-<id>.css に定義されます （背景、テキスト、ボーダー、インタラクティブ、アクセント、 ステータス、演習フィードバック、スター、チャート、シャドウ）。 [data-theme] を切り替えるとすべてが切り替わります。 すべてのテーマがまったく同じセットを定義しなければなりません （themes.test.ts でピン留め）。
  2. テーマ非依存のトークン — 構造上どのテーマでも同じ値 （例：ブランドパレット、シンタックスカラー、レイアウトの 間隔）。これらは global.css :root に置かれます。
  3. レガシーエイリアス — --surface、--danger のような古い 名前で、正規トークンを経由して解決されます。

規則（要点）

  • 消費側の宣言に生の色リテラル（#hex、rgb()、hsl()）を 書かないこと。リテラルは --token: 定義の値としてのみ許可 されます。コンポーネントや CSS ルールではトークンを参照します： color: var(--fg-primary)。
  • 固定パレットの Tailwind ユーティリティ（bg-blue-500）を 使わないこと。トークンに基づくユーティリティ （bg-accent → var(--accent)）か、トークン上の任意値を 使います。
  • 色値を含むインラインスタイルを使わないこと。
  • シャドウ、角丸、間隔もトークンです （--shadow-elevated、--radius-md、--space-4）。

テーマを作成または調整する

  1. 既存の theme-<id>.css をテンプレートとしてコピーします。
  2. 44 個すべての正規トークンを設定します（同一性は必須です）。
  3. WCAG AA のコントラストに注意します — contrast.test.ts が すべてのテーマを計算的に検査します。
  4. テーマを登録します。設定 → 表示 のピッカーがそれを取り込みます。

新しい機能に新しい色が必要な場合は、トークンを追加し、 リテラルは書きません。テーマごとに変わる場合はすべての theme-*.css に追加し、どこでも同じ場合は global.css :root に 追加します。

強制

make test では 3 つのガードが実行されます （no-hardcoded-colors.test.ts）。.tsx 内の色リテラル （縮小のみが許される許可リスト経由）、非テーマ CSS 内の色リテラル、 固定パレットの Tailwind ユーティリティ（ゼロでなければなりません）。 これに加えて、themes.test.ts（トークンの同一性）と contrast.test.ts（すべてのテーマにわたる AA）があります。

関連ページ