從前端程式碼提取設計系統
分析前端原始碼，提取一份全面的設計系統文件（DESIGN.md），該文件直接從原始檔案中捕捉專案的視覺語言——顏色、排版、間距、元件模式和佈局原則——無需構建或渲染應用程式。
為何存在
design-md 技能是從渲染後的 HTML 中提取設計。但通常你有一個程式碼庫，希望在甚至能夠執行應用程式之前就了解其設計系統——可能依賴缺失、構建失敗，或者你只是想快速審查。此技能會讀取原始檔案本身：樣式表、元件檔案、主題設定和 Tailwind 設定。它更快，且在任何地方都能運作。
何時使用
- 使用者有一個前端程式碼庫，想要提取或記錄其設計系統
- 使用者想要將專案的視覺識別遷移到 Stitch
- 使用者要求「審查樣式」或「了解倉庫的設計語言」
- 使用者想要從現有原始碼建立 DESIGN.md
- 應用程式無法構建/渲染，但原始碼可用
- 使用者想要統一模組化整個程式碼庫中不一致的樣式
先決條件
- 可存取前端專案的原始目錄
- 不需要構建或執行時期依賴——此技能僅讀取原始檔案
工作流程
第一階段：專案探索
首先了解你正在處理的是什麼。這決定了要使用哪些提取模式。
1. 檢測框架和技術棧
掃描專案根目錄以尋找標誌性檔案：
| 標誌性檔案 | 框架/工具 |
|---|---|
package.json 包含 react | React / Next.js |
package.json 包含 vue | Vue / Nuxt |
package.json 包含 svelte | Svelte / SvelteKit |
package.json 包含 @angular/core | Angular |
tailwind.config.js/ts | Tailwind CSS |
postcss.config.js | PostCSS 管道 |
styled-components 或 @emotion 在依賴中 | CSS-in-JS |
僅 .css / .scss / .less 檔案 | 純 CSS / SASS |
theme.js / theme.ts / tokens.js | 設計代碼檔案 |
首先讀取 package.json——它會揭示框架、CSS 工具以及任何設計代碼庫（例如 style-dictionary、@chakra-ui/react、@mui/material、ant-design）。這個上下文告訴你在哪裡尋找樣式資訊。
2. 映射原始檔樹
識別你將分析的主要目錄和檔案：
src/
├── components/ ← 元件層級樣式
├── styles/ ← 全域樣式表
├── theme/ ← 主題定義、代碼
├── assets/ ← 字型、圖片
├── app.css ← 根樣式
└── index.css ← 入口 CSS
也要檢查：
tailwind.config.js/tailwind.config.ts— 自訂顏色、字型、間距globals.css/global.css— CSS 自訂屬性（變數）- 任何
theme.*或tokens.*檔案 - 元件庫設定（例如
chakra-theme.ts、vuetify.config.ts）
3. 讀取框架特定指南
查閱適當的參考文件以了解提取模式：
- React / Next.js / Tailwind → references/react-tailwind.md
- Vue / Nuxt → references/vue.md
- Svelte / SvelteKit → references/svelte.md
- Angular → references/angular.md
- 純 CSS / SASS / Less → references/plain-css.md
這些參考文件包含框架特定的模式，用於定位顏色、排版、間距和元件樣式。在繼續之前，請閱讀與你專案相符的那個。
第二階段：深度提取
系統性地處理每個設計維度。對於每個維度，從原始檔案中收集原始數據，然後將其綜合為描述性語言。
目標不是傾倒每個 CSS 屬性——而是理解樣式選擇背後的意圖，並用人性化、編輯風格的語言描述它們，讓另一位設計師（或 Stitch）可以使用它們重新創造相同的視覺感受。
1. 視覺主題與氛圍
首先閱讀最廣泛的樣式，以了解整體情緒：
- 根背景：
body或根元素的背景是什麼？淺奶油色（#f 範圍）表示通風/乾淨；深色（#0-#2 範圍）表示陰鬱/戲劇化。 - 留白哲學：間距值是寬鬆的（32px+）還是緊湊的？檢查根容器、區塊包裝器和卡片元件的 padding/margin 值。
- 密度：計算每個頁面/區塊的元件數量。數量少且有空間 = 極簡；數量多且緊湊 = 資訊密集。
- 色溫：中性色是暖色（奶油色、棕褐色）還是冷色（藍灰色、石板色）？
- 整體感覺：將其綜合為 1-2 句豐富的句子，捕捉情緒。
在原始碼中尋找這些信號：
| 原始位置 | 它告訴你的資訊 |
|---|---|
根 background-color 或 Tailwind bg-* 在佈局上 | 整體明暗度 |
| Tailwind 設定中的間距比例或 CSS 變數 | 留白哲學 |
| 元件數量與包裝器 padding | 密度 |
自訂屬性命名（--warm-* 與 --cool-*） | 色溫意圖 |
| 主題檔案中的註解 | 開發者自己話語中的設計意圖 |
2. 顏色調色盤與角色
從程式碼庫中提取每種獨特的顏色，並分配功能角色。跨所有層級進行搜尋：
在哪裡尋找顏色：
| 層級 | 要搜尋什麼 |
|---|---|
| CSS 自訂屬性 | --color-*、--primary、--bg-* |
| Tailwind 設定 | theme.extend.colors |
| 主題/代碼檔案 | 顏色物件、調色盤 |
| 元件樣式 | background-color、color、border-color |
| 內聯/作用域樣式 | 範本中的 bg-*、text-* 類別 |
| CSS-in-JS 主題物件 | colors、palette 鍵 |
如何組織： 按功能將顏色分組，而不是按色調：
- 主要基礎 — 背景和表面顏色
- 強調與互動 — 號召性用語按鈕、活動狀態、連結
- 排版與文字層級 — 主要、次要、第三級文字
- 功能狀態 — 成功、錯誤、警告、資訊
對於每種顏色，創建一個描述性名稱，喚起顏色的特質，而不是其原始的十六進位值：
- ❌
#294056→ "藍色" - ✅
#294056→ "深沈柔和的藍綠色" — 主要 CTA，活動導航
去重很重要。 程式碼庫通常有接近重複的顏色（例如 #333 和 #2C2C2C）。將它們統一到最能代表預期顏色的名稱下。
3. 排版規則
提取完整的排版系統：
字型系列：
- 檢查 CSS
font-family、TailwindfontFamily、Google Fonts 連結或本機@font-face宣告。 - 注意每種字型的特徵：幾何 vs 人文主義、襯線 vs 無襯線、它所喚起的感覺。
字級比例（層級）：
- 找到每個標題層級（H1-H6）和正文，記錄：
font-size（以 rem 或 px 為單位）font-weight（數值 + 描述性名稱）letter-spacing（以及原因——優雅？緊湊？）line-height（寬鬆以利閱讀？緊湊以利顯示？）
- 繪製元件使用圖：產品卡片使用哪個標題層級？英雄區塊呢？
間距原則：
- 文字間距如何與整體間距比例相關聯？
- 標題與正文的字母間距模式
- 行高哲學（正文寬鬆/放鬆，顯示用更緊湊）
4. 元件樣式
分析 4-5 個最重要的 UI 原始元件：
按鈕：
- 圓角半徑（以及它傳達的資訊——有趣？專業？極簡？）
- 主要、次要和幽靈變體的配色方案
- 懸停/焦點/活動狀態和過渡時序
- 內邊距比例（水平 vs 垂直）
卡片 / 容器：
- 圓角半徑（通常與按鈕不同——稍微更圓）
- 陰影策略：平面、微妙的懸停陰影，或始終浮起？
- 邊框處理：極細邊框、彩色強調邊框，或無？
- 內部內邊距（寬鬆還是緊湊？）
- 卡片內的圖片處理（滿版出血、帶內邊距、圓角？）
導航：
- 佈局模式（水平欄、垂直側邊欄、抽屜）
- 排版處理（大寫、字母間距、粗細）
- 活動/懸停狀態指示器（底線、顏色、背景）
- 行動裝置行為（漢堡選單、底部導航、抽屜）
輸入框與表單：
- 邊框樣式和焦點狀態行為
- 與按鈕的圓角一致性
- 內邊距和觸控目標尺寸
領域特定元件：
- 識別 1-2 個此專案獨有的元件（例如產品卡片、儀表板小工具、聊天泡泡），並描述其樣式模式。
5. 佈局原則
提取結構系統：
網格與結構：
- 最大內容寬度（來自容器上的
max-width） - 欄位系統（CSS Grid、Flexbox 模式、定義的斷點）
- 響應式斷點（來自媒體查詢或 Tailwind 設定）
留白策略：
- 基本間距單位（8px 網格？4px？自訂？）
- 區塊邊距（主要區塊之間的空間量）
- 邊緣內邊距（不同斷點下的頁面邊距）
對齊與視覺平衡：
- 文字對齊模式（居中英雄區塊、左對齊正文）
- 圖片與文字比例
- 視覺重量分佈
響應式行為：
- 行動優先還是桌面優先？
- 網格如何折疊？內邊距比例？
- 觸控目標尺寸
6. Stitch 生成筆記
將提取的結果綜合為 Stitch 的可操作提示：
- 氛圍語言：將情緒轉換為自然描述詞
- 顏色參考：按描述性名稱 + hex 列出顏色
- 元件提示：撰寫 2-3 個範例提示，可用於在 Stitch 中重新建立關鍵元件
- 迭代指南：在此設計系統中改進畫面的技巧
第三階段：撰寫 DESIGN.md
將所有內容組裝成標準的 DESIGN.md 格式。將其放置在專案目錄的 .stitch/DESIGN.md 位置（如果 .stitch/ 目錄不存在，請建立它）。
[!IMPORTANT] 你必須在檔案頂部包含 YAML Frontmatter，其中包含
name和colors對應，與 examples/DESIGN.md 中顯示的範例完全相同。此結構化數據是其他技能解析設計系統所必需的。如果未包含此 YAML 區塊（至少包含核心顏色代碼），則未能正確使用此技能。
使用 examples/DESIGN.md 中的範例作為你的模板。檔案必須以 YAML 區塊開頭，後跟 markdown 區塊：
# 設計系統：[專案名稱]
**專案 ID：** [如果已知，否則省略]
## 1. 視覺主題與氛圍
[關於情緒、哲學和關鍵特徵的 2 段豐富描述]
## 2. 顏色調色盤與角色
### 主要基礎
### 強調與互動
### 排版與文字層級
### 功能狀態
## 3. 排版規則
### 層級與粗細
### 間距原則
## 4. 元件樣式
### 按鈕
### 卡片與 [領域特定容器]
### 導航
### 輸入框與表單
### [領域特定元件]
## 5. 佈局原則
### 網格與結構
### 留白策略
### 對齊與視覺平衡
### 響應式行為與觸控
## 6. Stitch 生成的設計系統筆記
### 要使用的語言
### 顏色參考
### 元件提示
### 增量迭代
第四階段：整合（可選）
如果使用者想要將設計系統推送到 Stitch：
- 將工作交給
manage-design-system技能，以進行 MCP 建立/更新呼叫 - 你撰寫的 DESIGN.md 是輸入——manage-design-system 技能會處理 Stitch API 整合
如果使用者只想要文件，則在第三階段後你就完成了。
品質檢查清單
在交付 DESIGN.md 之前，請驗證：
- 每種顏色都有描述性名稱、十六進位代碼和功能角色
- 排版包括字型系列、特徵描述和完整層級
- 元件樣式描述形狀、顏色、狀態和轉換
- 佈局包括最大寬度、網格、斷點和間距策略
- Stitch 生成筆記使用自然語言，而非 CSS 語法
- 氛圍部分讀起來像是編輯文案，而非技術文件
- 接近重複的顏色已合併
- 文件捕捉了樣式背後的意圖，而不僅僅是原始值
更好提取的技巧
- 閱讀註解和提交訊息。 開發者經常在程式碼註解（
/* 英雄區塊 — 通風 */）和提交訊息中記錄設計意圖。這些是理解為什麼的寶貴資源。 - 檢查設計代碼庫。 如果專案使用
style-dictionary、@tokens-studio或類似工具，這些檔案是設計值最權威的來源。 - 主題檔案比元件樣式提供更高信號。 定義調色盤的
theme.ts告訴你預期的設計系統；元件中分散的內聯樣式告訴你實際出貨的內容。兩者都很重要，但從主題開始。 - Tailwind 設定就是一個設計系統。 如果專案有自訂的
tailwind.config.js，那就是設計系統——先從中提取，然後抽查元件的覆寫。 - CSS 自訂屬性是刻意的。 如果開發者定義了
--brand-primary，他們是在告訴你這是一個設計代碼。請尊重它。