我做了一個開源的設計工作臺：管理 & 編輯 & 生成 DESIGN.md

原始來源與檔名：2026-09-04T094457+0800-我做了一個開源的設計工作臺：管理 & 編輯 & 生成 DESIGN.md

SOURCE | 資訊源評估

• 準確性: 高 - 作者親自介紹其開源專案 (RICOUI DESIGN) 的設計理念、架構與使用方式。
• 易理解性: 高 - 透過清晰的表格、使用場景劃分（看 vs 做）與架構圖，清楚說明 DESIGN.md 的結構與價值。
• 閱讀策略建議: 適合設計師與前端工程師閱讀。重點關注 DESIGN.md 的骨架結構，以及如何將「不該怎麼做 (Don’ts)」納入給 AI 的提示詞中。

NAPKIN | 餐巾紙

餐巾紙公式

DESIGN.md = Design Tokens (顏色/排版/間距) + 元件約束 + Do’s and Don’ts 一份人類好讀、AI 易懂，並能自動派生 CSS 與 JSON 的唯一設計真相源 (Single Source of Truth)。

一句話

作者開源了一個名為 RICOUI DESIGN 的工作臺，推廣使用 DESIGN.md 作為介於 Figma 與前端程式碼之間的橋樑，讓 AI 與開發者能準確理解並生成符合品牌規範的介面。

餐巾紙草圖

+-----------------------+
| 參考源 (Brands/網址)    | -> (AI 萃取)
+-----------------------+      |
                               v
                     +-------------------+
                     |    DESIGN.md      | (唯一維護的原始檔)
                     | - 結構化 Markdown   |
                     | - 包含品質護欄       |
                     +-------------------+
                       /       |       \
                     /         |         \ (自動派生檢查)
                   v           v           v
          +---------+   +----------+   +----------+
          |  預覽檢視 |   | Token JSON |   | CSS 變數 |
          +---------+   +----------+   +----------+
          (設計師看)     (前端工程師用)   (AI 工具用)

ROUND 1: SKELETON | 骨架掃描

“這本書在說什麼”

• 核心問題: 設計規範散落在 Figma、協作檔案和程式碼中，難以維護，且現有的 Design Token 無法有效告訴 AI「元件該怎麼用」以及「不該做什麼」。
• 核心答案: 建立一個基於 Markdown 的標準化檔案 DESIGN.md 作為唯一事實來源，並透過工作臺進行視覺化編輯、預覽，再自動派生出開發所需的 CSS 與 JSON。
• 論證結構: 痛點與解法介紹 -> 解釋 DESIGN.md 的結構與意義 -> 產品功能走查 (看與做) -> 不同角色的獲益 -> 雲端與開源部署說明 -> 核心設計哲學。

章節骨架

1. 背景與痛點: 品牌庫好用但難以直接轉化為專案規範，設計細節容易遺忘。
2. DESIGN.md 是什麼: 一套固定的 Markdown 骨架 (包含 Tokens, Components, Do’s and Don’ts)，人類與 AI 皆可讀。
3. 工作臺功能 - 看與做: 從品牌庫找靈感 (看)，到修改、建立與交付自己的規範 (做)。
4. 角色收益: 設計師得視覺控制、前端得程式碼、AI 得上下文。
5. AI 輔助生成: 可輸入公開網址，讓 AI 萃取並起草 DESIGN.md (作為分析起點而非精確複製)。
6. 派生與安全機制: 只有透過校驗的 MD 才能匯出 CSS/JSON，避免產生錯誤依賴。

ROUND 2: DISSECTION | 血肉解剖

“憑什麼這麼說”

論證鏈

Figma 專注於視覺，Design Token 僅包含原子數值，兩者都缺乏語意化的設計上下文 --> 透過建立 DESIGN.md，將數值與「設計決策 (約束與禁忌)」結合 --> AI 獲得了完整的上下文，能寫出更符合品牌規範的程式碼，同時前端也免去了手動維護 Token 的麻煩。

關鍵證據

1. 品質護欄 (Do’s and Don’ts) 的價值: 作者指出，告訴 AI「不隨意增加新的強調色」或「不同時出現多個主要按鈕」，往往比單純給 AI 一個色值更能防止設計崩壞。
2. 單一真實來源 (SSOT): 實務上，若允許修改產出的 JSON 或 CSS，會導致規範立刻與設計稿脫節。因此係統設計為「CSS 匯出會被鎖住，除非 DESIGN.md 透過語法與變數引用檢查」。

隱形假設與邊界

• 隱形假設:
  • AI (如 Claude, Cursor) 具備足夠的 Markdown 閱讀與理解能力，能嚴格遵循檔案中的約束。
• 邊界條件:
  • 透過網址自動生成 DESIGN.md 僅能作為「分析起點」，無法 100% 準確還原複雜網站的佈局層級與隱藏狀態。

ROUND 3: SOUL | 靈魂提取

“還能怎麼用”

• 作者盲點: 對於大型企業中「多品牌 (Multi-brand)」或「多主題 (Multi-theme, 如高對比模式)」在單一 Markdown 中的組織與繼承方式，說明較少。
• 知識連線: 此概念與基礎設施即程式碼 (Infrastructure as Code) 中的宣告式配置 (Declarative Configuration) 類似，將「設計」宣告為一份文字，再由系統編譯 (派生) 為各種最終產物。
• 行動觸發: 在團隊的 Frontend Repo 根目錄下建立一份 DESIGN.md，並把「不要做的事情 (Don’ts)」寫清楚，然後將其加入 Cursor 的 .cursorrules 參考檔案中。

留白提問 (Guided Reflection)

• 提問：在你的專案中，當 AI 幫你寫前端 UI 時，它是否經常發明新的顏色或間距？
  • 架構師視角 (引導思路)：這通常是因為缺少了「設計上下文」。你給了 AI Tailwind 的工具，卻沒有給它設計手冊。匯入 DESIGN.md 作為 Prompt 的一部分，是收斂 AI 輸出的最佳解法。

跨域對映

• 在 軟體架構，這叫 單一真相來源 (Single Source of Truth) 與檔案即程式碼 (Docs-as-Code)。

DEEP READ | 精讀指引 (Must-Read Segments)

[!IMPORTANT] 學習的本質需要「認知阻力」。請親自回到原文閱讀以下核心段落，感受原始論述的阻力，不要只依賴 AI 的總結。

1. DESIGN.md 是什麼 (結構與意義)

   • 「Figma 仍然更適合做視覺設計和元件協作，Design Token 更適合儲存顏色、字號、間距、圓角這些原子值。DESIGN.md 在我的工作流裡更像一層『設計上下文』…」
   • 推薦理由: 精準定位了 DESIGN.md 在現代工具鏈中的生態位。它不是用來取代 Figma，而是補足了設計決策與 AI Prompt 之間的缺失環節。

2. 檢查、匯出說明 (派生校驗機制)

   • 「一份文件『能儲存』和『能正確派生 Token、CSS』是兩回事…如果檢查沒有透過，CSS 匯出會被鎖住…這樣做是為了避免匯出一份彼此對不上的 CSS。」
   • 推薦理由: 這展現了嚴謹的工程思維。容錯的 Markdown 編輯與嚴格的程式碼編譯分離，確保了下游工程師不會拿到破壞性的依賴。

STRUCTURE MAP | 全書結構圖

RICOUI DESIGN (DESIGN.md 工作臺)
+-- 為什麼需要 DESIGN.md
|   +-- 解決設計規範散落的問題
|   +-- 提供給 AI 完整的設計上下文 (超越純 Token)
+-- 核心骨架 (Markdown 結構)
|   +-- 品牌調性 & Theme
|   +-- Tokens (Colors, Typography, Spacing/Shapes)
|   +-- Components (元件約束)
|   +-- Do's and Don'ts (品質護欄，對 AI 極重要)
+-- 產品功能模組
|   +-- 看：Brands 品牌參考庫 (拆解成熟產品)
|   +-- 做：編輯器 (原始碼/結構化/預覽檢視切換)
|   +-- 魔法：輸入網址透過 AI 萃取起草
+-- 工程與交付
|   +-- 派生校驗：必須合法才能產出 CSS/JSON
|   +-- 產出物：tokens.json, variables.css, Tailwind v4 theme
+-- 部署與架構
|   +-- 本地優先 (IndexedDB)
|   +-- 支援 Supabase 雲端同步與開源自建

/我做了一個開源的設計工作臺：管理 & 編輯 & 生成 DESIGN.md

我做了一個開源的設計工作臺：管理 & 編輯 & 生成 DESIGN.md (Architectural Deep Dive)

前言/背景

當 AI（如 Cursor、Claude 等）開始接管越來越多的前端與介面開發工作時，開發者面臨了一個巨大的痛點：設計規範散落在 Figma、協作文件和程式碼中，導致 AI 在生成介面時經常「發明」新的顏色或破壞品牌調性。為此，開源專案 RICOUI DESIGN 的作者提出了一種架構解法：將設計系統抽象化為一份結構化的 Markdown 文件——DESIGN.md，並為其打造了集管理、編輯、生成於一體的工作檯。這本質上是將「設計規範」程式碼化（Docs-as-Code），作為跨越設計師、前端工程師與 AI 之間的「單一真相來源（Single Source of Truth）」。

章節詳細總結

1. DESIGN.md 的架構定位與骨架設計

作者明確指出，DESIGN.md 並非用來取代現有的設計工具：

• Figma 依然最適合做視覺設計與元件協作。
• Design Token 依然最適合儲存顏色、字號等原子值。 DESIGN.md 在系統工作流中的生態位，是一層「設計上下文（Design Context）」。它本質上是一份依照固定結構撰寫的 Markdown，既能讓人類閱讀，也能讓 AI 輕易解析。

一份標準的 DESIGN.md 最小骨架包含以下結構：

# Acme — Style Reference
> 一句话品牌调性
**Theme:** light

## Tokens — Colors
## Tokens — Typography (包含完整的 fallback chain)
## Tokens — Spacing & Shapes
## Components (元件約束)
## Do's and Don'ts (品質護欄)
## Imagery / Layout (圖片風格與佈局)

在撰寫規範上，作者堅持了幾項工程實踐：

1. 表格化管理：Token 必須使用 Markdown 表格儲存，保留 Name / Value / Token / Role 欄位，方便程式解析。
2. 字型後備機制：直接在文件中寫入完整的 Fallback Chain，免去另行維護字型清單的麻煩。
3. 語義化引用：組件部分必須引用前面定義好的 Token（例如：按鈕的主色使用 --color-brand），絕對不允許重新硬編碼（Hardcode）色值。

2. 對 AI 最致命的環節：品質護欄 (Do’s and Don’ts)

這份設計系統中最具價值的段落，往往不是精確的 HEX 色碼，而是 Do's and Don'ts。作者強調：「告訴 AI 不應該怎麼設計，比單純告訴它一個數值更有用。」 例如，在文件中明確規定：

• Do: 保持大面積留白；一屏只保留一個主要操作。
• Don’t: 不隨意增加新的強調色；不同時出現多個主要按鈕。 這些自然語言的約束，無法被轉換為 CSS 變數，但在作為 AI 的 System Prompt 時具有決定性作用。它讓 AI 知道「這個產品應該繼續怎麼設計」，有效抑制了 LLM 在生成介面時過度發散的幻覺。

3. 工作檯的兩大核心：看與做 (Browse & Build)

RICOUI DESIGN 提供了極低摩擦力的工作流：

• 看（品牌參考）：系統內建了大量知名品牌的 DESIGN.md 解析。使用者不再只是看 UI 截圖（截圖只能告訴你最後長怎樣），而是可以直接拆解其顏色層級、間距階梯與元件約束，甚至直接複製一份作為自己專案的起點。
• 做（編輯與交付）：如果連第一版都不想寫，可以輸入一個公開網址，利用 AI（接入自己的 API Key）先起草一份 DESIGN.md。系統會讀取頁面元資訊與樣式訊號，提取出品牌色、字型與 Token 結構。但作者嚴格界定了邊界：這只是分析起點，複雜網站背後的完整設計系統不可能從單一頁面完全還原，重要數值仍需人工覆核。

4. 嚴謹的派生與防呆機制 (Validation & Derivation)

在軟體架構設計上，作者展現了極強的工程思維：區分了「能保存的文件」與「能正確派生出程式碼的文件」。 普通 Markdown 只要有內容就能保存；但若 Token 名稱不合法、變數引用（如 var(--token)）最終無法解析，此時如果系統依然生成 CSS，將會導致下游前端工程師拿到損壞的依賴。 因此，系統實作了嚴格的狀態機校驗：

• 只有當 Token 與數值通過派生檢查後，系統才會解鎖 CSS 與 JSON 的匯出功能。
• 通過檢查後，系統會從 DESIGN.md 單向派生出 tokens.json (DTCG 格式)、variables.css (CSS Custom Properties)、theme.css (Tailwind v4) 與 ZIP 壓縮包。 這強制了使用者必須將 DESIGN.md 作為唯一維護的原始檔，徹底杜絕了「手動去改生成的 CSS 導致設計規範脫節」的歷史難題。

總結與結論

• Docs-as-Code 的實踐：將設計規範抽象為高度結構化的 DESIGN.md，實現了人類可讀、機器可解析、AI 可推理的三贏局面。
• 上下文比數值更重要：在 AI Coding 時代，約束語意（Do’s and Don’ts）和元件間的關聯關係，才是確保 AI 產出穩定介面的核心防線。
• 單向資料流與防呆：透過嚴格的派生檢查，確保 DESIGN.md 始終是唯一且純潔的真相來源（Single Source of Truth），避免了設計與開發的長期脫節。