從前端程式碼提取設計系統
分析前端原始碼，提取一份全面的設計系統文件 (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-* vs --cool-*） | 色溫意圖 |
| 主題檔案中的註解 | 開發者自己文字中的設計意圖 |
2. 色彩調色盤與角色
從程式碼庫中提取每個獨特的顏色，並分配功能角色。搜尋所有層級：
在哪裡找到顏色：
| 層級 | 搜尋什麼 |
|---|---|
| CSS 自訂屬性 | --color-*、--primary、--bg-* |
| Tailwind 配置 | theme.extend.colors |
| 主題/代碼檔案 | 顏色物件、調色盤 |
| 組件樣式 | background-color、color、border-color |
| 內聯/作用域樣式 | 模板中的 bg-*、text-* 類別 |
| CSS-in-JS 主題物件 | colors、palette 鍵 |
如何組織： 按功能（而非色調）對顏色進行分組：
- 主要基礎 —— 背景和表面顏色
- 強調與互動 —— CTA 按鈕、活躍狀態、連結
- 排版與文字層級 —— 主要、次要、第三級文字
- 功能狀態 —— 成功、錯誤、警告、資訊
對於每種顏色，建立一個描述性名稱，喚起顏色的特質，而非原始十六進位值：
- ❌
#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（寬敞以提高可讀性？緊湊以用於顯示？）
- 映射組件使用情況：產品卡片使用哪個標題層級？英雄區段呢？
間距原則：
- 文字間距如何與整體間距比例相關？
- 標題 vs 正文的字母間距模式
- 行高哲學（正文寬敞/放鬆，顯示緊湊）
4. 組件樣式
分析 4-5 個最重要的 UI 基本元素：
按鈕：
- 邊角半徑（以及它傳達了什麼 —— 俏皮？專業？極簡？）
- 主要、次要和幽靈變體的配色方案
- 懸停/焦點/活躍狀態和轉場時機
- 內邊距比例（水平 vs 垂直）
卡片 / 容器：
- 邊角半徑（通常與按鈕不同 —— 略圓）
- 陰影策略：平坦、微妙的懸停陰影、或總是升高？
- 邊框處理：髮絲線邊框、彩色強調邊框或無？
- 內部內邊距（寬敞或緊湊？）
- 卡片內的圖片處理（滿版出血、內邊距、圓角？）
導航：
- 佈局模式（水平欄、垂直側邊欄、抽屜）
- 排版處理（大寫、字母間距、粗細）
- 活躍/懸停狀態指示器（底線、顏色、背景）
- 行動裝置行為（漢堡選單、底部導航、抽屜）
輸入框與表單：
- 邊框樣式和焦點狀態行為
- 與按鈕一致的邊角樣式
- 內邊距和觸控目標大小
領域特定組件：
- 標示出該專案獨有的 1-2 個組件（例如產品卡片、儀表板小工具、聊天氣泡）並描述其樣式模式。
5. 佈局原則
提取結構系統：
網格與結構：
- 最大內容寬度（來自容器上的
max-width） - 欄位系統（CSS Grid、Flexbox 模式、定義的中斷點）
- 響應式中斷點（來自 media query 或 Tailwind 配置）
留白策略：
- 基本間距單位（8px 網格？4px？自訂？）
- 區段邊距（主要區段之間的間距）
- 邊緣內邊距（不同中斷點下的頁面邊距）
對齊與視覺平衡：
- 文字對齊模式（置中英雄、左對齊正文）
- 圖片與文字的比例
- 視覺重量分佈
響應式行為：
- 行動優先還是桌面優先？
- 網格如何折疊？內邊距比例？
- 觸控目標大小
6. Stitch 生成備註
將萃取結果綜合為可操作的 Stitch 提示：
- 氛圍語言：將氛圍轉譯為自然描述符
- 顏色參考：按描述性名稱 + 十六進位值列出顏色
- 組件提示：撰寫 2-3 個範例提示，可在 Stitch 中重建關鍵組件
- 迭代指引：在此設計系統中優化畫面的技巧
第三階段：撰寫 DESIGN.md
將所有內容組裝成標準的 DESIGN.md 格式。將其放置在專案目錄的 .stitch/DESIGN.md 中（如果 .stitch/ 目錄不存在，請建立它）。
[!IMPORTANT] 你必須在檔案頂部包含 YAML 前置元資料，並包含
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 語法
- 氛圍章節讀起來像編輯文案，而非技術文件
- 近乎重複的顏色已合併
- 文件捕捉了樣式背後的意圖，而不僅僅是原始值
更好的提取技巧
- 閱讀註解和提交訊息。 開發者經常在程式碼註解（
/* hero section — breathable */）和提交訊息中記錄設計意圖。這些對於理解原因非常有價值。 - 檢查設計代碼函式庫。 如果專案使用
style-dictionary、@tokens-studio或類似套件，這些檔案是設計值最權威的來源。 - 主題檔案的信號強度高於組件樣式。 定義調色盤的
theme.ts告訴你預期的設計系統；散落在組件中的內聯樣式則告訴你實際交付的內容。兩者都很重要，但從主題開始。 - Tailwind 配置就是一個設計系統。 如果一個專案有自訂的
tailwind.config.js，那就是設計系統 —— 先從中提取，然後抽查組件是否有覆蓋。 - CSS 自訂屬性是刻意的。 如果開發者定義了
--brand-primary，他們是在告訴你這是一個設計代碼。請尊重它。