jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/docs/autoflow/03-design/design-review.md
jim800121chen fb7da5d180 chore(autoflow): migrate .autoflow/ 共享層文件至 docs/autoflow/ 
依 autoflow-agent workspace v2 設計把 PRD / 設計 / 架構 / 交付類
共享文件從個人層 .autoflow/（ignored）搬到 docs/autoflow/（進 git），
讓團隊可共享產品與架構文件，個人層只留 progress / review / testing 等
per-branch 筆記。

- 02-prd/        21 個檔（PRD、features、market-analysis 等）
- 03-design/     18 個檔（design-spec、wireframes、flows 等）
- 04-architecture/ 31 個檔（TDD、design-doc、ADR×14、API 規格等）
- 07-delivery/   3 個檔（project-summary、phase-0.6-handover、stage-deployment-setup）

合計 73 檔。原檔已從 .autoflow/ 移除（migration 工具執行 git mv，
但因 .autoflow/ 在 .gitignore 中、git 將此操作視為新增、無 rename history）。
2026-05-04 16:55:55 +08:00

13 KiB
Raw Blame History

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 階段補。