この記事では design.md に絞って、作り方とサンプルの探し方を説明します。AIエージェント全般は AIエージェントフレームワーク比較2026|LangGraph・CrewAI・Dify等9種をStar数・実コードで検証 をご覧ください。
AIにUIを作らせると、毎回違う色・違う余白のページが出てくる。「Stripeっぽく」と頼んでも、AIが勝手に解釈した別物が返る。これを防ぐデザイン仕様書のフォーマットが design.md だ。
VAGUE VS FIXED指示の置き換え
曖昧な言葉を、design.mdの具体値に置き換える
プロンプトの言い方
design.md に書く値
プロンプトの言い方: Stripeっぽい紫で
design.md に書く値: Accent: #E5835C
プロンプトの言い方: モダンなサンセリフで
design.md に書く値: Inter, Hiragino Sans, sans-serif
プロンプトの言い方: ゆとりをもって
design.md に書く値: 余白は 8 / 12 / 16 / 24 / 32 に限定
プロンプトの言い方: 派手にしない
design.md に書く値: 禁止: ネオン色・過度なシャドウ
design.mdとは — 30秒でわかる全体像
① AIエージェント(Claude Code・Cursor等)に一貫したUIを作らせる仕様書
② 色・フォント・余白・コンポーネントを書き、プロジェクトルートに置く
③ README.md が人間向けなのに対し、DESIGN.md はAI向けの実装値を持つ
Google Stitchが先陣を切り、Google Labsが仕様をOSS(google-labs-code/design.md)として公開した。ブランド別のサンプルは VoltAgent/awesome-design-md に集まり、2026-08-06時点で74ブランド・★107,036になっている(この数字は8月の実測値で、今回は再取得していない)。収録の中身は awesome-design-mdの詳細レビュー にある。
| 課題 | 従来のやり方 | 結果 |
|---|---|---|
| 色 | 「Stripeっぽい紫で」 | 毎回微妙に違う紫になる |
| フォント | 「モダンなサンセリフで」 | AIが知らないフォントを指定する |
| 余白 | 「ゆとりをもって」 | 解釈で暴走する |
design.mdはこの曖昧さを具体値で固定する。LLMのコンテキストに入り、生成のたびに参照される。
design.mdの作り方 — 最小テンプレートとファイル構造
design.mdは2層でできている。上部の YAML front matter が機械の読むトークン、下部の Markdown 本文が「なぜその値か」の説明だ。README の仕様では、本文の節は Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do’s and Don’ts の順に並べる(省略は可)。
TWO LAYERSファイルの2層構造
上は機械が読むトークン、下は人とAIが読む理由
YAML front matter
正確な値(lint の対象)
- colors / typography
- rounded / spacing
- components({colors.accent} で参照)
Markdown 本文
なぜその値かの説明
- Overview → Colors → Typography
- Layout → Elevation → Shapes
- Components → Do's and Don'ts
最小のテンプレートは次のとおり。components では {colors.accent} のようにトークンを参照できる。
---
name: Minimal
colors:
primary: "#0F172A"
accent: "#E5835C"
text: "#F8FAFC"
typography:
body-md:
fontFamily: Inter
fontSize: 1rem
rounded:
md: 8px
spacing:
md: 16px
components:
button-primary:
backgroundColor: "{colors.accent}"
textColor: "{colors.primary}"
rounded: "{rounded.md}"
---
## Overview
端的・機能的。装飾は最小限。
## Colors
- **Primary (#0F172A):** 背景
- **Accent (#E5835C):** CTAのみ
## Do's and Don'ts
- 禁止: 丸型ボタン、ネオン色、過度なシャドウ
- 推奨: 矩形、モノトーン基調
このテンプレートを保存して npx @google/design.md lint DESIGN.md を実行すると、エラー0件・警告1件(text がどのコンポーネントからも参照されていない、という orphaned-tokens)が返った(2026-10-15 実行)。lint は壊れたトークン参照やWCAGのコントラスト比も検査する。
| ファイル名 | 意味 |
|---|---|
DESIGN.md |
最も一般的(Google Stitch準拠) |
design.md |
小文字版 |
docs/design-system.md |
大規模プロジェクトで docs 配下に置く |
design.mdのサンプルと書き方の3原則
サンプルを見るなら awesome-design-md が早い。ブランドごとに design-md/<ブランド名>/DESIGN.md がある。以前の brands/ というパスは404になっており、ネットの古い解説をコピペすると失敗する。
# 参考ブランドのDESIGN.mdをコピー(2026-08-06 動作確認。raw URL はいまも200)
npx degit VoltAgent/awesome-design-md/design-md/stripe/DESIGN.md ./DESIGN.md
# 上でコピーした実物を Google の lint にかける
npx @google/design.md lint DESIGN.md
stripe のサンプルは先頭が YAML front matter で、colors・typography・components などを持つ。lint にかけるとエラー0件・警告11件だった(2026-10-15、警告の中身までは精査していない)。つまりサンプルも YAML トークン形式で、lint が通る。日本語UI向けの拡張は awesome-design-md-jp にまとめてある。
書くときの原則は3つ。
・具体値で固定する:「ダークな青」ではなく #0F172A。抽象語は解釈の余地を残す
・禁止事項を書く:「何をしないか」を書かないと、AIは平均的な学習データの「それっぽい」デザインを返す
・階層を浅く保つ:深いネストはLLMが取り違えることがある。2〜3階層にする
フォントはフォールバックも書く。Geist だけだと未インストール環境で崩れるので、'Geist', 'Inter', 'Hiragino Sans', sans-serif のように連ねる。
design.mdをAIに読み込ませる方法とつまずき
置いただけで読まれるとは限らない。Claude Code では CLAUDE.md から明示的に参照するのが確実だ。
## Design System
新しいUIを追加するときは @DESIGN.md を参照し、色・タイポグラフィ・余白の規約に従う。
新しい色やフォントが要る場合は、DESIGN.md に追記してから使う。
Cursor は .cursorrules に「UI生成時は ./DESIGN.md を参照し、定義済みトークン以外を作らない」と書く。Google Stitch は DESIGN.md をネイティブに扱う。
従わないときは、次の順で疑う。長すぎる場合の目安は500〜800行への圧縮で、詳細は別ファイルに分ける。
NOT FOLLOWED?従わないとき
AIが従わないときは、読まれていないところから疑う
-
1.置き場所と明示的な参照
ルートに DESIGN.md があり、CLAUDE.md や .cursorrules から指しているか
-
2.長さ
長すぎると前半が省略される。500〜800行に圧縮
-
3.セッション
更新したら新しいセッションで読み直させる
design.mdと他のフォーマットの比較
| フォーマット | 形式 | AIが直接読めるか | 主用途 |
|---|---|---|---|
| design.md | YAML+Markdown | 読める | AIコーディングエージェント向け |
| Figma Tokens | JSON | 変換が必要 | Figma → コード連携 |
| Style Dictionary | JSON | 変換が必要 | Web / iOS / Android の同期 |
| Tailwind config | JavaScript | プロジェクト依存 | Tailwind 利用プロジェクト |
| CSS Variables | CSS | 読めるが構造が弱い | ブラウザ実行時 |
design.md の強みは、依存ゼロでLLMが直接読めることと、値と理由を1ファイルに持てることだ。JSON系と併用し、design.md を最小仕様にするチームもある。
まとめ
design.md は、AIにUIを作らせるときの曖昧さを具体値と禁止事項で潰す仕様書だ。最小テンプレートを書き、lint で検証し、CLAUDE.md や .cursorrules から参照させる。うまくいかなければ置き場所・参照・長さ・セッションの順に疑う。
サンプルは awesome-design-md、日本語UIは awesome-design-md-jp から入るとよい。
参照ソース
・google-labs-code/design.md(仕様とlint CLI)
・VoltAgent/awesome-design-md(ブランド別サンプル)
・Google Stitch
・awesome-design-md詳細レビュー(本サイト)





