Style Dictionary：トークンの変換と生成

Style Dictionary（Amazonが作成）は、デザイントークンの定義をJSON形式で受け取り、CSSカスタムプロパティ、JavaScript ESモジュール、Sass変数、iOSのSwift定数、AndroidのXMLリソース、その他定義した任意の形式に出力できるビルドツールです。1つの正規ソースから、さまざまな形式に出力できます。

npm install --save-dev style-dictionary でインストールします。npx style-dictionary init を実行すると、config.json（または config.js）と tokens/ ディレクトリが作成され、プロジェクト構成が初期化されます。設定ファイルでは、Style Dictionaryがトークンファイルをどこから読み込み、出力先にどこへ書き込むかを指定します。

Style Dictionaryでは、末端ノードに value プロパティを持つ、入れ子構造のJSONを使用します。たとえば、{ "color": { "primary": { "500": { "value": "#3b82f6" } } } } のように記述します。値までのパス（color、primary、500）は、変換後にトークン名となり、通常は color-primary-500 または --color-primary-500 の形式になります。

npx style-dictionary build --config config.json を実行します（package.jsonのscriptsに設定している場合は style-dictionary build でも実行できます）。Style Dictionaryは、設定されたソースからすべてのトークンファイルを読み込み、変換を適用して、設定された出力先に結果を書き込みます。トークン形式のエラーは、ファイル名とパスを含めて報告されます。

config.json では、プラットフォームを定義します。css はカスタムプロパティを含むCSSファイルを出力し、js はJSオブジェクトを出力し、scss はSass変数を出力します。各プラットフォームでは、出力ディレクトリ、ファイル名、形式（テンプレート）、適用する変換（名前と値を処理する関数）を指定します。

Style Dictionaryには、組み込みのトランスフォームが用意されています。name/cti/kebab は入れ子になったパスを color-primary-500 に変換し、name/cti/camel は colorPrimary500 を生成し、size/rem はピクセル値をremに変換し、color/hex は色を16進数形式に正規化します。トランスフォームは組み合わせて使用でき、指定した順序で適用されます。

StyleDictionary.registerTransform() を使って、カスタムトランスフォームを登録できます。たとえば、ピクセル値をiOSのポイントに変換するトランスフォームや、すべてのトークン名に企業固有のプレフィックスを追加するトランスフォームを作成できます。カスタムトランスフォームを使えば、出力前の値の処理方法を完全に制御できます。

カスタムフォーマットでは、出力ファイルのテンプレートを定義します。StyleDictionary.registerFormat() は変換済みトークンの辞書を受け取り、文字列（ファイルの内容）を返します。トークンをTypeScriptの型、Reactのテーマオブジェクト、Tailwindの設定拡張、または利用する技術スタックに必要なその他の形式として出力できます。

ビルド後、グローバルスタイルシートでCSS出力をインポートします。@import './tokens/tokens.css' のように記述します。コンポーネントやTailwindの設定では、JS出力を import tokens from './tokens/tokens.js' のようにインポートします。CSSを使うと実行時のテーマ切り替えに利用できるカスタムプロパティが得られ、JSを使うとTailwindやJavaScriptのロジックで利用できる型付き定数が得られます。

Style Dictionaryでは、中かっこを使ってトークンを参照できます。{ "value": "{color.primary.500}" } のように記述します。これにより、セマンティックトークンがプリミティブトークンを参照する、セマンティックトークンのエイリアスを作成できます。ビルド時にStyle Dictionaryが参照を解決し、最終的な解決済みの値を出力します（フォーマットによってはCSS変数の参照を出力します）。

アプリケーションのビルド前にトークンが必ず再生成されるよう、Style Dictionaryを prebuild npmスクリプトとして実行します。package.json に "prebuild": "style-dictionary build" を追加します。これにより、トークンJSONファイルを変更すると、その内容がReactのビルドで処理される前にCSSとJSの出力へ反映されます。

Style Dictionaryにおけるトランスフォームの目的は何ですか？

Style Dictionaryは、トークンのJSONをCSS変数、JSモジュール、Sass、iOS、Androidなど、任意の出力形式に変換します。トークンJSONでは、末端ノードに value を持つ入れ子オブジェクトを使用します。トランスフォームは名前と値（camelCase、pxからremなど）を処理し、フォーマットは出力テンプレートを定義します。トークン参照（{color.primary.500}）によって、セマンティックなエイリアスを作成できます。prebuild スクリプトで自動化すれば、Reactのビルド前にトークンを常に最新の状態に保てます。