design.md vs デザイントークン：AI UIワークフロー比較
AIエージェントの可読性・一貫性・ワークフローの移植性に注目し、design.mdと従来のデザイントークンをAI UIワークフローの観点から比較します。
私はDoraです。週のほとんどをコーディングエージェントとAI UIツール — Cursor、Claude Code、Stitch、おなじみのラインナップ — の中で過ごし、ドキュメント化する時間もないほどの速さでインターフェースを作っては作り直しています。約1ヶ月前から、触れるほぼすべてのリポジトリに同じファイルが現れるようになりました：DESIGN.md。同じ名前、同じYAMLが上にあり散文が下に続く形。3プロジェクト目で、これが偶然ではないと気づきました。それは、私たちのほとんどがかつてtokens.jsonとして出荷していたものに取って代わるものでした。
そこで自分のコンポーネントライブラリの一つを2回作り直しました — 1回は古典的なDTCGスタイルのトークンファイルで、1回はDESIGN.mdで — そして同じコーディングエージェントを両方に対して実行しました。これが私が文書化されているのを見つけられなかった比較の部分です：各フォーマットが何であるかではなく、それぞれが実際に何を最適化しているのか、そして今あなたのスタックのどちらが属しているのか。
design.md vs 伝統的なデザイントークン
各フォーマットが最適化しているもの
古典的な意味でのデザイントークンは方法論です。この用語は2014年頃にSalesforceで生まれ、非常に具体的なスケーリング問題を解決するために作られました：4チケットを出すことなく、Web、iOS、Android、4つのコードベース間でカラーの決定を同期し続けるにはどうすればよいか？答えは、プラットフォームに依存しない名前と値のペアで、JSONまたはYAMLに格納され、ビルド時に各プラットフォームが必要とするものに変換されるというものでした。その方法論は現在W3CのDesign Tokens Community Groupによって成文化されており、2025年末にはDTCGフォーマットが安定したv1仕様を持っています。
トークンは確定的な配布を最適化します。16進コードが入力され、すべてのプラットフォーム、すべてのビルドで、永遠に同じ16進コードが出力されます。曖昧さはありません。ただし、ナラティブもありません — トークンファイルはprimary: #1A1C1Eを伝えますが、そのカラーがなぜ存在するのか、いつ使わないべきかは伝えません。
DESIGN.mdは2026年4月にGoogle Labsによってオープンソース化されましたが、別のものを最適化しています：トークンファイルがカバーしていない決定を下せるだけのコンテキストをコーディングエージェントに与えること。 トークン用のYAMLフロントマターと、その下に理由を説明する散文を持つ単一のマークダウンファイルです。同じファイル、2つのオーディエンス — パーサー用の確定的な部分、リポジトリを読んでいるLLM用のナラティブ部分。
これが実際の分割です。「古い vs 新しい」でも「JSON vs Markdown」でもありません。それは値と同じファイル内の値と理由の違いです。
AIエージェントが新しい要件セットを生み出す理由
人間がデザインを実装するとき、「トークンは#1A1C1Eと言っている」と「この空の状態にはトーン・オブ・ボイスが必要」のギャップは人間によって埋められます。彼らはFigmaファイルを見ています。ブランドワークショップに参加していました。セカンダリボタンが主張せず、静かな印象を与えるべきだと知っています。
コーディングエージェントにはそれがありません。リポジトリに置かれたものとファイル名から推論できるものしかありません。だから、トークンファイルが完全に指定していない画面を生成するよう求めると — エッジケース、新しいコンポーネント、レイアウトの決定 — 推測するか、トレーニングで最もよく見たデフォルトに戻ります。それが誰もが不満を言う「AIベージュ」美学の源です：悪いモデルではなく、単にコンテキストが欠けているだけです。
これがDESIGN.mdが解決していることです。GitHub上の公式仕様はそれを明示しています — トークンはエージェントに正確な値を与え、散文はそれらの値がなぜ存在し、どのように適用するかを伝えます。フォーマットは両方の半分を期待しています。
design.mdが価値を追加する場所
永続的なナラティブコンテキスト
テストの最初の48時間で気づいたこと：同じエージェントが、同じブリーフが与えられたとき、散文コンテキストが存在するときに明らかに異なるアウトプットを生成します。「少し良い色」ではありません。異なるレイアウトの選択、異なるコピーのレジスター、異なるコンポーネントの密度です。両方のランでトークン値は同一でした — 変わったのは、エージェントが「ブランドボイスは抑制的でエディトリアルです；デコレーションよりホワイトスペースを優先してください」と書かれた段落を持っていたかどうかでした。
これは伝統的なトークンパイプラインが持ち運ばない部分です。DTCGのJSONファイルは--color-primaryを正確に説明できますが、プライマリカラーは控えめに使用されることを意図しているとエージェントに伝えることはできません。DESIGN.mdはその判断をすべての生成パスに、永続的に、誰かがプロンプトに再入力しなくても持ち込みます。
機能します。
生成ワークフローのためのより良いマルチスクリーン一貫性
2番目のテストでは、2日間にわたって同じアプリのために8つの画面を生成しました。トークンのみのコンテキストで、画面5〜8がドリフトし始めました — 同じパレットですが、レイアウト言語が緩んできました。DESIGN.mdが存在すると、ドリフトははるかに小さくなりました。ゼロではありません。小さくなりました。
私の考えでは：散文セクションはエージェントがファイルを読むたびに再アンカーのように機能します。トークンだけでは、エージェントが個々の値で正確であるのに十分です。ナラティブは、トークンが予測していなかった決定を横断して一貫しているのに十分です。一回限りの生成ではそのギャップは重要ではありません。マルチスクリーン出力と継続的な反復では、それが積み重なります。
これはまた、DESIGN.mdがより広いエージェント指示スタックとうまく機能する場所でもあります — ほとんどのセットアップは今、SKILL.mdファイルとともにAGENTS.mdからそれを参照しており、デザインシステムはエージェントの永続的な指示の残りと同じコンテキスト層に位置します。
伝統的なトークンがまだ勝つ場所
2つのシナリオ、どちらも実際のものです。
Web以外のクロスプラットフォーム配布。 iOS、Android、React Nativeアプリ、マーケティングサイトに同じデザインシステムを出荷する場合、Style DictionaryやTerrazzoを通じたDTCGパイプラインが依然として最も手間のかからないパスです。DESIGN.mdのYAMLは公式の@google/design.md CLIを通じてDTCGのJSONにエクスポートできますが、ソース・オブ・トゥルースの問題はまだ重要です — トークングラフが大きく、マルチテーマで、非AIツールによって消費される場合、DTCGを正規フォーマットとして保持することがよりクリーンなセットアップです。
確立されたガバナンスを持つ成熟したデザインシステム。 トークンは単なるファイルフォーマットではありません。それらは約10年の蓄積された実践を持つ方法論です — プリミティブ層、セマンティック層、エイリアシング、テーマ、Nathan CurtisがTokens in Design Systemsで説明した全体の分類法。チームがすでにその方法で運営している場合、DESIGN.mdはそれを置き換えません。エージェント用のコンテキスト層として、その上または横に位置します。トークンは正規のソースとして残り、マークダウンはAI向けの翻訳になります。
間違いはDESIGN.mdをトークンパイプラインの代替として読むことでしょう。そうではありません。異なるコンシューマーを持つ異なる層です。
AI UIパイプラインを構築するチームのための意思決定フレームワーク
リポジトリに何を置くかを決定する際、私は4つの質問に立ち返ります：
- このファイルを誰が読むのか？ 主要なコンシューマーがCSS、Swift、Kotlinを出力するビルドパイプラインであれば、正規フォーマットのトークンが必要です。主要なコンシューマーがオンデマンドでUIを生成するコーディングエージェントであれば、DESIGN.mdが必要です。両方であれば、両方を保持します — そしてマークダウンファイルのYAMLがトークンのサブセットをミラーするようにします。
- UIサーフェスはどのくらいの頻度で再生成されるのか？ 低頻度のチーム（安定した製品、時折の新画面）はトークンから価値のほとんどを得ます。高頻度のチーム（急速なプロトタイピング、エージェント駆動の反復、毎週新しい画面）はコンテキスト不足のギャップを鋭く感じます。再生成の頻度が高いほど、散文層はその存在価値を高めます。
- プラットフォームはいくつあるのか？ Webのみ、またはエージェント駆動の生成を伴うWeb中心 — DESIGN.mdがシンプルなスタックです。深刻なネイティブプレゼンスを持つ3プラットフォーム以上 — トークンファースト、DESIGN.mdをダウンストリームアーティファクトとして。
- 理由はすでにどこかに文書化されているのか？ ブランドガイドライン、ボイスドキュメント、コンポーネント哲学がどのエージェントも読まないNotionページに存在する場合、DESIGN.mdは今四半期に行える単一の最高レバレッジの動きです。新しいドキュメントを作成しているのではなく、エージェントが実際に開くファイルに既存のドキュメントを移動させています。
これが私のフレームワークです。あなたのものは異なるかもしれません。フラグを立てたいこと：新しいからという理由でフォーマットを選ばないでください。ファイルを読む人が誰かに基づいて選んでください。
FAQ
design.mdはデザイントークンの代替ですか？
いいえ。DESIGN.mdはデザイントークン（YAMLフロントマター内）とその周囲の理由（マークダウン散文内）を含むラッパーです。その中のトークンは依然として従来の意味でのデザイントークンです。すでにDTCG形式のトークンファイルを持っている場合、DESIGN.mdはそれを置き換えません — AIエージェント用の並行アーティファクトとして位置するか、必要に応じてマークダウンからDTCG JSONをエクスポートできます。
AIエージェントはなぜ数値トークン以上のものを必要とするのですか？
ほとんどのUI生成リクエストがトークングラフによって完全に指定されていないからです。「価格設定ページを生成して」には、トークンファイルがカバーしない何百ものマイクロ決定が必要です — 階層、密度、トーン、何を強調するか。ナラティブコンテキストなしでは、エージェントはトレーニングデータで見たもので空白を埋め、ほとんどのAI生成UIが共有するジェネリックな外観を生み出します。DESIGN.mdの散文がそのギャップを閉じます。
どのワークフローがdesign.mdから最も恩恵を受けますか？
私が最も効果を見た3つのパターン：
- Cursor、Claude Code、またはStitchを使って手書きよりも速くUIを出荷しているソロビルダーと小チーム。
- AIで生成された画面での一貫性が本物の問題になっている複数の内部製品を維持しているデザインシステムチーム。
- どのコーディングエージェントにもクライアントのデザイン言語をエンコードする単一のドロップインファイルが欲しいエージェンシーやコントラクトチーム。
ワークフローが主に手書きで時折AIアシスタンスを使う場合、限界的な価値は下がります。
古典的なデザイントークンインフラがまだ十分な場合はいつですか？
エージェントでUIを生成していない場合、またはプラットフォームリーチがWeb以外にも広がっている場合です。ネイティブモバイルが重い、マルチテーマのホワイトラベル製品、成熟したデザインオペス実践 — これらはマークダウンファイルよりもDTCGエコシステムからまだ多くを得ます。2つは相互に排他的ではありませんが、1つを選んで投資する必要がある場合、答えは生成の摩擦が実際にどこにあるかによります。
まとめ
正直なバージョン：DESIGN.mdはパラダイムシフトではありません。それは特定のギャップへの焦点を絞った解決策です — トークンファイルが持ち運ばない理由を欠いているコーディングエージェント。そのギャップが実在するワークフローでは、利益は即時で明白です。そうでないワークフローでは、伝統的なトークンが依然として仕事をこなします。
私は実行するすべてのAI生成プロジェクトでDESIGN.mdを使って2ヶ月になります。それはワークフローに残っており、それが私が信頼する唯一のテストです。トークンファイルもどこにも行っていません — 今もずっとやってきたことをしており、ただ数字以上のものを必要とするオーディエンスのためのサイブリングファイルを今では持っています。
自分のプロジェクトで実行してみてください。2日間でこの記事より多くのことがわかるでしょう。
過去の投稿：
