interface-design
儀表板、後台、工具這類介面的設計基礎。這份是 init、extract、audit、status 四個指令共用的原則與檢查,也是 quality-gate-push.sh 對 UI 改動做設計稽核時的對照依據。
對象是資料密集、長期使用、操作導向的產品介面,不是行銷頁或 landing page。那兩類重氣氛與轉換,這裡重的是可讀、可掃描、可長時間操作不累。
設計系統檔:.interface-design/system.md
每個前端專案把設計決策寫進 .interface-design/system.md,當作這個專案的單一真相來源。extract 從既有程式碼抽出目前的樣子寫成這份檔,init 從頭建立,audit 拿程式碼對照這份檔找違規,status 回報目前狀態。
system.md 至少要涵蓋:
- 色彩角色:不是列一堆色票,而是講每個角色(背景、表面、前景、次要前景、邊框、primary、destructive、success、warning)對應哪個 token、Light 與 Dark 各是什麼值。
- 字型與字級:字型家族,加上一張字級表(名稱、大小、字重、行高、用途)。
- 間距尺階:基數(通常 4px)與允許的間距階梯。只用階梯上的值。
- 圓角尺階:radius 的幾個級距,哪種元件用哪級。
- 深度策略:陰影或邊框的層級怎麼表達高低,一個介面只用一套。
- 元件模式:卡片、表格、表單、badge、按鈕各自的結構與狀態規則。
這份檔與 cis-design-system 產生的 wireframes/cis-design-tokens.html(C1 到 C7 區塊)是同一套 token 的兩個視角:system.md 給設計與稽核讀,cis-design-tokens.html 給人看。兩者的 token 值要一致。
設計原則
間距用節奏,不用隨手填
間距從固定尺階來(4 的倍數),同一層級的元素用同一個值。版面的呼吸感來自一致的節奏,不是每處微調。看到 13px、7px 這種落在尺階外的值就是警訊。
深度策略一套到底
表達「這塊浮在上面」只用一種手法:全站用陰影,或全站用邊框,不混用。陰影就定義好幾個固定級距(卡片、浮層、對話框各一級),不要每個元件自己調一組 rgba。
色彩講角色,不講顏色
程式碼裡不出現 hardcode 的 hex 或 rgb,一律走語意 token。改配色時改 token 一處,不是全站搜字串。badge 這類用「半透明底加實色字」的規則統一處理,不每個顏色各寫一套。
層級靠對比,不靠裝飾
重要的東西用大小、字重、留白拉出來,不靠加框加色加陰影堆疊。一個畫面裡最多一個主要行動(primary),其餘降級。
狀態要蓋滿
每個互動元件都要想過這些狀態,缺一個就是半成品:預設、hover、focus(鍵盤可見)、active、disabled。每個資料區塊都要想過:載入中、空資料、錯誤、正常。空狀態不是空白,要講為什麼空、下一步做什麼。
密度配場景
資料密集的後台可以緊,但要靠對齊與分組維持可掃描;對外或低頻的頁面可以鬆。密度是刻意選的,不是放著不管的結果。
audit 檢查項
audit 拿程式碼對照 system.md,找這些違規,照嚴重度排序:
- hardcode 的色值(hex / rgb / hsl 字面值),該走 token。
- 落在間距尺階外的 margin / padding / gap。
- 圓角、陰影不在定義的級距內,或深度手法混用。
- 互動元件缺狀態:沒有 focus 樣式(鍵盤無法定位)、沒有 disabled、沒有 hover 回饋。
- 資料區塊缺載入、空、錯誤狀態。
- 同一種元件在不同頁面長得不一樣(卡片內距、按鈕高度不一致)。
- 一個畫面出現多個 primary 行動,層級不清。
- 字級不在字級表內,或用 inline style 硬寫大小。
找到就回報位置、違反哪一條、對應 system.md 哪個 token 或規則,不要只說「不一致」。
與其他機制的關係
- cis-design-system 負責把 token 寫成
wireframes/cis-design-tokens.html(C1 到 C7),是給人讀的設計規範。interface-design 負責設計方法與程式碼稽核,讀.interface-design/system.md。兩邊 token 一致。 - quality-gate-push.sh 在 UI 改動時要求跑 audit,並檢查
.interface-design/system.md是否存在。新專案或既有專案首次改 UI 時用 extract 或 init 補上。 - 新頁上線前的使用者導覽元素(PageHero、NextStepGuide、InfoTooltip、麵包屑、BackToTop)見 design-system.md,屬內容層導覽,與本 skill 的視覺層檢查互補。
輸出
設計或改 UI 時,先確認 system.md 存在且讀過,照上面原則實作。被要求 audit 時,回傳照嚴重度排序的違規清單,每項附位置與對應規則。不改設計決策本身,那是 system.md 的事。