swift-web 設計語言

無論你在 Figma 還是 Claude Design 裡工作，用到的都是同一套設計語言。本頁講清楚它的三個組成部分：語意 token（顏色 / 圓角 / 陰影 / 字體的命名系統）、元件形態（框架提供哪些現成元件、長什麼樣）、以及給新網站配色的正確工作流程。

語意 token：設計決策的命名系統

swift-web 的所有視覺決策都收斂為一組語意化命名的變數（業界通稱 design token）。「語意化」的意思是：名字描述用途而不是色值——--primary 是「品牌主色」，而不是「藍色」。換品牌時改的是變數的值，所有用到它的地方自動跟隨。

設計師需要認識的核心 token（完整清單見樣式與 Token）：

三個閱讀要點：

1. *-foreground 配對。每個「底色」token 都有一個配對的「文字色」token（--primary ↔ --primary-foreground）。設計時保證每對的對比度達標，程式碼側就永遠不會出現「深底配深字」。
2. 明暗兩套值。每個顏色 token 在亮色 / 暗色主題下各有一個值，切主題就是整組換值——設計稿如果需要暗色版本，改的同樣只是 token 值。
3. 命名遵循業界慣例（Shadcn 風格）。用過主流設計系統的設計師和 AI 工具都能零成本讀懂。

元件形態：20 張卡片的清單

設計資源目前固化為 20 張預覽卡片（Claude Design 側的設計系統即由它們構成；Figma 側元件庫以同一清單為藍本建設）。每張卡片的 CSS 直接取自框架元件源碼，卡片長什麼樣，線上元件就長什麼樣：

一個重要標註：部分卡片帶有「參考實作（非框架內建）」字樣——比如按鈕的彩色 variant、表單欄位的輸入框視覺。這表示框架有意不內建這部分樣式（留給業務自訂），卡片展示的是按語意 token 的建議畫法。設計師可以照用，也可以重新設計——只要仍然落在 token 詞彙表內。

這 20 張卡片的整寬實卡預覽與逐卡說明（每張卡展示什麼、設計時怎麼用、出稿時怎麼對 AI 點名）單獨成頁：設計卡片總覽——設計前當形態字典翻一遍，比這裡的清單表直觀得多。資源包下載（Claude Design / Open Design 兩種形態）也在那一頁。

框架元件的完整能力（屬性、事件、互動細節）見元件總覽；設計師通常只需要認識形態，不必讀 API。

給新網站配色：正確的工作流程

這是設計師最常問的問題：「設計系統帶的是預設色 / 某個現有品牌的色，我要設計一個全新的網站，怎麼換成我的配色？」

答案是這套體系的最大優勢所在：換配色 = 覆蓋十幾個語意 token 的值。元件不寫死任何顏色，只引用 token——你重新定義 --primary、--background 等一組值，全部元件自動換裝，不需要逐一修改。

建議工作流程（以 Claude Design 為例，Figma 裡改 Variables 集合同理）：

1. 從底版設計系統起稿（中性預設色），先專注結構與佈局。
2. 在 token 層調色。對 AI 說「主色換成暗紅金，整體奢華暗色調」這類意圖，或直接給出具體值——關鍵約束是：調整發生在語意 token 上，而不是在稿子裡散點取色。一處 token 變更全稿連動，這既是效率，也是後面能落地的前提。
3. 迭代到滿意，產出定稿。
4. 交付「品牌 token 清單」：把最終確定的一組 token 值（--primary: #xxx、--background: #xxx……通常 15～25 個）整理成清單交給前端 / 框架維護者。
5. 維護側一鍵落地：拿這張清單生成兩樣東西——該品牌的專屬設計系統（供後續設計複用）和專案的品牌覆蓋樣式（程式碼側 rebrand）。設計資源與程式碼同源更新，一次交付、兩側生效。

直觀理解：品牌 token 清單是設計與程式碼之間的合約。清單之內的自由（值隨便定）完全屬於設計師；清單之外的散點色不進合約，落地時會遺失或被歸一。語意 token 覆蓋不了的品牌特有色（如 VIP 金色系、角標色），在清單裡以補充項列出即可，程式碼側有對應的擴充機制（--brand-* 命名空間）。

品牌變體機制

設計系統按品牌分層：底版（框架預設中性色，新專案 / 探索用）+ 品牌變體（每個業務品牌一套，底版卡片注入該品牌 token 後生成）。設計某個現有品牌的新頁面時選它的品牌變體，顏色和元件形態與線上完全一致；設計全新網站時從底版開始，走上面的配色工作流程。

品牌變體由維護側的自動化管線生成（不是手動維護的副本），需要新增品牌變體時聯絡框架維護者，提供品牌 token 清單即可。

相關連結

• 樣式與 Token — token 在程式碼側的完整清單與消費方式
• 元件總覽 — 全部框架元件的能力文件
• 主題系統 — 明暗主題與 token 的關係
• 規範與治理 — token 層調色紀律與品牌接入流程