テーマシステム¶

Phase 58（v1.41.0）は、旧来のライト／ダークのペアを、単一の data-theme ディメンション上の 6 つのクラシックテーマからなるシステムに置き換え、加えて OS に追随する auto 選択を導入しました。Phase 63（v1.63.0）は、推奨される WCAG AA プリセットを 6 つ追加し、ピッカー全体で12 テーマを扱うようになりました。

推奨プリセット（Phase 63 / v1.63.0）¶

設定 → 表示のピッカーは、推奨サブタブが先頭に来ます。

ライト： catppuccin-latte、supabase、graphite
ダーク： catppuccin-mocha、soft-pop、amethyst-haze

これらは tweakcn のプリセットから scripts/generate_preset_themes.py によって完全な 44 トークンのテーマとして生成され、計算的に強制された WCAG AA （12 テーマすべてにわたる contrast.test.ts）を備えています。クラシックな 6 つ（light、dark、ocean、forest、 high-contrast、sepia）は変更されていません。

仕組み¶

正規のカラートークンは frontend/src/styles/themes/theme-<id>.css にあり、 data-theme の値（light、dark、ocean、forest、 high-contrast、sepia）ごとに 1 ブロックです。各ファイルは 完全なセマンティックトークンセットを定義します。ライトへのフォールスルーはありません。
テーマに依存しないトークン（間隔、角丸、フォント、ブランドのメソッドパレット）とレガシーエイリアス（--bg、--surface、 --fg、--danger など）は styles/global.css :root にあります。エイリアスは正規トークンを経由して解決されるため、古いルールも自動的にアクティブなテーマに追従します。
テーマファイルは main.tsx でインポートされ、ライトが先頭に来るので、アクティブなテーマが :root に対する特異性の引き分けに勝ちます。
frontend/src/lib/themes.ts はレジストリです。THEMES、型 ThemeId / ThemeChoice、auto のマッピング用の resolveTheme(choice, prefersDark)、そしてプレビューのスウォッチです。
frontend/src/hooks/useTheme.ts は適用される data-theme 属性を所有し、選択を adaptive-learner.theme として永続化します（古い adaptive-learner-theme キーを一度だけ移行します）。
index.html には、保存されたテーマを最初のペイントの前に適用する小さなインラインスクリプトがあります（ちらつきなし）。これはフックの解決をミラーリングしています。両者を同期させておいてください。
チャート（Recharts）は CSS 変数を SVG 属性で読めないため、 lib/chartTheme.ts + useChartTheme が計算済みのトークン値を読み取り、data-theme の変更時に再読み込みします。

トークンセット（すべてのテーマが定義する）¶

背景（--bg-primary/secondary/surface/elevated/overlay）、テキスト（--fg-primary/secondary/muted/inverse）、ボーダー（--border-primary/subtle/accent）、インタラクティブ（--interactive-bg/hover/active/disabled）、アクセント（--accent、-hover、-fg、-subtle、-rgb）、ステータスのペア（--success/-bg、--error/-bg、--warning/-bg、 --info/-bg）、演習フィードバック（--exercise-correct/-wrong/-selected/-matched）、--star、チャートシリーズ（--chart-1..6）、シャドウ（--shadow-card/-elevated/-md）。

styles/themes/themes.test.ts は、あるテーマがこれらのトークンのいずれかを欠くか、余分なものを持つと失敗します。 styles/contrast.test.ts は 12 テーマすべてにわたって WCAG 2.1 AA を検査します。完全なトークンリファレンスはデザイントークン・アーキテクチャにあります。

新しいテーマを追加する¶

既存のファイルをコピーします。例： cp theme-dark.css theme-midnight.css。セレクタを [data-theme="midnight"] に変更します。すべてのトークンを保持し、値だけを変更します。ここにコンポーネントのスタイルは書きません。
lib/themes.ts に登録します。THEMES に ThemeMeta エントリ（id、英語の label、family light|dark、設定のプレビュー用の swatch）を追加し、ThemeId の union に id を加えます。
main.tsx で theme-light.css の後にインポートします（順序はライトに対する相対位置だけが重要です）。
プリペイントガードで許可します。index.html のインライン <script> 内の valid 配列に id を加えます。
i18n：backend/config/i18n/*.yaml の 8 つすべてのカタログに ui.themes.midnight を追加し、make sync-i18n を実行します。
検査：npx vitest run src/styles/themes src/styles/contrast — 完全性とコントラストのピンがグリーンのままでなければなりません（新しいテーマでコントラストが AA を満たすまで値を調整します）。

これで完了です。ThemePicker、プリペイントスクリプト、チャート、そしてすべてのコンポーネントは、いずれも正規トークンを読むので、新しいテーマを自動的に取り込みます。

規則¶

コンポーネントに色をハードコードしないこと。 styles/no-hardcoded-colors.test.ts が .tsx のスタイルについてこれを強制します（文書化された許可リストがチャートのリゾルバ、装飾的な紙吹雪、データの色をカバーします）。
すべてのテーマがすべてのトークンを定義する。 ライトからの継承によるギャップはありません。これが F1 監査のバグ（ダークモードで明るい hex を表示した未定義のトークン）でした。
テーマの切り替えは即座です。data-theme の入れ替えであり、再読み込みは決して行いません。