デザイントークンの価値は2026年に広く認められている——しかし実際に落地しているチームは多くない。問題は「トークンを使うべきか」ではなく、「トークンをどう管理すれば別のクソコードにならないか」だ。本記事では実際の開発経験から、デザイントークンの分層アーキテクチャ、変更治理、クロスプラットフォーム同期メカニズムについて議論する。
トークン三層モデル：色と余白だけではない
業界主流のトークン分層モデルは2026年に三つのレベルに収斂している：
第一層：基礎トークン（Primitive / Global Tokens）
最も低層で最も原子的な設計判断。典型的な内容：
- カラーパレット（
blue-500: #3B82F6、neutral-100: #F5F5F5など） - スペーシングスケール（
space-4: 4px、space-16: 16pxなど） - フォントサイズスケール（
font-size-sm: 0.875rem、font-size-xl: 1.25remなど） - 角丸、シャドウ、フォントウェイトなどの基礎属性
基礎トークンは純粋な値定義であり、セマンティクスを含まない。通常はデザインツール（Figma Tokens Studioなど）から直接エクスポートされ、フロントエンドが手動で修正すべきではない。
第二層：セマンティックトークン（Semantic / Alias Tokens）
この層は基礎トークンを意味のある用途に対応付ける：
color-text-primary→neutral-900color-surface-brand→blue-500spacing-card-padding→space-16font-size-heading→font-size-xl
セマンティックトークンの核心的価値は用途は安定しているが、値は切り替えられることだ。例えばダークモードではcolor-text-primaryがneutral-900からneutral-100に切り替わるが、コンポーネントコードは一切変更不要。またブランドリニューアル時もトークンの対応関係を変更するだけで、コンポーネントごとに色値を修正する必要がない。
第三層：コンポーネントトークン（Component Tokens）
この層はコンポーネントライブラリの具体的なコンポーネントに直接対応する：
button-primary-bg→color-surface-brandcard-padding-x→spacing-card-paddinginput-border-radius→radius-md
コンポーネントトークンの利点はコンポーネントの設計依存を明示化することだ。Buttonコンポーネントがどの設計判断を使用しているか知りたい時、トークンを見れば十分で、ソースコードを読む必要がない。
トークンのエンジニアリング管理：Figmaからコードへ
2026年の成熟したツールチェーン：
- デザイン側：デザイナーがFigmaでTokens Studioプラグインを使用してトークンを定義し、JSONとしてエクスポート
- 同期層：Style DictionaryまたはTokens StudioのCIプラグインを使用して、JSONをマルチプラットフォーム形式（CSS変数、Tailwind設定、iOS/Androidリソースファイル）に変換
- 利用側：フロントエンドコンポーネントがCSS変数またはTailwindテーマを通じてトークンを参照
推奨ディレクトリ構造：
design-tokens/
├── primitives/
│ ├── colors.json
│ ├── spacing.json
│ └── typography.json
├── semantic/
│ ├── light.json
│ └── dark.json
├── components/
│ ├── button.json
│ └── card.json
├── build/
│ ├── css-variables.css
│ ├── tailwind.config.ts
│ └── index.ts
└── scripts/
└── build-tokens.ts
トークン変更の審査フロー
トークン変更は高リスク操作だ——一つの基本色を変更すると数十のコンポーネントに影響する可能性がある。2026年の実践はトークン専用の変更フローを確立することだ：
変更タイプのレベル分け：
- P3（新規トークン追加）：新しいトークン値を追加し、既存コンポーネントに影響しない。通常のPRフローでよい。
- P2（セマンティック対応の修正）：
color-text-primaryをneutral-900からneutral-800に変更するなど。ビジュアル回帰テストのスクリーンショットを提供し、PRでデザイナーに承認を@する必要がある。 - P1（基礎トークンの修正）：カラーパレットの
blue-500値を修正するなど。RFCを発起し、影響範囲を評価し、ステージング環境で全量回帰を実施する必要がある。
自動化チェック：
- トークンJSONのSchemaバリデーション（スペルミスや型エラーを防止）
- 孤立トークンの検出（定義されているが参照されていない）
- 未定義参照の検出（コンポーネントが存在しないトークンを参照）
- ビジュアル回帰テスト（Chromatic / Percyで自動スクリーンショット比較）
クロスプラットフォーム同期：Webだけではない
デザイントークンの真の価値はクロスプラットフォームシナリオで完全に発揮される。2026年、ますます多くのチームがWeb、ミニプログラム、React Native、デスクトップを同時にサポートする必要がある。トークン同期の課題：
プラットフォーム差異の対応： プラットフォームごとに能力が異なる。CSSはrgba()とvar()をサポートするが、ミニプログラムはHEX色のみサポートするかもしれない。Transform関数はプラットフォームごとに異なる出力形式を生成する必要がある。良いアプローチは、ビルドスクリプトでプラットフォームごとにtransformerを保守し、入力は統一されたトークンJSON、出力はプラットフォームネイティブの形式とすることだ。
バージョン同期戦略： デザイントークンのリリース頻度は通常、業務コードより低いがメジャーバージョンより高い。推奨リズム：
- 毎週Figmaから最新トークンをコードリポジトリに同期
- 非破壊的変更（新規トークン追加、既存コンポーネントのセマンティック対応に影響しないトークン修正）は自動マージ
- 破壊的変更は手動承認フローをトリガー
ダークモードとマルチテーマ： トークンモデルは本質的にマルチテーマをサポートするが、注意点がある：コンポーネントごとに二套のスタイルを書くのではなく、トークンが異なるテーマで異なる値に対応するようにする。コンポーネントコード自体はテーマ非依存であるべきだ：
/* ✅ 正しい：コンポーネントはセマンティックトークンのみ参照 */
.button {
background: var(--color-surface-brand);
color: var(--color-text-on-brand);
}
/* ❌ 誤り：コンポーネントが基礎トークンを直接参照 */
.button {
background: var(--blue-500);
color: var(--white);
}
チーム協業におけるトークン治理
トークン治理の最も難しい部分は技術ではなく、人だ。デザイナーとデベロッパーのトークンに対する理解はしばしば同じレベルにない。協業をよりスムーズにする実践：
トークンは共通言語：PR議論では具体的な値ではなくトークン名でコミュニケーションする。「このボタンの
color-surface-brandは重すぎないか」は「このボタンの青色を#4A90D9に変える」よりも意思決定に有利だ。トークンのオーナーはデザインシステムチーム：組織構造に関わらず、デザイントークンには明確なオーナーが必要で、変更審査、一貫性維持、ドキュメントを担当する。
入門ドキュメントは形式だけでなく意図を伝える：「
spacing-mdの値は8px」と書くより、「spacing-mdはコンポーネント内部要素の間隔、例えばボタン内部のpadding、リスト項目間の間隔に使用する」と書く方がよい。定期的なトークン監査：四半期ごとにトークンの使用状況をチェックする。どのトークンが未使用か？どのトークンの値がプラットフォーム間で不一致か？どのトークンの命名が現在の設計意図を反映できなくなっているか？
まとめ
デザイントークン治理は「JSONをエクスポートしてコードリポジトリに置く」だけでは終わらない。三層分層アーキテクチャ（基礎→セマンティック→コンポーネント）、エンジニアリング化されたビルドパイプライン、レベル分けされた変更審査フロー、クロスプラットフォーム同期メカニズムが必要だ。さらに重要なのは、トークンはデザインとエンジニアリングの間の契約である——優れたトークン体系はデザイナーが独立してデザイン言語を反復できるようにし、デベロッパーがピクセル単位でデザイン意図を理解する必要をなくす。2026年のフロントエンドチームで、まだトークン治理フローを確立していないなら、今が最高のスタート地点だ。