この記事では 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秒でわかる全体像

3行でわかる design.md
① 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
出典: google-labs-code/design.md README(本文の節は、この順序で並べる)

最小のテンプレートは次のとおり。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. 1.置き場所と明示的な参照

    ルートに DESIGN.md があり、CLAUDE.md や .cursorrules から指しているか

  2. 2.長さ

    長すぎると前半が省略される。500〜800行に圧縮

  3. 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詳細レビュー(本サイト)