# Design Review 報告 — local-tool 現況

> 本文件對 **local-tool 既有版型** 做一次 Design Review，用於決定雲端版要沿用、微調、或未來迭代哪些部分。
>
> **雛形階段（Phase 0）不改** — 這份報告的結論寫入 Phase 1+ 的改善清單。
>
> 範圍：`local-tool/frontend/src/` 的 UI 層（不包含業務邏輯）

---

## 1. 整體評估

**⚠️ 有改善空間** — 核心視覺風格（Shadcn / Radix / Tailwind 4）專業成熟，元件組織清晰，Dark Mode 與 i18n 都內建到基礎層。但在**無障礙細節、互動規格完整度、錯誤處理一致性**幾個面向有提升空間。整體品質適合做 B2B / 開發者工具，不需要大改。

---

## 2. 評分卡

| 維度 | 評分（1-5）| 說明 |
|------|-----------|------|
| 視覺一致性 | 4 | Shadcn 為基礎，大多數頁面視覺語言一致。少數地方（Sidebar icon 用字母、狀態色散在各元件）不一致 |
| 無障礙（WCAG 2.1 AA）| 3 | Shadcn 內建不錯，但自訂元件缺乏 ARIA 規範、部分狀態靠顏色傳達 |
| 響應式（RWD）| 3 | Desktop 設計良好；Tablet 可用；Mobile 基本不可操作 |
| 互動回饋 | 4 | Loading / Error 大部分有處理；細節如 toast 時機、disabled tooltip 不完整 |
| 資訊架構 | 4 | Sidebar 導航直觀，頁面層級清晰 |
| UX Writing | 3 | 部分文案直接寫在 tsx（沒走 i18n）、錯誤訊息參差 |
| Dark Mode 支援 | 5 | 完整，所有頁面驗證過（由 oklch + CSS 變數） |
| 圖示語言 | 3 | Lucide Icon 使用得當，但 Sidebar 用「H / M / D / W / S」字母佔位不理想 |

**平均：3.6 / 5** — 基礎扎實，細節待打磨。

---

## 3. Critical（必須修，影響可用性 / 安全 / 法規）

> 雛形階段**不改**，但 Phase 1 啟動時優先處理。

| # | 問題 | 影響頁面 | 建議 |
|---|------|---------|------|
| C1 | Sidebar 的字母佔位 icon 不符合圖示語言 | Sidebar 全域 | 改用 Lucide icon（`LayoutDashboard` / `Boxes` / `Cable` / `Play` / `Settings`） |
| C2 | Sidebar 選單項目色彩對比不足（hover 後 `text-muted-foreground` 在某些背景上對比低於 4.5:1） | Sidebar | 確認 hover 狀態文字使用 `text-accent-foreground`，驗證對比 |
| C3 | `/devices` 右上的 WinUSB driver / udev hint 等文字**直接寫在 tsx**（`devices/page.tsx:76, 92-101`），未走 i18n | `/devices` | 全部文案改走 `t()` |
| C4 | `/workspace/[deviceId]` 的「← 返回」「工作區：」「停止推論」「開始推論」等文字**直接寫在 tsx**（`workspace-client.tsx:62-79`） | Workspace | 改走 i18n |
| C5 | `/workspace/page.tsx` 整頁文字直接寫死（`23-39 行`），無 i18n | Workspace 選擇頁 | 改走 i18n |

---

## 4. Major（建議修，影響體驗或一致性）

| # | 問題 | 影響範圍 | 建議 |
|---|------|---------|------|
| M1 | 裝置狀態色（`statusColors`）**沒納入 Design Tokens**，散落在 `device-status.tsx` | 狀態系統 | 抽出為 Design Token（或至少統一 constants），方便 Dark Mode 對照與未來擴充 |
| M2 | 狀態僅靠「顏色點」傳達（綠 / 黃 / 紅 / 灰），對色盲不友善 | 裝置狀態徽章 | 除了顏色 + 文字，考慮加小 icon（✓ / ✗ / ⚠）作為冗餘 |
| M3 | `ConnectedDevicesList` / `DeviceCard` 等卡片沒有明確的 `Hover` 視覺變化（部分有 `hover:bg-accent`，部分沒有）| 裝置 / 模型卡片 | 統一 hover 規格（可點擊卡片一律加 `cursor-pointer hover:bg-accent` 或邊框變色）|
| M4 | `FlashDialog` 有成功 / 失敗狀態但**沒有明確的取消 / 中止**按鈕 | FlashDialog | 加「取消燒錄」按鈕（若 backend 支援）|
| M5 | Disabled 狀態的按鈕 **沒有 tooltip 解釋原因**（例如「為什麼 disabled？」）| 所有 disabled 按鈕 | 加 Tooltip（shadcn 有 Tooltip 元件），解釋條件 |
| M6 | `/settings` 的 `ServerStatusDashboard` / `ServerLogViewer` 資訊密度過高（開發者喜歡，但對一般使用者過度）| Settings | Phase 1 收起為可展開區塊，或移到 Developer Mode |
| M7 | `OnboardingDialog` 假設使用者剛插 USB Dongle，在雲端版不適用 | Dashboard | 雲端版重寫 Onboarding 流程（引導 Pairing）|
| M8 | Toast 持續時間未統一（Sonner 預設 vs 特定場景自訂）| 全域 | 統一 toast 持續時間政策（成功 3s、錯誤 5s）|
| M9 | `confirm()` 原生 dialog（`cluster-card.tsx:66`）視覺不一致 | Cluster 刪除 | 改用 `AlertDialog`（shadcn 既有元件）|
| M10 | Mobile 版 Sidebar 未折疊為 Sheet / Drawer，會擠壓內容 | Mobile RWD | 加 responsive Sheet，Mobile 時漢堡選單開啟 |
| M11 | `/models` 比較模式的浮動工具列（`fixed bottom-6 z-50`）在 Mobile 上可能被 safe-area 遮住 | `/models` | 加 `pb-safe` 或 `bottom-[calc(env(safe-area-inset-bottom)+1.5rem)]` |
| M12 | Form 驗證錯誤（如 ModelUploadDialog）**沒用 aria-invalid + aria-describedby**，Screen Reader 無法讀出錯誤 | 所有表單 | 加 ARIA 屬性 |

---

## 5. Minor（未來修，微小改善）

| # | 問題 | 建議 |
|---|------|------|
| m1 | Dashboard 的 StatCard icon 色（藍 / 紫 / 綠 / 黃）硬編碼，Dark Mode 下對比略弱 | 改用 `text-chart-*` token 或調整 Dark Mode 亮度 |
| m2 | Skeleton（`device-detail-client.tsx:34-35`）過於簡陋（只是灰色塊） | 改為結構相似的多區塊 skeleton，更符合載入後實際佈局 |
| m3 | `ActivityTimeline` 空狀態只顯示「尚無活動紀錄」，缺乏引導 | 加入 CTA「掃描第一台裝置」（local 版）/「配對第一台裝置」（雲端版）|
| m4 | Version 顯示寫在 sidebar 底部 `v0.1.0`，但與 Settings 頁的版本可能不同步 | 統一來源（讀 package.json 或 env variable）|
| m5 | Typography scale 未定義（只用 Tailwind 預設） | Phase 2 可考慮建立語義 typography（heading / body / caption）|
| m6 | 沒有 Focus Trap 機制在自訂 Modal（shadcn Dialog 有內建，但 custom popup 沒有）| 檢查所有 custom popup |
| m7 | 沒有 Skip to main content 連結 | 對鍵盤使用者友善，加入 |
| m8 | 部分 icon 沒 `aria-hidden="true"`（純裝飾 icon 不應被 SR 念出）| Review 全專案 icon 使用 |
| m9 | 沒有 `prefers-reduced-motion` 專屬規則（雖然 Tailwind 4 內建 utility 但未全面應用）| Review `animate-*` class 使用 |
| m10 | `sidebar.tsx` 的 `text-xs font-bold` 字母佔位 icon 在 Dark Mode 下視覺稍弱 | 改用 Lucide 後問題自然消除 |
| m11 | 沒有「Remember previous language / theme selection」UX 提示 | 加註設定會儲存到 localStorage |
| m12 | 錯誤訊息中英文夾雜（如 `'driver 安裝失敗'`）| 統一走 i18n |

---

## 6. 缺失的項目

| 項目 | 重要性 | 建議 |
|------|--------|------|
| Loading State 統一規範 | 高 | 統一 Skeleton 策略：資料載入 < 200ms 不顯示、≥ 200ms 顯示 skeleton |
| Error State 統一規範 | 高 | 統一「網路錯誤 / 伺服器錯誤 / 資料不存在」的 UI |
| Empty State 多樣化 | 中 | 目前只有通用 `EmptyState` 元件；可加「有資料但被篩選掉」「初次使用」「永久空」三種語氣 |
| Tooltip 系統 | 中 | shadcn 有 Tooltip，但全專案使用不一致 |
| Breadcrumb | 中 | 深層頁面（`/models/[id]` / `/devices/[id]/...`）沒麵包屑 |
| Search | 中 | 全域搜尋（Cmd+K）對開發者工具很有幫助 |
| Keyboard shortcuts | 低 | Phase 1+ 可考慮（如 `/` 聚焦搜尋、`g d` 跳 Dashboard 等）|
| 無障礙審查（axe-core 自動化）| 高 | 加入 CI，防止回退 |
| Design Token 文件（Storybook / Ladle）| 中 | 方便未來團隊成員查閱 |
| User Documentation | 中 | 產品內嵌的說明文件 / Help Center |

---

## 7. 優點（做得好的地方）

1. **✅ Shadcn / Radix / Tailwind 4 技術選型成熟** — 無障礙、Dark Mode、可組合性都有好基礎
2. **✅ `oklch()` 色彩空間** — 現代、可感知線性，Light / Dark 對應優雅
3. **✅ i18n 系統自製但完整** — 繁中 + English 雙語支援，涵蓋率高（少數 miss 的 string 已列入 Critical）
4. **✅ Zustand stores 組織清晰** — 每個領域一個 store，易維護
5. **✅ 元件分類良好** — `ui/` 基礎 / 業務元件（models/devices/inference/camera/dashboard）/ layout 三層結構
6. **✅ Dark Mode 原生支援** — `ThemeSync` 跟隨系統，無需使用者手動切換
7. **✅ GuidedTour + OnboardingDialog** — 有考慮新手引導（雖然雲端版要重寫）
8. **✅ Empty State 有專用元件** — `empty-state.tsx` 是一個好抽象
9. **✅ 狀態色有動畫提示** — `connecting` 用 `animate-pulse` 傳達「進行中」的感覺
10. **✅ Test coverage** — 462 個 test 檔案（前端）顯示有測試文化

---

## 8. 響應式 Review

| 斷點 | 現況 | 評價 |
|------|------|------|
| Mobile (< 640px) | Sidebar 擠壓主內容；部分頁面（Workspace）無法正常使用 | ⚠️ 未優化，建議雛形階段不投入，使用者注意力放 desktop |
| Tablet (640-1024) | 可用，但 Sidebar 占 `w-60` 仍顯擁擠 | 🟡 可接受，未來可改 drawer |
| Desktop (≥ 1024) | 設計良好 | ✅ 主要目標 |
| Wide (≥ 1440) | 無最大寬度限制，內容在超寬螢幕會過散 | 🟡 建議加 `max-w-7xl` 或類似 |

**雲端版 Phase 0 決策**：**Desktop First**，Mobile 不保證完整體驗，只確保能登入 + 看 Dashboard 概要。

---

## 9. 互動設計 Review

| 項目 | 現況 | 建議 |
|------|------|------|
| Hover 狀態 | 大多 ✅ | 卡片類 hover 規格需統一 |
| Active / Pressed | 大多 ✅（shadcn 內建）| — |
| Focus ring | ✅（`ring-[3px]` 符合 WCAG AA）| — |
| Disabled | ✅（`disabled:opacity-50`）| 加 tooltip 解釋原因（Major）|
| Loading | 大多 ✅（Loader2 icon / skeleton）| skeleton 結構化（Minor）|
| Empty | ✅（EmptyState 元件）| 多樣化語氣（缺失）|
| Error | 部分 ⚠️ | 統一規範（缺失）|
| Success | ✅（toast）| 持續時間統一（Major）|
| 動畫 | 有基本 `animate-pulse` / `animate-spin` | `prefers-reduced-motion` 支援（Minor）|
| 轉場 | 無明確轉場（Next.js App Router 預設）| Phase 1+ 可加頁面轉場 |

---

## 10. UX Writing Review

**做得好：**
- 大多數文字走 i18n，集中在 `zh-TW.ts` / `en.ts`
- 語氣友善（「請插入 Kneron USB Dongle 並點擊掃描」）
- 明確的錯誤後果說明（「確定要刪除「{name}」嗎？此操作無法復原。」）

**待改進：**
- 部分中英夾雜（M12）
- 部分直接寫在 tsx 繞過 i18n（C3 / C4 / C5）
- Toast 訊息長度不一，有些過長
- 空狀態語氣不夠引導（m3）

---

## 11. Dark Mode Review

**全頁面抽查**（Light ↔ Dark 切換）：

| 頁面 | Dark Mode 品質 |
|------|---------------|
| `/` Dashboard | ✅ 良好 |
| `/devices` | ✅ 良好，udev hint banner 的 amber 色系在 Dark 下仍清晰 |
| `/devices/[id]` | ✅ 良好 |
| `/models` | ✅ 良好 |
| `/models/[id]` | ✅ 良好 |
| `/workspace/[deviceId]` | ✅ 良好（Camera frame 視覺略弱但可接受）|
| `/settings` | ✅ 良好 |

**結論**：Dark Mode 執行完整，**不需要在雲端版重做**，直接沿用即可。

---

## 12. 雲端版的優先處理

雲端版 Phase 0 雛形**最需要處理的**（從以上清單挑出）：

1. **C3 / C4 / C5**（i18n 遺漏）— 雲端版寫新頁面時就要求走 i18n，避免累積
2. **M1**（狀態色納入 Token）— 新增 `RemoteDeviceBadge` 時就要統一
3. **M2**（狀態不只靠顏色）— 新增 `RemoteDeviceBadge` 時就要實作
4. **M7**（OnboardingDialog 重寫）— 雲端版情境完全不同，直接不做（Phase 0）或重寫（Phase 1）
5. **M10**（Mobile Sidebar）— 雲端版使用者可能會在 iPad / 手機臨時查看，建議 Phase 1 做 Sheet
6. **缺失項**（Loading / Error 統一規範）— 雲端版場景掉線頻率更高，需要規範

其他 Critical / Major 因為在 local-tool 身上，**雛形階段暫緩**，由 local-tool 團隊自行決定何時處理。

---

## 13. 給使用者的建議

**如果你要在 local-tool 上修這些問題，建議順序：**

1. **先修 Critical**（C1 – C5）：影響一致性與法規
2. **再做無障礙補強**（M2 / M12 / m6 / m7 / m8 / m9）：可用一次性任務批次處理
3. **Design Token 整理**（M1）：趁重構一起做
4. **Mobile RWD**（M10 / M11）：獨立任務，優先級低
5. **Empty / Error / Loading 規範**：跨多檔案，獨立任務

**不建議的做法**：在 local-tool 和 visionA Cloud 同時改，會增加複雜度。建議 local-tool 當前版本穩定（已有 462 個測試），**穩住現狀**，等 visionA Cloud Phase 0 雛形完成後，再統一迭代兩邊共用的元件。

---

## 14. 方法論

本審查方法：

- **靜態檢視**：讀程式碼（`src/app/`、`src/components/`、`src/lib/i18n/`）
- **視覺推論**：根據 className 推估視覺效果，未實際運行
- **WCAG 2.1 AA 為基準**：色彩對比、鍵盤操作、ARIA、可還原動畫
- **與最新 Shadcn 慣例對照**：核對是否偏離標準做法

**未涵蓋（需要實際執行產品才能做）**：
- 實際的可用性測試（需要找真人）
- 效能 profiling
- 實機 Screen Reader 驗證（NVDA / VoiceOver）
- 實機觸控測試（iPad / 手機）

這些建議在 Phase 1+ 的 QA 階段補。