ui-craft 是做什麼的?
如何建構在任何平台上都看起來高級且易於使用的介面。 數字單位為 CSS px;對於原生應用程式,請將 px 讀作 pt(iOS、macOS)、dp(Android)或 epx(Windows)。
高級意味著四件事。 合適:符合受眾、他們的心境和平台。果決:到處應用一個小系統(少數尺寸、一個圓角族系、一個強調色)。精心雕琢:細節完善。誠實:贏得信任,絕不欺騙。一個只正確的畫面看起來很普通;一個只裝飾的畫面看起來很廉價。
1. 工作流程(每次都這樣做)
- 在建造之前先觀察。 檢查是否有現有的設計系統:Token、主題檔案、Tailwind 設定、元件庫、品牌顏色、字型,或是一個從 ui-craft Studio 導出的
DESIGN.md簡報和theme.css。如果存在,就使用它;不要發明第二個。 只填補缺口。 - 了解使用者。 誰在使用這個?處於什麼心境(匆忙、焦慮、懷疑、沉浸工作中的專家)?他們應該感受到什麼?一句話。參閱
references/psychology-emotion.md。 - 選擇一個方向。 如果沒有既定的品牌識別,從
references/directions.md中選擇一個視覺方向以適合受眾(不是為了新奇),閱讀assets/directions/中對應檔案的第一行,並記下其特徵。如果有品牌顏色,保留該方向並重建顏色:node <skill-dir>/scripts/palette.mjs --accent "#HEX"。偏好用肉眼選擇的人可以使用 ui-craft Studio (https://najeebafridi.github.io/ui-craft/):選擇一個方向,在即時畫面上調整,導出theme.css和一個供你遵循的DESIGN.md簡報。 - 在程式碼之前撰寫設計簡報(在你的回覆或註解中):
產品:小型企業薪資系統(網頁應用程式,以桌面為主) 使用者和感受:老闆在夜間處理薪資,對錯誤感到焦慮 -> 安全、有引導、精確 方向:可信賴的分類帳;強調色深藍綠色(他們的品牌),冷色調中性色,淺色主題 字體:IBM Plex Sans + Mono,14px 內文,表格數字 形狀與深度:6px 圓角,柔和陰影 密度與動畫:緊湊,清晰(120-200ms) 平台:響應式網頁 特徵:數字像分類帳一樣排列;確認訊息指出確切金額和時間 此畫面的主要任務:檢閱本月記錄並批准 - 先建構結構,再設計樣式。 先用真實內容建立佈局和層級,然後是系統(Token),最後是細節。不要使用 Lorem Ipsum:撰寫真實的名稱、數字和文案。早期就建立特徵,並讓其他一切都比它更安靜。 展示它正在運作。 第一個畫面是使用中的螢幕:真實資料、已經選好的合理預設值、可見的主要互動。永遠不要從一個完全空白或鎖定的狀態、一個無效的 "$0" 總計、或一個在前一個步驟完成之前就隱藏的關鍵步驟開始。
- 設計每一種狀態:載入中、空白、錯誤、成功、長文字、大量項目、單一項目、無權限(
references/feedback-states.md)。 - 完成並檢查。 執行
references/premium-craft.md中的最終潤飾。然後查看結果:如果 Node 和 Chrome 可用,執行node <skill-dir>/scripts/ui-audit.mjs page.html。它會在 1440px 和 390px 下評分對比度、尺寸、觸控目標和溢出內容,記錄工藝問題,並儲存截圖。打開兩張截圖,並像嚴格對待桌面版一樣嚴格評判手機版:沒有裁剪、遮擋或擠壓,關鍵內容在第一屏可見。檢查畫面是否講述一個故事:摘要符合選取項目,總計加總無誤,計數與清單相符,日期一致。修正你所看到的,然後移除任何對主要任務沒有幫助的東西。核對清單:references/review-checklist.md。
給客戶的快速原型:references/mockups.md。審查或評分現有產品:references/review-mode.md。
同一主題上的圖層。 對於 3D 場景、著色器、滾動敘事或電影級動畫,請使用 immersive-web 技能(同一個外掛):它讀取相同的這些 Token,而主題的 --immersive 等級(0 靜止到 3 敘事)指示了要進行到什麼程度。要借用另一種類型或媒介(遊戲、科幻、電影)的外觀,請閱讀 references/mixing.md。
2. 依產品類型的密度
| 產品 | 內文文字 | 密度 | 導覽 |
|---|---|---|---|
| 資料工具、管理後台、開發工具、金融 | 14px | 緊湊:行高 36px,控制項 32-36px | 左側欄 220-280px |
| SaaS 網頁應用程式 | 14-16px | 標準:控制項 36-40px | 側欄或頂部欄 |
| 儀表板、分析工具 | 14px | 緊湊 | 側欄 + 篩選列 |
| 行銷網站、著陸頁 | 16-18px | 寬敞:區塊間距 64-96px | 頂部欄,4-6 個連結 + 1 個行動呼籲按鈕 |
| 行動應用程式 | 16-17px | 觸控:目標至少 44px | 底部頁籤列,3-5 個項目 |
| 桌面應用程式 | 13-14px(平台預設) | 緊湊 | 側欄 + 工具列;遵循作業系統 |
| 消費性、趣味性 | 16px | 標準 | 依平台而定 |
內文文字預設為 16px;僅在密集的桌面工具中使用 14px。絕不可低於 12px。緊湊密度僅適用於滑鼠和鍵盤:在觸控螢幕上,每個控制項都應增大到 44px(§13)。
3. 層級(最大的效益)
- 每個畫面一個主角和一個主要操作。 主要操作是唯一的實心強調色按鈕;其他按鈕為外框、輕柔或純文字按鈕。
- 透過大小、粗細和顏色三者結合來建立層級。為了讓標題更突出,與其放大標題,不如讓標籤和中繼文字更安靜。
- 標籤比數值更安靜。在「營收 $48,210」中,標籤使用 12-14px 的柔和色,而數值使用 24px 的半粗體。
- 分組應優先使用間距,其次是背景色調,然後是線條,最後才是陰影。組與組之間的間距至少是組內間距的兩倍。越少的框線和線條看起來越昂貴。
- 閱讀順序與重要性相符:主要任務位於左上角(在从左到右的語言中)或中央。
4. 佈局與間距
- 間距尺度(4px 為基準):4, 8, 12, 16, 24, 32, 48, 64, 96。 僅限這些。
- 元件內部 4-12;元件之間 16-24;區塊之間 32-48(應用程式),64-96(行銷)。
- 頁面側邊內距:行動版 16px,平板 24px,桌面版 32px 或更多。內容最大寬度 1200-1440px(應用程式),1120-1280px(行銷);閱讀文字 65-75 個字元。
- 使用 grid 或 flex 搭配
gap進行佈局。在兩個軸向上對齊:相鄰元素共享左邊緣和基準線。接近但未對齊看起來很業餘。 - 外部內距至少等於內部間距。不確定時,增加空白並移除邊框。
- 沒有死空間。 不要拉伸卡片以匹配較高的相鄰元素(
align-items: start),也不要讓面板大部分為空:給它真實內容、縮小它、或移除它。 - 密度是一個決定:寬敞或緊湊,始終精確。斷點 640、1024、1440;至少檢查 375 和 1440。
詳細資訊:references/layout-spacing.md。
5. 字體排版
- 字體尺度:12, 14, 16, 18, 20, 24, 30, 36, 48, 60(更大僅用於展示)。應用程式畫面使用 4-6 種尺寸,行銷頁面最多 7 種。
- 字體來自方向或品牌:應用程式使用一種字體家族,最多兩種(一個展示字體用於標題,一個中性文字字體用於內文)。永遠不要因為它是預設字體而使用它。所有建議的字體都是免費的(SIL OFL)。
- 根據字體大小調整字體。 內文行高 1.5,標題 1.2-1.3,展示文字 1.05-1.15。字距:14-16px 為 0,20-24px 約 -0.015em,30-36px 為 -0.025em,48px 及以上為 -0.03 到 -0.04em;小型全大寫標籤為 +0.06em。
- 字重:內文 400,標籤和按鈕 500,標題 600;700+ 僅用於大型展示文字。每個畫面最多 3 種。字重從不在懸停時改變。
- 標題使用
text-wrap: balance,段落使用pretty。每個會改變或需要對齊的數字使用font-variant-numeric: tabular-nums;表格中的數字右對齊。 - 標題、按鈕和標籤使用句子大小寫。使用真正的引號、破折號和省略號。
詳細資訊:references/typography.md。
6. 顏色
- 先選擇感覺。 明度和飽和度比色相更能改變畫面的感覺:更亮更令人愉悅,更飽和更令人興奮,低飽和度搭配強烈對比則冷靜而嚴肅。然後選擇色相以符合意義、類別契合度和與競爭對手的差異性。
references/color-theory.md。 - 一個調色盤由帶色調的中性色 + 一個強調色 + 狀態色(成功、警告、危險、資訊)組成。中性色應帶有一絲顏色(暖色、冷色或品牌色相),絕不使用死灰色;大面積區域不使用純黑或純白。
- 大部分為中性色。 強調色約佔 5-10%:主要按鈕、連結、選取狀態、焦點、關鍵資料。高飽和度僅用於小而有價值的區域。
- 使用
scripts/palette.mjs(OKLCH 色域,淺色 + 深色,所有文字和邊框顏色已解決以通過對比)來建構,或從某個方向取得。切勿憑肉眼發明十六進位顏色值。 - 元件中僅使用語意化 Token:
--bg、--surface、--surface-2、--border、--border-strong、--text、--text-muted、--text-subtle、--accent、--accent-fg、--accent-soft、--accent-text、--focus、--danger……每個表面都有其前景色夥伴。 - 對比度下限(WCAG 2.2 AA):文字 4.5:1,大型文字(24px+,或 18.66px+ 粗體)和 UI 元件(輸入框邊框、圖示、焦點環、圖表標記)為 3:1。分隔線可以很淡;輸入框邊框使用
--border-strong。 - 絕不單獨使用顏色來表達意義:應加上圖示、文字或形狀。狀態色應與品牌色分開;紅色品牌色絕不能同時作為錯誤顏色。
- 深色模式有其自己的調色盤:近乎黑色的色調表面,凸起的表面較亮,米白色文字,較柔和的強調色。提供兩種主題並遵循作業系統設定。
詳細資訊:references/color-theory.md、references/color-dark-mode.md。Token:assets/tokens.css、assets/directions/。
7. 光線、深度與形狀
- 一個光源,從上方來,隨處可見。僅三個層級: 平面、凸起(
--shadow-raised)、覆蓋(--shadow-overlay)。 - 陰影是分層且帶有色調的:多個薄層,從不使用一個灰色模糊。越高越大、越柔和、越淡。
- 卡片和選單使用陰影中的1px 線環取代邊框;實心按鈕獲得一個微弱的頂部內發光(
--shadow-button)。 - 一個圓角族系。 圓角隨著高度增加而增大(控制項、卡片、面板)。嵌套角落是同心圓:內部圓角半徑 = 外部圓角半徑減去之間的內距。
- 在深色主題中,深度來自較亮的表面和線環,而非陰影。
- 每個產品使用一種深度技術(極細線、柔和、清晰、擴散、平面或唇形,由方向設定)。沒有光暈,沒有在每張卡片上使用陰影。
- 模糊和半透明僅屬於 chrome(如固定標題、面板、系統材質),絕不屬於內容卡片。
詳細資訊:references/premium-craft.md。
8. 元件
- 每個互動元素都有狀態: 預設、懸停、focus-visible、按下、禁用;按鈕有載入中;行和切換開關有選取狀態。懸停絕不是唯一的提示。
- 按鈕和輸入框:預設 40px,緊湊 32-36px,觸控 44-48px。水平內距約為垂直內距的兩倍。標籤 = 動詞 + 受詞("建立發票")。僅圖示按鈕需要
aria-label和工具提示。 - 鍵盤使用者始終可見焦點環:2px
--focus,偏移 2px。絕不能有outline: none而沒有替代方案。 - 輸入框:上方有可見標籤(佔位符不是標籤),
--border-strong邊緣,下方有輔助文字,錯誤訊息在下方並附帶圖示和文字。長表單在頂部添加錯誤摘要。 - 表單的主要操作(儲存、繼續)從一開始就可見。在發生變化之前,它可能看起來較安靜;但它絕不會在編輯後才出現。
- 切換開關立即生效;核取方塊則在儲存時應用。
- 卡片僅用於獨立、可比較的事物。不要圍繞每個區塊使用卡片;絕對不要在卡片內使用卡片。
- 圖示:一套圖示,一種筆畫粗細,尺寸與旁邊的文字相同。絕不使用表情符號作為圖示。
- 圖片:真實內容,固定的
aspect-ratio,有意義的alt,一個 1px 的內部輪廓。沒有預留服務。如果還沒有真實照片,請在最終裁剪中使用一個安靜的色調區塊,並附上一個小標題("照片:花園房");絕不要使用一個粗糙的主題繪圖,這會讓周圍的一切看起來廉價。 - 模態框僅用於簡短的集中任務;偏好內聯編輯或側面板。
- 破壞性操作:使用危險色,命名("刪除專案"),需要確認或可復原。對於頻繁執行的操作,「復原」優於「確認」。
references/forms.md、references/tables-lists.md、references/navigation.md、references/dashboards-charts.md。
9. 反饋狀態
- 在 100ms 內確認每次按壓。僅在約 300ms 後顯示旋轉圖示或骨架螢幕,然後保持約 500ms。
- 骨架螢幕用於加載已知佈局的頁面或區塊;按鈕和小型小部件內使用旋轉圖示;超過約 10s 時使用百分比進度條。
- 空白狀態 = 這是什麼 + 為什麼是空的 + 一個操作。錯誤 = 發生了什麼 + 如何修復,用白話文說明,在發生處顯示;永遠不要清除使用者的輸入。
- 成功是安靜且具體的("發票 1042 已於 14:02 發送給 Anna")。Toast 通知持續 4-6 秒,絕不能是重要資訊的唯一副本。
- 在安全的情況下樂觀地更新,失敗時提供復原。速度被視為品質。
詳細資訊:references/feedback-states.md。
10. 情感與信任
- 人們大約在 50ms 內判斷一個畫面的外觀,而這個外觀是他們對可信度的第一個考驗。簡單、結構熟悉、細節獨特會獲勝。
- 將設計與使用者的狀態相匹配:焦慮(說出下一步會發生什麼,提交前有摘要,容易返回)、匆忙(最少步驟,預先填寫,快捷方式)、懷疑(在聲明旁附上證據,早期顯示完整價格)、專家(密度,快捷鍵,用復原取代確認)、尷尬或悲傷(中性語氣,不慶祝)。
- 強烈地完成:最後一步和確認是人們記住的東西。
- 愉悅存在於低風險的時刻(首次執行、空白狀態、成功),絕不在錯誤或敏感任務期間出現。事件發生得越頻繁,它就越平淡。
- 拒絕暗黑模式:虛假的緊迫感或稀缺性、虛假的評價、預先勾選的附加項目、隱藏費用、難以取消、確認羞辱、一個大的「接受」旁邊是一個隱藏的「拒絕」。改為提供誠實的版本。
詳細資訊:references/emotion-trust.md。
11. 平台慣例
- 網頁:瀏覽器預設樣式是起點,而不是終點。響應式設計,
prefers-reduced-motion,鍵盤導航。 - macOS:使用系統字體 SF Pro,標題列工具列,側邊欄分節,標準快捷鍵(Cmd+, 偏好設定)。遵循 Human Interface Guidelines。
- Windows:使用 Segoe UI Variable,標題列在視窗內,功能區或傳統選單,Ctrl 快捷鍵。遵循 Fluent Design。
- iOS:SF Pro,導覽列,底部頁籤列,滑動手勢,HIG 導向的 Modal。原生導航轉場。
- Android:Roboto 或 Noto Sans,Material Design 元件,底部導覽,向上按鈕。
- 跨平台框架:尊重每個平台的慣例,不要強制使用一個統一的設計。
references/platform-conventions.md。
12. 可及性
- 有效的 HTML,語意化元素(
<nav>、<main>、<button>)。標題層級 (h1-h6) 不得跳過。 - 所有互動元素都可透過鍵盤操作,邏輯化的 tab 順序。焦點狀態可見。
- 顏色不只作為意義的傳達(§6)。表格和圖表有替代文字。
- 使用
prefers-reduced-motion減少動畫。 - 目標大小至少 44x44px 觸控,24x24px 滑鼠。
aria-label、aria-describedby、role如需要。表單錯誤與輸入關聯。- 以 200% 縮放測試,沒有內容遺失。
詳細資訊:references/accessibility.md。
13. 觸控目標
- 所有互動元素至少 44x44px。按鈕、連結、輸入框、圖示。
- 目標之間至少有 8px 間距。
- 在觸控螢幕上,所有控制項(包括緊湊設計)都應增大到 44px。
- 滑動手勢有視覺提示或可探索發現。
14. 動畫
- 持續時間:UI 元素 120-200ms,頁面轉場 200-300ms,複雜動畫 300-500ms。
- 緩動函式:進出 使用
ease或cubic-bezier(0.4, 0, 0.2, 1);進入使用ease-out;離開使用ease-in。 - 動畫應該是微妙的、有目的的,並且尊重
prefers-reduced-motion。 - 屬性:僅對
transform和opacity進行動畫處理以獲得最佳效能。
15. 檔案與專案結構
- 樣式表:
theme.css(Token)、components.css(元件樣式)、pages.css(頁面特定樣式)。 - 元件:每個元件一個資料夾,包含
Component.jsx、Component.css、Component.stories.js。 - 資產:
assets/(圖片、圖示、字體)。 - 腳本:
scripts/(工具)。 - 文件:
docs/(文件)。
16. 審計與評分
- 使用
scripts/ui-audit.mjs進行自動化 UI 審計。 - 評分類別:對比度、尺寸、觸控目標、內容溢出、工藝問題。
- 在視窗寬度 1440px 和 390px 下測試。
- 審計會產生螢幕截圖和評分報告。
17. 資源
- ui-craft Studio:https://najeebafridi.github.io/ui-craft/
- 參考資料:
references/資料夾包含詳細指南。 - 視覺方向:
assets/directions/資料夾包含 CSS 檔案。 - Token:
assets/tokens.css包含 CSS 自訂屬性。
關於此技能的詳細資訊
此技能旨在與 AI 代理(如 Claude Code、Cursor、Codex)協同工作,以產生高品質的 UI 設計。它提供了一個結構化的工作流程、具體的規則和實用的工具,以實現專業的結果。
關鍵原則:
- 始終從理解使用者及其上下文開始。
- 使用一個統一的設計系統(Token、方向)。
- 先構建結構和層級,然後再進行樣式設計。
- 測試每一種狀態和邊界情況。
- 使用自動化工具進行審計和驗證。
- 優先考慮可及性和平台慣例。
遵循這些原則,你可以始終如一地創建看起來高級、易於使用且感覺精心製作的介面。