トークン

デザイントークンは、見た目の値を名前付きの契約として公開する仕組みです。コンポーネントが特定の色や余白を直接参照せず、意味に結び付いたトークンを参照することで、テーマを差し替えても同じコンポーネントを再利用できます。

3層モデル

トークンは Primitive、Semantic、Component の3層に分けます。下位層は値の材料、上位層は利用場所の意味を表します。

層	役割	例	利用者
Primitive	色相・数値など、意味を持たない値のスケール	`--wui-color-blue-500`	Semantic の定義
Semantic	UI上の役割に対応する値	`--wui-text-primary`	コンポーネント、利用者
Component	特定コンポーネントの役割に対応する値	`--wui-button-primary-bg`	対象コンポーネント

コンポーネントのCSSが参照できるのは Semantic または Component です。Primitiveを直接参照すると、ブランド変更時にすべてのコンポーネントを個別に修正することになり、意味のない値への依存も残ります。

命名規則

すべてのCSSカスタムプロパティは --wui- で始めます。名前は用途が読める小文字の kebab-case とし、同じ値でも用途が異なる場合は別のトークンを定義します。

Primitive

色は --wui-color-<name>-<step> です。<step> は色の強さを表す数値で、ブランド色は 50 から 900 までの全スケールを持ちます。

--wui-color-blue-50
--wui-color-blue-500
--wui-color-blue-900

Primitiveには色以外に、--wui-space-<step>、--wui-radius-<size>、--wui-elevation-<level>、--wui-opacity-<name>、--wui-z-index-<name>、--wui-breakpoint-<name>、--wui-media-query-<name>、--wui-line-height-<name>、--wui-width-<name> のカテゴリを用意します。

Semantic

Semanticは --wui-<group>-<role> です。グループはUIの意味を表し、状態は独立した state グループにはしません。

Themeのオブジェクト表記とCSS変数表記は、同じグループとroleを変換したものです。たとえば semantic.state.hoverPrimary はCSSでは --wui-state-hover-primary と表記します。Theme側はcamelCase、CSS側はkebab-caseへ変換し、意味や階層を追加しません。

グループ	トークン名の例	用途
`page`	`--wui-page-bg`, `--wui-page-text`	ページ全体
`bg`	`--wui-bg-brand`, `--wui-bg-brand-hover`, `--wui-bg-brand-pressed`, `--wui-bg-brand-subtle`	背景と状態
`layer`	`--wui-layer-l1`, `--wui-layer-l1-hover`, `--wui-layer-l2`, `--wui-layer-l3`	面の階層と状態
`field`	`--wui-field-default`, `--wui-field-hover`, `--wui-field-focus`, `--wui-field-disabled`	入力欄の状態
`text`	`--wui-text-primary`, `--wui-text-secondary`, `--wui-text-tertiary`, `--wui-text-inverse`, `--wui-text-brand`, `--wui-text-disabled`	文字
`link`	`--wui-link-default`, `--wui-link-hover`, `--wui-link-visited`	リンク
`border`	`--wui-border-default`, `--wui-border-subtle`, `--wui-border-primary`, `--wui-border-secondary`, `--wui-border-strong`, `--wui-border-disabled`, `--wui-border-brand`, `--wui-border-focus`	境界線
`icon`	`--wui-icon-primary`, `--wui-icon-secondary`, `--wui-icon-inverse`, `--wui-icon-brand`, `--wui-icon-disabled`	アイコン
`feedback`	`--wui-feedback-success-text`, `--wui-feedback-success-bg`, `--wui-feedback-success-border`	成功・エラー・警告・情報
`focus`	`--wui-focus-ring`, `--wui-focus-ring-offset`	キーボードフォーカス
`overlay`	`--wui-overlay-bg`, `--wui-overlay-scrim`	モーダル等の覆い
`skeleton`	`--wui-skeleton-bg`, `--wui-skeleton-highlight`	ローディング表示

feedback は success、error、warning、info の各状態に対して text、bg、border を持ちます。これにより、色だけでなく用途を一貫して扱えます。

Component

Componentは --wui-<component>-<role> です。Semanticをコンポーネントの役割へ束ねるために使います。

--wui-button-primary-bg
--wui-button-primary-bg-hover
--wui-button-primary-text
--wui-input-border-focus

コンポーネント固有の契約が必要な場合だけComponentトークンを追加します。単に色を再公開するための別名は増やしません。

状態と強度

状態は各グループの中で表現します。--wui-state-* のような横断的なグループを作ると、背景・文字・境界線の意味が失われるためです。

ブランド背景・状態: semantic.bg.brand、semantic.state.hoverPrimary、semantic.state.pressedPrimary
控えめな背景: semantic.bg.brandSubtle（強度の語彙は subtle のみ）
フィールド: default、hover、focus、disabled
レイヤー: l1、l1Hover、l2、l3

任意の色を受け取るコンポーネントでは、既存のSemanticトークンを基本にし、必要な強弱はCSSの color-mix() で導出できます。新しい色の直値や、状態だけを理由にしたPrimitiveの追加は避けます。

寸法と補助カテゴリ

寸法はTailwind CSS v4のスケールに合わせます（現在の基準はv4.3）。space.px は1px、space.0.5 は2px、space.1 は4px、space.2 は8px、space.4 は16px、space.6 は24px、space.8 は32px、space.16 は64pxです。現行のプリセットは移行前の命名を含むため、#67以降で新しいスケールへ移行します。

角丸は sm、md、lg、full、文字サイズは xs、sm、base、lg、xl、2xl、3xl、4xl を使います。本文の基準は base（16px）です。

重なり順は用途を限定し、dropdown、sticky、overlay、dialog、popover、toast を予約します。ブレークポイントとメディアクエリは同じ境界値を共有し、レスポンシブ判定のずれを防ぎます。lineHeight と width も値を直接書かずカテゴリとして管理します。

コントラストに関わる text、link、border、feedback、focus の組み合わせは、背景との境界を満たすことを契約にします。値の一覧は各基礎ページとテーマ定義に置き、このページでは名前と関係だけを定めます。

ブランド上書きの契約

ブランド色を上書きするテーマは、50 から 900 までの全スケールを提供します。これは #66 以降で導入する新しいテーマ契約であり、現行 createTheme(DeepPartial<Theme>) の互換APIとは異なります。実装時はブランドスケール専用の必須型を追加し、既存APIを破壊する場合はメジャーバージョンを更新します。

特に brandHover を古いブランドのまま残す事故は、通常状態だけを更新したテーマで発生します。ブランドの全スケールと、そのスケールから導出される brandHover・brandPressed・brandSubtle を同時に更新することで防ぎます。

インスタンス変数

利用者が特定インスタンスだけを調整する必要がある場合は、コンポーネントの公開propsから一時的なCSS変数へ渡します。インスタンス変数も --wui-<component>-<role> の命名を使い、テーマ全体のSemanticを変更する用途には使いません。

避けること

コンポーネントCSSからPrimitiveを直接参照する
state グループや用途不明な primaryColor のような汎用名を追加する
subtle 以外の強度語彙を増やして同じ意味を複数の名前で表す
ブランドスケールを一部だけ上書きする
値をこの仕様ページに重複して記載し、テーマ定義とずれを作る