コーディングエージェントにとってdesign.mdとは何か？
design.mdは、コーディングエージェントがデザインシステムを理解するための構造化された方法を提供します。AI生成UIワークフローにおいてそれが重要な理由を解説します。
私はDoraです。先週、Claude Codeにサイドプロジェクトへ3つの新しい画面を追加するよう依頼しました。2画面目になると、ボタンの角丸が微妙にずれ、見出しフォントがいつの間にか変わり、「セカンダリ」グレーが別のグレーになっていました。プロンプトの構造は同じ。モデルも同じ。セッションも同じ。ただ、出力が以前の内容を気にすることをやめてしまったのです。
このような摩擦を取り除こうとしているのが、コーディングエージェント向けのdesign.mdです。これはプレーンなmarkdownファイルで、AIエージェントがUIを生成するたびに読み込めるかたちでデザインシステムを格納します。一度限りのプロンプトとしてではなく、永続的なコンテキストとして機能します。Stitchが読みます。Claude Codeが読みます。Cursorが読みます。リポジトリのルートからコンテキストファイルを拾う仕組みを持つツールならば、他のものも読めます。
design.mdとは何か、そしてなぜGoogle Labsがそれを公開したのか
ファイル形式とデザインシステムにおける役割
DESIGN.mdファイルは、2つのレイヤーを1つのドキュメントに重ねたものです。上部はYAMLフロントマター——色、タイポグラフィ、スペーシング、角丸、コンポーネント——が構造化されたトークンとして記述されています。その下には、それらのトークンが何のためにあり、どう使うかを説明するmarkdownの文章があります。トークンがエージェントに正確な値を与え、文章がその値の存在理由を伝えます。
フロントマターはおおむね次のような形をしています。GitHubのDESIGN.md公式仕様から引用しています：
yaml
---
version: alpha
name: Heritage
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 48px
fontWeight: 600
lineHeight: 1.1
rounded:
sm: 4px
spacing:
sm: 8px
md: 16px
---その下には、プレーンmarkdownで ## Overview、## Colors、## Typographyが続きます。セクションの順序は固定されており——Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do’s and Don’ts——省略は可能ですが、存在するセクションはその順序で並んでいる必要があります。セクション見出しの重複はエラーとなり、ファイルが拒否されます。
トークン参照の構文はW3C Design Tokens Format Moduleに由来し、{colors.primary} のような波括弧パスを使います。参照はプリミティブ値（グループではない）を指さなければなりませんが、コンポーネントセクション内ではタイポグラフィトークンへの複合参照が許可されています。色の値は現行仕様ではSRGB hexのみです。W3C DTCG 2025.10安定版仕様でサポートされているDisplay P3とOklchは、DESIGN.mdではまだサポートされておらず、リポジトリもversion: alphaマーカーでそれを明示しています。広色域トークンを管理している場合は知っておく価値があります。
このフォーマットにはCLIが付属しています——npmの@google/design.mdです。npx @google/design.md lintを実行すると、パースされたファイルに対して7つのルールが適用されます。私がよく遭遇するのは2つです：broken-ref（エラー重要度）は解決できないトークン参照を検出し、contrast-ratio（警告）はコンポーネントのbackgroundColor/textColorペアをWCAG AAの4.5:1最小値に対してチェックします。他の3つ——missing-primary、orphaned-tokens、構造ルール——は、ほとんどのチームがファイルを編集してから1週間以内に引き起こす問題を表面化します。CLIにはさらにdiff（バージョン間のトークンレベルのリグレッション）とexport（Tailwind v3 config、Tailwind v4 @theme CSS、またはW3C DTCG JSON）もあります。
コーディングエージェントに永続的な視覚コンテキストが重要な理由
問題はシンプルです。UIを生成するエージェントは、読み込める構造化されたものを与えない限り、あなたのデザインシステムを記憶していません。プロンプトでパレットを説明し、ボタンを得て、次にカードを依頼すると、スペーシングのロジックがリセットされます。モデルがコードを書くのが苦手なのではなく、アンカーがないのです。
design.mdがそのアンカーです。Stitchはすべての生成リクエストでコンテキストとして渡します。Claude CodeとCursorも、CLAUDE.mdやAGENTS.mdと同じように——エージェントが回答前に読み込むリポジトリルートのファイルとして——拾い上げます。オープンソース発表におけるGoogleのフレーミングは、これによりエージェントが「色が何のためにあるかを正確に把握」でき、プロンプトから意図を推測することなく済む、というものです。
私はこれを両プロジェクトでテストしました。手順：リポジトリのルートにDESIGN.mdを配置し、以前ずれが生じていた同じ5つの画面（ランディング、料金設定、サインアップ、ダッシュボード、設定）を再生成して、フロントマターに対するトークン違反をカウントしました。ファイルを置いた状態では、Claude Codeは5/5の画面で正確なprimaryとtertiaryのhex値および宣言されたrounded.smを使用しました。Cursorは4/5——ダッシュボードのカードでrounded.sm（4px）が繰り返しrounded.md（8px）で上書きされ、DESIGN.mdの文章がそれを明示的に禁止していませんでした。Do’s and Don’tsに「カードの角にはrounded.smを使用し、rounded.mdは使わない」という1行を追加したところ、次の再生成で修正されました。
AI UIジェネレーションで解決する本当の問題
画面と反復をまたいだ一貫性
先ほどのセッションで崩れたのは、1つの画面の品質ではありませんでした。個々の画面はそれぞれ問題なく見えていました。2画面目が1画面目で決定されたことを知らなかっただけです。すべての生成が「あなたのブランド」に対するわずかに異なる解釈から始まっていました。
これがdesign.mdが狙う失敗モードです。「UIをより美しくする」ことではなく——生成をまたいで同一のUIにする、ということです。トークンは規範的です。フロントマターがtertiary: "#B8422E"と言えば、エージェントにそれを「温かみのあるオレンジ」と解釈する余地はありません。そのhex値か、さもなければ間違いで、lintがそう言います。
高頻度のワークフロー——週に5、10、20画面をメンテナンスする人——においては、これは初回出力の品質よりも重要です。1画面に1つの不整合が積み重なれば、クリーンアップ作業になります。コーディングエージェントのデザイントークン——ファイルに一度定義したもの——は、そのクリーンアップ作業を始まる前に消し去ります。
トークンだけよりも、文章＋トークンが強力な理由
この部分はほぼ無視していました。「Boston Clayがインタラクションの唯一の担い手である」という段落を書く必要があるのでしょうか、hex値はすでにYAMLにあるのに？
なぜなら、エージェントはトークンがカバーしない判断を下すために文章を使うからです。トークンはtertiaryが#B8422Eだと言います。文章はその色がインタラクション専用であり——装飾的なアクセントには使わない、見出しにも使わない——と言います。プロンプトが曖昧なとき（「通知バッジを追加して」）、バッジにインタラクションカラーを使うかニュートラルを使うかを決めるのは文章です。上記のCursorの実行で、欠けていた文章の制約がまさにダッシュボードがずれた原因でした。
同じロジックがDo’s and Don’tsにも当てはまります——「カードには決してドロップシャドウを使わない」や「ボタンラベルには常にセンテンスケースを使う」といった明示的なガードレールです。ネガティブな制約は、純粋なトークンでは表現できない重みを持ちます。これはCSSファイルではなく、エージェント向けのデザイン仕様です。
このフォーマットはStitchに縛られていません。仕様はApache 2.0、CLIはnpmにあり、DTCGエクスポートはW3C標準を読めるあらゆるツールへトークンを流し込みます。そして、コミュニティはすでに動き始めています。VoltAgentのブランドに触発されたDESIGN.mdファイルのawesome-design-mdコレクションはローンチから数週間で71,000のGitHubスターを超え、design-md GitHubトピックには、Google外からの抽出ツール、Chrome拡張機能、コンパニオンSKILL.mdレジストリが並んでいます。採用こそが、フォーマットが本物であることを示すものです。
design.mdを気にすべき人は誰か
境界線について正直に言います。design.mdは万人向けではないからです。
次の場合は価値があります：
- 少なくとも週1回、複数の画面にわたってコーディングエージェントでUIを生成している
- 世代をまたいで保持したいデザインシステム——たとえ薄いものでも——がある
- 複数のエージェントやツールを使っており、すべてで同じブランドコンテキストを持ちたい
- すべてのプロンプトに「私たちのパレットはX、Y、Zです」と貼り付けることに疲れた
次の場合は価値がありません：
- 一発限りのモックアップを作ってそれを捨てる
- 「デザインシステム」が今回エージェントが生み出したものである
- FigmaリードのワークフローでStyle Dictionaryなどを通じた成熟したDTCGパイプラインを持っている——design.mdは持っているものより軽量であり、ダウングレードになってしまう
- 今すぐ広色域カラー（Display P3、Oklch）が必要——現行のアルファ仕様はSRGBのみ
CLAUDE.mdやAGENTS.mdなど他のAIワークフローファイルと並べてdesign.mdを運用するAIネイティブのプロダクトチームにとっては、すっきり収まります。1つの懸念事項につき1つのmarkdownファイル。ビルドステップなし。戦うJSONスキーマなし。試すコストはリポジトリルートの1ファイルとlintコマンドだけです。
エージェント駆動の生成サーフェスを構築するプラットフォーム——複数のモデルにわたってリクエストをルーティングする統合AI生成レイヤーを含み、各呼び出しでブランドコンテキストを保持する必要があるもの——にとって、design.mdはエコシステムがブランドとエージェントの間のポータブルなコントラクトに最も近いものです。Google Labsの発表によれば、このフォーマットはツールをまたいでエクスポートおよびインポートできるよう、特別に構築されたとのことです。その移植性こそが核心です。
FAQ
design.mdは何に使われますか？
コーディングエージェントにデザインシステムの永続的なコンテキストを与えるmarkdownファイルです——色、タイポグラフィ、スペーシング、コンポーネント、そしてそれらの適用方法を説明する文章を含みます。エージェントはUIを生成するたびにそれを読み込むため、各プロンプトでブランドルールを再指定することなく、画面やセッションをまたいで出力の一貫性が保たれます。
Google Stitchのワークフロー専用ですか？
いいえ。フォーマットはStitchに由来しますが、GoogleはApache 2.0でその仕様をオープンソース化しました。コンテキストファイルを読むAIツール——Claude Code、Cursor、GitHub Copilot、Antigravity、Gemini CLI——はすべて使えます。CLIはTailwind config、CSS変数、またはW3C DTCG JSONにエクスポートするため、トークンは非エージェントツールにも流れ込みます。
AI生成UIにデザインシステムファイルが必要な理由は？
モデルが生成をまたいでブランドを記憶していないからです。構造化されたAIデザインシステムファイルなしでは、すべてのプロンプトがゼロからデザイン言語を再解釈します。あれば、トークンがハードな制約として機能し、文章が判断の呼びかけをカバーします。違いはスケールで最も明確に現れます——design.mdを使って生成された5つの画面はスタイルを維持し、使わずに生成された5つはずれていきます。
最初に試すべきチームはどこですか？
すでに週次でコーディングエージェントを使ってUIを生成しているチームです。Claude CodeやCursorを使っている個人開発者や小規模プロダクトチームが最も早い恩恵を得られます——ファイルを配置して、再生成して、一貫性を確認する。FigmaとStyle Dictionaryの成熟したパイプラインを持つ大きな組織は、design.mdを代替ではなく補完として扱うべきです：既存システムのエージェントが消化しやすいサブセットを提供するために使ってください。
おわりに
design.mdは革命的なファイルフォーマットではありません。上部にYAMLを持つmarkdownファイルです。それが核心です——LLMが最も得意とするフォーマットは、最も多く学習したフォーマット、すなわちプレーンテキストです。
このファイルが実際にすることは、問いを「このプロンプトでどうデザインを説明するか」から「すべてのエージェントが読めるよう、デザインはどこに置くか」へ移すことです。1つのファイル、1つの場所、それを拾うすべてのツールが同じ答えを得る。再指定が1つ減る。小さいように聞こえる。積み上がると大きくなります。
2つのプロジェクトで1週間使いました。機能します。長期的に——チームがこれらのファイルを本物のデザインシステムと同じ厳密さで管理するのか、それともREADMEが腐るように腐っていくのか——それはまだ確認中です。自分のプロジェクトで試してみてください。私が言えることより、それがずっと多くを教えてくれるでしょう。
過去の投稿：
