マルチテーマ・マルチブランドのトークン設計

テーマは、同じブランドのカラーモードを変更するものです（同じ製品のライト版とダーク版など）。ブランドは異なるビジュアルアイデンティティを指します。同じデザインシステムのコンポーネントを、異なる色、タイポグラフィ、間隔で描画し、異なる製品や顧客に対応します。どちらも同じトークンアーキテクチャを使用しますが、適用する抽象化レベルが異なります。

プリミティブトークンは、システムで利用できる生の値をすべて含むパレットです。color-blue-50 から color-blue-900 までのすべての色段階、すべての間隔単位、すべてのフォントサイズなどが含まれます。プリミティブトークンをコンポーネントで直接使うことはありません。プリミティブトークンはセマンティックトークンからのみ参照します。パレットは一度定義し、すべてのテーマとブランドで共有します。

セマンティックトークンは意図を表します。たとえば、color-background-page、color-text-primary、color-action-primary です。各セマンティックトークンは、現在のテーマに適したプリミティブトークンの値を参照します。コンポーネントはセマンティックトークンだけを使って構築します。テーマの切り替えはこの層で行われます。

ライトテーマでは、color-background-page が color-white を参照し、color-text-primary が color-gray-900 を参照し、color-action-primary が color-blue-500 を参照します。これらのマッピングはテーマ固有のトークンファイルで定義し、ライトコンテキスト向けにセマンティック層を上書きします。

ダークテーマでは、color-background-page が color-gray-950 を参照し、color-text-primary が color-gray-50 を参照し、color-action-primary が color-blue-400 を参照します（暗い背景でコントラストを確保するため、やや明るい色を使います）。変更するのはセマンティックマッピングだけで、プリミティブパレットとすべてのコンポーネントは変更されません。

ブランドAはプライマリカラーに青を使い、color-action-primary: {color-blue-500} とします。ブランドBは緑を使い、color-action-primary: {color-green-500} とします。ボタンコンポーネントは var(--color-action-primary) を読み取るだけで、どのブランドが有効かをまったく意識しません。ブランドの上書きで変更するのはセマンティックトークンのマッピングだけであり、コンポーネントコードは変更しません。

CSSカスタムプロパティを使えば、実行時のテーマ切り替えは簡単です。現在のテーマをデータ属性に保存します。document.documentElement.setAttribute('data-theme', 'dark') のように記述します。CSSルールで [data-theme="dark"] の下にセマンティックトークンを上書きします。ブラウザはすべての var() 参照を新しい値に即座に解決するため、JavaScriptによる再レンダリングは必要ありません。

異なるブランドを個別のデプロイとして提供する場合は、ビルド時のテーマ設定を使います。Style Dictionaryでブランドごとに個別のCSSトークンファイルを生成し、アプリケーションの起動時に正しいブランドのCSSを読み込みます。この方法は、ブランドがユーザーの操作時ではなく、デプロイ時に決まる場合（異なるドメイン、サブドメイン、ホワイトラベルのインスタンスなど）に適しています。

複数ブランド・複数テーマのシステムには、ブランドAのライト、ブランドAのダーク、ブランドBのライト、ブランドBのダークという2次元の組み合わせが必要です。CSSカスタムプロパティなら、入れ子になったセレクターを使ってこの構成を簡潔に扱えます。[data-brand="a"][data-theme="dark"] で、その組み合わせに対応するセマンティックトークンを上書きします。4つの組み合わせでも、4つのコードベースではなく4つのCSSブロックで済みます。

デザインシステムが進化すると、トークンの追加、名前変更、削除が発生します。トークンはコードと同じリポジトリでバージョン管理します。トークンを非推奨にする場合は、1回のリリースサイクルの間、古い名前を新しい名前を指すエイリアスとして残し、非推奨であることをコメントに記載して、利用側のコードを更新します。構造化された変更履歴を通じて、デザインとエンジニアリングの間でトークンの変更を調整します。

ガバナンスによって、誰がトークンを追加・変更できるか、またどのようなレビュープロセスが必要かを定めます。プリミティブトークンにはデザインチームの承認が必要です。セマンティックトークンには、デザインとエンジニアリングの両方によるレビューが必要です。コンポーネントトークンは、コンポーネントのオーナーが管理できます。このガバナンスがなければ重複したトークンが生まれ、「信頼できる唯一の情報源」という保証が崩れます。

テーマはブランド内のカラーモードを切り替えます。一方、ブランドは異なるビジュアルアイデンティティです。プリミティブトークンは元となるパレットであり、セマンティックトークンは意味を表現してテーマ設定を可能にします。コンポーネントはセマンティックトークンだけを使用します。ダークモードやブランド用のオーバーライドでは、セマンティックトークンのマッピングだけが変わり、コンポーネントは変わりません。実行時のテーマ設定では、CSSカスタムプロパティと[data-theme]セレクターを使用します。ビルド時のブランディングでは、ブランドごとに個別のCSSを生成します。トークンのガバナンスとバージョニングにより、システムの進化に合わせて一貫性を維持できます。