デザイントークン・ドリフトとは

デザイントークン・ドリフトとは、デザインシステムが宣言したデザイントークン（色・スペーシング・タイポグラフィ・角丸などを名前付きの単一ソースにした値）と、実際にコードで使われている値とが、少しずつ乖離していく現象を指す。トークンを参照する代わりに、生の値（ハードコード）や一度限りの上書きが入り込むたびに発生し、コードベースは自分自身のデザインシステムと一致しなくなっていく。

ビジュアルバグと違い、ドリフトは静かに進む。一つ一つの変更は単独では妥当に見える——ここのボタンを少し濃く、あそこはトークンを探すより速いから生のhexを直書き。しかし集計すると、正（source of truth）と実際に出荷されるUIが知らぬ間にズレていく。そして「どのコミットで間違えたのか」という一点は存在しない。

まず、トークンは何のためにあるか

デザイントークンとは、デザイン上の決定を名前付きの単一ソースの値にしたものだ。#0a0a0a を40箇所に書く代わりに、color.accent を一度宣言してどこからも参照する。決定を一箇所で変えれば、プロダクト全体がそれに追従する。これがトークンの全目的だ——繰り返しではなく参照による一貫性。

つまりトークンは、参照され続けている間だけ価値がある。仕組みは「参照が保たれている」ことを前提にしている。ドリフトとは、その前提が崩れたとき——生の値が忍び込み、トークンが誰も使わない値になったとき——に起きることの名前だ。

なぜ起きるか——そしてなぜAIが悪化させるか

ドリフトの発生源は、たいてい3つある。

1. 手作業の近道。 締切の下では、#0a0a0a と打つ方が、その値を持つトークンを探すより速い。
2. 一度限りの上書き。「この画面だけ、少し濃く」。一度なら妥当。しかしスケールでは蝕む。次の人がそれをコピーするからだ。
3. AIコーディングエージェント。 これが新しい発生源だ。Claude Code・Cursor・Copilot・Codex はセッションを跨ぐとデザイン文脈を失い、トークン参照ではなく生の値をハードコードしてUIを再生成する。プロップの型は読めても、「このボタンの背景はaccentトークンでなければならない」という設計上の規則は型には現れない。

3つ目が、問題の規模を変える。AIはUIを数秒で出荷する——その速度は、そのままドリフトの速度だ。AIを使うチームではプルリクエストが 98% 増、レビュー時間が 91% 増と報告されている。ボトルネックは「書く」から「マージして安全か判断する」へ移った。そしてトークン整合性は、まさに人間のレビュアーが目視で追えない種類のものだ。diffは正しく見える。今日の時点では #0a0a0a は本当に正しい色だからだ。ただ、それを正しくしていた決定とは、もう繋がっていない。

どう検出するか

ドリフトは規律の問題ではなく、検出の問題だ。人に——あるいはエージェントに——「もっと気をつけて」と頼んでも直らない。特定のツールに依らず、3つが効く。

• トークンを、エージェントが書く前に実際に読める 機械可読な単一ソース として持つ。
• 参照率 を継続的に測り、生の値の再流入を「驚き」ではなく「シグナル」として可視化する。
• 変更ごとに 何がトークンから外れたか を、人が数秒で確認できるdiffとして見せる。

私たちが作っているのは、その形だ。npx harnd scan が既存コードを読んで、あなたが既に持っているトークンを抽出する。harnd validate が、生の色やスケール外のスペーシングを出荷前に指摘する——そして同じハーネスを、Claude Code や Cursor がUIを一行書く前に読む。ドリフトは、6週間後に気づくものではなくなる。

ドリフトは「負債」ではなく「観測不能性」だ

ドリフトを「デザイン負債」に分類したくなる。だが負債は、少なくとも見える——山が積み上がるのが分かる。ドリフトはもっと厄介だ。一度も観測されないまま蓄積するからだ。問題は、誰かがトークンを破ったことではない。トークンは現実の締切の下で常に破られる。問題は、破ったことが、誰にも見える形で痕跡を残さなかったことだ。

この捉え直しは、AI時代にこそ効く。旧来のドリフトは人間の速度で進んだが、新しいドリフトは機械の速度で進み、しかも何をしたかの記憶を残さない。だから答えは「もっとレビューを頑張る」ではない。数秒で画面を再生成するエージェントを、人間が読み勝つことはできない。答えは、デザイン層を機械可読にして、乖離を——後から発見するのではなく——検出し見せることだ。ドリフトは、観測可能にすることで止める。

ドリフトとは、トークンの契約が静かに破れた後の姿だ。それをコンポーネント粒度で支える単位が知りたければ、コンポーネント契約とは何かを読んでほしい。トークン・契約・ゲートを一つのソースに保つ機械可読な層全体については、デザインハーネスとは何かを。

そしてもし、これがもうあなたのコードベースで起きているなら——早期アクセスに登録して、エージェントが既に作ったアプリにHarndを向けてほしい。