DESIGN.md 是什麼？Vibe Coding 必備神器，讓 AI 遵循你的設計生成網站

什麼是 DESIGN.md？

DESIGN.md 是一個由 Google（在其 AI 設計工具 Google Stitch 中）引入的全新概念，專門用來解決 AI 生成程式碼時的 UI 設計一致性問題。

他是一個純文字的 Markdown 檔案，作為網站設計系統的資料。

過去我們做網站時，需要依賴依賴 Figma 的匯出檔或各種散落在各處和設計相關的需求，而 DESIGN.md 則直接使用純文字標記（tokens）來描述專案的視覺風格與介面規則。

透過 Markdown 格式，讓 AI（如 Claude Code、GitHub Copilot、Codex、Gemini CLI 等）理解專案的視覺設計，並應用在生成的程式碼中。

為什麼需要 DESIGN.md？

如果沒有 DESIGN.m，AI 生成程式碼往往會遇到以下問題Ｌ

1. AI 生成 UI 的不一致性： 當你要求 AI 寫一個元件時，如果沒有給予明確限制，AI 往往會生成非常通用或每次都不一樣的介面，或是需要浪費上下文，理解你的專案設計。而 DESIGN.md 給予了 AI 明確且一致的視覺規則，確保生成的設計符合你的產品風格。
2. 約束 AI 以產生更好的結果： 受約束的 AI 比不受約束的 AI 能產生更一致、更有用的輸出。透過提供色碼、字體和間距的硬性規定，AI 就能專注於處理版面結構、響應式行為、功能實現等複雜的決策，不需要胡亂猜測設計細節。
3. 人類與機器皆可讀： Markdown 格式不僅機器容易解析，設計師與開發者也能直接閱讀、編輯和討論，沒有什麼學習門檻。

DESIGN.md 9 大內容

一個標準的 design.md 檔案通常涵蓋了 AI 做出視覺決策所需的所有具體標記（Tokens），主要內容包含：

1. 色彩配置（Color palette）： 包含主色、次要色和強調色的精確 Hex 色碼，以及語意化色彩（如成功、警告、錯誤等）和文字顏色層級。
2. 排版與字體（Typography）： 字體家族與備用字體、字體大小縮放比例（標題、內文、註解）、字體粗細、行高與字距。
3. 間距與佈局（Spacing and layout）： 基礎間距單位（如 4px 或 8px 網格系統）、常用的間距數值、容器寬度與響應式斷點。
4. 元件樣式（Component styles）： 按鈕與卡片的圓角數值（Border radius）、陰影定義與層級、邊框樣式與粗細。

在某些擴充版本中，還會進一步包含：

5. 設計氛圍與主題（Visual Theme & Atmosphere）： 用文字描述整體視覺風格與品牌個性，比如「溫暖極簡」、「科技冷冽」、「文學質感」。這讓 AI 在面對沒有明確規範的設計決策時，有一個方向感可以依循，而不是靠猜測。
6. 陰影與層次（Elevation & Depth）： 定義不同高度層級對應的陰影規格，例如卡片、彈窗、浮動按鈕各自用什麼陰影。
7. 設計的 Do's and Don'ts（應做與不應做）： 明確列出哪些設計決策是禁區，例如「不要用純黑 #000000 作為文字色」、「按鈕不要加 box-shadow，用背景色區分狀態」。這類約束對 AI 特別有效，能防止它用正確規格做出風格不符的元件。
8. 互動模式（Interaction & Motion）： 描述 hover、focus、transition 的行為規則，包含動畫時長與緩動函數。
9. AI 提示詞指南（Agent Prompt Guide）： 直接在 DESIGN.md 裡放幾個標準元件的 prompt 範本，讓工程師可以直接複製貼上，快速生成符合設計系統的元件，或是讓 AI 生成時，可以參考下 Prompt 的指示。

如何創建 DESIGN.md

建立 DESIGN.md 不一定要從頭手寫，有幾種方式可以快速上手，不管你是全新專案還是既有專案都適用：

1. 手動創建：參考上面的資訊，直接在專案新增 DESIGN.md
2. 使用 Google Stitch：如果是新專案，也可以利用 Google Stitch，請他幫忙生成 DESIGN.md
3. 參考社群的最佳實踐：參考 Awesome Design md，裡面有多個品牌的 DESIGN.md，像是蘋果、Figma、Airbnb、Spotify 等等，直接複製到你的專案中即可使用。
4. 利用規格化的 Prompt：這邊也提供一個規格化的 Prompt，AI 會透過提問，幫你生成適合的 DESIGN.md

你是一位資深品牌顧問與產品策略師。

你的任務是一步一步引導使用者釐清品牌，透過對話收集資訊，最後產出可用於品牌網站的初步描述。

## 每次提問規則與格式

每次回覆請遵守：

1. 一次只問一個問題，等使用者回答後，才問下一題
2. 問題嚴格遵守下面提供的文字
3. 在第 1～5 題過程中，不要做任何總結或完整設計
4. 如果使用者回答不清楚，只針對該題做簡單追問
5. 每一步都要在內部整理目前已收集的資訊，並用來優化後續問題
6. 每次提問前，先用一句簡短自然的話，告訴使用者這一步要了解什麼

## 容錯規則

如果使用者出現以下情況：

- 回答「不知道」
- 回答過於模糊
- 回答「都可以」

請不要跳題。

改為只針對該題提供 2～3 個簡單範例或選項，幫助他選擇。

## 對話流程（固定順序）

請依照以下順序逐題詢問。

### 第 1 題：品牌名稱

詢問：

「你的品牌名稱是什麼？」

### 第 2 題：主要顏色

詢問：

「你的品牌主要顏色是什麼？

你可以用顏色名稱回答，例如鮮豔的粉紅色、較淡奶茶色、暗沉的紅色、科技感的藍色 … 等等；

也可以直接提供色碼，例如 #FFB6C1。」

### 第 3 題：品牌服務

詢問：

「你的品牌主要產品或服務式什麼？

例如可愛的手作飾品、男士服飾品牌、文青感的咖啡廳、線上課程等等。」

### 第 4 題：主要受眾

根據品牌名稱與品牌服務，生成 5 個目標客群選項，並詢問：

「你的主要客群比較接近哪一種？」

請遵守：

- 選項要彼此明顯不同
- 使用簡單語言，避免專業術語
- 每個選項一句話內
- 先用一句簡短過渡，再提供選項

格式如下：

A. ...

B. ...

C. ...

D. ...

E. ...

F. 其他（請描述）

### 第 5 題：網站風格

根據目前所有資訊（品牌名稱、顏色、服務、受眾），生成 10 個網站風格選項。

詢問：

「你希望網站風格比較接近哪一種？」

選項規則：

- 提供網站常見風格
- 描述簡單，例如可愛插畫風、極簡質感風
- 選項之間要有差異
- 每個選項後面要告訴使用者具體會如何影響網站風格，例如配色變淡、邊框有手繪感等等

格式如下：

A. ...（簡短描述）

B. ...

C. ...

D. ...

E. ...

…

J. 其他（請描述）

## 輸出品牌網站描述

```
## 1. Visual Theme & Atmosphere

## 2. Color palette

## 3. Typography

## 4. Spacing and layout

## 5. Component styles

## 6. Interaction & Motion

## 7. Responsive Behavior

## 8. Do's and Don'ts

## 9. Agent Prompt Guide
```

## 限制

- 你的角色是引導使用者釐清，不要在過程中做設計，只有在第 6 步，才進行完整輸出。
- 僅輸出合法 Markdown
- 不要輸出任何說明文字
- 不要產生程式碼

如何更新 DESIGN.md

DESIGN.md 應該被是一個活的文件，也就是說要定期更新、維護他。

當你的品牌顏色改變、新增子品牌、調整元件樣式或推行新的間距規範時，就需要進行更新。

這邊提供幾個更新 DESIGN.md 的方式與最佳實踐：

1. 整合至 Git 版本控制： 因為它是純文字檔，你可以自然地將它納入 Git 工作流程中。團隊可以透過 Commit 歷史記錄追蹤設計標記的變更，並透過 Pull Requests (PRs) 來審查設計更新，就像審查程式碼一樣。
2. AI 自動更新或手動編輯： 你可以使用 AI 工具（如 Google Stitch）透過自然語言提示（例如：「把我們的主題改成深色模式」）來自動產生或更新 DESIGN.md。
3. 保持規格具體且量化： 更新內容時，使用具體的數值而非模糊的描述。例如，寫 #1A73E8 而不是「讓人感到信任的藍色」；寫 8px 而不是一點點圓的圓角。我們的語意必須精確，盡可能讓 AI 知道他該知道的細節。
4. 精簡扼要： 不要把完整設計系統中的教學或什麼長篇大論塞進去，這無助於 AI 生成。只保留 AI 需要的具體 Token 即可。另外也不要讓檔案過時，否則 AI 就會生成不符合當前品牌的錯誤介面。

除了以上方法，我也很推薦大家使用 Skill 來維護 DESIGN.md：

你可以自己定義一個 /design-guard Skill，放到專案的 CLAUDE.md 或 ~/.claude/agents/ 下。

當你描述的元件或設計方向和 DESIGN.md 不一致時，先主動提醒你：

• 目前描述和 DESIGN.md 哪裡不同
• 是否要把這次的新設計同步回 DESIGN.md
• 如果要更新，應該新增、覆蓋，還是只補充例外規則

這樣做的好處是，AI 不會偷偷把設計規範改掉，也不會因為 DESIGN.md 過時而硬做出不符合需求的介面。

---
name: design-guard
description: 當使用者描述的元件或設計方向與 DESIGN.md 不一致時，主動詢問是否要更新 DESIGN.md
---

Before creating or modifying any UI component, read `DESIGN.md` and compare it
with the user's latest request.

If the user describes a component, layout, color, typography, spacing, motion,
or visual style that conflicts with `DESIGN.md`, do not update the file
silently.

First, explain the difference clearly and ask:

1. Should this new decision update `DESIGN.md`?
2. If yes, should it replace the existing rule, be added as a new rule, or be
   recorded as an exception for this specific component?

Only update `DESIGN.md` after the user confirms how the design system should
change.

如何在 Claude Code 中使用 DESIGN.md

由於目前 Claude Code 還沒有添加 DESIGN.md 的相關規範，所以我們可以在 CLAUDE.md 中，手中添加相關敘述，讓 Claude Code 自動套用網站的設計，比如說：

This project uses a design system defined in `design.md` at the project root. Always refer to this file when generating or modifying any UI component.

總結

DESIGN.md 的核心價值，在於它把原本散落在 Figma、設計稿、Confluence 的設計決策，濃縮成一份 AI 可以讀懂的參考文件，讓每一次請 AI 生成元件，都能符合你的品牌風格。

隨著 AI 工具逐漸成為前端開發的主要生產力，設計一致性的問題也會越來越重要。DESIGN.md 就是目前最輕量、最務實的解法，不需要什麼新的特殊工具、不需要學習新格式，只需要一份好好寫的 Markdown，就能讓你的 AI 助手真正理解你的設計語言。