UX 操作手冊 是做什麼的？
打造對商業正確、易於使用且一致的 UI。Mantine 提供元件；這本手冊告訴你何時使用哪個、畫面需要哪些狀態，以及如何檢查結果。請只閱讀你的任務所需的頁面。
優先順序
當來源意見不一致時，較高順位的優先：
- 商業需求：規格、票證或專案擁有者的指示。切勿未經告知即擅自更改。
- 產品自身規則：
AGENTS.md/CLAUDE.md、其 UX 及設計文件、既有元件。 - 本手冊。
- Mantine 的官方文件與預設值。
若 2 與 3 衝突，遵循 2。若你認為 2 或 1 有誤，仍應照做，並提出 UX 提案。
UI 工作開始前，先尋找產品內建的 UX 規則（在 repo 文件中搜尋「UX」、「UI」、「design」、「panel」）。若無則使用產品簡報模板草擬，並在計畫或 PR 中提出草稿，每項猜測標註 [Assumption]。
選擇層級
| 層級 | 變更類型 | 你的工作內容 |
|---|---|---|
| S | 既有畫面的小幅度修改：一個欄位、一個按鈕、一則訊息、一個欄位 | 閱讀你修改的元件對應的頁面。執行其檢查清單。若版面有變動則擷取螢幕截圖。 |
| M | 新畫面、對話框或表單，或對既有畫面進行大幅修改 | 先撰寫簡短 UX 規格。實作。執行視覺檢查。使用評分量表進行自我審查。 |
| L | 跨畫面的新流程、新功能區域，或導覽變更 | 先撰寫研究筆記並提出 2–3 個選項。先實作較安全的選項 A。之後將每個畫面視為 M 層級處理。 |
各層級的詳細說明與產出物請參考：工作流程
查詢頁面
| 你正在決定…… | 閱讀 |
|---|---|
| 頁面結構、階層、間距、響應式佈局 | decisions/layout |
| 按鈕、主要 vs 次要、圖示按鈕、動作選單 | decisions/actions |
| Modal vs Drawer vs Popover vs 行內、工具提示 | decisions/overlays |
| 應用程式導覽、分頁、麵包屑、步驟條、分頁器、連結 vs 按鈕 | decisions/navigation |
| 表格、列表、卡片、狀態標籤、日期、長文字 | decisions/data-display |
| Toast、警示、橫幅、行內訊息 | decisions/feedback |
| 選擇用哪種輸入元件：核取方塊、開關、單選按鈕、分段控制、選擇框、複合輸入框、晶片 | decisions/selection |
| 表單、標籤、驗證、必填欄位 | patterns/forms |
| 儲存按鈕、自動儲存、未儲存變更 | patterns/saving |
| 尚無資料可顯示、無搜尋結果 | patterns/empty-states |
| 等待資料載入或工作完成 | patterns/loading |
| 進階選項、「顯示更多」、按需顯示詳細資訊 | patterns/progressive-disclosure |
| 介紹新功能、首次執行、使用提示 | patterns/feature-onboarding |
| 後端服務中斷、離線、部分失敗、缺少權限 | patterns/degraded-experiences |
| 刪除、重設、撤銷、覆蓋 | flows/destructive-actions |
| 標籤、按鈕文字、錯誤訊息、空狀態文字 | writing |
| 鍵盤操作、焦點、標籤、對比度、ARIA | accessibility |
| 查詢 Mantine API、主題代碼、版本 | mantine |
| 規則背後的原因 | principles |
務必遵守
- 優先使用產品既有的元件與 Mantine，而非自行編寫。每個工作使用一個元件。
- 每個資料檢視都需提供載入中、空值與錯誤狀態。每個操作都需有等待狀態與結果回饋。
- 每個檢視只保留一個主要操作。次要操作應較低調。罕用操作則放入選單中。
- 暫時無法使用的操作保持可見並說明原因，且文字必須可透過鍵盤與觸控存取，而非僅在 tooltip 中顯示。優先使用
data-disabled來呈現無法使用的外觀，而非disabled屬性，且切勿停用送出按鈕：actions。 - 任何可能造成資料毀損的操作都需確認或允許復原。絕不能因錯誤而遺失使用者輸入的資料。
- 每個輸入欄位都需有可見標籤。意義不得僅由顏色傳達。所有元素都需可透過鍵盤操作。
- 在手機寬度與桌面寬度、淺色與深色模式下檢查結果：視覺檢查。
- 此處的範例使用字面英文。請改用產品的 i18n 機制。
當你認為還有改善空間時
你可以且應該提出更好的流程與元件。規則是先實作安全的預設方案，再附上提案：
- 依照規格要求並遵循此處的模式進行實作。
- 將你的想法以 UX 提案的形式，使用固定格式在計畫或 PR 中提出。
- 僅在規格可能導致資料遺失、暴露機密、阻止依賴鍵盤或螢幕閱讀器的使用者，或規格本身互相矛盾時，才在實作前暫停並提問。
報告
每個 UI 工作完成後，在 PR 或報告中附上 UX notes 區段：
## UX notes
- 層級：M — 新的「Mods」分頁
- 狀態：載入中 ✓ 空值 ✓ 錯誤 ✓ 禁用附原因 ✓
- 螢幕截圖：1280 淺色/深色，390 淺色/深色（已附上）
- 評分：全部通過；不適用：破壞性操作（無）
- 假設：[Assumption] Mods 列表較短（< 50），因此無需分頁
- UX 提案：1 個（見下方）