Communitygithub.com

omd-feel

將設計與前端業界憑「感覺」使用的介面細節,轉化為可量化的規則來應用(APPLY)或稽核(AUDIT)。

omd-feel 是什麼?

omd-feel 是一個專為 UI 開發與設計審查而生的 AI 代理技能,旨在將過去依賴設計師「直覺」的介面細節(如動畫時長、陰影模糊、行高、按鈕大小等)系統化為具有明確來源等級的量化規則。該技能支援「APPLY」模式,能在建立或修改 UI 時自動注入這些規則,以及「AUDIT」模式,可針對現有 HTML/JSX/TSX/CSS 檔案進行掃描,產生包含嚴重等級(BLOCK/WARN/FYI)的詳細報告。其規則體系涵蓋 17 個軸向、113 條規則,主要參考 W3C/WCAG、Human Interface Guidelines (HIG)、Material Design 以及業界共識,並根據來源權威性分為 SPEC、DS、CONV、OP、FOLK 五個等級,以決定規則的強制程度。此技能特別強調與品牌 DESIGN.md 協作,品牌定義的 token 永遠優先於通用規則,確保規則能融入既有設計系統而非覆蓋它。此外,它內建嚴格的安全護欄,例如禁止將民俗傳說(folklore)等級的規則當作規範強制、禁止發明規則表中不存在的數字,以及必須為所有動畫提供 `prefers-reduced-motion` 降級方案,以兼顧可及性。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/nococn/omd-feel/tree/HEAD

在你喜歡的 AI 中提問

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

說明文件

omd:feel — 介面感受,量化呈現

將業界過去憑「感覺」使用的介面細節 — 「這個速度差不多」、「這個陰影差不多」、「這個間距差不多」 — 轉換為附有來源等級、可檢查的數字,並進行應用與稽核的技能。繼承 Jakub Krehel 的 「優秀的介面是一堆小事累積而成的」 命題,但進一步用數字回答要符合哪些數字 / 何時不符合。

核心洞察:品質是將數十個小約束各自限制在容許範圍內的積分結果。600ms 的勾選框提示音、1px 的 focus ring、2.85:1 的本文對比度、缺少 @media (hover:hover) 保護的 hover lift — 每一項都是「感受」中可量化的扣分。這個技能的目的就是防止這些扣分。

完整規則(17 軸、113 條)位於 reference.md,各數字的來源、等級與方法論則在 provenance.md。下方的速查表是每次都會載入的核心內容,深入的稽核與邊緣軸向則需參考 reference 文件。

何時使用

  • APPLY — 在新建或修改 UI 時注入量化的感受規則。(「改善感受」、「調整互動」、「套用細節」)
  • AUDIT — 針對現有 HTML/JSX/TSX/CSS 與規則表進行比對,產出感受分數與 BLOCK/WARN/FYI 報告。(「感受檢查」、「稽核此畫面」)

若非 UI 相關工作則不會觸發。僅處理文案或資訊架構的工作不屬於此技能範疇。

0. 來源等級 → 強制強度(此技能的核心)

所有規則都帶有等級,而等級決定了強制強度。這就是將「感覺」誠實量化的方法 — 規格數字是門檻,品味數字則是建議。

徽章等級APPLYAUDIT 嚴重程度
🟢 SPECspec-authoritative(W3C/WCAG·HIG·規範性)強制BLOCK
🟢 DSds-token(已提交的設計系統 Token)強制(品牌未覆蓋時)BLOCK
🟡 CONVindustry-convention(≥2 位獨立實務者共識)預設套用WARN
⚪ OPsingle-opinion(可信賴的單一意見)僅建議FYI
⚪ FOLKfolklore-unverified(無法追溯來源)建議 + 標明等級FYI

分佈:SPEC 61 · DS 24 · CONV 19 · OP 7 · FOLK 2 → 85/113 條具備規範/Token 依據(可強制)。

DESIGN.md 始終優先。 品牌的 DESIGN.md Token 若與規則衝突,則以品牌 Token 為準。這些規則是品牌未定義時的預設值,而非覆蓋。若專案根目錄存在 DESIGN.md,則先以 omd:apply 讀取 Token,再用 feel 規則填補空缺的軸向。

1. 速查表 — 始終套用的核心數字

等級標示:🟢=強制,🟡=預設,⚪=建議。衝突時 DESIGN.md > 🟢 > 🟡 > ⚪。

動畫與時間

  • 日常 UI 轉場約 200ms(hover ≤150 · popover 約 200 · overlay/modal 約 300)。範圍 150–300ms,>400ms 會顯得遲緩。🟡
  • 持續時間以 50ms 為格線量化(禁止 220/333ms)。🟢
  • 退出約為進入的 0.8 倍(關閉比開啟快)。🟢
  • 禁止使用單一全域持續時間 — 應與移動面積/距離成比例。🟢

緩動與彈簧

  • 進入/使用者觸發 = ease-out cubic-bezier(0,0,0.2,1) · 退出 = ease-in/加速 · 已顯示的 morph = ease-in-out · 載入動畫/進度條 = linear。進入時禁止使用 ease-in。 🟡
  • Apple 預設彈簧 (response 0.55, damping 0.825, bounce 0),功能性 UI 的 bounce <0.4。🟢
  • 可中斷:互動狀態應使用 transition/spring(可重新定位),僅一次性動畫才用 @keyframes。🟢

間距 · 圓角 · 節奏

  • 8px 為基數,4px 為半階(4·8·12·16·24·32·40·48·64)。🟢
  • 內部 padding ≤ 兄弟元件間的外部 gap。 🟡
  • 同心圓圓角:外層 = 內層 + padding。 🟢
  • UI 字級比例約 1.25(大三度)。🟡

陰影與深度

  • 分層陰影 3–5 層,光源為上方單一光源。低海拔=緊實+銳利,高海拔=擴散+廣泛(類似 Tailwind md→lg 階梯)。🟡/DS
  • 暗色模式使用明亮表面而非陰影來表現深度。🟡

字體排版

  • 本文 line-height 1.5,行長約 66ch(45–75)。🟢
  • 標題字距 −0.02~−0.03em,全大寫 +0.05~0.1em,本文約 0。🟡
  • 變動數字使用 tabular-nums;標題使用 text-wrap: balance,本文使用 pretty;版面使用 antialiased。(參考 seed/jakub)🟡

色彩與對比

  • 文字 4.5:1(大字 3:1)AA · 非文字/UI 邊界 3:1 · focus ring 3:1 + 2px + 約 2px offset。🟢
  • M3 狀態圖層:hover 8% · focus 10% · pressed 10% · dragged 16%。 🟢
  • 停用狀態約 38% 透明度。🟡

狀態與回饋

  • 資料元件需定義全部 5 種狀態(empty/loading/error/content/skeleton)。🟡
  • pressed:scale 0.96–0.97,150ms ease-out(底限 0.95)。DS/⚪
  • 圖示狀態切換:scale+opacity+blur 4px→0,彈簧約 0.3。🟡

目標與指標

  • 觸控目標 44pt(iOS/WCAG AAA) / 48dp(Material) / 24px(WCAG AA 最小),相鄰目標間距 ≥8pt。🟢
  • cursor:可互動=pointer · 停用=not-allowed · 拖曳=grab→grabbing · 編輯=text。🟡

捲動與手勢

  • 覆蓋層/巢狀捲動容器使用 overscroll-behavior: contain(防止捲動鏈結、下拉重新整理穿透)。🟢
  • 滑動解除閾值 約 30% 距離或 velocity flick。DS
  • scroll-snap:長表格=proximity · 輪播=mandatory。🟢

回應時間與感知效能

  • 100ms = 即時 · 1s = 思緒連續性極限 · 10s = 注意力極限(需顯示 % 進度)。 Doherty 400ms 上限。🟢
  • INP ≤200ms p75,影格預算 16.6ms。 🟢
  • 載入動畫僅在預估等待 >1s 時顯示;若顯示則至少維持 500ms(防止閃爍)。若已知版面佈局則使用 skeleton。🟡/DS

版面穩定性 (CLS)

  • CLS ≤0.1 p75。 多媒體需使用 width/height 或 aspect-ratio 預留空間。scrollbar-gutter: stable。font-display: optional(或 swap)+ metric override。禁止在輸入後 500ms 範圍外於內容頂部插入新內容。🟢

模態框 · 覆蓋層 · Z-index

  • 使用 role=dialog + aria-modal=true,開啟時 focus 移入對話框,Tab 循環、Esc 關閉、關閉時 focus 回到觸發元素、背景設定 inert。遮罩 #000 約 32%。🟢
  • light-dismiss:臨時/資訊對話框可開啟,資料輸入/破壞性操作則關閉。 🟢
  • Z 階層:dropdown 1000 / sticky 1100 / fixed 1200 / backdrop 1300 / modal 1400 / popover 1500 / toast 1600 / tooltip 1700。覆蓋層使用 portal。(填補空缺)

效能 · 毛玻璃 · 無障礙

  • 動畫僅使用 transform/opacity(+filter),禁止 transition: all;will-change 為暫時性(閒置時移除)。🟢
  • 毛玻璃:backdrop-filter: blur(16px) saturate(180%) + 半透明填色約 0.6 + 1px 邊線 + 不透明 fallback,文字 ≥4.5:1。🟡/🟢
  • prefers-reduced-motion: reduce → 使用 cross-fade/立即切換,移除大幅移動/視差(小幅透明度可保留)。≤3 flashes/s。禁止替代方案而僅移除 focus outline(使用 :focus-visible)。🟢

表單驗證

  • 初次驗證在 blur 時進行,一旦發生錯誤後該欄位改為 on-change(即時) 驗證(修正後立即解除錯誤)。非同步驗證防抖 300–500ms。🟡

2. APPLY 工作流程

  1. 偵測上下文 — 專案根目錄/目標資料夾是否存在 DESIGN.md?若存在,先以 omd:apply 流程讀取 Token(顏色·圓角·間距·動畫·字體)。品牌 Token 擁有權威。
  2. 填補空缺軸向 — 僅針對 DESIGN.md 未定義的軸向填入速查表預設值。深入軸向(如捲動物理、毛玻璃、Z 階層、CLS)則參考 reference.md 的對應章節。
  3. 尊重等級 — 🟢 直接套用,🟡 作為預設值(品牌或請求可覆蓋),⚪/FOLK 則明確告知「這是品味啟發式規則」 並僅作為建議。
  4. 在輸出中保留依據 — 對於非顯而易見的數字(例如退出速度 0.8 倍、focus offset 2px),應在程式碼註解或說明中一行解釋原因並標明等級。禁止發明數字 — 若速查表/reference 中不存在,則應閱讀 reference 或告知「不知道」。
  5. 始終附帶 prefers-reduced-motion — 加入動畫時必須同時提供減少動畫的分支(無障礙非選項)。

3. AUDIT 工作流程

採用類似 omd:designer-review 的顧問模式(唯讀)+ feel 軸向。每次呼叫均重新讀取 DESIGN.md(禁止快取)。

  1. 輸入:artifact_path(HTML/JSX/TSX/CSS)+(若存在)design_md_path + viewport。
  2. machine_check 掃描 — 將 reference.md 中各規則的 🔍 machine_check 套用至 artifact。例如:
    • 檢測 transition: all / >400ms 持續時間 / 非格線化持續時間
    • 檢測觸控目標 <44px、focus outline 被移除、文字對比 <4.5:1
    • 檢測缺少 aspect-ratio 的 <img>、缺少 aria-modal 的 modal、缺少 overscroll-behavior 的覆蓋層
  3. 嚴重程度 = 等級對應 — SPEC/DS 違規 = BLOCK,CONV = WARN,OP/FOLK = FYI。(禁止抬高/降低嚴重程度。)
  4. 感受分數 — 計算可套用軸向中落在容許範圍內的比例:以 🟢 in-band / 🟢 applicable 為核心數字,WARN/FYI 為輔助。「感受分數 18/22 SPEC in-band,BLOCK 2,WARN 5」。
  5. 輸出:<work_dir>/.reviews/feel-audit-round-<N>.md — 每個問題包含 行號 + 等級 + machine_check 依據 + 修正方式(可操作)。禁止無行號的模糊問題或「看起來沒問題」的橡皮圖章。
### [BLOCK] 觸控目標低於最小值 — 圖示按鈕
- **位置:** `components/Toolbar.tsx:31`
- **規則:** §8 目標 — 44pt/48dp/24px 最小(🟢 SPEC,WCAG 2.5.8)
- **證據:** `<button className="w-6 h-6">` → 24px,無點擊區域擴展
- **修正:** 透過 padding 確保 44×44 點擊區域(`p-2.5` + 保持視覺 24px 圖示)

4. 安全護欄

  • ❌ 禁止將民俗傳說(folklore)當作規範呈現。 ⚪/FOLK 必須始終標明等級。(語料庫附錄 B 的降級清單 — Hick-Hyman 0.155s/bit、Fitts ms/bit、rubberband 0.7、pressed 0.95 底限、exit 0.8 倍、stagger 80/100ms、optical 2px 等 — 禁止強制當作數字門檻,僅借用其方向。)
  • ❌ 禁止發明數字。 若速查表/reference 中不存在,則應閱讀 reference 或告知「不知道」。
  • ❌ 禁止忽視 DESIGN.md 而以通用最佳實踐覆蓋。 品牌 Token 優先。
  • ❌ 禁止加入動畫後遺漏 prefers-reduced-motion 分支。
  • ❌ AUDIT 時禁止升高嚴重程度(全部標 BLOCK)、降低嚴重程度(將 BLOCK 降為 FYI)、或產出無行號的問題。
  • ❌ 若需修改數字,請勿手動編輯 reference.md,而應透過 corpus → generator 重新產生。

5. omd 生態系關係

  • omd:apply — 套用品牌 DESIGN.md Token。omd:feel 在其之上填補 Token 未定義的感受層面。
  • omd:designer-review — 審查品牌一致性(字體/色彩預算/圓角尺度)。omd:feel AUDIT 是其感受軸向的夥伴(動畫時間·目標·CLS·無障礙)。
  • omd:taste — 使用者品味儀表板(獨立概念)。重複的感受決策若固化為品味,則可透過 omd:remember 記錄。

手動驗證:若對一個包含 transition: all 0.6s + <button class="w-5 h-5"> + 缺少 prefers-reduced-motion 分支的元件進行 AUDIT,則應產生至少 3 個 BLOCK(transition all=GPU SPEC、20px 目標=WCAG SPEC、缺少減少動畫分支=a11y SPEC),每項皆附行號,且感受分數應相應降低。

相關技能