什麼是 DESIGN.md？

每個專案都有一套視覺識別：色彩、字型、間距、元件樣式。長久以來，這些東西存在於 Figma 檔案、品牌 PDF，或設計師的腦袋裡。這些形式，AI 代理程式全都讀不懂。

DESIGN.md 改變了這一切。 它是一份純文字設計系統文件，人類與代理程式都能閱讀、編輯並強制執行。你可以把它想成 AGENTS.md 在設計上的對應版本：

檔案	誰會讀它	它定義了什麼
README.md	人類	專案是什麼
AGENTS.md	程式碼代理程式	如何建構專案
DESIGN.md	設計代理程式	專案該呈現什麼樣的樣貌與感受

它能為你帶來什麼

當 Stitch 這類設計代理程式讀取你的 DESIGN.md 時，它產生的每一張螢幕都會遵循同一套視覺規則：你的色彩調色盤、你的字體排印、你的元件樣式模式。少了它，每張螢幕各自獨立；有了它，它們看起來就像是同一個設計體系出來的。

DESIGN.md 是一份活的產物，而不是靜態的設定檔。它會隨著你的設計演進而演進。代理程式產生它，你把它打磨得更精緻，而當你持續迭代時，它會再次套用到螢幕上。

在底層結構上，每份 DESIGN.md 都包含兩層：YAML front matter，存放機器可讀的設計 token（精確的十六進位色值、字型屬性、間距級距），以及 markdown 本文，提供人類可讀的設計理念。Token 為代理程式提供精確的數值；文字說明則告訴它們這些數值存在的原因。完整格式請參閱規範。

設計哲學

DESIGN.md 規範是一套基礎，而非處方。它提供代理程式、工具與團隊都能倚賴的共同基礎——一套涵蓋色彩、字體排印、版面配置與元件的共用詞彙——同時保留為特定領域需求擴充格式的自由。未知的章節與自訂 token 會被接受，而不是遭到拒絕。

如何建立

建立 DESIGN.md 有三條路徑，從毫不費力到精準嚴謹。

Stitch

讓代理程式自行產生

描述你想要的氛圍。代理程式會把你的美學意圖轉譯成 token 與設計準則。

Stitch 會產生完整的設計系統（色彩、字體排印、間距、元件樣式），並摘要成一份 DESIGN.md。

從品牌推導

如果你已經有品牌，提供 URL 或圖像即可。代理程式會擷取你的調色盤、字體排印與樣式模式，從既有素材建構出 DESIGN.md。

Stitch

親手撰寫

進階使用者可以直接撰寫 DESIGN.md，把精確的設計偏好編碼進去。每個章節都只是 markdown，可選擇加上用於設計 token 的 YAML front matter。除了標準 markdown 與 YAML 之外，沒有特殊語法。

範例

以下是深色主題生產力應用程式的精簡 DESIGN.md 範例。YAML front matter 定義精確的 token 數值；markdown 本文則說明設計意圖。

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14–16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

這就是代理程式在產生下一張螢幕時所讀取的內容。完整格式規範請參閱規範；想依照規範驗證你的 DESIGN.md，請參閱使用 CLI 驗證。