設計卡片總覽

這一頁是 swift-web 設計資源的實卡字典：20 張卡片逐張整寬展示，配「它是什麼、設計時怎麼用」的說明。卡片 HTML 與 Claude Design / Open Design 裡的設計系統是同一流水線產物（全部從框架源碼派生）——你在這裡看到什麼，在工具裡選用 swift-web 設計系統後 AI 參照的就是什麼，線上元件渲染出來也是什麼。

怎麼用這一頁

  • 設計前翻一遍（形態字典）：知道框架現成提供哪些元件形態，設計時優先組合現成形態——落地映射一對一，不需要前端「翻譯」。
  • 出稿時對 AI 點名卡片：卡片名就是共同語言。在 Claude Design / Open Design 裡直接說「按 SwRail 的形態做一排電影封面」「彈窗用 SwModal 的結構」，AI 讀的設計系統裡就有這些卡，會精確對上。
  • 走查時對照：設計稿或線上頁面與卡片形態對不上時，以卡片為準報給維護者核對（卡片是源碼派生的，不會撒謊）。

兩個標註約定：

  • 「參考實現（非框架內建）」：出現這行字的部分（如按鈕的彩色 variant、表單輸入框的視覺），表示框架有意不內建該樣式、留給業務自訂——卡片展示的是按語意 token 的推薦畫法。你可以照用，也可以重新設計，只要仍落在 token 詞彙表內。
  • 想改卡片本身（覺得某元件預設形態不合理）：卡片是派生物、不手動改，訴求提給框架維護者走規範與治理·紀律二。

Tokens（3 張）

Colors · 語意色 Token

全部語意色變數的名稱與實際值（明暗兩套）。設計稿裡的任何顏色都應能指回這張卡上的某個名字——換品牌時改的就是這些值，所以「按名字用色」的稿子天然可交付。三級文字灰度（--foreground / --foreground-soft / --muted-foreground）的對比也在這裡看。

Typography · 排版 Token

字體堆疊（中文優先的系統字體，無 webfont）、字階層次、連結與焦點樣式。內文行高約 1.5、標題 600 字重——排版的「為什麼長這樣」都在這張卡。

Shape & Layout · 圓角 / 陰影 / 佈局

統一圓角 0.5rem、三檔陰影（sm/md/lg）、導航高度 60px、內容最大寬 1920px。卡片、按鈕、彈窗的圓角為什麼一致——出處就是這裡。

基礎元件（9 張）

SwButton · 按鈕

主/次/幽靈三形態 + loading / disabled 態。hover 統一「變暗一檔」（全站家規，不另發明 hover 色）。彩色 variant 是參考實現——業務可重新設計，落在 token 內即可。

SwSegmented · 平鋪選項組

選項少且需要全部可見時的單選（如「最新 / 最熱 / 好評」切換）。與下拉的 SwSelect 互補：選項多、省橫向空間才用下拉。

SwSelect · 下拉選擇

單選 / 多選 / 分組 / 可清空的下拉。設計篩選區時先判斷：選項 ≤5 且重要 → SwSegmented 平鋪；更多 → 這張卡。

SwModal · 彈窗

置中面板 + 遮罩，標題 / 內文 / 動作區三段結構。焦點管理、Esc 關閉等無障礙行為框架內建——設計只需關心面板內容排布。

SwToast · 輕提示

堆疊的短時回饋，按語意色分狀態（成功綠 / 錯誤紅 / 警告金）。需要使用者決策的內容別設計成 toast（用彈窗），它會自動消失。

SwPagination · 分頁

頁碼翻頁，當前頁主色高亮。適用「替換式」列表（翻頁換整屏內容）；「載入更多」式的串流列表看 SwGallery。

SwBreadcrumb · 麵包屑

層級導航（首頁 / 分類 / 詳情）。中間節點是真實連結，利於 SEO——詳情頁設計帶上它對搜尋收錄有實際收益。

SwFormField · 表單欄位

label / 輸入區 / 錯誤提示的欄位結構，錯誤態紅色系。輸入框本身的視覺是參考實現——表單風格業務可自訂，欄位結構建議保持。

SwTable · 資料表格

管理台資料表：表頭弱化底 + 行分隔線的基線視覺，內建欄排序箭頭、行選 checkbox、斑馬紋 / 緊湊密度 / 黏性表頭。管理台列表頁先翻這張卡；分頁、篩選不在表格內——用 SwPagination / SwSegmented 在頁面層組合。

內容元件（8 張）

SwImage · 圖片

所有內容圖（封面 / banner / 頭像）的載體：按比例佔位（圖未到時佈局不跳動）、載入失敗有兜底態。設計封面卡時定好寬高比即可（影視直版常用 2:3）。

SwRail · 橫滾卡片排

一行放不下就橫向滑的卡片排（首頁推薦樓層主力）。卡片尺寸由設計定；桌面 hover 出箭頭、行動端手指滑。與輪播的區別：Rail 是多張並排滑動，Carousel 是整屏一張切換。

SwCarousel · 輪播

整屏輪播 banner：自動播放、無縫循環、圓點/縮圖指示器。首頁頭部大圖位就是它。

SwGallery · 網格畫廊

等高網格 + 「載入更多」（片庫 / 分類全列表頁主力）。列數隨屏寬自適應，設計時給一張卡的形態即可。

SwAd 廣告位族

12 種廣告位形態：橫幅 / 矩形位 / 宮格 / 文字鏈 / 跑馬燈 / 訊息流原生卡 / 側懸浮 / 開屏 / 彈窗 / 影片貼片 / 暫停廣告 + 合規角標。做廣告位先翻這張卡選形態——每種位的曝光統計口徑不同，形態選對數據才對。

SwVideoPlayer · 播放器

影片播放器：控制條 / 彈幕 / 前貼片與暫停廣告位插槽。播放頁設計圍繞它佈局，播放器內部形態不需要重畫。

SwUpload 上傳族

圖片 / 影片 / 通用檔案三種上傳的按鈕與拖曳區形態，含上傳中 / 進度態。UGC 投稿頁會用到。

SwEditor · 富文本編輯器

Tiptap 底座的編輯器：工具列 / @提及 / #話題 / emoji / 圖片影片插入。留言區、發文頁的輸入區形態。

下載與匯入

相關連結