Communitygithub.com

ui-craft

為任何軟體設計與建構優質、專業且易於使用的介面,涵蓋網頁應用程式、儀表板、桌面應用程式、行動裝置與平板應用程式,以及行銷網站。

ui-craft 是什麼?

ui-craft 是一套全面的指引與工具集,旨在協助開發者與設計師為任何平台打造高質感、專業且人性化的使用者介面。其核心理念是「優質」應具備四個面向:合適(符合受眾與平台)、果決(統一的設計系統)、精心雕琢(細節完善)及誠實(贏得信任)。此技能支援從概念發想、色彩心理學、排版系統、元件設計到最終審計的完整工作流程,並內建了 16 種預設的視覺風格方向供快速選用。 ui-craft 不僅提供理論指導,還包含實用的自動化工具,例如基於 OKLCH 色域的色彩調色盤生成器與 UI 審計腳本,能針對對比度、尺寸、觸控目標及內容溢出進行評分。它鼓勵以設計簡報作為開發起點,遵循嚴謹的間距、字體與深度系統,並特別強調「語意化 Token」的使用,確保設計的一致性和可維護性。此外,此技能也處理暗色模式、錯誤狀態及情感設計(如緩解使用者焦慮或滿足專業用戶需求)等進階主題。 此技能適用於所有主要平台,包括網頁、桌面(Mac、Windows、Electron)、行動裝置(iOS、Android、Flutter、React Native)及平板。它可與 Claude Code、Cursor 等 AI 代理工具協作,透過讀取現有設計系統或生成全新的設計 Token 來快速迭代 UI。其最終目標是幫助使用者創建不僅功能正確,而且視覺上令人信賴、感到高級且絕非「AI 生成感」的介面,無論是從頭建構、重新設計還是審計現有產品都非常有用。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/najeebafridi/ui-craft/tree/HEAD/skills/ui-craft

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

ui-craft 是做什麼的?

如何建構在任何平台上都看起來高級且易於使用的介面。 數字單位為 CSS px;對於原生應用程式,請將 px 讀作 pt(iOS、macOS)、dp(Android)或 epx(Windows)。

高級意味著四件事。 合適:符合受眾、他們的心境和平台。果決:到處應用一個小系統(少數尺寸、一個圓角族系、一個強調色)。精心雕琢:細節完善。誠實:贏得信任,絕不欺騙。一個只正確的畫面看起來很普通;一個只裝飾的畫面看起來很廉價。

1. 工作流程(每次都這樣做)

  1. 在建造之前先觀察。 檢查是否有現有的設計系統:Token、主題檔案、Tailwind 設定、元件庫、品牌顏色、字型,或是一個從 ui-craft Studio 導出的 DESIGN.md 簡報和 theme.css。如果存在,就使用它;不要發明第二個。 只填補缺口。
  2. 了解使用者。 誰在使用這個?處於什麼心境(匆忙、焦慮、懷疑、沉浸工作中的專家)?他們應該感受到什麼?一句話。參閱 references/psychology-emotion.md。
  3. 選擇一個方向。 如果沒有既定的品牌識別,從 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 簡報。
  4. 在程式碼之前撰寫設計簡報(在你的回覆或註解中):
    產品:小型企業薪資系統(網頁應用程式,以桌面為主)
    使用者和感受:老闆在夜間處理薪資,對錯誤感到焦慮 -> 安全、有引導、精確
    方向:可信賴的分類帳;強調色深藍綠色(他們的品牌),冷色調中性色,淺色主題
    字體:IBM Plex Sans + Mono,14px 內文,表格數字     形狀與深度:6px 圓角,柔和陰影
    密度與動畫:緊湊,清晰(120-200ms)                 平台:響應式網頁
    特徵:數字像分類帳一樣排列;確認訊息指出確切金額和時間
    此畫面的主要任務:檢閱本月記錄並批准
    
  5. 先建構結構,再設計樣式。 先用真實內容建立佈局和層級,然後是系統(Token),最後是細節。不要使用 Lorem Ipsum:撰寫真實的名稱、數字和文案。早期就建立特徵,並讓其他一切都比它更安靜。 展示它正在運作。 第一個畫面是使用中的螢幕:真實資料、已經選好的合理預設值、可見的主要互動。永遠不要從一個完全空白或鎖定的狀態、一個無效的 "$0" 總計、或一個在前一個步驟完成之前就隱藏的關鍵步驟開始。
  6. 設計每一種狀態:載入中、空白、錯誤、成功、長文字、大量項目、單一項目、無權限(references/feedback-states.md)。
  7. 完成並檢查。 執行 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、方向)。
  • 先構建結構和層級,然後再進行樣式設計。
  • 測試每一種狀態和邊界情況。
  • 使用自動化工具進行審計和驗證。
  • 優先考慮可及性和平台慣例。

遵循這些原則,你可以始終如一地創建看起來高級、易於使用且感覺精心製作的介面。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能