awesome-design-md：DESIGN.mdでAIにUI生成させる方法【58+24日本語ブランド対応】

この記事ではUIデザインに特化して解説します。デザインシステム・UI生成全般は デザインシステムとは？仕組み・構成要素・有名事例をエンジニア向けに完全解説 をご覧ください。

DESIGN.mdとは何か ── AIエージェント時代のデザイン仕様書

AIにUIを作らせると、毎回違う色、違うフォントサイズ、違う余白のページが出てくる。「Stripeっぽいデザインで」と指示しても、AIが勝手に解釈した「それっぽい」結果しか得られない。

この問題を解決するのがDESIGN.mdという新しいフォーマットだ。Google Stitchで導入されたこの仕様では、デザインシステムの全要素をMarkdownで記述する。プロジェクトルートに置くだけで、Claude CodeやCursor、Google StitchなどのAIエージェントが仕様を読み取り、一貫したUIを生成する。基本の書き方や最小テンプレートはDESIGN.md入門記事にまとめているので、初めて触る場合はそちらを先に読むとスムーズだ。

awesome-design-mdは、このDESIGN.mdを58ブランド分キュレーションしたOSSリポジトリだ。Vercel、Stripe、Claude、Linear、Notion、Figma、Airbnb、SpaceXなど、一流企業のデザインシステムを参考にしたDESIGN.mdファイルをnpx1コマンドで自分のプロジェクトに導入できる。2026年3月31日の公開直後から急成長し、4月上旬には週間GitHubトレンド上位を独占。現在は35,000スターを超えており、今年最速で伸びたリポジトリの1つになった。

AI design.md の役割 — LLM向け設計ドキュメントの書き方

「ai design.md」で情報を探している読者が最初に押さえたいのは、「design.mdとは何のためのファイルで、どう書けばAIが正しく解釈するのか」という点だ。DESIGN.mdはLLM・AIエージェントに読ませることを目的とした設計ドキュメントで、人間向けREADMEとは明確に役割が異なる。プロジェクトルートに置くだけでClaude Code・Cursor・Google StitchなどのAIエージェントがUI生成時に自動参照し、毎回ブレていたデザインを一貫化できる。

AI向け設計ドキュメントとしてDESIGN.mdを書く際のコツは以下の5点だ。

awesome-design-mdが生成するDESIGN.mdは、約310行・9セクション構成で、上記5つのパターンを全て網羅している。最小構成なら以下の3セクションだけでも実用する。

# My Product Design System

## Color Palette
| Role | Hex | Usage |
|------|-----|-------|
| Primary | #0052CC | CTA, リンク |
| Background | #ffffff | ページ背景 |
| Text | #171717 | 本文 |

## Typography
| Role | Size | Weight |
|------|------|--------|
| Heading | 32px | 600 |
| Body | 16px | 400 |

## Do's and Don'ts
### Don't
- border-radius を 12px 以上にしない
- グラデーション背景を使わない
- 本文に weight 700 を使わない

AI向け設計ドキュメントとしてDESIGN.mdを採用する最大の利点は、確率的に出力するLLMに対して「境界条件」を明示的に与えられる点にある。READMEやFigmaのスクリーンショットだけでは伝わらない「やってはいけないこと」を、AIが参照可能な構造化ドキュメントに落とし込むことで、v0・Claude Code・Cursorどれを使っても同じブランドトーンのUIに収束させられる。

AGENTS.md × CLAUDE.md × DESIGN.md ── 3層のMarkdown仕様書

AIエージェント向けのコンテキストファイルは役割が分かれている。DESIGN.mdだけを見ても全体像はつかめないので、関連する3つのMarkdownファイルの分業を先に整理する。CLAUDE.mdの書き方はKarpathy流CLAUDE.md徹底解説が、さらに一段抽象度を上げた「スキル」という概念はClaude Skills完全解説で詳しく扱っている。

この3つが揃うと、AIは「ビルドが通る・規約を守った・ブランドらしい」コードを生成できる。awesome-design-mdは3つのうちDESIGN.mdだけを専門にキュレーションしているプロジェクトだ。

npxコマンドで即導入 ── awesome-design-mdの使い方

インストール不要。npxで即実行できる。

# Vercelスタイルを導入（プロジェクトルートにDESIGN.mdが生成）
npx getdesign@latest add vercel

# 58ブランドの一覧を確認
npx getdesign@latest list

# 別ブランドを追加（2つ目以降はブランド名フォルダに配置）
npx getdesign@latest add stripe

# 出力先を指定
npx getdesign@latest add claude --out ./docs/DESIGN.md

# 既存のDESIGN.mdを上書き
npx getdesign@latest add linear --force

listコマンドで出力される58ブランドの一部を紹介する。

DESIGN.mdの中身 ── 9セクション310行の設計仕様書

生成されるDESIGN.mdは約310行。9つのセクションで構成される。実際にVercelのDESIGN.mdから抜粋して内容を見てみよう。

セクション1: Visual Theme（デザイン哲学）

デザインの方向性を言語化している。AIはこれを読んで「このブランドらしさ」を判断する。

# Design System Inspiration of Vercel

## 1. Visual Theme & Atmosphere

Vercel's website is the visual thesis of developer infrastructure
made invisible — a design system so restrained it borders on
philosophical. This isn't minimalism as decoration; it's minimalism
as engineering principle.

セクション2-3: Color Palette + Typography

全色のHex値と役割、全フォントサイズ・ウェイト・字間の対応表がテーブル形式で定義される。

## 2. Color Palette & Roles

### Workflow Accent Colors
- **Ship Red** (`#ff5b4f`): the "ship to production" workflow step
- **Preview Pink** (`#de1d8d`): the preview deployment workflow
- **Develop Blue** (`#0a72ef`): the development workflow

## 3. Typography Rules

| Role | Size | Weight | Letter Spacing | Notes |
|------|------|--------|----------------|-------|
| Display Hero | 48px | 600 | -2.4px | Maximum compression |
| Body Large | 20px | 400 | normal | Feature descriptions |
| Mono Caption | 13px | 500 | normal | Code labels |

セクション7: Do’s and Don’ts

AIに「やるな」を明確に指示するセクション。これがDESIGN.mdの最大の強み。

## 7. Do's and Don'ts

### Don't
- Don't use weight 700 (bold) on body text — 600 is the maximum
- Don't use traditional CSS `border` — use shadow-border technique
- Don't use pill radius (9999px) on primary buttons — pills are for badges only
- Don't skip the inner #fafafa ring in card shadows

セクション9: Agent Prompt Guide

AIエージェントにそのまま渡せるプロンプト例が記載されている。

## 9. Agent Prompt Guide

### Example Component Prompts
- "Create a hero section on white background. Headline at 48px
   weight 600, letter-spacing -2.4px, color #171717."
- "Design a card: no CSS border. Use shadow stack:
   rgba(0,0,0,0.08) 0px 0px 0px 1px."

DESIGN.mdあり/なしで出力はどう変わるか

同じ指示「ランディングページのヒーローセクションを作って」をAIに渡して、DESIGN.mdの有無で比較した結果を示す。

DESIGN.mdなし ── AIが「それっぽく」判断した汎用デザイン

紫グラデーション背景、pill型ボタン、半透明カード。どこかで見たことあるような、個性のないUI。AIが「ランディングページ」と聞いて連想した平均値が出力される。

Vercel DESIGN.md準拠 ── 白と黒の精密なミニマリズム

白背景に#171717テキスト。枠線はCSSのborderではなくbox-shadow: 0px 0px 0px 1pxで表現するVercel独自の手法。見出しの字間は-2.4pxで圧縮され、Develop（青）→Preview（ピンク）→Ship（赤）の3色パイプラインが再現されている。

Stripe DESIGN.md準拠 ── 極細フォントと青みシャドウの高級感

見出しがfont-weight: 300の極細。CTAは#533afdパープル。カードのシャドウはrgba(50,50,93,0.25)という青みがかった色で、ダークセクションは#1c1e54（純黒ではなく深い紺）。Stripeの「金融×高級感」がそのまま出力される。

結果: 同じ「ヒーローセクションを作って」という指示でも、DESIGN.mdがあるだけで出力が根本的に変わる。 特にVercelの「shadow-as-borderテクニック」やStripeの「weight 300見出し」など、各ブランド固有のデザイン判断がAIの出力に反映される。

DESIGN.md vs Figma Make vs v0 vs Google Stitch ── 使い分けの基準

AIでUIを生成する手段はDESIGN.mdだけではない。Figma Make（Figmaが提供するAIデザイン生成）、v0（Vercelのプロンプト→React UI）、Stitch（GoogleのAIデザイナー）が主要な選択肢として並ぶ。それぞれ強みが違うので、プロジェクトの段階に応じて使い分けるのが2026年の実践パターンだ。

2026年実践ワークフローは3ツールの合わせ技が主流になっている。Stitchで方向性を探り、Figma Makeで詳細を詰め、Claude Code + DESIGN.mdで実装するパイプラインだ。

v0だけで作り続けると「毎回微妙に違うUI」が量産されてブランド崩壊につながる。DESIGN.mdを挟むことで、v0出力もClaude Code出力も同じ色・同じフォント・同じ余白に収束する。

Claude Code・Cursor・Google Stitchでの活用方法

Claude Codeで使う場合

DESIGN.mdをプロジェクトルートに置き、CLAUDE.mdに参照指示を追加する。

# CLAUDE.md に追記する内容

## デザインルール
- UIコンポーネント生成時は必ず DESIGN.md を参照すること
- DESIGN.md で定義された色・フォント・余白のみ使用
- 新しいデザイン値を勝手に発明しない

これだけでClaude Codeがデザイン仕様を自動的に読み込み、指示に従ったUIを生成する。

Cursorで使う場合

.cursor/rulesにDESIGN.mdの参照ルールを追加する。Cursor 3.0のマルチエージェント機能と組み合わせると、複数のコンポーネントを並列生成しながらデザイン一貫性を保てる。

Google Stitchで使う場合

Google StitchはDESIGN.mdをネイティブサポートしている。プロジェクトにDESIGN.mdを含めるだけで、Geminiが全プロンプトに対してデザイン仕様を自動適用する。

関連プロジェクトとエコシステム

awesome-design-mdを中心に関連ツールが成長している。

awesome-design-md-skillsは、Claude Code向けのスキル集として有名なmattpocock/skillsと同じ考え方でDESIGN.mdをパッケージ化する試みだ。UIコンポーネント集と組み合わせて使うなら、shadcn studioのテーマジェネレータやSquare UIのレイアウトコレクションのトークンをDESIGN.mdに流し込むワークフローが実用的になる。

AIエージェントフレームワークと組み合わせることで、デザイン生成を自動パイプラインに組み込むことも可能だ。

awesome-design-md-jp ── 日本語サービス特化の拡張

本家awesome-design-mdは海外ブランド中心で、日本語UIの細かな作法（縦書き対応、和文欧文混植、句読点の扱い、CJKフォントのウェイト差など）はカバーされていない。この隙間を埋めるのがawesome-design-md-jp（スター670+）で、SmartHR、freee、note、メルカリ、LINE、Qiita、Zenn、無印良品、トヨタ、Apple Japan、任天堂、虎屋など182サイトのDESIGN.mdを収録している。本セクションは要点のみ抑えるので、日本語タイポ拡張の中身・本家との差分・落とし穴は専用記事の awesome-design-md-jp：182サイトの日本語UI DESIGN.md集（CJKタイポグラフィ拡張） を参照すると深く把握できる。

本家との構造的な違い

awesome-design-md-jpは本家の9セクション構成を踏襲しつつ、日本語タイポグラフィ専用のサブセクションを拡張している。

CJKフォントの扱いはDESIGN.mdの追加セクション「Japanese Typography Rules」で明示される。例えばnoteのDESIGN.mdは以下のような項目を含む。

## Japanese Typography Rules

| Role | Font | Size | Line Height | Letter Spacing |
|------|------|------|-------------|----------------|
| Heading JP | "Noto Sans JP" 700 | 28px | 1.5 | 0.02em |
| Body JP | "Noto Sans JP" 400 | 16px | 1.85 | 0.05em |
| Caption JP | "Noto Sans JP" 400 | 13px | 1.6 | 0.04em |

### Don't
- 日本語本文に letter-spacing: 0 を使わない（字詰めが崩れる）
- 縦書きモードで `font-variant-east-asian: proportional-width` を指定しない
- 全角スペースを padding の代わりに使わない

導入方法

# リポジトリをクローン
git clone https://github.com/kzhrknt/awesome-design-md-jp.git

# 使いたいブランドのDESIGN.mdをコピー
cp awesome-design-md-jp/services/smarthr/DESIGN.md ./DESIGN.md

# テンプレートから自社用を作成する場合
cp awesome-design-md-jp/template/DESIGN.md ./DESIGN.md

各ブランドディレクトリにはDESIGN.md本体に加え、preview.html（ビジュアルプレビュー）とスクリーンショットが含まれている。

jp-ui-contracts ── 日本語UI設計の「契約書」

jp-ui-contractsは、awesome-design-md-jpとは異なるアプローチで日本語UIの品質を担保するプロジェクトだ。DESIGN.mdが「ビジュアルの仕様書」なら、jp-ui-contractsは「AIが日本語UIを壊さないための契約書」という位置づけになる。

awesome-design-md-jpとの違い

AIが日本語UIで起こす典型的な崩れ

jp-ui-contractsの作者hirokaji氏は、AI生成UIの問題を「AIの精度不足ではなく、日本語UI設計の契約が不十分」と分析している。具体的には以下の崩れが頻発する。

5つのプロファイル

jp-ui-contractsの特徴は用途別の5プロファイルだ。「メディアサイト」と「管理画面」では最適な密度やタイポグラフィが異なるという考え方に基づく。

# jp-ui-contractsの構成
jp-ui-contracts/
├── templates/     # 用途別DESIGN.mdテンプレート
├── recipes/       # 日本語タイポグラフィCSSスニペット
├── validators/    # AI生成UIのレビュールール
├── schema/        # 機械検証用スキーマ（将来対応）
└── examples/      # サンプルDESIGN.md + preview.html

運用ワークフロー

jp-ui-contractsは「一度書いて終わり」ではなく、反復ループを前提としている。

日本語プロジェクトでの3点セット

日本語UIの品質を確保するには、以下の3つを組み合わせるのが定番化しつつある。

1. 本家 awesome-design-md — ベースとなるデザインシステムの雛形
2. awesome-design-md-jp — 日本語タイポグラフィの仕様拡張
3. jp-ui-contracts — 用途別の契約テンプレート＋バリデーション

Claude Designがコードベースからデザインシステムを自動構築する際も、DESIGN.mdに日本語タイポグラフィルールが明記されているかどうかで出力品質が大きく変わる。デザインシステムの基本概念を理解した上で、日本語特有の拡張をDESIGN.mdに落とし込むことが重要だ。

導入時の注意点と限界

DESIGN.mdは確率的に解釈される。 AIが仕様を「理解」して適用するが、CSSコンパイラのようにピクセル単位で正確に再現するわけではない。DESIGN.mdはガイドであり、コンパイラではない。

知っておくべき制約

• 公式デザインシステムではない — 各企業の公開CSS/パターンからリバースエンジニアリングした「インスピレーション」ファイル
• カスタムフォント問題 — VercelのGeistやStripeのsohne-varは利用不可。Inter等の代替フォントで近似する必要がある
• プロダクション運用 — 成熟したチームはDESIGN.md（AI向け）と従来のデザイントークン（CSS向け）を併用している
• CJKフォント — 日本語プロジェクトではawsome-design-md-jpの拡張が必要になる場合がある

カスタムフォントの代替表

各ブランドのカスタムフォントは有料・非公開のものが多く、そのままでは再現できない。実用的な代替フォントの対応表を下にまとめる。Google Fontsで揃うものを優先している。

DESIGN.md内のfont-family定義を書き換える際、CSS変数経由で差し替えられるように記述しておくと切り替えが楽になる。

:root {
  --font-sans: "Inter", -apple-system, "Noto Sans JP", sans-serif;
  --font-display: "Space Grotesk", var(--font-sans);
  --font-mono: "JetBrains Mono", ui-monospace, monospace;
}

自社DESIGN.mdを書く場合のポイント

既存の58ブランドのDESIGN.mdを雛形として、自社デザインシステムを記述するのが最も効率的。最低限必要なのは以下の3セクション。

# My Company Design System

## Color Palette
| Role | Hex | Usage |
|------|-----|-------|
| Primary | #0052CC | CTA, リンク |
| Background | #ffffff | ページ背景 |
| Text | #171717 | 本文 |

## Typography
| Role | Size | Weight |
|------|------|--------|
| Heading | 32px | 600 |
| Body | 16px | 400 |

## Do's and Don'ts
### Don't
- border-radius を 12px 以上にしない
- グラデーション背景を使わない

まとめ

awesome-design-mdは「AIにUIを作らせるとデザインがブレる」問題を、310行のMarkdown仕様書で解決するツールだ。

npx getdesign@latest add vercel の1コマンドで58ブランドのデザイン仕様を導入でき、Claude Code・Cursor・Google Stitchでそのまま使える。特にDo’s and Don’tsセクションでAIに「やってはいけないこと」を明示できる点が、従来の「いい感じにして」型プロンプトとの決定的な違いになる。

Nothing Design SkillのようなAI向けデザイン学習ツールと組み合わせれば、デザイナーなしでもブランド一貫性のあるUI開発が現実的になる。

さらに2026年4月リリースのClaude Designでは、コードベースからデザインシステムを自動構築し、DESIGN.mdと連携してプロトタイプ・スライド・3Dデモまで生成できるようになった。デザインシステムの基本概念から実装パターンまではデザインシステム入門ガイドにまとめている。

なお、DESIGN.mdフォーマットの提唱元であるGoogleは、2026年4月にそのフォーマット仕様をOSSとして公式公開した。@google/design.md v0.1.0では、YAML+Markdownの2層構造・W3Cデザイントークン互換性・lint/diff/export CLIまで仕様化されており、awesome-design-mdとの連携も期待されている。

参照ソース

• VoltAgent/awesome-design-md - GitHub
• Google Stitch - DESIGN.md Documentation
• getdesign.md CLI
• awesome-design-md-jp - 日本語版
• DESIGN.md: The Markdown File That Became GitHub’s Fastest Design Standard - OSS Insight
• awesome-design-md: Design Systems for AI - Stefano Salvucci
• Stitch × Figma Make × Claude Code で個人サイトがすんなり完成した話 - Zenn
• DESIGN.md入門 — AIエージェントのUI生成を一貫させるデザインファイルの書き方 - Zenn