# visionA Cloud — 設計規格（Design Spec）索引 | 項目 | 內容 | |------|------| | 專案代號 | visionA Cloud（`visionA-frontend`） | | 文件版本 | v0.1（Phase 0 雛形規劃） | | 最後更新 | 2026-04-21 | | 狀態 | 三方聯合討論中（Design Agent 產出） | | 主要負責 | Design Agent | | 基礎設計稿 | `local-tool/frontend/` 既有實作（Shadcn 風）+ `edge-ai-platform` POC 的 clusters 頁面 | | 模式 | 既有版型反向整理 + 補齊雲端版缺失 + 局部 Design Review | > **本規格從既有程式碼反向整理**。版型與 Design Tokens 直接沿用 local-tool，以確保「離線版 / 雲端版同一套前端」的決策可執行。雲端版新增的頁面（登入、註冊、帳號、Pairing、Clusters）與狀態（在線 / 離線 / 遠端掉線）為本次新增設計。 --- ## 文件結構 本規格採用模組化結構，避免單檔過大。本檔為索引，詳細內容拆成以下子檔案： ``` .autoflow/03-design/ ├── design-spec.md ← 本檔（索引 + 設計系統概述 + 整體策略） ├── design-tokens.md ← Design Tokens 三層架構 ├── components.md ← 元件庫清單與規格 ├── pages.md ← 頁面結構（既有 + 雲端新增） ├── flows/ │ ├── flow-pairing.md ← Pairing 流程（最重要的新增流程） │ ├── flow-offline-handling.md ← 離線 / 掉線 UI 行為 │ ├── flow-auth.md ← 登入 / 註冊流程（雛形 stub） │ └── flow-conversion.md ← 轉檔流程（Phase 0.8 新增） ├── design-review.md ← 對既有 local-tool 版型的 Design Review └── wireframes/ ← 文字版 wireframe（僅針對雲端新增頁面） ├── wf-login.md ├── wf-register.md ├── wf-account.md ├── wf-pairing.md ├── wf-clusters.md └── wireframe-conversion.md ← 轉檔頁面 wireframe（Phase 0.8 新增） ``` > `03-design/prototype/` 在 Phase 0 雛形**暫不產出** high-fidelity prototype。版型直接沿用 local-tool 實作，前端工程師可直接參考 `local-tool/frontend/` 複用元件。 --- ## 1. 設計系統概述 ### 1.1 設計哲學 **「Editor-grade Console — 開發者每天要用 8 小時也不累的工作台」。** visionA Cloud 的使用者是**開發者 / FAE / SI**，不是一般消費者。他們： - 一天可能開著這個頁面數小時 - 熟悉技術細節，不需要過度的引導 - 重視資訊密度與快速操作，勝過視覺華麗 - 多半在桌面環境工作（Mac / Windows） - 對載入狀態、連線狀態、錯誤訊息的「誠實性」非常敏感 **設計原則（由此延伸）：** 1. **資訊優先於裝飾** — 任何視覺元素都要有功能理由。不用漸層、不用花俏動畫。 2. **誠實呈現狀態** — 在線 / 離線 / 連線中 / 錯誤，一定要讓使用者看得出差別（不是只用顏色，必須搭配文字 / icon）。 3. **一致性勝過驚喜** — 與 local-tool 完全共用同一套元件與版型，使用者在兩種模式間切換無感。 4. **可預期勝過可愛** — 按鈕按下去會發生什麼事，應該從文字、位置、圖示就能預測。 5. **鍵盤友善** — 所有操作都應該有鍵盤路徑（符合 WCAG 2.1 AA）。 6. **Dark Mode 第一** — 跟隨系統主題，不做強制光亮。 ### 1.2 設計目標 | 目標 | 衡量方式（供 Testing 參考） | |------|--------------------------| | 與 local-tool 視覺一致 | 同一使用者在兩種模式間能一眼認出是同個產品 | | 雲端特性清晰 | 使用者隨時知道「我現在連的是哪台遠端裝置」「它在線嗎」 | | 學習成本 < 10 分鐘 | 看得懂 Dashboard、能找到 `/devices/pair`、能開 Workspace | | 無障礙符合 WCAG 2.1 AA | axe-core 自動掃描 0 個 Critical；鍵盤可操作所有核心流程 | | Dark Mode 完整 | 100% 頁面在 Dark Mode 下色彩對比達標 | ### 1.3 設計範圍（Phase 0 雛形） | 類別 | 頁面 / 元件 | 範圍 | |------|-----------|------| | **沿用 local-tool**（版型完全不動） | `/`、`/devices`、`/devices/[id]`、`/models`、`/models/[id]`、`/workspace`、`/workspace/[deviceId]`、`/settings` | 複用元件、複用 Design Tokens；只改 API base URL 的連法 | | **從 POC 搬**（適配雲端） | `/clusters`、`/workspace/cluster/[clusterId]` | 視覺風格與既有頁面對齊，搬完就等同「原生雲端功能」 | | **雲端新增 — 雛形 stub** | `/login`、`/register`、`/account` | 低保真，能 compile 可導覽即可，UI 細節可 Phase 1 細化 | | **雲端新增 — 完整設計** | `/devices/pair`、Sidebar 的帳號區塊、裝置掉線徽章與降級體驗 | 本次規格 focus 的核心 | | **全域行為改動** | 頂部 `ConnectionStatus`、`api.ts` 錯誤處理、WebSocket 重連 UI | 雲端場景連線邏輯不同，需要調整 | ### 1.4 設計範圍外（不做的事） - 高保真 prototype（Figma 或 HTML）— 版型沿用 local-tool，沒有價值 - 行銷 Landing Page — 不在雛形範圍 - Onboarding Wizard — 雲端版的 onboarding 等 Phase 1 再細化 - Mobile 響應式完整版 — 雛形只保證 Desktop，Tablet 可讀，Mobile 降級（詳見第 6 節） - 重新發明 Design Tokens — 完全沿用 local-tool 的 CSS 變數 --- ## 2. 子文件總覽 詳細內容在各子文件。以下是一句話摘要： ### [2.1 Design Tokens](design-tokens.md) **完整沿用 local-tool 的 shadcn CSS 變數系統**，包含 Reference / Semantic / Component 三層。色彩使用 `oklch()` 色彩空間、radius base `0.625rem`、Tailwind 4 `@theme inline`。Dark Mode 透過 `.dark` class 切換。**本專案不新增、不覆寫任何 Token。** ### [2.2 元件庫清單](components.md) **基礎 UI（Shadcn 風）22 個**：Button、Card、Dialog、AlertDialog、Tabs、Input、Select、Badge、Slider、Progress、Checkbox、Label、Separator、ScrollArea、Sonner（toast）、EmptyState… **業務元件（沿用）**：models/、devices/、inference/、camera/、dashboard/ **Layout**：Header、Sidebar、ConnectionStatus、HelpButton **新增（雲端版）**：UserMenu、PairingTokenCard、RemoteDeviceBadge、NetworkErrorBanner ### [2.3 頁面結構](pages.md) 逐頁規格：沿用頁面列出「版型沿用 + 雲端適配點」，新增頁面列出「版型、主要區塊、互動重點」。雲端新增 5 個頁面（`/login`、`/register`、`/account`、`/devices/pair`、`/clusters`）。 ### [2.4 Pairing 流程](flows/flow-pairing.md) **雲端版最關鍵的新增流程**。使用者在雲端 Web 登入 → 進 `/devices/pair` → 產生 Pairing Token（`vAc_` + 32 字元 hex，TTL **15 分鐘**，一次性使用；local agent 成功換取後獲得 90 天 Session Token 維持 tunnel，使用者感受不到後者）→ 複製 token → 到自己電腦的 local agent 貼上 → 顯示 local agent 已連上雲端 → 回 `/devices` 看到遠端裝置。 ### [2.5 離線 / 掉線處理](flows/flow-offline-handling.md) 雲端版特有：local agent 可能掉線、tunnel 可能斷。裝置列表、裝置詳情頁、Workspace 都要能「誠實顯示狀態」。建議新增一個全域的 `RemoteDeviceBadge`，在裝置列表 / 卡片 / Header 顯示「最後心跳 X 秒前」。 ### [2.6 登入 / 註冊流程](flows/flow-auth.md) Phase 0 雛形只需要 **stub 頁面**：Email + Password 輸入框、一個登入按鈕、一個「還沒有帳號？註冊」連結。後端尚未接，送出後直接跳 Dashboard 即可。實際 OAuth / 密碼驗證 Phase 1 再做。 ### [2.7 Design Review](design-review.md) 對既有 local-tool 版型做一次檢查。目前已知的改善點整理成 Critical / Major / Minor 三級，**雛形階段不改**，但寫進文件給 Phase 1+ 參考。 ### [2.8 轉檔流程](flows/flow-conversion.md) + [Wireframe](wireframes/wireframe-conversion.md) **Phase 0.8 新增的核心動線**。Sidebar 加「轉檔」tab（Wand2 icon），單頁 `/conversion` 用 state 機切 `idle / uploading / processing / completed.success / completed.failed` 五個畫面。上傳走 visionA backend streaming proxy（XHR + 進度條），轉檔以 polling（5–10 秒）追狀態，完成後**半自動**讓使用者選「加到模型庫」或「下載」（兩按鈕互不互斥）。失敗時顯示翻譯後的錯誤訊息（PRD §F5 對照表）+ suggestions。**前端不持久化 jobId**，由 backend `GET /jobs/active` 提供 source of truth，跨瀏覽器 / 多分頁 / 重新整理都能正確恢復。 --- ## 3. 技術對齊 | 項目 | 決策 | 備註 | |------|------|------| | UI 框架 | Next.js App Router 16 + React 19 | 沿用 local-tool | | 樣式 | Tailwind CSS 4 + shadcn/ui（Radix UI 封裝）| 沿用 | | 圖示 | Lucide React | 沿用 | | 狀態管理 | Zustand 5 | 沿用；新增 `auth-store`、`session-store` | | Toast | Sonner | 沿用 | | i18n | 自訂實作（`src/lib/i18n`），繁中 + English | 沿用 | | 圖表 | Recharts 3 | 沿用（Workspace 效能圖表） | | 引導 | driver.js | 沿用（Dashboard onboarding） | | 無障礙 | 以 shadcn/ui 內建 ARIA 為基礎，關鍵頁面補強 | 目標 WCAG 2.1 AA | | Dark Mode | 跟隨系統主題（`theme-sync.tsx`）| 沿用 | --- ## 4. 設計與開發的職責切分 為避免設計與實作脫節，明確職責： | 誰做 | 什麼 | |------|------| | **Design Agent（本文件）** | Design Tokens 規格 / 元件清單 / 頁面結構 / 互動規格 / UX Writing 文案規範 / Design Review | | **Architect Agent** | API 契約 / Session 設計 / 狀態同步策略 / Token 生命週期 | | **Frontend Agent** | 依本文件實作 React 元件 / 接 API / 實作 WebSocket 重連邏輯 | | **PM Agent** | User Story / 成功指標 / Persona | **設計規格有衝突時的排序：** 使用者口述需求 > PRD > 本設計規格 > local-tool 現況 > 個人偏好。 --- ## 5. 與 PM / Architect 的協作提醒 ### 5.1 給 PM 的提醒 - Phase 0 雛形**不做完整 Onboarding**。Dashboard 的 `OnboardingDialog` 在雲端版情境不合適（local-tool 的版本假設使用者「插 USB Dongle 掃描」，雲端版第一步是 Pairing），建議 Phase 1 重寫。 - `/settings` 頁的「Advanced」分頁目前有 ServerStatusDashboard 與 ServerLogViewer，**雲端版應該移除或重新定位**（使用者看不到「他電腦上的 local agent log」，除非有專門的 remote log 設計）— 建議 Phase 1 再處理。 - 未來如果有 Billing，`/account` 會擴展成 `/account/*`（profile / billing / api-keys / sessions）。Phase 0 只做單頁 stub。 ### 5.2 給 Architect 的提醒 - **裝置狀態同步**：雲端版裝置狀態依賴 local agent 的 heartbeat / WebSocket，前端必須能顯示「上次心跳 X 秒前」。建議 API 直接回傳 `lastSeenAt` 欄位（ISO 8601）。 - **Pairing Token 顯示格式**：設計上用「8+8 分隔顯示」（`a1b2c3d4 e5f6g7h8`）方便肉眼辨識複製；API 回傳請保持原始無空白字串，由前端格式化顯示。 - **WebSocket 重連策略**：前端會用指數退避，但需要 Architect 確認後端能否容忍短暫重連抖動。 - **錯誤分類**：前端需要區分「雲端 API 不可達」（整個服務掛）vs「local agent 掉線」（單裝置不可用）。API 錯誤回應的 `error.code` 請明確分類，讓 UI 可以給不同提示。 --- ## 6. 響應式策略（整體總綱，詳見 pages.md） | 斷點 | 寬度 | 雛形策略 | |------|------|---------| | Mobile | < 640px | **降級顯示**：能讀但不建議操作，顯示提示「建議使用桌面版」於關鍵頁面（如 Pairing、Workspace） | | Tablet | 640 – 1024px | **可用**：Sidebar 折疊為 drawer，主內容區單欄 | | Desktop | 1024 – 1440px | **主要目標**：Sidebar 展開（w-60），主內容區自適應 | | Wide | > 1440px | 最大寬度限制 max-w-7xl（1280px）內容置中 | **核心決策**：**Desktop First**。使用者是開發者，主要用桌機。Mobile 僅確保能登入、看 Dashboard 資訊、讀通知；不要求能操作推論。 --- ## 7. 國際化策略（沿用 local-tool） - **支援語言**：繁體中文（`zh-TW`）、English（`en`） - **預設語言**：跟隨系統 locale，無法辨識則 `en` - **切換位置**：`/settings` → 一般 → 語言；使用者選擇會存 `localStorage` - **文案位置**：`src/lib/i18n/zh-TW.ts`、`src/lib/i18n/en.ts` - **新增雲端版的文案 key**： ``` auth.login.* 登入頁 auth.register.* 註冊頁 auth.error.* 認證錯誤訊息 account.* 帳號設定頁 pairing.* Pairing 頁與流程 cluster.* 叢集（已在 POC 存在，整併） remote.* 遠端裝置相關（掉線、心跳、最後連線） nav.cloudAppName visionA Cloud（取代 visionA Local） ``` - **UX Writing 原則**：參考 `components.md` 第 8 節。 --- ## 8. 無障礙基準（WCAG 2.1 AA） ### 8.1 色彩對比 - 一般文字對背景 ≥ 4.5:1 - 大文字（18pt+/14pt Bold+）≥ 3:1 - Icon / UI 元件 ≥ 3:1 - 不只靠顏色傳達資訊（裝置狀態徽章同時有「圓點 + 文字」） ### 8.2 鍵盤操作 - 所有互動元素可 Tab 聚焦 - Focus ring 可見（shadcn 預設 `ring-[3px]` 已達標） - Modal 聚焦陷阱（Dialog 自動處理） - Escape 關閉 Modal（Dialog 自動處理） - Skip link（全新頁面需要加） ### 8.3 ARIA 與語意 - 使用語意化 HTML（`