DESIGN.mdとは？ AIエージェントにデザインシステムを読ませるファイル

DESIGN.mdは、Google Stitchがオープンソースとして公開した、AIコーディングエージェント向けのデザインシステム用ファイル規約です。YAMLトークンとMarkdown本文の構造、lint·export CLI、Claude Code·Cursorとの連携方法、限界まで解説します。

SeokWoo LeeシニアiOSソフトウェアエンジニア公開 2026年8月9日更新 2026年8月27日読了 9 分

DESIGN.mdとは？ AIエージェントにデザインシステムを読ませるファイルのカバー画像

AIエージェントにUIを作らせたことがあるなら、こんな経験があるはずです。昨日作った画面は青いボタンに角丸だったのに、今日新しいセッションで作った画面は紫のグラデーションに角ばったボタン。同じプロジェクトなのに、画面ごとに別のブランドのアプリになっていきます。そこで毎回プロンプトに「ブランドカラーは#2563EB、角の丸みは8pxで…」とコピー＆ペーストします。

DESIGN.mdは、この問題を対象にしたファイル規約です。Google Labsは、自社のAI UIデザインツールStitchで使っていた形式を2026年4月21日にオープンソースとして公開しました（Google公式発表）。一言でいえば**「コーディングエージェントにビジュアルアイデンティティを説明する形式仕様」**です。プロジェクトリポジトリにMarkdownファイルを1つ置き、エージェントがUIを作るたびに読ませます。

プロンプトではなくファイルにする理由

ブランドルールをプロンプトに入れる方式の弱点は、揮発性です。セッションが終われば消え、チームメンバーごとに異なるバージョンのルールを持つことになります。リポジトリにコミットされたファイルは違います。

バージョン管理できます。 デザインルールの変更がGitの履歴に残り、PRレビューの対象になります。
コードと同じ場所にあります。 エージェントがコードを読む場所にデザインルールもあるため、別のツールやリンクなしでコンテキストに入ります。
ツールに依存しません。 プレーンテキストなので、Claude Code、Cursor、Copilotなど、どのエージェントでも読めます。

この発想自体は目新しくありません。エージェントに行動ルールを与えるCLAUDE.mdやAGENTS.mdが、すでに同じ原理で動いているからです。DESIGN.mdはその慣例をデザインシステムの領域まで広げました。CLAUDE.mdが「このプロジェクトでどう働くか」を記すなら、DESIGN.mdは「このプロダクトがどう見えるべきか」を記します。常時ロードするコンテキストの設計についてはCLAUDE.mdはなぜ短くすべきかで詳しく扱っています。

混同しやすい点が1つあります。spec-driven developmentのワークフローでrequirements.md → design.md → tasks.mdの順に作る「技術設計文書design.md」とは、名前が同じだけで別物です。この記事のDESIGN.mdはアーキテクチャ設計書ではなく、デザインシステム用ファイルです。

ファイル構造：機械が読むトークン＋人が読む散文

公式仕様によると、DESIGN.mdは2つの部分で構成されます。前半にはYAMLフロントマターで機械が読むデザイントークンを、後半にはMarkdown本文で人が読むデザインの意図を記します。

---
name: My Product
version: alpha
colors:
  primary: "#2563EB"
  surface: "#FFFFFF"
  onSurface: "#0F172A"
typography:
  headline:
    fontFamily: Pretendard
    fontSize: 28px
    fontWeight: 700
spacing:
  sm: 8px
  md: 16px
rounded:
  card: 12px
components:
  button:
    backgroundColor: "{colors.primary}"
    rounded: 8px
---

## Overview
落ち着きと信頼感のある金融サービス。華やかな装飾より情報の明瞭さを優先する.

## Colors
primaryは行動喚起要素にだけ控えめに使う。画面の 80%は surface 系で統一する.
...

ここに設計の核心が見えます。トークンが規範で、散文がコンテキストです。 colors.primary: "#2563EB"という値は、エージェントがそのまま従うべき正解です。「primaryは行動喚起要素にだけ控えめに使う」という散文は、その値をいつどこで使うか判断する根拠になります。色コードだけを渡せばエージェントはどこにでも塗り、雰囲気の説明だけなら色を勝手に選びます。だから両方を1つのファイルにまとめています。

仕様が定めるルールをいくつか見てみましょう。

フロントマターではnameが必須で、色は最低でもprimaryを1つ定義する必要があります。
トークン同士は{colors.primary}のようなパス参照でつなぎます。ボタンの背景色がprimaryを参照していれば、primaryを1か所変えるだけで連鎖的に反映されます。
本文にはOverview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do’s and Don’tsの8セクションが定義されています。すべて任意ですが、追加するセクションはこの順序に従う必要があります。
扱わない領域は、理由とともにomittedフィールドへ明記できます。「書かれていないもの」と「意図的に省いたもの」をエージェントが区別するための仕組みです。

Google Stitchが公開したDESIGN.md発表画像と、エディターで開かれたファイル画面 — Stitchチームが公開した発表画像です。エディターで開く普通のMarkdownファイルであることがポイントです。

検証ツールまである理由

形式仕様だけでなく、公式CLIツール（@google/design.md、Apache-2.0ライセンス）も同時に公開されました。コマンドは4つです。

コマンド	処理内容
`lint`	ファイル構造の検証＋トークン参照の検査＋WCAGコントラスト比の検査
`diff`	2つのバージョンを比較し、トークン単位の変更を報告
`export`	トークンをTailwind設定またはW3C DTCG形式へ変換
`spec`	仕様全文を出力—エージェントのプロンプトへ注入する用途

lintが興味深いところです。色の値を内部でsRGBに変換し、WCAG（Web Content Accessibility Guidelines、ウェブコンテンツ・アクセシビリティ・ガイドライン）のコントラスト比を検査します。エージェントが「それらしく見える」色の組み合わせを作っても、アクセシビリティ基準に達しなければ機械的に弾けます。デザインルールの遵守をエージェントの誠実さに任せず、CIで検証できる形にしたわけです。Googleも公開文書でこの点を強調しています。公式発表の表現を借りれば、目標はエージェントが推測するのではなく「色の用途を正確に理解し、選択をWCAGアクセシビリティルールと照合して検証できるようにする」ことです。

exportでTailwind設定を取り出せる点も、実務では重要です。DESIGN.mdを単一の情報源とし、実際のCSS設定をそこから派生させる構成が可能になります。

実際の使い方

始め方は2つあります。

Stitchで生成する。 Stitchでデザインを作成すると、DESIGN.mdファイルとして書き出せます。いくつかの画面をデザインし、そのビジュアル言語をファイルに抽出して、コーディングエージェントに渡す流れです。

手で書く。 普通のMarkdownなので、エディターで直接書けます。すでにデザイントークンを整理しているチームなら、既存のトークンをフロントマターへ移し、デザインガイドの「なぜ」にあたる部分を本文セクションへ移します。

ファイルを作ったらリポジトリのルートに置き、エージェントに参照させます。ここで注意が1つ。DESIGN.mdはCLAUDE.mdのように、エージェントが自動的にセッションへロードするファイルではありません。まだアルファ段階の新しい規約なので、CLAUDE.mdやAGENTS.mdに「UI作業時は先にDESIGN.mdを読み、トークンに従うこと」のような一文を追加して接続するのが確実です。UI作業のないセッションまでデザインシステム全体でコンテキストを消費する必要はないため、常時ロードではなく必要時に読ませる方がコンテキストコストの面でも優れています。

DESIGN.mdのYAMLトークンとMarkdown本文が、コーディングエージェントとCLI検証につながる流れを示す図 — トークンと散文が1つのファイルからエージェント側とCLI検証側へ分かれて流れる構造です。

限界と展望

冷静に見ておきたい点もあります。

まだアルファです。 仕様のversion値自体が「alpha」で、フィールド構成も変わり得るドラフト段階です。今導入するなら、仕様変更を追う覚悟が必要です。

エージェントの遵守は依然として確率的です。 ファイルにトークンをどれほど正確に書いても、エージェントがそのまま従うとは限りません。結局はLLMの指示遂行だからです。CLAUDE.mdの指示が時々無視されるのと同じ原理です。そこでlintのような決定的な検証ツールがセットで公開されました。実運用でも「ファイルで指示＋CIで検証」を1つの組み合わせとして考える必要があります。

カバー範囲はまだ狭いです。 現在の仕様は色・タイポグラフィ・間隔・角・コンポーネントが中心です。モーション、アイコンセット、レスポンシブブレークポイントなどは本文の散文で記述できますが、トークンスキーマはありません。

それでも方向性は明確です。エージェントに与えるコンテキストをプロンプトではなく、リポジトリでバージョン管理されるファイルへ移す流れは、CLAUDE.md、AGENTS.mdに続いてデザイン領域にも届きました。ツールが変わってもファイルは残るため、特定のエージェントに依存しない投資でもあります。UIの一貫性のためにプロンプトへブランドルールをコピーしていたなら、まずその内容を1つのDESIGN.mdファイルへ移してみてください。

出典と確認基準

Stitch's DESIGN.md format is now open-sourceGoogle (2026-04-21) · 公式発表 · 確認日 2026年8月8日根拠: DESIGN.mdのオープンソース公開、公開の目的（エージェントが色の用途を理解し、WCAG検証を行えること）、Stitchでの生成サポート
google-labs-code/design.mdGoogle Labs · 公式ドキュメント · 確認日 2026年8月8日根拠: Apache-2.0ライセンス、アルファ版の状態、@google/design.md CLIのlint·diff·export·specコマンドと機能
DESIGN.md SpecificationGoogle Labs · 標準・仕様 · 確認日 2026年8月8日根拠: フロントマターのフィールド構成（name必須、primaryカラー必須）、本文の8セクション、トークン参照構文、omittedフィールド、WCAGコントラスト比の検査方法