design.mdとは — 30秒でわかる全体像
① AIエージェント（Claude Code・Cursor等）に「一貫したUI」を作らせるための仕様書
② 色・フォント・余白・コンポーネントをMarkdownで記述し、プロジェクトルートに配置する
③ `README.md` が人間向けなのに対し、`DESIGN.md` は機械（AI）向け
AIにUIを作らせると、毎回違う色・違うフォントサイズ・違う余白のページが出てくる。「Stripeっぽく」と指示しても、AIが勝手に解釈した別物が返ってくる。この問題を解決するのがdesign.md — AIに読ませるためのデザイン仕様書フォーマットだ。
Google Stitchが先陣を切り、VoltAgentの awesome-design-md が58ブランド分のリアル実装を公開してエコシステムが急拡大した。実装例は awesome-design-md 関連記事（58ブランド対応レビュー）で確認できる。本記事は「どう書けばいいか」が分からない入門者向けの 設計思想と最小テンプレ に絞る。
なぜ今この仕様が必要になったのか
2025年以降、Claude CodeやCursorなどAIコーディングエージェントの普及で「AIにUIを書かせる」が日常化した。しかし従来の指示方法には3つの限界があった。
| 課題 | 従来のやり方 | 結果 |
|---|---|---|
| 色指定 | プロンプトに「Stripeっぽい紫で」 | 毎回微妙に違う紫が出る |
| フォント | 「モダンなサンセリフで」 | AIが知らないフォントを指定することも |
| 余白 | 「詰めすぎず、ゆとりをもって」 | AIが解釈で暴走 |
design.mdはこの曖昧性を仕様書で固定する。LLMのコンテキストウィンドウに直接取り込まれ、生成時に毎回参照される のでブレが激減する。
design.md の基本構造
design.mdはMarkdownだが、一定の規約がある。VoltAgent/awesome-design-mdに収録されている58ブランド分を分析すると、ほぼ以下の構造に収束する。
典型的な章立て
世界観・トーン"] A --> C["Color Palette
プライマリ・アクセント"] A --> D["Typography
フォント・サイズ・ウェイト"] A --> E["Spacing
余白・グリッド"] A --> F["Components
ボタン・カード・入力"] A --> G["Motion
アニメーション原則"] A --> H["Do & Don't
禁止事項"]
この構造をLLMが読み取り、各UIコンポーネントを生成する際に整合性を自動的に担保する。
最小テンプレート — 50行で始める
# DESIGN.md
## Brand Identity
- トーン: 端的・機能的・エンジニア向け
- 避けるべき表現: 過剰な装飾、不要なアニメーション
## Color Palette
- Primary: #0F172A（濃紺、背景）
- Accent: #E5835C（アクセント、CTA）
- Text primary: #F8FAFC
- Text secondary: #94A3B8
- Border: rgba(255,255,255,0.08)
## Typography
- Font family: 'Inter', 'Hiragino Sans', sans-serif
- Mono: 'JetBrains Mono', monospace
- Base size: 16px
- Heading scale: 32 / 24 / 20 / 18
## Spacing
- Base unit: 4px
- 余白は 8 / 12 / 16 / 24 / 32 / 48 / 64 に限定
- Gridは 8px 基準
## Components
### Button
- Padding: 10px 20px
- Border-radius: 8px
- Primary: Accent背景 + 白文字
- Secondary: 透明背景 + Border
### Card
- Padding: 24px
- Border-radius: 12px
- Border: 1px solid Border
- Hover: border-color を Accent の 40% 不透明度に
## Motion
- Transition: 150-200ms ease
- Hover scale: 1.02 まで
- 大きなスケール変化は禁止
## Do & Don't
❌ 禁止: 丸型ボタン、ネオン色、過度なシャドウ
✅ 推奨: シャープな矩形、モノトーン基調、抑制的なシャドウ
このテンプレを DESIGN.md としてプロジェクトルートに置くだけで、Claude CodeやCursorが自動検出する。最小50行でもAIの出力品質が劇的に安定する。
ファイル名の慣習
| ファイル名 | 意味 |
|---|---|
DESIGN.md |
最も一般的（Google Stitch準拠） |
design.md |
小文字版。同じ扱いを受ける |
docs/design-system.md |
大規模プロジェクトでdocs配下に配置 |
.claude/design.md |
Claude Codeのカスタムスキル配下 |
AIエージェントは大文字小文字を区別しないことが多いが、チームで統一する のがチーム内の可読性に効く。
AIエージェントでの読み込み方法
design.mdは、配置しただけで自動検出されるケースと、明示的にコンテキストに含める必要があるケースがある。
Claude Code での利用
Claude Codeの場合、プロジェクトルートの DESIGN.md は CLAUDE.md経由で参照されるのが確実。
# CLAUDE.md
## Design System
プロジェクト内で新しいUIを追加する際は、必ず @DESIGN.md を参照し、
色・タイポグラフィ・スペーシングの規約に従う。
新しい色やフォントを追加する必要がある場合は、DESIGN.mdに追記してから使う。
この2〜3行をCLAUDE.mdに追加するだけで、Claude Codeは毎回design.mdを読み込む。
Cursor / Cline での利用
Cursorの .cursorrules に以下を追加する。
When generating UI components, always reference ./DESIGN.md
for color palette, typography, spacing, and component patterns.
Do not invent new design tokens; only use those defined.
Google Stitch での利用
Google Stitchは DESIGN.md を自動検出するネイティブサポート。プロジェクトのルートに配置するだけで、プロンプトに含めなくても参照される。
design.mdを書いたのにAIが従わない場合、以下を確認:
① ファイル名が DESIGN.md / design.md か（拡張子が .txt じゃないか）
② プロジェクトルートまたは設定で指定したパスに配置されているか
③ LLMのコンテキストウィンドウが上限に達していないか（長すぎると省略される）
④ CLAUDE.md や .cursorrules で明示的に参照しているか
書き方の3原則
design.mdを書く際、初心者が陥りがちな失敗を避けるための3原則がある。
原則1: 具体値で固定、抽象語を使わない
❌ Primary color: ダークで落ち着いた青
✅ Primary color: #0F172A
AIは「ダークで落ち着いた」を解釈する自由度を持つ。色コードで固定すれば解釈の余地がゼロになる。
原則2: 禁止事項を明示する
## Do & Don't
❌ 禁止: グラデーション背景、ネオン色、丸型ボタン
✅ 推奨: 単色背景、抑制色、矩形ボタン
AIは「何をすべきでないか」を明示されない限り、平均的な学習データから「それっぽい」デザインを返す。禁止事項を書くとブランド独自性が際立つ。
原則3: 階層構造を浅く保つ
❌ 深すぎる階層
## Components
### Buttons
#### Primary
##### States
###### Hover
- ...
✅ 平坦構造
## Button Primary
- Background: ...
- Hover: ...
- Disabled: ...
LLMはMarkdownの深いネストを取り違えることがある。2〜3階層に抑えると出力精度が安定する。
よくある失敗と対処法
失敗1: design.mdが長すぎてコンテキスト圧迫
| 症状 | 原因 | 対処 |
|---|---|---|
| 生成されたUIがdesign.mdを無視する | 1000行超で前半が切り捨てられた | 500〜800行に圧縮、詳細は別ファイルへ |
| LLM応答が遅い | context windowの多くをdesign.mdが占有 | 使う色パレットだけをprompt injectする |
失敗2: フォント指定が効かない
❌ Font: 'Geist', sans-serif
# → Geist は多くのユーザー環境で未インストール
✅ Font: 'Geist', 'Inter', 'Hiragino Sans', sans-serif
# → フォールバックチェーンで代替
カスタムフォントはWebフォント読み込み設定も別途記述する。
失敗3: design.md を後から変えた際にAIが古いキャッシュを使う
Claude Codeは会話セッション内で同じファイルを何度も読み込みはしない。design.mdを更新したら 新しいセッションを開始 するか、明示的に再読み込みを指示する。
design.md と 他のフォーマットの比較
複数のデザイン定義フォーマットが共存しているため、使い分けを表で整理する。
| フォーマット | 形式 | AIエージェント直接読み込み | 主用途 |
|---|---|---|---|
| design.md | Markdown | ✅ プレーンMarkdown | AIコーディングエージェント向け |
| Figma Tokens | JSON | 変換必要 | Figma → コード連携 |
| Style Dictionary | JSON | 変換必要 | マルチプラットフォーム（Web / iOS / Android）同期 |
| Tailwind config | JavaScript | プロジェクト依存 | Tailwind利用プロジェクト |
| CSS Variables | CSS | 読み込めるが構造化が弱い | ブラウザランタイム |
design.md の強みは ゼロ依存・ゼロ変換・LLMが即座に解釈可能 という点にある。Figma TokensやStyle Dictionaryと併用し、「design.md が最小仕様、JSONが詳細仕様」と役割分担するチームも多い。
発展: 58ブランドの実装例と自作テンプレート
最小テンプレで始めたあと、より洗練された構造を求めるなら VoltAgent/awesome-design-md を見るとよい。Vercel・Stripe・Claude・Anthropic・Notion等58ブランドの実装が公開されている。
# 参考ブランドのdesign.mdを自プロジェクトにコピー
npx degit VoltAgent/awesome-design-md/brands/stripe/DESIGN.md ./DESIGN.md
# 58ブランド一覧を取得
git clone https://github.com/VoltAgent/awesome-design-md
cd awesome-design-md/brands
ls # vercel, stripe, claude, notion, ... 58件
① 本記事のミニマル50行テンプレから始める
② プロジェクトで5〜10回UIを生成し、AIが従わない箇所を見つける
③ 禁止事項・コンポーネント仕様を追記していく
④ 100〜200行の自分仕様になったら、[awesome-design-md](/agent/awesome-design-md/) のスタイルと比較して洗練
スキルとして配布する方法（Claude Code向け）
Claude Codeのカスタムスキルに組み込むと、プロジェクトをまたいで再利用できる。
# Claude Codeのskills配下にdesign.mdを配置
mkdir -p ~/.claude/skills/my-design-system
cp DESIGN.md ~/.claude/skills/my-design-system/DESIGN.md
# SKILL.md で定義を呼び出す
cat > ~/.claude/skills/my-design-system/SKILL.md <<'EOF'
---
name: my-design-system
description: 自社UIを生成する際の仕様を適用
---
このスキルが有効なとき、@DESIGN.md を必ず参照し、色・フォント・余白の規約に従うこと。
EOF
これで /my-design-system コマンドで任意のプロジェクトから呼び出せる。
まとめ
design.md は AIエージェント時代のデザイン仕様書 であり、Markdownというシンプルなフォーマットで「AIに一貫UIを生成させる」問題を解決する。
重要な3点を再確認する。
- 具体値で固定する — 「ダークな青」ではなく
#0F172A - 禁止事項を明示する — 「やるな」を書くとブランド独自性が出る
- 階層を浅く保つ — 2〜3階層で LLM の解釈ミスを防ぐ
最小50行のテンプレートから始め、必要に応じて拡張していくのが失敗しないアプローチ。58ブランドの実装例とnpxコマンドでコピーできる発展テンプレートは awesome-design-md レビュー記事 で確認できる。
AIコーディングの時代、プロジェクトルートに DESIGN.md を1ファイル置くかどうかで、生成UIの品質が段違いになる。まずは最小テンプレから始めてみてほしい。
