セマンティックトークンとプリミティブトークン
セマンティックトークンとは、保持する値ではなく果たす役割にちなんで名付けられたデザイントークンです。--color-red-600 ではなく --color-text-danger のように命名し、通常はプリミティブトークンを参照するため、参照側の名前を変えずに元の値だけを差し替えられます。
二つの層
成熟したトークン体系のほとんどには、少なくとも二つの階層があります。
プリミティブトークン（raw、グローバル、コアとも呼ばれます）は実際の値を保持し、見た目どおりの名前が付きます。
--red-600: #DC2626;
--blue-500: #2563EB;
--space-4: 16px;セマンティックトークンは、それらの値をどこで使うかという決定を保持し、役割で名付けられます。
--color-text-danger: var(--red-600);
--color-action-primary: var(--blue-500);
--space-card-padding: var(--space-4);コンポーネントはセマンティック層を参照します。プリミティブを直接参照してよいものは、ほとんどありません。
間接参照が割に合う理由
リブランドが書き直しでなくなります。 --color-action-primary の指し先を変えれば、すべてのボタンが追随します。もしコンポーネントが --blue-500 を参照していたら、一つひとつ直すことになり、しかもアクションとは無関係な理由で青を使っていた箇所は壊れます。
テーマが成立します。 ダークモードとは、同じセマンティック名が別のプリミティブを指すことです。セマンティック層がなければ、指し替える対象そのものがありません。
コードが意味を語ります。 --color-text-danger は、なぜその値がそこにあるのかを読む人に伝えます。--red-600 は何も伝えません。これは、変更して安全かどうかを誰かが判断しなければならない場面でとりわけ効いてきます。
よくある失敗
チームがセマンティック層を飛ばすのは、初日にはそれが形式主義に見えるからです。色は十一しかなく、誰もが用途を覚えています。
代償は最初のリブランド、最初のダークモード、あるいは最初のアクセシビリティ対応で表面化します。そのころにはプリミティブが数百か所から参照されています。あとからセマンティック層を入れる作業は機械的ですが骨が折れ、誰も計画に入れません。
三つ目の階層
規模の大きい体系では、コンポーネント単位のトークンを足します。--button-primary-background が --color-action-primary を指し、それが --blue-500 を指す、という形です。
コンポーネントが本当に分岐する必要があるときには役立ち、そうでないときは間接参照のコストだけが残ります。既定は二階層。三つ目は実際の必要が出てきたときに足すもので、先回りして用意するものではありません。
Flash DSM との関係
生成された体系には、はじめから両方の階層が備わっています。プリミティブなスケールと、それを参照する文字・背景・境界線・ステータスのセマンティックな役割が、ライトとダークの両方で用意されます。