「Claude Code で UI コンポーネントを作ってもらうたびに、色もフォントも毎回バラバラになる」——そんな悩みを解決するのが design.md です。

Google Labs が提唱したこのフォーマットを使えば、プロジェクトのカラーパレット・タイポグラフィ・コンポーネントルールを一か所にまとめ、Claude に「このプロジェクトの顔」を伝えることができます。

本記事では design.md の概要から、実際の書き方・Claude Code での参照方法・CLAUDE.md との使い分けまでを網羅的に解説します。

スポンサーリンク

目次

1. design.md とは何か
2. なぜ design.md が必要なのか
3. design.md の構成（9セクション）
4. 実際の書き方とサンプル
5. Claude Code での使い方
6. CLAUDE.md との違い・使い分け
7. awesome-design-md の活用法
8. まとめ

1. design.md とは何か

design.md は Google Labs が提唱したマークダウン形式のデザイン仕様書です。AIコーディングエージェントに対して、プロジェクトのビジュアルアイデンティティ（色・フォント・コンポーネントの見た目）を構造化された形式で伝えることを目的としています。

Claude Code の公式機能ではない

まず重要な点として、design.md は Claude Code の組み込み機能ではありません。CLAUDE.md のように自動読み込みされるわけではなく、あくまでも「AIエージェントに伝わりやすい構造でデザイン情報をまとめる命名規則」です。

その分、使い方の自由度が高く、Claude Code 以外の AI ツール（Cursor・Copilot・Gemini CLI）でも同じファイルを流用できます。

2. なぜ design.md が必要なのか

AI 生成 UI の「毎回バラバラ問題」

Claude Code に「ボタンを作って」「カードコンポーネントを追加して」と頼むたびに、微妙に異なるスタイルが生成されることがあります。これは Claude がプロジェクトのデザインシステムを知らないまま、そのとき最も自然と判断した UI を出力しているためです。

design.md で解決できること

design.md にプロジェクトのデザインルールを一度書いておけば、プロンプトで @design.md と参照するだけで Claude がそのルールに従った UI を生成します。「毎回説明するコスト」が消え、デザインの一貫性が保たれます。

3. design.md の構成（9セクション）

Google Labs の仕様では、design.md は以下の9つのセクションで構成されます。すべてを書く必要はなく、プロジェクトに必要なものだけ記述します。

4. 実際の書き方とサンプル

最小構成の例（Webサービス向け）

まずは Color Palette・Typography・Components の3セクションだけで始めるのが現実的です。

# Design System

## Visual Theme
クリーンでプロフェッショナルな印象。余白を広く取り、
情報密度より可読性を優先する。アクセントはインディゴ。

## Color Palette

| Role       | Value     | Usage                      |
|------------|-----------|----------------------------|
| Primary    | #4f46e5   | ボタン・リンク・アクティブ状態    |
| Secondary  | #7c3aed   | グラデーション・アクセント       |
| Background | #f8fafc   | ページ背景                   |
| Surface    | #ffffff   | カード・モーダル背景           |
| Text       | #1a1a2e   | 本文テキスト                 |
| Muted      | #64748b   | サブテキスト・プレースホルダー   |
| Border     | #e2e8f0   | ボーダー・区切り線            |
| Success    | #16a34a   | 成功・完了ステータス           |
| Warning    | #d97706   | 警告・注意                   |
| Error      | #dc2626   | エラー・削除                 |

## Typography

- フォント: "Helvetica Neue", Arial, "Hiragino Kaku Gothic ProN", sans-serif
- H1: 2rem / font-weight: 700
- H2: 1.5rem / font-weight: 700
- H3: 1.15rem / font-weight: 600
- Body: 0.97rem / line-height: 1.8
- Code: "SFMono-Regular", Consolas, Menlo, monospace / 0.875rem

## Components

### Button (Primary)
- background: #4f46e5
- color: #ffffff
- padding: 10px 24px
- border-radius: 8px
- font-weight: 600
- hover: background #3730a3

### Card
- background: #ffffff
- border: 1px solid #e2e8f0
- border-radius: 10px
- padding: 24px
- box-shadow: 0 1px 3px rgba(0,0,0,0.08)

### Badge
- background: #eef2ff
- color: #4f46e5
- padding: 4px 12px
- border-radius: 20px
- font-size: 0.8rem
- font-weight: 700

## Layout

- max-width: 800px
- section-spacing: 60px
- element-spacing: 24px
- mobile-padding: 16px

## Do's and Don'ts

### Do's
- 余白は多めに取る（要素間は最低 16px）
- ボーダーは細く（1px）、角丸は 8px 以上
- 色は必ず上記パレットから選ぶ

### Don'ts
- 蛍光色・彩度の高い色の多用
- テキストリンクへの下線（ホバー時のみ可）
- 影の多用（カードは box-shadow 1段階のみ）
- CSS カスタムプロパティ（var(--xxx)）の使用

## Agent Prompt Guide

このファイルを参照した場合:
1. 必ず上記カラーパレットの hex 値を直接使用する
2. コンポーネントの border-radius は 8px を基準にする
3. var(--xxx) は使用せず、すべて直接値で記述する
4. 新しい色を作らず、既存パレットから選ぶ

書き方のコツ

## Color Palette

- 青系の色を使う
- 背景は白っぽく
- テキストは暗い色

## Color Palette

- Primary: #4f46e5
- Background: #f8fafc
- Text: #1a1a2e

5. Claude Code での使い方

design.md は CLAUDE.md のように自動読み込みはされません。以下の3つの方法で参照させます。

方法①：プロンプトで直接 @ 参照する（最も簡単）

@design.md に従って、ユーザープロフィールのカードコンポーネントを作って

この方法はその場限りの参照です。毎回 @design.md と書く必要がありますが、特定の作業にだけデザイン指定を適用したい場合に向いています。

方法②：CLAUDE.md に import として記載する（推奨）

# プロジェクト名

[概要説明]

## デザインシステム

UI コンポーネントを作成・修正するときは必ず @design.md を参照すること。
色・フォント・コンポーネントのスタイルはすべて design.md に定義されている。

## 技術スタック
...

CLAUDE.md は Claude Code 起動時に自動で読み込まれるため、@design.md の参照指示を書いておけば、以降の UI 関連タスクでは常にデザインシステムが適用されます。

方法③：.claude/rules/ に配置してパスマッチを使う

.claude/
└── rules/
    └── design.md   ← UI 関連ファイルに自動適用

.claude/rules/ ディレクトリに配置したファイルは、パスマッチで特定のファイルへの編集時に自動参照させることができます（Claude Code の Rules 機能）。フロントエンドのコンポーネントファイルに対する編集時にだけ design.md を適用するといった使い方が可能です。

実践的なプロンプトの書き方

# NG: デザイン指定なし
ボタンコンポーネントを React で作って

# OK: design.md を参照させる
@design.md に従って、ログインボタンのコンポーネントを React で作って。
Primary カラーを使い、ホバー状態も実装すること。

# より具体的な場合
@design.md のカラーパレットとコンポーネント定義に従って、
エラーメッセージ表示用の AlertBox コンポーネントを作って。
Error カラー (#dc2626) を使い、アイコンは左に配置すること。

6. CLAUDE.md との違い・使い分け

2ファイル構成が基本

実際の運用では CLAUDE.md と design.md を両方置いて使うのが基本形です。CLAUDE.md には「UI を作るときは @design.md を参照すること」と書いておき、design.md にはビジュアルの定義だけを集中させます。

プロジェクト/
├── CLAUDE.md       ← 自動読み込み。技術スタック・規約・禁止事項
├── design.md       ← UI作業時に @参照。色・フォント・コンポーネント
└── src/

7. awesome-design-md の活用法

VoltAgent/awesome-design-md（GitHub）は、有名ブランドの design.md ファイルを集めたコミュニティリポジトリです。Apple・Stripe・Linear・Vercel・Notion などのデザインシステムがマークダウン形式で揃っています。

使い方①：有名ブランドのスタイルを参考にする

「Stripe のようなクリーンな UI にしたい」という場合、Stripe の design.md を参照してコンポーネントを生成できます。既存のデザインシステムから学ぶための教材としても優れています。

# Stripe スタイルのカードコンポーネントを作って
@stripe-design.md に従って、決済フォームのカードコンポーネントを作って

使い方②：自分のプロジェクト用の叩き台にする

既存のブランドファイルをコピーして、色と名前だけ変えれば自分のプロジェクトの design.md が即座に完成します。ゼロから書くより格段に速いです。

使い方③：複数ブランドのスタイルをミックスする

# Linear の色 + Apple のタイポグラフィで作って
@linear-design.md のカラーパレットと @apple-design.md のタイポグラフィに従って、
ダッシュボードのサイドバーを作って

8. まとめ

design.md を導入することで、Claude Code で生成される UI のデザイン一貫性が大幅に向上します。まずはプロジェクトの主要カラーと本文フォントだけを書いた最小構成の design.md を作り、UI 生成の精度を確かめながら少しずつ詳細を追加していくアプローチがおすすめです。