設計系統建構器
設計系統是一組一次性做出的決定，讓每個畫面都不需要重新決定。Token 承載這些決定，元件應用它們，文件解釋它們。根據專案規模調整工作量：一個週末的 App 需要一個 40 行的 Token 檔案和一份 DESIGN.md；一個多團隊的產品需要管線與治理。從小處著手，透過提取來成長。
流程
0. 讀取現有內容
尋找：tokens/theme 檔案、tailwind 設定或 @theme 區塊、components.json、CSS 變數、theme/ 模組、Figma 連結（如果已連線，可使用 Figma MCP 的 get_variable_defs / search_design_system）、DESIGN.md / .interface-design/system.md。在現有程式碼庫中，先提取再發明：grep 實際使用的顏色、字型大小、間距與圓角，將其分組，然後提出整合後的規模。向使用者展示調整前後的對應關係。
1. 定義方向（一個段落）
誰會使用它、它應該給人什麼感覺（用具體的詞語描述：「像交易終端一樣密集」、「像閱讀 App 一樣寧靜」）、平台、品牌限制、密度、淺色/深色模式。這會決定以下所有規模的選擇。如果有 interface-design 或 frontend-design 技能參與，它們負責這個美學步驟；此技能則將方向轉化為系統。
2. 基礎（Token）
按照以下順序建構——每個階段都依賴前一個階段：
- 色彩 → 執行
color-theory技能的工具：python3 <skills-dir>/color-theory/scripts/palette.py system <brand-hex> --format tailwind|css|json（color-theory是此技能目錄的同級目錄）。它會產生原始色階以及經過驗證的淺色/深色語意角色。 - 字型 → 字型系列（≤2 種，加上等寬字型）、具有命名角色的字型比例、行高、字重、字距。請參閱
references/scales.md。 - 間距 → 4px 基礎網格；T-Shirt 或數字比例；版面間距與元件內距分開。
- 形狀 → 圓角比例（以及巢狀規則：內部圓角 = 外部圓角 − 內距）、邊框寬度。
- 高度 → 陰影比例（淺色模式）和表面亮度階梯（深色模式）、Z-index 層級。
- 動態 → 持續時間 + 緩動函數作為 Token（以及減少動效行為）。
- 版型 → 斷點、容器寬度、網格欄數、安全區域（行動裝置）。
- 尺寸 → 控制高度（sm/md/lg）、圖示尺寸、最小觸控目標。
3. Token 架構
三個層級——元件必須僅使用語意（或元件）層級：
原始層 --blue-600, --space-4, --radius-2 原始值，以它們「是什麼」命名
語意層 --color-accent, --space-inset-md, --radius-control 以「職責」命名，別名原始層，每個主題切換
元件層 --button-bg, --card-padding 選用；僅用於有真正主題需求的元件
主題切換（深色模式、品牌、密度、高對比） = 重新對應語意 Token。元件永不改變。完整的命名規則、DTCG 格式、模式：references/token-architecture.md。
4. 交付至平台
- 單一 Web App：手寫 CSS 變數 + Tailwind v4
@theme就夠了。 - Web + 行動裝置，或多個 App：以 DTCG JSON 撰寫 Token（單一來源），使用 Style Dictionary v5 或 Terrazzo 建置為 CSS、Tailwind、TypeScript、Swift、Kotlin/Compose、Flutter、React Native。
每個平台的範例與輸出食譜：references/platform-outputs.md。DTCG 入門檔案：assets/tokens.example.json。
5. 元件
建立在易於使用的基礎元件之上（請參閱 ui-stack-advisor）。一致的 API：variant（視覺意圖）、size、tone/color（僅在需要時）、透過 data 屬性的狀態、組合優於設定。每個元件記錄所有狀態：預設、懸停、啟用、焦點可見、停用、載入、錯誤、空白、選取、唯讀。慣例與檢查清單：references/components.md。
6. 文件與治理
從 assets/DESIGN.template.md 在專案根目錄撰寫 DESIGN.md——方向、Token 表格、元件清單、注意事項，以及做出決定的原因。這個檔案是未來的工作階段用來保持一致的參考；請保持簡潔且最新。較大的系統會加入 Storybook（或 Ladle/Histoire）、視覺回歸測試、包含語意化版本的變更日誌，以及貢獻流程（references/components.md#governance）。
可用的預設值（當使用者沒有偏好時）
| 基礎項目 | 預設值 |
|---|---|
| 基本單位 | 4px；間距規模 0, 1, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96 px |
| 字型比例 | 12, 14, 16（內文）, 18, 20, 24, 30, 36, 48, 60 px（≈1.2–1.25 比例）；產品 UI 可使用 14px 內文 |
| 行高 | 內文 1.5，標題 1.2–1.3，展示文字 1.1；較大尺寸時收緊字距（−0.01 至 −0.03em） |
| 圓角 | 0, 4, 6, 8, 12, 16, 24, full — 選擇一種個性：銳利（2–4）、柔和（8–12）、圓潤（16+）並一致地應用 |
| 控制項 | 高度 32 / 36–40 / 44–48 px；觸控目標 ≥ 44pt（iOS）/ 48dp（Android）/ 24px 最小 WCAG 2.2（目標 44） |
| 動態 | 100 / 150 / 200 / 300 / 500 ms；進入用 ease-out cubic-bezier(0.23,1,0.32,1)，移動用 ease-in-out，行動裝置用彈簧 |
| 斷點 | 640, 768, 1024, 1280, 1536（Tailwind）；元件優先使用容器查詢 |
| 高度 | 4–5 個陰影層級；深色模式使用較亮的表面 + 微妙的邊框代替 |
| Z-index | base 0, dropdown 1000, sticky 1100, overlay 1300, modal 1400, popover 1500, toast 1600, tooltip 1700 |
預設值是一個基礎，而不是一種風格。獨特性來自於那些有所變化的選擇：字體、強調色調、中性色溫、圓角個性、密度和動態特徵。
品質檢查清單（在宣佈完成前檢查）
- 元件中沒有原始值（十六進位顏色、px 字型大小、任意間距）——透過 grep 搜尋
- 語意名稱描述的是職責，而非數值或色調
- 淺色 + 深色模式都已設計並通過對比驗證（WCAG 2.2 AA）
- 每個互動式元件都有可見的焦點、停用、載入、錯誤狀態
- 字型比例具有命名角色（display, h1–h3, body, label, caption, code），而不只是尺寸
- 間距一致：相同的關係 → 使用相同的 Token
- 動態 Token 有減少動效的變體
-
DESIGN.md已撰寫且準確 - 行動裝置：尊重 Dynamic Type / 字型縮放、將安全區域設為 Token、觸控目標 ≥ 44/48
參考資料
references/token-architecture.md— 層級、命名語法、DTCG 2025.10 格式、模式/主題、別名規則references/scales.md— 字型（比例、流體字型、配對）、間距、圓角、高度、動態、密度、斷點references/platform-outputs.md— CSS、Tailwind v4、shadcn 主題、React Native（NativeWind/Unistyles/Tamagui）、Flutter、SwiftUI、Compose、Style Dictionary/Terrazzo 管線references/components.md— 元件 API 慣例、結構、狀態矩陣、組合、文件、測試、治理assets/tokens.example.json— DTCG Token 入門檔案assets/DESIGN.template.md— DESIGN.md 範本