dark-mode-converter

ダークモード変換

デザインの成熟したプロダクトのようにダークモードを構築します。色を反転しただけのライトテーマではなく、独自のロジックを持つ第2のテーマとして設計します。反転ではうまくいきません。ダーク UI では、影ではなく明るいサーフェスで高さを表現し、彩度の高い色は暗い背景でちらつき、純粋な黒と純粋な白の組み合わせはコントラストではなくまぶしさになるからです。

ワークフロー

1. まずトークン化します。 コードベース内のすべての色を洗い出します。コンポーネントに色がハードコードされている場合は、変換する前にセマンティックトークンへ置き換えます。bg.base、surface、surface.raised、text.primary、text.muted、border、accent、状態などです。生の HEX 値の置き換えに基づくダークモードでは、次の機能追加で破綻します。（トークンがすでにある場合は、同じ作業で残っている色も監査します。）
2. ダーク UI の特性に沿って、役割ごとにダークパレットを設計します。ベースはダークグレーにし、#000 は使いません（#0f1115～#1a1d23 あたり、またはブランドの色相に寄せた色）。サーフェスは高くなるほど明るくします（ベース → カード → ポップオーバーの順に、各段階で明るくします）。テキストはオフホワイトにし、#fff は使いません（#e8eaed 程度、白の約 87%）。ミュート状態にも段階を設けます。アクセントは彩度を下げて1～2段階明るくし、暗い背景でちらつかないようにします。ボーダーは不透明度の低い白にし、影はより暗く、輪郭を狭くするか、サーフェスの明るさだけで表現します。テキストとサーフェスのすべての組み合わせが、WCAG AA の最低基準を満たすか確認します。
3. スタックに合わせて仕組みを組み込みます。Tailwind では class 戦略の dark:（v4 では @variant dark）、またはカスタムプロパティを再定義する [data-theme="dark"] ブロックを使います。ライト／ダーク／システムの3状態を切り替えるトグル、localStorage への保存、prefers-color-scheme によるデフォルト設定、そして最初の描画前にクラスを設定する <head> 内のフラッシュ防止インラインスクリプトを追加します。
4. 難所に対処します。単純な変換ではうまくいかない箇所です。白い背景が埋め込まれた画像やイラストには、別バージョンを使う、背後に控えめなサーフェスを追加する、または許容できる場合はロゴに CSS フィルターを適用します。チャートやデータ可視化のパレットには、専用のダーク用系列色が必要です。フォームコントロールには color-scheme: dark を設定し、ネイティブ入力、スクロールバー、自動入力の見た目を合わせます。埋め込みのサードパーティウィジェット（地図テーマ、iframe）にも対応します。テーマを継承しないメールテンプレートや Open Graph 画像も考慮します。ダーク背景で見えなくなるフォーカスリングにも対処します。
5. 監査します。 主要なルートを両方のモードでスクリーンショットを確認しながらチェックします（または、ユーザーが確認できるようにルートを一覧にします）。明るいまま取り残されたサーフェス、影で区切っていた箇所に生じた二重ボーダー、読みにくいミュートテキスト、存在感が失われたアクセントボタンを探します。dark-mode-report.md を出力します。トークンマップ（役割ごとのライト → ダーク）、変更したファイル、コントラスト表、デザイン担当者による確認が必要な残項目を記載します。

ルール

• セマンティックトークンを使うか、何もしないかです。90個のコンポーネントに dark:bg-gray-800 を散りばめるのは、テーマではなく保守の負債です。対応関係を一元化します。
• ベースに純粋な黒を使わず、テキストに純粋な白を使いません。どちらもデフォルトではなく、ここぞという場面に限って使います。
• 高さの表現は反転します。ライトモードでは影で「高い」ことを示し、ダークモードではより明るいサーフェスで示します。色だけでなくロジックも変換します。
• アクセントは調整しますが、ブランドは変えません。暗い背景になじむように明度と彩度を調整しつつ、ブランドの色相は維持します。ブランドカラーと暗い背景のコントラストを確認し、実際に問題がある場合は色相を黙って変えるのではなく、ユーザーに伝えます。
• 今後、両方のモードを第一級のものとして扱います。すべてのレポートに、新しいコンポーネントでは両方のテーマのトークンを定義しなければレビューに通らないというルールを記載します。
• システム設定の変更をリアルタイムでテストします。system 設定は、再読み込みしなくても OS の変更に反応する必要があります。

クイックコマンド

• 「このプロジェクトをダークモードに変換して」 -- ワークフロー全体
• 「まず色をトークン化して」 -- ステップ1のみ
• 「ダークパレットだけ設計して」 -- 既存のトークンを使ったステップ2
• 「ダークモードを監査して」 -- 既存の実装に対するステップ5