DESIGN.md 入門 — AIエージェントにデザインを伝える新しい標準ファイル
はじめに
AIコーディングエージェントにUIを生成させると、ボタンの色が毎回変わる、フォントサイズがページごとにバラバラ、角丸の半径がコンポーネントごとに違う——こうした「デザインの一貫性崩壊」は、多くの開発者が直面する問題です。
2026年3月、Google Labs の Stitch チームがこの課題に対する解答として DESIGN.md という新しいファイル形式を提唱しました。README.md がプロジェクトの説明を人間に伝えるように、DESIGN.md はデザインシステムを AI エージェントに伝えます。公開直後から大きな注目を集め、関連リポジトリ awesome-design-md は数日で多くの GitHub スターを獲得しました。
この記事のポイント
- DESIGN.md は配色・フォント・スペーシング・コンポーネント仕様を Markdown で記述するファイル形式
- Google Stitch が提唱し、Claude Code・Cursor・Gemini CLI など主要 AI ツールでコンテキストとして活用できる
- プロジェクトルートに置くことで AI が生成する UI の一貫性向上が期待できる
- 既存サイトのデザインを DESIGN.md に変換するツールやコレクションも急速に充実
DESIGN.md はなぜ生まれたのか？
AIコーディングエージェントの進化に伴い、「コードの書き方」を指示するファイル形式は充実してきました。Cursor の .cursorrules、Anthropic の CLAUDE.md、Microsoft の AGENTS.md などがその代表例です。しかし、これらはすべて コードの振る舞い を定義するものであり、見た目の振る舞い については対応していませんでした。
DESIGN.md が解決するのは、まさにこの「ビジュアルデザインのコンテキスト不足」です。AI エージェントはプロンプトごとにゼロからデザイン判断を行うため、指示がなければ汎用的なデフォルトに落ち着きます。DESIGN.md をプロジェクトルートに配置することで、エージェントがそのファイルをコンテキストとして参照でき、ブランドに合った一貫した UI を生成しやすくなります。
AI 向けコンテキストファイルの系譜
| ファイル | 提唱元 | 対象領域 |
|---|---|---|
.cursorrules | Cursor | コーディングルール |
CLAUDE.md | Anthropic | プロジェクトコンテキスト全般 |
AGENTS.md | Microsoft（GitHub Copilot 向け） | エージェント向けコーディング規約 |
DESIGN.md | Google / Stitch | ビジュアルデザインシステム |
これらは競合ではなく補完関係にあります。CLAUDE.md や AGENTS.md が「どうコードを書くか」を伝え、DESIGN.md が「どう見せるか」を伝える——両方揃うことで、AI エージェントは機能面とデザイン面の両方で一貫した出力を実現します。
DESIGN.md の構成と主要セクション
DESIGN.md はプレーンな Markdown で記述します。JSON や YAML のような厳密なスキーマはなく、AI が自然言語として読み取れる形式です。Google Stitch の公式ドキュメントとコミュニティの実践から、以下の構成が標準化されつつあります。
1. ビジュアルテーマ（Overview）
プロジェクト全体のデザインの方向性を 2〜3 文で記述します。ミニマル、ダーク、グラスモーフィズムなどのキーワードを含めると、AI が全体のトーンを理解しやすくなります。
2. カラーパレット（Colors）
配色を 用途 + HEX コード + 説明 のセットで定義します。
## Colors
- **Primary** (#6366F1): メインブランドカラー。ボタン、リンクに使用
- **Secondary** (#EC4899): アクセントカラー。CTAやハイライトに使用
- **Background** (#0F172A): ページ背景
- **Surface** (#1E293B): カード、モーダルの背景
- **Text Primary** (#F8FAFC): 本文テキスト
- **Text Secondary** (#94A3B8): 補足テキスト
- **Success** (#10B981): 成功状態
- **Error** (#EF4444): エラー状態3. タイポグラフィ（Typography）
フォントファミリー、サイズ、ウェイト、行間を階層ごとに記述します。
## Typography
- **Font Family**: Inter, system-ui, sans-serif
- **Heading 1**: 48px, Bold (700), line-height 1.2
- **Heading 2**: 32px, Semibold (600), line-height 1.3
- **Body**: 16px, Regular (400), line-height 1.6
- **Caption**: 14px, Regular (400), line-height 1.44. スペーシングとレイアウト（Spacing & Layout）
基準単位とブレークポイントを定義します。
## Spacing
- Base unit: 8px
- Scale: 4, 8, 12, 16, 24, 32, 48, 64px
- Container max-width: 1280px
- Breakpoints: Mobile 640px, Tablet 768px, Desktop 1024px, Wide 1280px5. コンポーネントスタイル（Components）
ボタン、カード、インプットなど主要 UI 要素の具体的なスタイルを記述します。
6. エレベーション（Elevation）
シャドウ、ボーダー、グロー効果のレベルを定義します。
7. Do's and Don'ts
デザインのガードレールを明示します。このセクションがないと、AI はデフォルトの判断に頼ることになり、意図しないデザインが生成されやすくなります。
## Do's and Don'ts
### Do
- すべてのインタラクティブ要素に hover/focus 状態を付ける
- カード間のスペーシングを 24px に統一する
- アイコンは Lucide Icons を使用する
### Don't
- ドロップシャドウをインタラクティブ要素に使わない
- 本文テキストを中央揃えにしない
- 3色以上のグラデーションを使わないDESIGN.md の書き方：実践的な 3 ステップ
DESIGN.md を書くには、ゼロから手書きする方法と、既存サイトから抽出する方法の2つがあります。
ステップ 1: カラーとタイポグラフィから始める
デザインの一貫性に最も影響するのは配色とフォントです。まずこの 2 セクションだけで DESIGN.md を作成し、AI にいくつか UI を生成させてみましょう。それだけで出力の一貫性が大きく改善されることを実感できます。
ステップ 2: コンポーネントスタイルを追加する
ボタン、カード、インプットフィールドなど、プロジェクトで多用する UI 要素のスタイルを追加します。要素のサイズ、角丸、パディング、各状態（hover、disabled など）の見た目を明記します。
ステップ 3: ガードレール（Do's/Don'ts）を追加する
AI に「やってはいけないこと」を明示します。ガードレールがないと、AI は確率的に判断するため、プロンプトの微妙な違いでデザインが揺れます。
既存サイトから DESIGN.md を生成する
ゼロから書く必要はありません。以下のツールで既存サイトのデザインを DESIGN.md に変換できます。
- Google Stitch: URL を入力するだけでデザインシステムを抽出し、DESIGN.md を生成
- awesome-design-md: VoltAgent が公開する 58 ブランド分の DESIGN.md コレクション。Stripe、Vercel、Linear、Notion など著名サービスのデザインシステムが含まれる
- awesome-design-md-jp: 日本語サービスに特化した DESIGN.md コレクション（後述）
- getdesign.md: CLI ツール（
npx getdesign add [brand]）でブランドの DESIGN.md をプロジェクトに追加可能
注意: 既存サイトから抽出した DESIGN.md は、そのサイトの「現在の見た目」を反映したスナップショットです。サイトが更新されると乖離が生じるため、正規のデザイントークンをベースに作成するのが理想です。
DESIGN.md を書くときのベストプラクティスは？
効果的な DESIGN.md を書くためのポイントをまとめます。
具体的な値を使う。 「モダンな感じのブルー」ではなく #1A73E8 と書きます。AI は具体的な数値を最も正確に解釈します。
セマンティックに命名する。 色は HEX コードだけでなく、用途（Primary、Error、Surface など）で命名します。AI がコンテキストに応じた適切な色選択を行えるようになります。
簡潔に保つ。 DESIGN.md はフルのデザインシステムではありません。「このボタンはいつ使うべきか」という UX 判断は含めず、「このボタンの色、角丸、パディングは何か」という機械的な視覚情報に絞ります。
バージョン管理する。 Git でコミットし、PR でレビューします。デザインの変更履歴が残り、チームメンバーやAIエージェントが常に最新のデザインルールを参照できます。
段階的に育てる。 最初から完璧なファイルを目指す必要はありません。カラーとタイポグラフィから始めて、プロジェクトの成長とともにセクションを追加していくのが現実的です。
ダーク/ライトのデュアルテーマにはどう対応する？
多くの Web サイトがダークモードとライトモードの切り替えに対応していますが、DESIGN.md でデュアルテーマを表現する標準的な方法は まだ確立されていません。
Google Stitch の公式フォーマット仕様にもデュアルテーマの記法は定義されておらず、awesome-design-md に収録されているファイルも基本的に メインテーマ 1 つのみ を記述しています。Stripe はライトテーマのみ、Linear はダークテーマのみで書かれています。
ただし Linear の DESIGN.md には興味深いパターンがあります。ダークテーマをメインに記述しつつ、Colors セクション内に ### Light Mode Neutrals (for light theme contexts) というサブセクションで、ライトモードの一部カラーを補足的に追記しています。
現時点での実践的なアプローチ
デュアルテーマのサイトでは、以下のような書き方が考えられます。
## Colors
### Light Mode
- **Background** (#FFFFFF): ページ背景
- **Surface** (#F8FAFC): カード背景
- **Text Primary** (#0F172A): 本文テキスト
### Dark Mode
- **Background** (#0F172A): ページ背景
- **Surface** (#1E293B): カード背景
- **Text Primary** (#F8FAFC): 本文テキスト
### Shared (Theme-independent)
- **Primary** (#6366F1): ブランドカラー（両テーマ共通）
- **Error** (#EF4444): エラー状態（両テーマ共通）Colors セクション内を Light Mode / Dark Mode / Shared のサブセクションに分ける方式です。1 ファイルに収まり、AI が各テーマのコンテキストを理解しやすい構造になります。
デュアルテーマの DESIGN.md はまだ発展途上の領域です。今後 Google Stitch やコミュニティから標準的なパターンが提案される可能性があります。現時点では「メインテーマを軸に、サブテーマのカラーを補足する」アプローチが最も実用的です。
Google Stitch と DESIGN.md のエコシステム
DESIGN.md は Google Stitch のために生まれましたが、特定のツールに依存しない汎用フォーマットです。
Google Stitch とは
Stitch は Google Labs が提供する AI デザインツールです。2025年5月の Google I/O で発表されました。2026年3月のアップデートで DESIGN.md の導入、マルチスクリーン生成、インタラクティブプロトタイピングに対応し、大幅な機能強化が行われました。
Stitch ではプロンプトを送るたびに、プロジェクトの DESIGN.md が自動的にコンテキストとして付与されます。つまり、毎回「ブランドカラーは #6366F1 で...」と指定する必要がなくなります。
他ツールでの活用
DESIGN.md はプレーンな Markdown であるため、Stitch 以外の AI ツールでもそのまま使えます。
- Claude Code: プロジェクトルートに配置すれば、Claude が UI 関連のコード生成時にデザインルールを参照できる
- Cursor: プロジェクトコンテキストとして扱える場合がある
- Gemini CLI: コンテキストファイルとして指定可能
- GitHub Copilot: リポジトリ内のファイルとしてコンテキストに含められる
コミュニティの広がり
VoltAgent の awesome-design-md リポジトリは公開から数日で急速にスターを獲得し、58 ブランド分の DESIGN.md が MIT ライセンスで公開されています。getdesign.md や designmd.app など周辺ツールも続々と登場しており、エコシステムが急速に形成されています。
日本語サービス向け：awesome-design-md-jp
awesome-design-md は欧米サービスが中心ですが、日本語 UI には独自のタイポグラフィ要件があります。和文フォントのフォールバックチェーン、広い行間（line-height 1.5〜2.0）、禁則処理、OpenType 機能（palt、kern）、混植ルール（和文と欧文の組み合わせ）——これらの仕様が欠けていると、AI は壊れた日本語 UI を生成してしまいます。
awesome-design-md-jp は、この課題を解決するために作られた日本語サービス特化の DESIGN.md コレクションです。SmartHR、freee、note、無印良品、メルカリ、LINE、クックパッド、Qiita、Zenn など 24 サイト分の DESIGN.md が収録されています。
標準の 9 セクション構成を日本語タイポグラフィ向けに拡張し、Typography セクションに以下のサブセクションを追加しています。
- 和文フォント / 欧文フォント / font-family 指定（フォールバック込み）
- 文字サイズ・ウェイト階層 / 行間・字間
- 禁則処理・改行ルール / OpenType 機能 / 縦書き
日本語の Web サービスやアプリを AI で開発する場合、このコレクションをベースにすることで、AI が生成する日本語 UI の品質を大幅に改善できます。
よくある質問
Q. DESIGN.md を書くのにデザイナーの知識は必要ですか？
A. 必須ではありません。既存サイトから DESIGN.md を自動生成するツール（Google Stitch、getdesign.md）を使えば、デザインの専門知識がなくても始められます。awesome-design-md の既存テンプレートをベースにカスタマイズするのも効果的です。
Q. DESIGN.md と CSS 変数（カスタムプロパティ）はどう違いますか？
A. CSS 変数はブラウザが解釈する技術的な実装です。DESIGN.md は AI エージェントが解釈する自然言語のドキュメントです。両方を併用するのが理想で、DESIGN.md でデザイン意図を伝え、CSS 変数で実装を統一します。
Q. DESIGN.md を更新したら AI の出力はすぐ変わりますか？
A. はい。DESIGN.md がプロンプト時にコンテキストとして参照される場合、ファイルを更新すれば次の生成から反映されます。ただし、AI はガイドを確率的に解釈するため、ピクセル単位の完全な再現を保証するものではありません。
Q. Tailwind CSS のプロジェクトでも使えますか？
A. はい。DESIGN.md でデザイントークンを定義し、Tailwind の tailwind.config.js でそれを実装する使い方が推奨されます。AI は DESIGN.md を読んで適切な Tailwind クラスを選択できます。
Q. ダークモードとライトモードの両方があるサイトはどう書きますか？
A. 現時点で公式な標準はありません。実践的には、Colors セクション内を Light Mode / Dark Mode / Shared のサブセクションに分ける方法が有効です。タイポグラフィやスペーシングはテーマ間で共通のことが多いため、色のセクションだけ分ければ十分です。
Q. CLAUDE.md や AGENTS.md と一緒に使えますか？
A. はい。これらは補完関係にあります。CLAUDE.md / AGENTS.md が「コードの書き方」を指示し、DESIGN.md が「見た目のルール」を指示します。プロジェクトルートに両方を配置するのがベストプラクティスです。
まとめ
DESIGN.md は、AI エージェント時代における「デザインの共通言語」として急速に普及しつつあります。プレーンな Markdown という手軽さ、ツール非依存のポータビリティ、Git との親和性——これらの特性が、README.md や .gitignore のようなプロジェクトの標準ファイルになる可能性を示しています。
まずはカラーパレットとタイポグラフィの 2 セクションだけでも作成し、AI エージェントに UI を生成させてみてください。一貫性の違いを体感できるはずです。
ZenChAIne でも、AI エージェントを活用した開発プロセスの改善に取り組んでいます。DESIGN.md のようなツールを活用し、デザインと開発の橋渡しを効率化する方法を引き続き発信していきます。
参考ソース
- Design UI using AI with Stitch from Google Labs
- DESIGN.md — Stitch Documentation
- VoltAgent/awesome-design-md — GitHub
- What Is Google Stitch's Design.md File? — MindStudio
- AIがバラバラなUIを作る問題、これで解決？ Google提唱の新標準「DESIGN.md」とは — @IT
- クラメソのデザインガイドをDESIGN.mdで実装してみた — DevelopersIO
- awesome-design-md-jp — 日本語サービス向け DESIGN.md コレクション
- DESIGN.md files and the foundational patterns of AI-assisted design — Fifty Five and Five