Tailwind のトークン、CSS 変数、CSS-in-JS

Style DictionaryのCSSプラットフォーム向け出力では、CSSカスタムプロパティのファイルが生成されます。--color-primary-500: #3b82f6; --spacing-4: 16px;などの変数が:rootで定義され、グローバルに利用できるようになります。これは、アプリケーション内であらゆるトークンを利用するための基盤です。

生成されたCSSトークンファイルを、グローバルスタイルシートまたはルートレイアウトコンポーネントでインポートします。@import './tokens/tokens.css'。Next.jsでは、app/layout.tsxまたはstyles/globals.cssでインポートします。インポートすると、アプリケーション内のすべてのCSSルールとコンポーネントからカスタムプロパティを参照できるようになります。

コンポーネントのスタイルシートまたはCSS ModulesでCSS変数を参照します。background-color: var(--color-primary-500);やpadding: var(--spacing-4);のように記述します。JSONソースのトークン値を変更してStyle Dictionaryを再ビルドすると、CSSファイルが更新され、その変数を使用するすべてのコンポーネントに新しい値が自動的に反映されます。

CSSカスタムプロパティを使うと、実行時にテーマを切り替えられます。ダークモードでは、テーマセレクターの下でトークンの値を上書きします。[data-theme="dark"] { --color-background: #1a1a2a; --color-text: #f0f0f0; }。document.documentElement.setAttribute('data-theme', 'dark')を設定すると、再読み込みや再ビルドを行わずに、すべてのトークン値が即座に切り替わります。

tailwind.config.jsでTailwindのテーマを拡張し、トークンの値を使用します。theme: { extend: { colors: { primary: { 500: tokenOutput.color.primary[500] } } } }。Style DictionaryのJS出力をTailwind設定にインポートすることで、Tailwindクラス（bg-primary-500）が常に信頼できるトークン値を使用するようにします。

Tailwindで実行時に切り替え可能なテーマを使用するには、色がCSS変数を参照するように設定します。'primary': 'rgb(var(--color-primary-rgb) / <alpha-value>)'。この設定では、CSS変数にrgb()のラッパーを付けず、RGBの各成分を保存する必要があります（--color-primary-rgb: 59 130 246）。これにより、Tailwindが不透明度ユーティリティを自動的に処理します。

CSS-in-JSライブラリでは、JavaScriptのテーマオブジェクトを使用します。Style DictionaryのJS出力をテーマプロバイダーの値として渡します。<ThemeProvider theme={tokens}>。コンポーネントはconst theme = useTheme()とtheme.color.primary[500]を使ってトークンにアクセスします。Style Dictionaryが型付きトークンオブジェクトを生成し、テーマプロバイダーがそれを配布します。

stylelint-no-hardcoded-colorsプラグインとカスタムESLintルールを使うと、スタイルシートやコンポーネントファイルにハードコードされた16進数値が現れないように強制できます。開発者がcolor: var(--color-primary-500)ではなくcolor: #3b82f6と記述すると、リンターが警告します。これにより、トークンシステムが唯一の色の供給元になります。

実行時にトークン名からTailwindクラス名を動的に組み立てる場合、ソース内に静的な文字列として現れないため、Tailwindのpurgeによってクラスが削除されることがあります。tailwind.config.jsのsafelistに動的なクラスのパターンを追加します。safelist: [{ pattern: /bg-primary-/ }]。

Figma Tokensプラグインは、Figmaのトークン値をStyle DictionaryのJSON形式に直接エクスポートします。ワークフローは次のとおりです。デザイナーがFigma Variablesで色を更新し、プラグイン経由でエクスポートし、更新されたJSONをコミットすると、prebuildスクリプトがStyle Dictionaryを実行します。その後、更新されたCSSとJSの出力がReactアプリで使われます。これにより、デザインとコードが同期された状態に保たれます。

CSSカスタムプロパティは、定義された要素とその子孫要素のスコープに属します。これにより、コンポーネント単位でテーマを上書きできます。たとえば、カードコンポーネントのルート要素で--color-background: var(--color-surface-elevated)を設定すると、すべての子孫要素がプロップのバケツリレーなしで、浮き上がったサーフェスの色を使用します。

トークンにおいて、静的なTailwindの値よりCSSカスタムプロパティ（変数）を使う主な利点は何ですか

Style Dictionaryは、グローバルインポート用のCSSカスタムプロパティと、TailwindやCSS-in-JSとの統合用のJSオブジェクトを出力します。CSS変数を[data-theme]で上書きすると、実行時にテーマを切り替えられます。TailwindはJS出力のトークン値で設定を拡張します。不透明度に対応したテーマでは、TailwindがRGBのCSS変数を参照するように設定します。Lintルールによってトークン以外の色の使用を強制的に排除し、コードベースからハードコードされた値をなくせます。