デザイントークン移行：役割を分けて旧トークンを廃止する

デザイントークンは、繰り返し使う判断を明示します。色の役割、余白の段階、文字サイズの尺度、エレベーションの値などを、コンポーネントやプラットフォームをまたいで再利用できます。難しくなるのは、トークンが誤っていたり、意味が曖昧だったり、製品に合わなくなったりしたときです。名前や値を一括で置き換えると、コントラスト、レイアウト、ドキュメント、コードを同時に壊すおそれがあります。

より安全なのは、トークンの変更を移行として扱う方法です。まず古い判断がどこで使われているかを把握し、次により明確な置き換え先を用意し、小さな単位で利用箇所を移します。古い名前を廃止するのは、安全だと判断できる証拠がそろってからです。これはトークン一式をゼロから作る作業ではなく、既存のデザインシステムを継続的に発展させるための保守です。

基礎については、デザイントークンのガイド（英語）とPixsoのデザイントークンの概要を参照してください。ここでは、非推奨化、責任の所在、移行の検証に範囲を絞ります。

トークンの変更にリスクが生じる理由

古いトークンは、検索結果から分かる以上に多くの場所で使われている可能性があります。意味上の役割を持つ色が、ボタン、グラフ、無効状態、パートナーブランドのテーマへ渡されているかもしれません。余白のトークンがコンポーネントの上書き設定にコピーされたり、プラットフォーム固有の定数に変換されたりしていることもあります。blue-500のような名前は、一方の製品では成功を示す色、別の製品ではアクセント色として使われるまでは、問題がないように見えるかもしれません。

移行のリスクは、主に次の四つの不足から生じます。

1. チームがトークンの利用箇所を把握していない。
2. 置き換えによって、値だけでなく意味も変わる。
3. デザインとコードが異なる日程で移行する。
4. 古いトークンについて、何をもって「完了」とするか定義されていない。

解決策はシステムの変更を止めることではありません。置き換えを発表する前に、依存関係と判断の根拠を見えるようにすることです。

名前だけでなく役割からトークンを棚卸しする

意図と利用状況を記す表から始めます。トークン名、カテゴリ、意味上の役割、対応モード、利用するコンポーネント、責任者、予定する対応を含めます。16進数の色値だけから役割を推測してはいけません。同じ値の二つのトークンが別々の仕事を担うことも、一つのトークンがライトテーマとダークテーマで異なる値を必要とすることもあります。

最初から分類体系を完璧にしようとせず、確認できた事実を記録します。依存関係を推測で埋めた大きな一覧より、小さくても正確な棚卸しのほうが有用です。デザイントークンの命名ガイド（英語）は命名の原則を考える助けになりますが、移行を判断するのは、そのトークンを使う製品の担当チームです。

名前変更・エイリアス・役割の置き換えを使い分ける

名前変更、エイリアス、役割の置き換えは、それぞれ異なる問題を解決します。

意図を明確にするための名前変更

トークンの意味は適切でも、名前が誤解を招いたり統一されていなかったりする場合は、名前を変更します。期間を定め、古い名前から新しい名前へのエイリアスを残します。名前変更と同時に、説明なくコントラストや余白まで変えてはいけません。そうすると、不具合がどの変更によって起きたのか分からなくなります。

互換性を保つためのエイリアス

互換エイリアスを設けると、利用側が置き換え先へ移る間も、古い名前から値を解決できます。そのエイリアスに責任者と廃止条件を定めます。これは恒久的な意味上の参照とは区別してください。たとえばtext-secondaryが、システムの存続期間を通じて基礎となる色トークンを参照するのは正当な使い方です。他のトークンを参照しているというだけで、どちらかが非推奨になるわけではありません。

意味上の役割の置き換え

一つの名前が両立しない用途を担っている場合は、意味上の役割を置き換えます。たとえばtext-mutedが、読める必要のあるフォームの案内文と、無効なボタンのラベルの両方に使われているとします。補足情報にはtext-secondary、無効なコントロールにはtext-disabledと分けます。一度の全体置換で古い名前を両方へ正しく対応付けることはできないため、利用箇所ごとに役割を確認します。

利用箇所がなくなってから削除する

削除は最後の工程です。チームが調査できないパッケージで古いトークンがまだ使われているなら、その確認範囲の限界を記録し、トークンは非推奨のまま残します。トークンが見つからずビルド時に代替値が使われるようになったことは、整理が成功した証拠にはなりません。

評価できる置き換え先を作る

置き換え先には、一文の定義、利用してよい文脈、モード、正しい使い方と誤った使い方の例を用意します。値も変えるなら、色見本だけでなく実際のコンポーネントで変更前後を示します。フォーカス、ホバー、無効、選択、エラー、情報密度が高い状態を確認します。トークンの問題は、通常のコンポーネント表示には出ていない状態に潜みがちです。

補助的なテキストでも、読みやすさは必要です。色を薄くすることは、コントラストを無視してよい理由にはなりません。WCAGの無効なコントロールに関する例外は、コントロールの実際の状態に適用されるもので、トークン名に「disabled」が含まれるかどうかでは決まりません。他のカテゴリのトークンでも、利用するコンポーネント上で改行、余白、フォーカスの見え方、テーマごとの挙動を調べます。色見本では適切な値でも、利用する文脈では問題を起こすことがあります。

置き換え先の隣に、移行についての注記を加えます。

text-mutedの新規使用は非推奨です。読み取れる必要がある補助文はtext-secondaryへ、無効なコントロールのラベルはtext-disabledへ対応付けます。既存の利用箇所は、コンポーネントのレビューが終わるまで以前の値を維持します。コンポーネントの責任者が各移行を記録し、互換経路を削除できる時点を確認します。

このように適用範囲を具体化すると、プルリクエストで古い参照を見つけたデザイナー、開発者、レビュー担当者にも役立つ注記になります。

この比較に絞ったPixsoファイルで、text-mutedをtext-secondaryとtext-disabledに分ける前後の、同じ設定カードを並べます。レイアウトと文言は変えません。「日付を選択」という案内は読める必要があり、「変更を保存」は実行できない操作を表します。各ラベルが使う役割を注記し、実装責任者と二つのコンポーネントをレビューします。対応するコード側のマッピングは別途記録し、レビューが完了してから、承認されたデザインライブラリの更新を公開します。

Pixsoでスタイルの置き換えを比較する →

利用箇所を意味のある単位で移行する

一つのコンポーネント群、一つの製品画面、一つのテーマなど、レビューして元に戻せる単位を選びます。大きなファイル内のすべてのトークンを一度に移すと効率的に見えても、見た目の不具合がどこで起きたかを特定しにくくなります。通常、操作中、無効、エラーの各状態でそのトークンを使う、代表的なコンポーネントから始めます。

移行の単位ごとに、次を記録します。

• 古いトークン名と新しいトークン名。
• 影響を受けるコンポーネントと状態。
• 想定する見た目または意味の変化。
• デザイン側とコード側の責任者。
• 検証用スクリーンショットまたはリンク。
• その単位でエイリアスへの依存を解消できる日。

この段階では、共有のデザイン作業環境が、状態の比較や判断のレビューに役立ちます。デザインシステムの事例（英語）とデザインシステムの拡張（英語）は、より広い背景を理解するための資料です。ただし、移行記録そのものは具体的にし、現在扱っているコンポーネントと結び付けておきます。

意味と見た目の不具合を別々に確認する

見た目の比較は必要ですが、それだけでは不十分です。置き換え後の外観が似ていても、意味、コントラスト、フォーカス表示、コードの利用側で適用される代替値が変わる場合があります。二つのチェックリストを使い分けます。

意味と仕様の確認

• トークンは、文書化された役割だけに使われているか？
• 値は、プロジェクトのコントラストと状態の要件を満たしているか？
• 対応する各テーマで、一貫した挙動になっているか？
• 書き出す名前とプラットフォームごとの対応付けは安定しているか？
• サポートしない使い方は拒否されるか、少なくともレビューで分かるようになっているか？

見た目の確認

• 想定する幅で、テキストの改行位置が変わっていないか？
• 境界線、区切り線、フォーカスリングは引き続き識別できるか？
• オーバーレイとメニューは、意図した階層関係を保っているか？
• データの多い画面で、情報密度と一覧性が維持されているか？
• モバイルとデスクトップのコンポーネントの整合は保たれているか？

二つを分けて確認することで、整ったスクリーンショットの陰に重大な状態の不具合やアクセシビリティの問題が隠れるのを防ぎます。コンポーネントのレビューに証拠を添え、両方のリストを満たしてからトークンの状態を更新します。

非推奨化を製品の変更として伝える

利用側には、古い名前、変更する理由、置き換えのルール、影響するコンポーネント、責任者、削除予定のリリースを具体的に通知します。トークンファイルでデザイントークン形式モジュール（英語）を使っている場合、$deprecatedでトークンを非推奨とし、理由を記載できます。このメタデータは状態を伝えるものであり、利用箇所を自動で見つけたり、その参照を移したりするものではありません。

チーム全体で同じ意味に理解できる状態名を使います。

状態はトークンの隣とリリースノートの両方に記載します。チーム内の移行情報一覧からデザイントークンのリリース資料へリンクすることはできますが、一般的な製品ページを根拠に、個別プロジェクトの移行日程が決まっているかのように示してはいけません。

証拠を確認して古いトークンを廃止する

削除の前に、デザインファイル、コードパッケージ、ドキュメント、書き出したアセットを対象として、最後にもう一度利用箇所を検索します。外部向けまたはアーカイブ済みの画面の責任者にも、担当範囲を確認してもらいます。ソースファイルだけでなく生成済みファイルも調べます。ビルドが通っていても、生成されたパッケージに古い名前が残っている可能性があります。

完了条件を明確な記録にします。

1. サポート対象の利用箇所に、古い名前を必要とするものが残っていない。例外がある場合は、他のパッケージからトークンを削除する前に、その利用側のための互換経路を残す。
2. 置き換え先は、対応するすべてのモードで意味と見た目の確認に合格している。
3. エイリアスと移行注記の削除日が告知されている。
4. ドキュメント、例、コードの自動補完が、古い名前を推奨しなくなっている。
5. 後から利用箇所が見つかった場合に備え、ロールバックの経路がある。

古いトークンを削除するのは、そのパッケージがサポートする利用側の移行が済んだ場合だけです。最後に正常動作していたパッケージのバージョン、マッピング、検証例をまとめて保管し、ロールバックで以前の取り決めを復元できるようにします。後から未移行の利用箇所が見つかった場合は、その責任者が対応付けを確認する間、互換性を復旧します。見た目が似た値へ黙って差し替えてはいけません。

例外を台帳に記録する

すべての利用側が同じ日程で移行できるとは限りません。モバイル版のリリースが凍結されている、パートナー向けパッケージがトークン名を外部へ公開している、古いテーマがまだ置き換え先に対応していない、といった場合があります。各例外について、責任者、影響範囲、理由、再確認日を記録します。説明なくエイリアスを残し続けるより、明示された一時的な例外として扱うほうが安全です。

例外台帳には、移行期間中に利用者が何を見るかも記します。古いテーマで以前の値を保つなら、想定される表示の差と、まだ検証していない状態を記録します。責任者が条件の変化を確認したら、利用箇所の一覧を更新して例外を解消します。文書化されていない第二の移行経路を残さないようにします。製品とパッケージが別々に進化しても、こうした記録によってトークン管理を実態に即したものに保てます。

利用箇所ごとに移行の完了を判断する

設定カードの移行完了とは、補助文と無効なラベルが、デザインと実装の両方で定義された役割を使い、対応テーマがレビューされ、サポート対象のどの使用箇所もtext-mutedへ依存していない状態です。未解決の利用箇所は移行記録に残します。新しいトークンが単体で完成して見えるからではなく、こうした依存が解消されたときに、古い名前をパッケージから取り除けます。

参考資料

• Design Tokens Community Group：形式モジュール（英語）
• W3CのDesign Tokens Community Group（英語）
• Material Design：デザイントークン（英語）