AIにUIを作らせると、毎回違う色、違うフォントサイズ、違う余白のページが返ってきます。「Stripeっぽく」と指示しても、AIが解釈した「それっぽい」結果しか得られません。この問題を1枚のMarkdown仕様書で解決するのがDESIGN.mdで、各社のDESIGN.mdをコピー1つで配っているのが awesome-design-md です。

まったく同じ指示「ヒーローセクションを作って」を同じAIに渡した結果です。左はDESIGN.mdなし、右はVercelのDESIGN.mdを1つ置いただけの出力です。

DESIGN.mdなしでAIが生成した汎用的な紫グラデーションのランディングページ

DESIGN.mdなし
紫グラデ・pill型ボタン・個性なし

Vercelの DESIGN.md を1つ置くだけでAIが生成した白黒ミニマルなランディングページ

Vercel DESIGN.md を1つ置いただけ
白黒精密・Develop→Preview→Ship 再現

同じAI・同じプロンプトでも、DESIGN.mdを1枚渡すだけで出力が根本的に変わる(当サイト検証。DESIGN.mdは VoltAgent/awesome-design-md より)

30秒で理解する awesome-design-md

  • ・DESIGN.mdは、AIエージェントにUI仕様(色・フォント・余白・Do/Don't)を伝えるMarkdownファイル。Google Stitch発祥で、2026年4月にGoogleが @google/design.md v0.1.0 として公式OSS化
  • ・awesome-design-mdは、Vercel/Stripe/Claudeなど74ブランドのDESIGN.mdをコピー1つで導入できるOSS。105,399★(2026-07-30)
  • ・npx getdesign@latest add vercel が今も通ることを2026-08-26に実測
  • ・日本語UIには awesome-design-md-jp(182サイト)と jp-ui-contracts(5プロファイル)を組み合わせる

エージェントにツールやルールを渡して動かす枠組み全般は AIエージェントフレームワーク比較2026|LangGraph・CrewAI・Dify等9種をStar数・実コードで検証 をご覧ください。DESIGN.mdはその中で「UIの作法だけをエージェントに渡す」もっとも軽量な部品にあたります。

design.mdとは:AIエージェント向けのUI仕様書

READMEが「人間に読ませる説明書」なら、DESIGN.mdは「AIに読ませるデザイン仕様書」です。プロジェクトルートに DESIGN.md を置くと、Claude Code・Cursor・Google Stitch・v0がUI生成時に参照します。2026年4月にはGoogleが @google/design.md v0.1.0 として公式OSS仕様を公開し、YAML+Markdownの2層構造・W3C Design Tokens互換・lint/diff/export CLIまで整いました。基本の書き方は DESIGN.md入門 にまとめています。表記は DESIGN.md / design.md / design md のどれも同じファイルを指します(GitHubの慣習は大文字、Googleのパッケージ名は小文字)。

THREE MARKDOWN FILES役割分担

ビルドはAGENTS.md、規約はCLAUDE.md、見た目はDESIGN.md

  1. 01

    AGENTS.md

    ビルド・テスト・依存関係。OpenAI/Codex中心に策定

    バックエンド / DevOps

  2. 02

    CLAUDE.md

    コーディング規約・命名・禁止事項。Claude Code標準

    テックリード

  3. 03

    DESIGN.md

    色・タイポ・余白・Do's and Don'ts。Google Stitch発祥

    デザイナー / フロントエンド

3つともリポジトリルートに置く(DESIGN.md は docs/ も可)。当サイトの整理

3つが揃うと、AIは「ビルドが通る・規約を守った・ブランドらしい」コードを出せます。awesome-design-mdはこのうちDESIGN.mdだけを専門にキュレーションしています。AIが解釈しやすく書くコツは次の5つです。

ポイント 書き方 理由
①セクション見出しを番号付きで固定 ## 1. Visual Theme, ## 2. Color Palette 参照箇所が安定する
②色はHex値とロールを対にする - Primary (#0052CC): CTA, リンク 曖昧な色指定を排除
③タイポグラフィはテーブル形式 Role / Size / Weight / Letter Spacing 機械的に抽出できる
④Do’s and Don’tsを明示 Don't use weight 700 on body text 禁止事項を強制できる
⑤Agent Prompt Guideを付ける そのまま渡せる例文 プロンプト設計の手間を削減

最小構成なら、次の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 を使わない

最大の利点は、確率的に出力するLLMに「やってはいけないこと」という境界条件を明示できる点です。READMEやFigmaのスクリーンショットでは伝わりません。

awesome-design-mdの使い方:コピー1つ、またはnpxで導入

READMEの「How to Use」は2行だけです。使いたいサイトの DESIGN.md をプロジェクトルートにコピーし、AIに「このDESIGN.mdを使ってUIを作って」と伝えます。入手経路は3つで、中身は同じファイルです。

・Webカタログ(推奨) — getdesign.md でブランドを選び、Download DESIGN.md かコピーで取得。色・タイポ・コンポーネントのプレビュー(Light / Dark)を確認してから選べる
・GitHub — awesome-design-md から目的ブランドの DESIGN.md をコピー
・npx — 各ブランドページに表示されるコマンドを実行する

# プロジェクトルートに DESIGN.md が生成される
npx getdesign@latest add vercel

# 別ブランドはブランド名を変えるだけ
npx getdesign@latest add stripe
npx getdesign@latest add claude

置いたら、たとえば「プロジェクトルートの DESIGN.md を厳守して、ランディングページのヒーローセクションを作って。DESIGN.mdに無い色・フォント・余白は使わないこと」と指示します。

2026年8月26日に空ディレクトリで実行すると、✓ DESIGN.md inspired by vercel installed と出て終了コード0。冒頭はYAML frontmatterで、version: alpha / name / description に続いて colors: 以下に primary on-primary ink body といったロール名つきの色が並びます。GitHub Tree API(?recursive=1)で再帰的に数えると、design-md/ 配下のブランドディレクトリも DESIGN.md の実ファイルもちょうど74個でした。

MEASURED数え直した

収録はちょうど74ブランド、1ファイルは約41KB

74ブランド

design-md/ 配下のディレクトリ

DESIGN.md の実ファイルも74個

41,396B

vercel の DESIGN.md

npx getdesign@latest add vercel

105,399★

GitHub スター

Fork 12,051(2026-07-30)

出典: 当サイト実測(2026-08-26・GitHub Tree API と npx の実行)。スターは 2026-07-30 時点

生成物の description は “An inspired interpretation of Vercel’s design language” と自称しています。公式のデザイントークンではなく、公開UIから起こした解釈なので、商標やブランドガイドラインの制約がある場面では自社プロダクトにそのまま流用しない前提で使ってください。

カテゴリ ブランド例(74ブランド、Webカタログ上は75+)
AI・LLM Claude, Ollama, Together AI, ElevenLabs, Mistral AI, xAI, Runway, Replicate, VoltAgent
開発者ツール・IDE Vercel, Cursor, Warp, Raycast, Expo, Superhuman, Lovable
バックエンド・DB・DevOps Supabase, MongoDB, ClickHouse, HashiCorp, Sentry, PostHog, Sanity, Composio
生産性・SaaS Linear, Notion, Intercom, Zapier, Cal.com, Mintlify, Resend
デザイン・クリエイティブ Figma, Framer, Miro, Webflow, Airtable, Clay
フィンテック・暗号資産 Stripe, Coinbase, Revolut, Wise, Kraken, Binance, Mastercard
EC・小売 Airbnb, Shopify, Nike, Starbucks, Meta
メディア・家電 Apple, NVIDIA, IBM, HP, Spotify, Pinterest, PlayStation, WIRED, The Verge, Uber, SpaceX, Vodafone
自動車 Tesla, BMW, BMW M, Bugatti, Ferrari, Lamborghini, Renault

毎週土曜更新の「Retro Web / DESIGN.md Nostalgia」シリーズでは、Dell (1996) や Nintendo.com (2001) のような1990〜2000年代のWebを分析したDESIGN.mdも配っています。

DESIGN.mdの中身:9セクション構成

Stitchの DESIGN.md フォーマットを拡張した9セクションで、色だけでなくコンポーネントの状態・レイアウト・影・レスポンシブ・プロンプト例まで1ファイルに畳み込みます。

# セクション 何を定義するか
1 Visual Theme & Atmosphere ムード・密度・デザイン哲学
2 Color Palette & Roles 意味名 + Hex + 機能ロール
3 Typography Rules フォント・階層テーブル
4 Component Stylings ボタン・カード・入力・ナビ(状態込み)
5 Layout Principles 余白スケール・グリッド
6 Depth & Elevation 影システム・サーフェス階層
7 Do’s and Don’ts ガードレールとアンチパターン
8 Responsive Behavior ブレークポイント・タッチ領域
9 Agent Prompt Guide 色クイックリファレンス + すぐ使えるプロンプト

各ブランドには preview.html(色スウォッチ・タイポスケール・ボタン・カードの視覚カタログ)と preview-dark.html も同梱されます。VercelのDESIGN.mdから、色・タイポと Do’s and Don’ts を抜粋します。

## 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

### 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

Section 1は “Vercel’s website is the visual thesis of developer infrastructure made invisible” のようにデザイン哲学を言語化し、Section 9には “Create a hero section on white background. Headline at 48px weight 600, letter-spacing -2.4px, color #171717.” のようなそのまま渡せるプロンプト例が入ります。

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

SAME PROMPTあり / なし

同じ指示でも、DESIGN.mdの1枚で細部が置き換わる

DESIGN.mdなし

Vercel の DESIGN.md

DESIGN.mdなし: 紫グラデーション背景

Vercel の DESIGN.md: 白 #ffffff と #171717 の文字

DESIGN.mdなし: 見出し weight 700・字間 0

Vercel の DESIGN.md: weight 600・字間 -2.4px

DESIGN.mdなし: pill 型ボタン

Vercel の DESIGN.md: 6px radius

DESIGN.mdなし: border: 2px solid

Vercel の DESIGN.md: 影で枠線を描く(shadow-as-border)

出典: 当サイト検証。プロンプトは「ランディングページのヒーローセクションを作って」

DESIGN.mdなしの出力は「悪いAI」ではなく、「ランディングページ」と聞いて連想した平均値です。Vercel準拠では、枠線をCSSの border ではなく box-shadow: 0px 0px 0px 1px で描き、Develop(青)→Preview(ピンク)→Ship(赤)の3色パイプラインまで再現されました。Do’s and Don’ts と Component Stylings がこの細部を強制しています。同じプロンプトにStripeのDESIGN.mdを渡すと、まったく別のトーンに収束します。

Stripe の DESIGN.md 準拠でAIが生成した、極細見出しと青みシャドウのランディングページ
Stripe DESIGN.md 準拠のAI出力(当サイト検証)。weight 300 の極細見出しと青みがかった多層シャドウが特徴
比較項目 DESIGN.mdなし Vercel準拠 Stripe準拠
背景色 紫グラデ #ffffff #ffffff(#1c1e54 の紺セクション)
見出しweight 700 600 300(極細)
字間 0 -2.4px -1.4px
ボタン形状 pill 6px radius 4px radius(CTAは #533afd)
枠線 border: 2px solid 影で表現 1px solid #e5edf5
シャドウ 黒の単層 多層スタック 青み(rgba(50,50,93,0.25))の多層

AIでUIを作る手段は他にもあり、段階で使い分けます。

ツール 主な用途 入力 ブランド一貫性
DESIGN.md 既存プロジェクトに一貫性を足す Markdown仕様書 ◎(仕様書で厳密に制御)
Figma Make Figma上で詳細を詰める プロンプト + Guidelines.md ◯
v0.dev プロンプトだけで素早くプロトタイプ 自然言語 △(都度ブレる)
Google Stitch デザインの方向性を探る 参考画像 + プロンプト ◯(DESIGN.md出力可)

Stitchで方向性を探り、Figma Makeで詳細を詰め、Claude Code + DESIGN.mdで実装し、人間 + Cursorで微調整する流れが実践的です。Claude Codeでは、CLAUDE.mdに参照指示を足すと確実に効きます。

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

Cursorでは .cursor/rules に参照ルールを足し、Cursor 3.0のマルチエージェント機能と組み合わせれば複数コンポーネントを並列生成しながら一貫性を保てます。Google StitchはDESIGN.mdをネイティブサポートしており、含めるだけでGeminiが全プロンプトに仕様を適用します。

日本語UI:awesome-design-md-jpとjp-ui-contracts

本家は海外ブランド中心で、縦書き・和文欧文混植・句読点・CJKフォントのウェイト差はカバーされていません。awesome-design-md-jp(670+★)はSmartHR、freee、note、メルカリ、LINE、Qiita、Zenn、無印良品、トヨタ、Apple Japan、任天堂、虎屋など182サイトを収録しています。中身と落とし穴は専用記事の awesome-design-md-jp|182サイトの日本語UI DESIGN.md集(CJKタイポグラフィ拡張) で扱いました。CJKフォントは追加セクション「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 の代わりに使わない

jp-ui-contracts(54★)は「AIが日本語UIを壊さないための契約書」です。作者のhirokaji氏は、崩れの原因を「AIの精度不足ではなく、日本語UI設計の契約が不十分」と分析しています。

問題 原因 対策
見出しの折り返しが不自然 word-break: break-all の誤用 禁則処理ルール
本文の行間が狭すぎる 欧文基準の line-height: 1.4 日本語は 1.7〜2.0 を契約で指定
英語サービス名との混在が不自然 和文欧文のスペーシング未定義 混植ルールをCSS変数で定義
フォーム・テーブルが窮屈 本文タイポや行間が漏れる コンテキスト別プロファイルで分離

プロファイルは base(共通基盤)、media(記事・行間広め)、saas(管理画面・高密度)、docs(コードとテキストのバランス)、dashboard(数字の視認性)の5つ。本家で雛形、awesome-design-md-jpで日本語タイポ、jp-ui-contractsで用途別の契約とバリデーション、という3点の組み合わせが定番になりつつあります。

導入時の注意点と、2026年のエコシステム

DESIGN.mdはガイドであり、コンパイラではない

  • ・AIが確率的に解釈するので、ピクセル単位で正確には再現しない
  • ・公式デザインシステムではない。リポジトリ自身も各社の視覚的アイデンティティの所有権を主張しない
  • ・Vercelの Geist やStripeの sohne-var などのカスタムフォントは使えない。成熟したチームはAI向けのDESIGN.mdとCSS向けのデザイントークンを併用する
オリジナル 代替フォント 使用ブランド
Geist Sans Inter, Space Grotesk Vercel
sohne-var Manrope, Sora Stripe
Tiempos Headline Fraunces, Playfair Display Stripe見出し
Inter Display Inter(weight 600以上) Linear, Notion
Söhne Inter, IBM Plex Sans ChatGPT
Styrene A Satoshi, Söhne代替 Claude
SF Pro -apple-system, Inter Apple系

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;
}
時期 出来事
2026-03-31 VoltAgent が awesome-design-md を公開。3日で5,000★突破、週間トレンド1位
2026-04-09 awesome-design-md-jp が日本語UI 24サイトで公開
2026-04-14 DESIGN.md 入門記事を公開
2026-04-23 Google が @google/design.md v0.1.0 を公式OSS公開(YAML+Markdown 2層、W3C互換)
2026-05 awesome-design-md-jp が182サイト・670★に、jp-ui-contracts が5プロファイル化
2026-06 導入方式が「コピー/Download」中心に整理、Retro Webシリーズ追加
2026-07-上旬 awesome-design-md が95,000★を突破(GitHub全体で約150位)
2026-07-30 105,399★・Fork 12,051・74ブランド(直近コミットは2026-06-16。ブランドは73→74)

awesome-design-mdがキュレーション集なのに対し、Googleの @google/design.md はフォーマット自体の仕様です。各ツールが同じ仕様で DESIGN.md を解釈できる土台ができ、design.md lint・design.md diff・design.md export --to=css-vars のような扱いもできるようになりました。

---
# YAML 層 (フロントマター): 機械可読なデザイントークン
spec: design.md/v0.1
tokens:
  color:
    primary: "#0052CC"
    background: "#ffffff"
  font:
    body: { family: "Inter", size: 16, weight: 400 }
---

# Markdown 層: 人間 + AI 向けの説明
## Visual Theme
...

周辺には、Claude/Codex/Gemini向けのスキルファイル awesome-design-md-skills(54★)、FigmaのトークンをDESIGN.md形式に変換する figma-design-system-to-design-md(15★)もあります。shadcn studioやSquare UIのトークンをDESIGN.mdに流し込む使い方も実用的です。既存ブランドのDESIGN.mdを配るawesome-design-mdに対し、AnthropicのClaude Designは自社コードからDESIGN.mdを抽出する側で、両者は競合しません。

参照ソース