CSS変数によるマルチブランドテーマの実装

マルチブランドのテーマ設定では、1組のコンポーネントエイリアストークンを、ブランドごとに異なるグローバルトークン値へマッピングします。コンポーネントはエイリアストークンを参照し、ブランドテーマファイルがエイリアスをブランド固有のグローバル値に再マッピングします。

:rootでグローバルトークンを定義します。すべての生のカラー値、スペーシング値、タイポグラフィ値をここに定義します。これがデフォルトブランドです。コンポーネントからグローバルを直接参照することはありません。必ずエイリアス経由で参照します。

エイリアストークンはvar()を使ってグローバルを参照します：--color-action: var(--color-brand-primary)。コンポーネントでは--color-actionを使います。--color-brand-primaryの意味を切り替えるだけで、システム全体が変わります。

htmlまたはコンテナ要素にクラスを付けてブランドテーマを適用します。各テーマクラスは、そのブランドのスコープにおけるグローバルトークンを上書きします。コンテナ内のコンポーネントは、ブランドの値を自動的に継承します。

ダークモードはテーマのバリアントです。カラー トークンを上書きするクラスまたはメディアクエリとして実装します。OSのデフォルトにはprefers-color-schemeを、ユーザーによる上書きには.darkクラスを使います。どちらも同じエイリアストークンを変更します。

CSSカスタムプロパティはカスケードし、継承されます。コンテナ要素に適用したテーマは、すべての子孫要素に影響します。ネストしたテーマはコンテナレベルで外側のテーマを上書きするため、ページ内にウィジェットを配置するテーマ設定などに便利です。

エイリアストークンが常に定義されるようにします。テーマクラスがない場合、エイリアスはデフォルトに適切にフォールバックする必要があります。CSSのvar()フォールバック構文であるvar(--color-action, #3b82f6)を使い、見えないテキストや背景の欠落を防ぎます。

Style Dictionaryでは、1つのトークンJSONからテーマごとに別のCSSファイルを出力できます。ビルドステップでtheme-brand-a.cssとtheme-brand-b.cssを生成します。実行時に適切なファイルを読み込むか、ブランドごとに別のバンドルへコンパイルします。

各テーマで各コンポーネントを描画するビジュアルリグレッションテストを作成します。PercyとChromaticでは、テーマのバリアントごとにスクリーンショットを取得できます。自動ビジュアルテストにより、グローバルトークンの値が予期せず変わったときのリグレッションを検出できます。

JavaScriptでテーマクラスを切り替えます：document.documentElement.classList.replace("theme-a", "theme-b")。CSS変数はコンポーネントを再描画せずに即座に更新されます。Reactの再レンダリングや、静的な値のスタイル再計算は必要ありません。

CSS変数はペイント時に解決されるため、ルート変数を変更すると、それを使うすべての要素で再ペイントが発生します。グローバル変数の変更はアニメーションループではなく、テーマの切り替えなどのユーザー操作に限定します。アニメーションによるテーマ効果には、個別のプロパティトランジションを使います。

CSSカスタムプロパティのテーマを使うと、コンポーネントのCSSを変更せずにブランドを切り替えられるのはなぜですか？

マルチブランドのテーマ設定では、グローバルな生のトークン値と、セマンティックなエイリアストークンを分離します。テーマクラスはコンテナのスコープでグローバルを上書きします。エイリアスを参照するコンポーネントは、現在有効なブランドテーマを自動的に反映するため、コンポーネントコードを変更せずに実行時の切り替えが可能です。