awesome-design-md 完整教學 — 用 DESIGN.md 讓 AI agent 生出對的 UI

📁 對應 metadata 報告：2026-05-18-github-VoltAgent-awesome-design-md.md 🌐 對應 HTML：projects/awesome-design-md/quarkdown-out/02-tutorial/index.html

1. 專案定位

1.1 一句話定位

DESIGN.md = 設計版的 AGENTS.md。把品牌的「design tokens (設計變數;顏色 / 字型 / 間距 / 元件)」變成一份純文字 markdown，丟到專案 root，AI coding agent (AI 編程代理) 讀完就能 generate 出風格對齊的 UI。

awesome-design-md 把 71 個真實品牌 的視覺語言抽成 71 份 DESIGN.md，讓你不用自己造輪子。

1.2 為什麼需要它

不用 DESIGN.md 的世界：

1你 → "蓋一個 Stripe 風格的 landing page"
2AI agent → 用它腦中對 Stripe 的「印象」生 UI
3結果 → 紫色到了，但比例 / 字重 / 間距全錯，看起來像贗品

用 DESIGN.md 的世界：

1你 → 把 design-md/stripe/DESIGN.md 丟到專案 root
2你 → "蓋 landing page，照 DESIGN.md 來"
3AI agent → 拿到精確的 #635BFF / Inter font / 0.4px letter-spacing / weight-300 ...
4結果 → 像 Stripe 親自蓋的

1.3 跟其他「設計 → AI」方案的比較

1.4 何時用、何時不用

2. 安裝指南

2.1 不用安裝

這個 repo 不是套件，是一份 awesome-list。沒有 npm install / pip install。

2.2 怎麼「拿」

三種選擇：

方法 A — Git clone（最完整）

1git clone https://github.com/VoltAgent/awesome-design-md.git
2ls awesome-design-md/design-md/
3# airbnb / airtable / apple / binance / claude / ... (71 個)

方法 B — 單檔下載（用一個就好）

1# 用 Stripe DESIGN.md
2curl -L -o DESIGN.md \
3  https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/stripe/DESIGN.md

方法 C — 線上目錄（含 dark preview）

逛 https://getdesign.md/，挑好下載 raw markdown。

2.3 用在不同 AI agent

3. 核心架構解析

3.1 整體結構（極簡）

 1awesome-design-md/
 2├── design-md/                  # 71 個品牌資料夾
 3│   ├── stripe/
 4│   │   ├── DESIGN.md          # 主檔（YAML frontmatter + Markdown）
 5│   │   └── README.md          # 5 行：指向 getdesign.md
 6│   ├── claude/                # 同上結構
 7│   ├── ... 共 71 個
 8├── README.md                  # 198 行：完整品牌清單 + 9 段格式說明
 9├── CONTRIBUTING.md            # 短指南
10├── LICENSE                    # MIT
11└── .github/
12    ├── FUNDING.yml
13    └── ISSUE_TEMPLATE/design-md-request.yml

3.2 一份 DESIGN.md 內部解剖（以 Claude 為例）

DESIGN.md 結構分兩段：

Part A — YAML frontmatter (machine-readable)

 1---
 2version: alpha
 3name: Claude-design-analysis
 4description: A warm-canvas editorial interface for Anthropic's Claude...
 5
 6colors:
 7  primary: "#cc785c"        # 暖珊瑚色
 8  primary-active: "#a9583e"
 9  canvas: "#faf9f5"         # 暖奶油底色
10  ink: "#141413"
11  body: "#3d3d3a"
12  ...
13
14typography:
15  display-xl:
16    fontFamily: "Copernicus, Tiempos Headline, serif"
17    fontSize: 64px
18    fontWeight: 400
19    lineHeight: 1.05
20    letterSpacing: -1.5px
21  ...

Part B — Markdown narrative (human + LLM readable)

跟著 9 段標準結構：

 1## 1. Visual Theme & Atmosphere
 2
 3The interface uses a warm canvas (#faf9f5) anchoring serif display
 4headlines with humanist sans body...
 5
 6## 2. Color Palette & Roles
 7
 8| Token         | Hex      | Role          |
 9|---------------|----------|---------------|
10| primary       | #cc785c  | Primary CTA   |
11| ink           | #141413  | Headlines     |
12| ...
13
14## 3. Typography Rules
15... (font 規格 + 完整 h1-h6 + body + caption 表)
16
17## 4. Component Stylings
18... (Button / Card / Input / Nav 各狀態)
19
20## 5. Layout Principles
21... (8pt grid / max-width 1280 / gutter 24px)
22
23## 6. Depth & Elevation
24... (shadow scale 0-5)
25
26## 7. Do's and Don'ts
27... (Anti-pattern：絕不用純白 background；CTA 不用 outline)
28
29## 8. Responsive Behavior
30... (breakpoints / touch targets / nav collapsing)
31
32## 9. Agent Prompt Guide
33... (Ready-to-use："Use #cc785c as primary CTA, serif display for h1...")

3.3 DESIGN.md 為什麼是 markdown 不是 JSON？

💡 這個設計選擇是 DESIGN.md 真正的洞見：markdown 是 LLM 的母語。

3.4 跟 AGENTS.md 的關係

兩者可同時放在專案 root；coding agent 同時讀。

4. Helper Scripts 詳細用法

4.1 沒有 helper scripts

這個 repo 是純資料倉庫，沒有任何可執行程式碼（143 個 .md + 2 個 .yml + LICENSE）。

4.2 拿單檔的常用指令

 1# 看完整目錄
 2curl -s https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/README.md | less
 3
 4# 下載某品牌
 5curl -L -o DESIGN.md \
 6  https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/linear.app/DESIGN.md
 7
 8# 批次下載多個
 9for b in stripe linear.app vercel notion; do
10  mkdir -p designs/$b
11  curl -sL -o designs/$b/DESIGN.md \
12    "https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/$b/DESIGN.md"
13done

4.3 自己做 CLI（10 行）

1#!/usr/bin/env bash
2# get-design.sh — 把指定品牌 DESIGN.md 抓到當前目錄
3brand="${1:?usage: get-design.sh <brand>}"
4url="https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/${brand}/DESIGN.md"
5if curl -fLso DESIGN.md "$url"; then
6  echo "✅ DESIGN.md ($brand) saved."
7else
8  echo "❌ Brand '$brand' not found. See https://github.com/VoltAgent/awesome-design-md"
9fi

5. 應用場景

5.1 蓋一個「Stripe 風」landing page（最常見）

1mkdir my-saas && cd my-saas
2curl -L -o DESIGN.md \
3  https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/stripe/DESIGN.md
4
5# 開 Claude Code
6claude
7> 按照 DESIGN.md 蓋一個 Next.js landing page，hero + features 三欄 + pricing 三檔 + footer。

5.2 多品牌 A/B 比較

1for b in stripe linear.app vercel; do
2  mkdir variant-$b && curl -sL -o variant-$b/DESIGN.md \
3    "https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/$b/DESIGN.md"
4done
5# 同樣 prompt 在三個資料夾跑，比較哪個品牌風格適合產品

5.3 把 DESIGN.md 當「設計面試題」

給設計師看 design-md/notion/DESIGN.md，問：「這份缺什麼？怎麼改進？」是訓練 design system 思維的好教材。

5.4 拼出自己的 DESIGN.md

從相近品牌挑一份 → 改顏色 / 字型 → commit 自己的 brand。範本選擇建議：

5.5 與 voltagent 整合

VoltAgent 是同一團隊的 AI agent 框架；可以用 voltagent 寫 agent 自動讀 DESIGN.md 並 generate components。詳見 https://github.com/VoltAgent/voltagent。

6. 資安掃描報告

掃描範圍：143 個 .md + 2 個 .yml。方法：grep -rlnE 對 <script / javascript: / onerror= / eval( / Function( / fetch( / XMLHttpRequest / 外部 URL。

🟢 整體：極低風險（純文字內容）

為什麼勾「中」風險？

這個 repo 80,319 stars + 9,692 forks，是 AI agent 讀取的 supply chain。Issue #396 社群已提出「vulnerability scanning for all design.md files」。當你：

1. 下載任一 DESIGN.md
2. 放進專案 root
3. AI agent 自動讀

→ DESIGN.md 內的文字會 被當成 system prompt 的一部分。攻擊者只要 PR 一份惡意 DESIGN.md，所有用它的人都受影響。

給導入團隊的清單

• 下載後先 diff：用前後 commit 對比 git log --oneline design-md/<brand>/DESIGN.md

• 檢查 prompt injection pattern：grep 是否有 ignore previous / system prompt / exfiltrate / curl / 異常 URL

• AI agent 啟用 sandboxed read：別讓 agent 在 read DESIGN.md 後自動執行 shell command（Claude Code 預設要 approval，OK；Cursor agent mode 要小心）

• 固定版本：用 git submodule 或下載指定 commit 的 raw，不要 always-main

• 對外發佈 / 內部標準化前 pin 到一個 commit SHA 並 review 一次：

  1COMMIT=4482a96  # 2026-05-17 main HEAD
  2curl -L -o DESIGN.md \
  3  "https://raw.githubusercontent.com/VoltAgent/awesome-design-md/${COMMIT}/design-md/stripe/DESIGN.md"
  

• 公司內如果有 design system 中央目錄，自己 fork + 內部 mirror，不要直接連外部 raw URL

⚠️ 這不是說 awesome-design-md 不安全 — 維護者 VoltAgent 看起來認真（PR review、issue triage 都活）。是說 這類「AI agent 讀的 markdown」應該套用 supply chain 思維：固定版本、code review、不 auto-fetch。

7. FAQ

Q1. DESIGN.md 跟 Tailwind config 哪個好？ A：兩者不衝突。DESIGN.md 規範「品牌語言」，Tailwind config 規範「實作 token」。最佳實踐：DESIGN.md → 人手轉成 tailwind.config.ts（或 AI agent 自動轉）。

Q2. 71 個都看完不可能，怎麼挑？ A：先讀 README 的分類，挑 2–3 個跟你產品 vibe 接近的。每份 DESIGN.md 約 400–850 行（純文字 + YAML），讀一份 5–10 分鐘。

Q3. 我自己的品牌沒在清單裡，能加嗎？ A：CONTRIBUTING.md 明確說：「不再接受新 DESIGN.md PR」（為了維持收錄品質）。但你可以：(1) Issue request；(2) 在自己 fork 加；(3) 用 getdesign.md 的 request 功能。

Q4. DESIGN.md v2 跟 v1 差在哪？ A：v2 主要重排 YAML 結構（更精準的 token 命名）+ 補完 9 段全部。看 commit history 2026-05-08 ~ 2026-05-17 多次 update DESIGN.md to v2 提交可追。

Q5. 為什麼 stars 8 萬 fork 卻不到 1 萬？ A：8.27 stars/fork 比例略偏 watch-only，但這在 awesome-list 屬正常。fork 多半發生在「想自製 DESIGN.md 又懶得從零開始」的人。

Q6. AGENTS.md 跟 DESIGN.md 要不要同時放？ A：要。AGENTS.md 給 coding agent 看「怎麼建專案」，DESIGN.md 給「該長什麼樣」。一份完整的 AI-readable repo 應該兩份都有。

Q7. 從 design-md//preview.html 哪去了？ A：v2 升級時搬到 getdesign.md 中央站（避免 71 × 2 = 142 份 HTML 在 repo 內維護）。要看 preview 直接到 <https://getdesign.md//design-md>。

8. 進階技巧

8.1 自己寫 DESIGN.md 的 7 個步驟

1. 挑相近品牌的 DESIGN.md 當 template（見 §5.4）
2. 抓自家品牌的 design tokens（從 Figma / Sketch / 既有 CSS variable export）
3. 填 YAML frontmatter：colors / typography / spacing / shadows
4. 寫 §1 Visual Theme：用「一句話形容感覺 + 一句話形容對比品牌」
5. 填 §4 Components：列出 Button / Card / Input 等各狀態（hover / active / disabled / focus）
6. 寫 §7 Do’s and Don’ts：這段是 agent 最常看的，寫得越具體 prompt 結果越好
7. 寫 §9 Agent Prompt Guide：直接給 ready-to-use prompts，例如「Use #635BFF as primary, Inter weight-300 for h1…」

8.2 DESIGN.md → Tailwind config（一步轉換）

1# 給 Claude Code 一個 prompt：
2> 讀 DESIGN.md，把 colors 段轉成 tailwind.config.ts 的 theme.extend.colors 設定，
3> 把 typography 段轉成 fontFamily + fontSize + fontWeight。

8.3 DESIGN.md → Style Dictionary tokens

同上邏輯，prompt 改成轉 tokens.json Style Dictionary 格式。

8.4 對多份 DESIGN.md 做語意搜尋

1# 用 graphify 對 design-md/ 跑知識圖
2graphify analyze design-md/
3graphify query "找用紫色 primary + sans-serif display 的品牌"

或用 paper-qa-lite 做 RAG 問答：

1pq: 哪個品牌的 button hover state 用 transform: scale()? --files design-md/

8.5 自製 DESIGN.md 驗證器

 1import yaml
 2from pathlib import Path
 3
 4def validate_design_md(p: Path) -> list[str]:
 5    text = p.read_text()
 6    fm_match = re.match(r"^---\n(.*?)\n---\n", text, re.DOTALL)
 7    if not fm_match:
 8        return ["missing YAML frontmatter"]
 9    fm = yaml.safe_load(fm_match.group(1))
10    errs = []
11    required = ["colors", "typography"]
12    for k in required:
13        if k not in fm: errs.append(f"missing key: {k}")
14    # 9 段標題檢查
15    for i, name in enumerate([
16        "Visual Theme", "Color Palette", "Typography Rules",
17        "Component Stylings", "Layout Principles", "Depth",
18        "Do's and Don'ts", "Responsive", "Agent Prompt Guide",
19    ], 1):
20        if f"## {i}" not in text and f"## {i}." not in text:
21            errs.append(f"missing section {i}: {name}")
22    return errs

8.6 把 DESIGN.md 接到 Storybook

寫一個 Storybook addon，把 DESIGN.md 的 colors / typography 段渲染成 swatch + type scale 頁。比手寫 Storybook tokens 文件快 10×。

9. 整合進其他工作流

9.1 與本知識系統的關係

9.2 推薦進階組合

1DESIGN.md (本 repo) → 抽 design tokens
2   ↓
3AGENTS.md (專案 root)
4   ↓
5Claude Code / Cursor → 蓋 React + Tailwind landing page
6   ↓
7Storybook (DESIGN.md addon) → 互動式 design system docs
8   ↓
9graphify 索引 → 內部 AI 設計問答

10. 重點摘要 Checklist

• DESIGN.md = 設計版的 AGENTS.md，LLM 母語格式 (markdown + YAML)
• 71 個品牌 ready-to-use；MIT license；無需安裝
• 9 段標準結構（Theme / Color / Typography / Component / Layout / Depth / Dos&Donts / Responsive / Agent Prompt）
• 用法：curl raw URL → DESIGN.md → 放專案 root → AI agent 自動讀
• 跟 AGENTS.md 並存：AGENTS.md（怎麼建）+ DESIGN.md（怎麼長）
• 沒有任何可執行碼，但 有 prompt injection vector（issue #396 提出）
• 資安做法：固定 commit SHA、內部 mirror、grep 異常 pattern、sandboxed AI agent
• 挑檔策略：先按分類（AI / Devtool / Fintech / Auto 等）→ 挑 2–3 vibe 接近 → 5–10 分鐘讀完一份
• CONTRIBUTING.md 明示「不再接受新 DESIGN.md PR」→ 要新品牌走 issue request
• 進階：DESIGN.md → Tailwind config / Style Dictionary / Storybook addon

11. 進一步閱讀

• Google Stitch DESIGN.md spec：https://stitch.withgoogle.com/docs/design-md/overview/
• Google Stitch DESIGN.md format：https://stitch.withgoogle.com/docs/design-md/format/
• 中央目錄 + dark preview：https://getdesign.md/
• 請求新 DESIGN.md：https://getdesign.md/request
• VoltAgent AI agent 框架：https://github.com/VoltAgent/voltagent
• Discord 社群：https://s.voltagent.dev/discord
• Style Dictionary（design token 管理）：https://amzn.github.io/style-dictionary/
• Tailwind CSS：https://tailwindcss.com/
• 「AGENTS.md」概念：https://github.com/openai/codex/blob/main/AGENTS.md（業界 reference）

教學完成日：2026-05-18 | 對應 commit：4482a96（2026-05-17 main HEAD）| Generated by gh-tutorial-qd skill