DESIGN.mdとは？Google発のAI向けデザイン仕様を解説

DESIGN.md は、AI コーディングエージェントにブランドの見た目とデザインシステムを伝えるための、プレーンテキストの形式仕様です。Google Labs のデザインツール Stitch が導入し、2026 年 4 月 21 日にドラフト仕様がオープンソースとして公開されました。この記事では、ファイルの構造、公式 CLI でできること、仕様が置いている思想、AI コーディングエージェントに読ませる方法、そして gaipack が実案件と自社サイトで運用してわかった「DESIGN.md 1 本では足りなかったこと」を解説します。

DESIGN.mdとは何か

仕様書の冒頭は、DESIGN.md を「デザインシステムの自己完結したプレーンテキスト表現」と定義しています。ブランドと製品の視覚的アイデンティティを定義し、デザインのセッションをまたいでも、異なる AI エージェントやツールの間でも、同じ様式が守られるようにするためのファイルです。人間にもモデルにも読める形式なので、両者が同じ文書を読み、同じ文書を直せます。

セッションごとに見た目がぶれる問題

AI コーディングエージェントに UI を作らせると、ページごとにボタンの色が違う、余白の取り方が画面ごとに変わる、といった統一感の崩れが起きます。原因の 1 つは、エージェントがデザインの意図を毎回推測していることです。Google の公式ブログは、DESIGN.md があれば「意図を推測する代わりに、エージェントはその色が何のためにあるかを正確に知り、WCAG のアクセシビリティ基準に照らして自分の選択を検証できる」と説明しています。

gaipack でも同じ課題に向き合ってきました。AIDD デザインのサービス定義には、「AI に UI の自動生成を任せると統一感がなく意図しないデザインになり、AI が参照できる信頼できるデザインシステムが存在しない」という課題が起点として書かれています。当初は Figma と MCP で参照基盤を作る前提で検証を進めましたが、解釈の精度と運用コスト、ツール依存の観点で限界があり、DESIGN.md の登場を機に Markdown で直接渡す方式へ移りました。

Stitch との関係と公開までの経緯

DESIGN.md はもともと、Google Labs の AI デザインツール Stitch の機能として 2026 年 3 月に登場しました。Stitch ではプロジェクト間でデザインルールを書き出したり取り込んだりするために使われます。同年 4 月 21 日、Google はドラフト仕様をオープンソースとして公開し、Stitch 以外のツールやプラットフォームでも使えるようにしました。

リポジトリ自体も .agents/skills/ に TDD や CLI 設計のスキルを置いて開発されており、エージェントに読ませる前提で作られた仕様であることが構成からも分かります。

alpha である点は、導入判断で押さえておきたい前提です。リリースごとに export 形式の名前が変わる（0.2.0 で tailwind が json-tailwind に改名され、旧名は互換エイリアスとして残る）、front matter のキーが増える（0.4.0 で omitted が追加）といった変化が続いています。

DESIGN.mdとはどんな構造か：YAML トークンと Markdown 本文の 2 層

DESIGN.md は 1 つのファイルの中に、機械が読む層と人が読む層を持ちます。前半の YAML front matter にデザイントークン（値）を、後半の Markdown 本文にその値をどう使うかの根拠と規則を書きます。

仕様は「トークンが規範となる値で、散文はそれをどう適用するかの文脈を与える」と役割を分けています。本文の中では「Midnight Forest Green」のような説明的な色名を使ってよく、それが primary のような体系的なトークン名に対応する、という関係です。

前半：YAML front matter に書くトークン

front matter は省略可能で、書く場合は --- で囲みます。スキーマで定義されているキーは次のとおりです。

トークンの体系は W3C Design Tokens 仕様を下敷きにしており、{colors.primary} のように波括弧で他のトークンを参照できます。components の中では {typography.label-md} のような複合値の参照も許されます。仕様書は、この形式なら tokens.json、Figma の変数、Tailwind のテーマ設定と相互に変換しやすい、と述べています。

---
version: alpha
name: Daylight Prestige
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
---

後半：決まった順序で並べる 8 つの章

本文は ## 見出しの章で構成し、章の順序が決まっています。使わない章は省略できますが、書く場合はこの順に並べます。

1. Overview（Brand & Style とも呼ぶ）
2. Colors
3. Typography
4. Layout（Layout & Spacing とも）
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

Overview には、ブランドの性格、対象ユーザー、UI が呼び起こすべき感情（遊び心があるか、専門的か、密か、余白が多いか）を書きます。仕様はこの章を「特定の規則やトークンが定義されていないときに、エージェントの高レベルな様式判断を導く基礎的な文脈」と位置づけています。Do's and Don'ts は、トークンでは表現できない禁止事項と推奨事項を並べる章です。

拡張：仕様にない内容を書いたときの扱い

仕様書の末尾には「未知の内容に対する消費側の振る舞い」の表があり、拡張の余地が明示されています。

つまり、8 章の外に自分たちの章を足してよく、トークン名も自由に増やせます。後述の gaipack のファイルは、この規定に沿って Motion やロゴの章を追加しています。

PHILOSOPHY.md が示す思想：値より散文を重んじる

0.3.0 で追加された PHILOSOPHY.md は、この仕様が何を大事にしているかを述べた文書です。冒頭で、DESIGN.md は見た目・感触・振る舞いを捉えるものであり、散文こそがデザインの居場所で、文書の他の部分はそれを支えるために存在する、と宣言しています。

The quality of a generated design is determined less by the precision of its values than by how clearly the intent is described.

（生成されるデザインの品質を決めるのは、値の精度よりも、意図がどれだけ明確に記述されているかである。出典: google-labs-code/design.md PHILOSOPHY.md）

同文書は、トークンの値は文脈であって描画命令ではない、とも書いています。仕様書側の「トークンが規範値」という記述と読み合わせると、値そのものはトークンに置き、その値をいつ・どこで・なぜ使うかは散文で書く、という分担になります。

形容詞の列挙より、具体的な参照が多くを伝える

PHILOSOPHY.md の例が分かりやすいので紹介します。「1970 年代の、伝統ある大学の大学院講義配布資料」という 1 文は、1 色のインク、広い余白、読みやすいサイズのセリフ体、装飾の不在といった世界をまるごと呼び出します。一方「モダン、クリーン、信頼できる、プレミアム」という形容詞は、その語が指す領域の中心にある平均的なものを生むだけで、特定の何かを指しません。形容詞は領域を、具体的な参照は点を記述する、という整理です。

否定的な制約についても同じ論法です。参照が十分に具体的なら、「光らない」「グラデーションを使わない」といった禁止事項は自動的についてきます。Do's and Don'ts の長い列挙は、参照が曖昧だった兆候かもしれない、と PHILOSOPHY.md は指摘しています。

公式 CLI でできること：lint・export・diff・spec

@google/design.md パッケージには 4 つのコマンドがあります。Node.js 18 以上があれば npx で実行できます（Windows の PowerShell では .md の関連付けと衝突するため、designmd という別名が用意されています）。

npx @google/design.md lint DESIGN.md
npx @google/design.md lint --format json DESIGN.md
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md diff DESIGN.before.md DESIGN.after.md
npx @google/design.md spec --rules-only

lint のルールのうち、エラーになるのは壊れた参照（broken-ref）だけで、残りは警告と情報です。コントラスト比の検査は components の backgroundColor と textColor の組に対して行われ、WCAG AA の 4.5:1 を下回ると警告します。0.4.0 からは、export の終了コードが lint の警告から切り離され、警告が残っていても変換結果はパイプラインを通るようになりました。

公開中の DESIGN.md に lint をかけてみた結果

gaipack は自社サイトのデザインシステムを DESIGN.md として公開しています。1,082 行のこのファイルに 0.4.0 の lint を実行すると、結果は次のとおりでした。

読み取れることが 2 つあります。1 つは、コンポーネントの枠線色（borderColor）を仕様がまだ認識しないので、自分たちの拡張として使うなら警告を受け入れる判断が要ることです。もう 1 つは、透明度つきの背景色に対してコントラスト比が正しく計算されない点で、この 3 件は実際の表示とは異なる警告でした。lint の警告はそのまま直す対象ではなく、仕様の alpha 段階を踏まえて 1 件ずつ判断するのが現実的です。一方で、番号つきの見出し（## 1. Overview）や 8 章の後に追加した Motion・ロゴ・ガバナンスの章は、警告なしで通りました。

AI コーディングエージェントに DESIGN.md を読ませる方法

DESIGN.md はリポジトリの直下に置きます。Claude Code、Cursor、GitHub Copilot、Gemini CLI など、ファイルを読めるコーディングエージェントならどれでも使えます。ただし、多くのコーディングエージェントは DESIGN.md を自動では読みません。エージェントが起動時に読むのは AGENTS.md や CLAUDE.md のようなプロジェクト指示ファイルなので、そこに「UI を実装する前に DESIGN.md を読む」と参照順序を書くか、依頼のたびに @DESIGN.md のようにファイルを指定して渡します。

Stitch を使う場合は、Google が公開している stitch-skills に、既存の Stitch プロジェクトの画面から DESIGN.md を合成するスキルが含まれています。Agent Skills の標準形式なので、Claude Code・Gemini CLI・Cursor などから利用できます。

すでに公開されているブランドのデザインを参考にしたい場合は、DESIGN.md のカタログが複数あります。GitHub の VoltAgent/awesome-design-md（2026 年 9 月 10 日時点でスター数 115,046）や日本語 UI 向けの kzhrknt/awesome-design-md-jp、Web カタログの designmd.ai などです。ただし、他社ブランドの配色やロゴの扱いは各社のブランドガイドラインと利用規約の範囲で判断する必要があります。カタログの DESIGN.md は書き方の参考として読み、自社の値は自社で決めるのが安全です。

DESIGN.md 1 本では足りなかったこと：gaipack の 4 点構成

gaipack は当初、DESIGN.md 1 本にデザインシステムを集約して運用していました。そこに画面レイアウトの話やコンポーネントの使い方を足していくと、中身の大半が視覚トークン以外で埋まり、AI にモックを作らせたときにつまずく箇所は値ではなく判断に集中するようになりました。

判断ルールを DESIGN.md に足すと、機械が読む YAML の層と人が読む本文の層が混ざり、値を確認したいのに散文が挟まる状態になりました。そこで役割ごとにファイルを分けたのが、現在の 4 点構成です。

4 点のうち Google の公開仕様に準拠しているのは DESIGN.md だけで、残りは gaipack が運用の中で分離した構成です。似た分け方は各所で生まれつつありますが、標準化された仕様があるわけではありません。

読ませる順序と、判断の余地を減らす仕掛け

AI に UI を実装させるときは、次の順序で読ませます。

読む前にコードを書かせない、というのがこの順序の趣旨です。あわせて、AGENTS.md には規範同士が矛盾したときの優先度表、規範にない UI を検出したら作業を止めて人に確認する停止プロセス、要件にない検索バーや通知アイコンを足すことを名指しで禁じるリストを置きます。DESIGN.md 側には「適切な色を選ぶ」という指示を禁じ、条件から使うトークンが一意に決まる対応表を置きます。いずれも AI に良い判断をさせるのではなく、判断の余地そのものを減らす方向の設計です。

運用で役立った原則も 1 つ挙げておきます。同じ情報を 2 か所に書かないことです。先行案件では、DESIGN.md から自動生成した CSS と手書きの CSS で同じトークンが二重定義され、後に書いた手書きが優先されて「DESIGN.md にある文字サイズと画面に適用されている値が違う」事態が起きました。エラーが出ないので気づきにくく、現在は自動生成の範囲をマーカーで囲んで手編集を禁止しています。

公開サンプルと関連する実践

gaipack サイトは自身のデザインシステムをこの構成で公開しています（DESIGN.md / COMPONENTS.md / PATTERNS.md / AGENTS.md / CHANGELOG.md）。2026 年 9 月 3 日に、それまで 1 本だった DESIGN.md をこの 5 ファイルへ再構成した記録も CHANGELOG.md に残っています。サイトを Claude Code でデュアルテーマ化した際の進め方はダークモード固定だった gaipack サイトを、Claude Code と 3 日でデュアルテーマ化しましたに、Figma Make で画面を作る前に 4 つの .md ファイルで AI の揺らぎを抑えた実践はFigma Make でワイヤーフレームを作る前の下準備にまとめています。

サービスとしての提供内容は AIDD デザインを、AI が参照できるデザインシステムで開発工数を短縮した事例は商業施設向け DX システムの導入事例とマスタ管理システムの導入事例を参照してください。

DESIGN.md と AGENTS.md・Figma・tokens.json の違い

デザインを AI に伝える手段は DESIGN.md だけではありません。役割の違いで整理します。

DESIGN.md が担うのは、値と根拠を 1 か所に置くことです。値だけなら tokens.json で足り、手順だけなら AGENTS.md で足ります。両方を人とモデルが同じ文書で読めることが、この形式を選ぶ理由になります。

DESIGN.mdとは何かに関するよくある質問

導入を検討するときによく出る質問に、仕様と運用の範囲で答えます。

Awesome DESIGN.md はどう使えばよいですか

VoltAgent/awesome-design-md をはじめとするカタログには、有名ブランドやツールの見た目を分析して書き起こした DESIGN.md が集まっています。使い方は、ファイルをリポジトリに置いてエージェントに参照させるだけです。ただし、他社の配色やロゴをそのまま自社の製品に使うことは、各社のブランドガイドラインや利用規約に照らして判断が必要です。章の分け方、Do's and Don'ts の書きぶり、Overview の具体性の水準を学ぶ材料として読み、値は自社で決めることをおすすめします。

DESIGN.md と AGENTS.md はどう違いますか

DESIGN.md は「見た目の値と根拠」の正本で、AGENTS.md は「AI がどう作業するか」の正本です。なお、海外の記事には、同じ DESIGN.md という名前で「コードをなぜそう設計したか」を記録するファイルを指すものもあります。こちらは Google の仕様とは無関係の慣習で、lint も存在しないので、検索で混同しないよう注意してください。gaipack では、AGENTS.md に PRD → PATTERNS.md → COMPONENTS.md → DESIGN.md の参照順序を書き、DESIGN.md には視覚の規則だけを書いて、実装手順や停止条件を混ぜないようにしています。

Claude Code や Cursor で DESIGN.md を読ませるにはどうしますか

自動では読まれないので、CLAUDE.md や AGENTS.md などプロジェクト指示ファイルに「UI を実装する前に DESIGN.md を読む」と参照順序を書くか、依頼時に @DESIGN.md のようにファイルを明示します。Google の stitch-skills には、Stitch のプロジェクトから DESIGN.md を合成する Agent Skills 形式のスキルも含まれています。

DESIGN.md があれば Figma は不要になりますか

トークンの定義と、その使い方の記述は DESIGN.md に寄せられます。gaipack の現行フローでは全画面の Figma デザイン作成を前提にせず、PRD と規範ドキュメントから AI が UI モックを生成します。ただし、新しいコンポーネントの視覚的な検討や複雑なレイアウトの試作では Figma を補助的に使い、確定したルールを規範ドキュメントに書き戻しています。

仕様が alpha でも導入してよいですか

gaipack は alpha の段階で実案件と自社サイトに導入しています。リリースごとに export 形式の名前や front matter のキーが変わるので、CLI のバージョンを固定し、lint の警告は 1 件ずつ判断する運用にしています。形式そのものは Markdown と YAML なので、仕様が変わってもファイルが読めなくなることはありません。

まとめ

• DESIGN.md は、AI コーディングエージェントにデザインシステムを伝えるための Google Labs 発のオープンな形式です。2026 年 3 月に Stitch の機能として登場し、4 月 21 日にドラフト仕様が公開されました。状態は alpha です
• 前半の YAML にトークン（値）を、後半の Markdown に 8 つの章で根拠と規則を書きます。値はトークンに、意図は散文に置くのが仕様の思想です
• 公式 CLI の lint は 11 ルールで構造を検査し、export は Tailwind・DTCG・CSS 変数へ変換します。gaipack の公開 DESIGN.md では error 0 件、warning 48 件で、alpha ゆえに判断が要る警告も含まれていました
• 画面が増えると DESIGN.md 1 本では判断のぶれを抑えきれません。gaipack はコンポーネント・画面パターン・AI の作業手順を別ファイルに分け、判断の余地を減らす方向で運用しています

DESIGN.md を起点にしたデザインシステムの構築と、AI による UI 生成フローの立ち上げは AIDD デザインで支援しています。AI 駆動開発の全体像は AI駆動開発の記事をあわせてご覧ください。