存続するトークン

ほとんどのデザイントークンシステムは2年以内に廃止されます。その理由は、その時点でのビジュアル値をエンコードしているのであって、その背後にあるセマンティック意図をエンコードしていないからです。blue-500という名前のトークンは永遠にその青い値に束縛されます。一方、accent-primaryという名前のトークンは色の変更を超えて存続します。なぜなら、次のデザイナーが新しいシステムの青相当の値にそれをマッピングするからです。

トークンシステムが存続するものと消滅するものを分ける単一のルール：トークンに外観ではなく目的で名前を付けます。accent-primary、surface-base、text-secondary、danger-bg。絶対に blue-500、gray-900、red-light ではありません。セマンティック名は契約です。値は実装の詳細です。

レイヤー1：プリミティブ。生のカラー値、スペーシング値、タイポグラフィ値。blue-50、blue-100、blue-200...、blue-900。space-1、space-2...、space-12。これらは基礎となるスケールとして存在し、ほとんど変わりません。

レイヤー2：セマンティック。プリミティブにマッピングされた目的を明示したトークン。accent-primaryはblue-500にマッピング、accent-hoverはblue-600、surface-baseはgray-50、text-primaryはgray-900。コンポーネントはこれらを参照し、プリミティブに直接アクセスしない。

レイヤー3：コンポーネントスコープ。セマンティックトークンにマッピングされたコンポーネント単位のトークン。button-primary-bgはaccent-primaryにマッピング、card-borderはborder-subtle、nav-active-bgはaccent-emphasis。コンポーネントはこれらを消費する。

ブランドリフレッシュが発生したとき、プリミティブスケールを変更し、セマンティック・トゥ・プリミティブのマッピングを必要に応じて変更する。コンポーネントスコープのトークンは変更されずに流れる。リデザインは数か月ではなく数日でシップできる。

エンコード：色、スペーシング、タイポグラフィ（フォントファミリー、サイズ、ウェイト、行の高さ）、border-radius、シャドウ、モーションデュレーションとイージング、ブレークポイント幅。

エンコードしない：レイアウト固有の値（記事テンプレート上の1280のmax-width）、1回限りのポジショニングオフセット、単一のコンポーネントに固有なアニメーションの振り付け。これらはインラインに属する。エンコードするとシステムが自分自身と闘うことになる。

リトマステスト：別のコンポーネントがこの同じ値を妥当に使用する可能性があるか。そうなら、エンコードする。そうでなければ、ハードコードする。

トークン境界でのCSSカスタムプロパティ。:rootでプリミティブとセマンティックを定義し、[data-theme="dark"]でオーバーライドする。コンポーネントはセマンティックトークンを参照し、プリミティブには決してアクセスしない。

同じソースから生成されたTypeScriptファイル経由でJSがアクセス可能なトークン。Style Dictionary、Theo、または小規模なカスタムジェネレータのようなツールが、単一のJSONまたはYAMLソースからCSSカスタムプロパティとTSエクスポートの両方を生成する。単一ソースは、JS アニメーションとstyled componentsがスタイルシートと同期を保つことを意味する。

システムを単一ページ（Storybook ページまたはサイト自体の /design ページ）に文書化し、将来の貢献者がそれを見つけられるようにしてください。発見可能性の低いトークンシステムは、それが存在することを知らない人々によって数ヶ月以内に無視されます。