StyleXでデザイントークンを設計するStyleXでデザイントークンを設計する

なぜトークン層を分けるのか

UI実装で色や余白を都度指定すると、レビュー時に「このグレーは前の画面と同じ？」という議論が必ず起きます。トークン層を先に定義しておけば、変更は一箇所で済み、コンポーネントは意味ベースの名前だけを参照できます。

StyleX では stylex.defineVars でセマンティックトークンを宣言し、コンポーネント側は colors.fg のように利用します。生値をコンポーネントに書かないルールを徹底するのが要点です。

命名と粒度

トークン名は見た目ではなく役割で命名します。gray-700 ではなく fgMuted のように、文脈に依存しないセマンティック名を使います。スケール系（spacing, fontSize）は段階数を絞り、選択コストを下げます。

export const spacing = stylex.defineVars({
  xs: "0.5rem",
  sm: "0.75rem",
  md: "1rem",
  lg: "1.5rem",
  xl: "2.5rem",
});

コンポーネントでの使い方

stylex.create でスタイル定義し、stylex.props で適用するのが基本パターンです。疑似クラスやメディアクエリも同じオブジェクト内に書けるため、CSSファイルを分けずに状態管理できます。

運用のコツ

トークン追加は「2回以上使う見込みがあるとき」に限定すると、スケールが肥大化しません。逆に、一度だけ使う装飾は局所スタイルでよい場合もあります。境界を曖昧にしないことが、長期保守の鍵になります。