# KNEO Academy（Innovedus AI Playground）設計規格文件

> **文件性質說明**：本設計規格從既有程式碼反向整理，涵蓋 `src/config.py`、各 View 檔案及 `uxui/` 目錄下的 UI 資源。標注「⚠️ 待確認」的項目為推斷內容或程式碼中資訊不足的部分。

---

## ① Design Tokens

> 以下 Token 直接從 `src/config.py` 及各 View 的 `setStyleSheet()` 提取。

### 1.1 色彩系統（Color Tokens）

#### Reference Tokens（原始值）

| Token 名稱 | 色碼 | 說明 |
|-----------|------|------|
| color.navy.900 | `#143058` | 深海軍藍（MainWindow 背景） |
| color.blue.600 | `#005ED7` | 亮藍（SecondaryColor，Popup / 元件背景） |
| color.blue.500 | `#3498DB` | 標準藍（UtilitiesScreen 按鈕、表格 Header） |
| color.blue.400 | `#2980B9` | 藍 Hover 色 |
| color.blue.300 | `#1F618D` | 藍 Pressed 色 |
| color.slate.800 | `#2C3E50` | 深石板藍（LoginScreen/UtilitiesScreen Header 背景） |
| color.slate.700 | `#34495E` | 石板藍（SelectionScreen Header、按鈕文字） |
| color.gray.100 | `#F8F9FA` | 極淺灰（進度區塊背景） |
| color.gray.50 | `#F5F7FA` | 淺灰（LoginScreen / UtilitiesScreen 頁面背景） |
| color.gray.200 | `#E0E0E0` | 邊框灰（卡片、輸入框邊框） |
| color.gray.400 | `#BDC3C7` | 中灰（非選中導航按鈕文字） |
| color.gray.500 | `#95A5A6` | 灰（Footer 文字、Back 按鈕） |
| color.gray.600 | `#7F8C8D` | 深灰（描述文字、次要標籤） |
| color.green.500 | `#2ECC71` | 標準綠（Download 按鈕） |
| color.green.600 | `#27AE60` | 綠 Hover |
| color.green.700 | `#1E8449` | 綠 Pressed |
| color.green.400 | `#4CAF50` | 成功狀態綠（Custom Model 上傳成功） |
| color.orange.500 | `#F39C12` | 橘（Firmware Update 按鈕） |
| color.orange.600 | `#D35400` | 橘 Hover |
| color.orange.700 | `#A04000` | 橘 Pressed |
| color.purple.500 | `#9B59B6` | 紫（Install Driver 按鈕） |
| color.purple.600 | `#8E44AD` | 紫 Hover |
| color.purple.700 | `#7D3C98` | 紫 Pressed |
| color.red.500 | `#E74C3C` | 紅（錯誤訊息文字） |
| color.red.400 | `#ff6b6b` | 亮紅（Stop 按鈕文字及邊框） |
| color.white | `#FFFFFF` | 純白 |
| color.black | `#000000` | 純黑（Canvas 背景） |
| color.selection | `#F8F9FA` | 選取頁面背景 |

#### Semantic Tokens（語義映射）

| Semantic Token | Reference Token | 說明 |
|---------------|----------------|------|
| color.bg.primary | color.navy.900（`#143058`） | MainWindow 頁面背景 |
| color.bg.light | color.gray.50（`#F5F7FA`） | Login / Utilities 頁面背景 |
| color.bg.selection | color.selection（`#F8F9FA`） | SelectionScreen 頁面背景 |
| color.bg.card | color.white | 卡片、表單容器背景 |
| color.bg.header.dark | color.slate.800（`#2C3E50`） | Login / Utilities Header 背景 |
| color.bg.header.alt | color.slate.700（`#34495E`） | SelectionScreen Header 背景 |
| color.bg.component | color.blue.600（`#005ED7`） | 側邊欄元件背景（Device Panel、Custom Model Block、Media Panel、Popup） |
| color.bg.canvas | color.black | Camera / 推論顯示區域背景 |
| color.bg.mask | `rgba(0, 0, 0, 0.7)` | Device Popup 蒙版 |
| color.border.default | color.gray.200（`#E0E0E0`） | 卡片、輸入框、表格邊框 |
| color.text.primary | color.slate.700（`#34495E`） | 主要文字（深色背景上） |
| color.text.secondary | color.gray.600（`#7F8C8D`） | 次要說明文字 |
| color.text.on-dark | color.white | 深色背景上的文字 |
| color.text.placeholder | color.gray.500（`#95A5A6`） | 輸入框 Placeholder |
| color.text.error | color.red.500（`#E74C3C`） | 錯誤訊息 |
| color.text.success | color.green.400（`#4CAF50`） | 成功狀態訊息 |
| color.text.footer | color.gray.500（`#95A5A6`） | Footer 版權文字 |
| color.action.primary | color.blue.500（`#3498DB`） | 主要 CTA 按鈕（Login、Refresh、Utilities Tab） |
| color.action.primary.hover | color.blue.400（`#2980B9`） | |
| color.action.primary.pressed | color.blue.300（`#1F618D`） | |
| color.action.success | color.green.500（`#2ECC71`） | 下載、Register 按鈕 |
| color.action.warning | color.orange.500（`#F39C12`） | Firmware Update 按鈕 |
| color.action.danger | color.red.400（`#ff6b6b`） | Stop 按鈕 |
| color.action.neutral | color.gray.500（`#95A5A6`） | Back 按鈕（中性） |
| color.action.special | color.purple.500（`#9B59B6`） | Install Driver 按鈕 |
| color.input.focus-border | color.blue.500（`#3498DB`） | 輸入框 Focus 狀態邊框 |
| color.table.header | color.blue.500（`#3498DB`） | 表格 Header 背景 |
| color.table.selected | color.blue.500（`#3498DB`） | 表格選中列背景 |

---

### 1.2 尺寸系統（Size Tokens）

#### 視窗尺寸

| Token | 數值 | 說明 |
|-------|------|------|
| window.width | 1200px | 固定視窗寬度（`WINDOW_SIZE`） |
| window.height | 900px | 固定視窗高度（`WINDOW_SIZE`） |
| popup.ratio | 0.67 | Device Popup 相對視窗的寬高比（`POPUP_SIZE_RATIO`） |
| popup.width | ~804px | 計算值（1200 × 0.67） |
| popup.height | ~603px | 計算值（900 × 0.67） |

#### 佈局尺寸

| Token | 數值 | 說明 |
|-------|------|------|
| layout.left-panel.width | 260px | MainWindow 左側面板固定寬度 |
| layout.canvas.width | 900px | Camera Canvas 固定寬度 |
| layout.canvas.height | 750px | Camera Canvas 固定高度 |
| layout.canvas.inner.width | 880px | Canvas Label 最小寬度 |
| layout.canvas.inner.height | 730px | Canvas Label 最小高度 |
| layout.header.height | 60px | UtilitiesScreen Header 固定高度 |
| layout.header.height.alt | 100px | LoginScreen / SelectionScreen Header 固定高度 |

#### 元件尺寸

| Token | 數值 | 說明 |
|-------|------|------|
| component.device-panel.width | 240px | Device Panel 固定寬度 |
| component.device-panel.height | 200px | Device Panel 固定高度 |
| component.custom-model.width | 240px | Custom Model Block 固定寬度 |
| component.custom-model.height | 270px | Custom Model Block 固定高度 |
| component.media-panel.width | 90px | Media Panel 固定寬度 |
| component.media-panel.height | 290px | Media Panel 固定高度 |
| component.selection-card.min-width | 300px | SelectionScreen 選項卡片最小寬度 |
| component.selection-card.min-height | 250px | SelectionScreen 選項卡片最小高度 |

#### 按鈕尺寸

| Token | 數值 | 說明 |
|-------|------|------|
| button.standard.min-height | 40px | 標準操作按鈕最小高度（UtilitiesScreen） |
| button.login.min-height | 45px | 登入頁按鈕最小高度 |
| button.icon.size | 50×50px | Media Panel 圖示按鈕尺寸 |
| button.icon.inner | 40×40px | Media Panel SVG 圖示尺寸 |
| button.popup.size | 150×45px | Popup 中 Refresh / Done 按鈕尺寸 |
| button.detail.size | 72×30px | Device Panel 中 Details 按鈕尺寸 |
| button.back.size | 40×40px | Header Back 按鈕尺寸 |
| button.file-upload.size | 28×22px | Custom Model 上傳按鈕（"..."）尺寸 |
| button.custom-model-action.height | 32px | Custom Model Stop / Run 按鈕高度 |

#### 圖示尺寸

| Token | 數值 | 說明 |
|-------|------|------|
| icon.header.window | 35×35px | Popup 視窗 title 圖示 |
| icon.nav | 20×20px | Device Panel title 圖示 |
| icon.title.custom-model | 28×28px | Custom Model Block title 圖示 |
| icon.card.selection | 64×64px | SelectionScreen 卡片圖示 |
| icon.dongle.popup | 30×30px | Device Popup 中裝置圖示 |
| icon.dongle.list | 30×30px | Device List 中裝置圖示容器 |
| icon.logo.main | 104×40px | MainWindow / UtilitiesScreen 縮小 Logo |
| icon.logo.selection | 150×60px | SelectionScreen / LoginScreen 大型 Logo |
| icon.combo-arrow | 12×12px | QComboBox 下拉箭頭圖示 |

---

### 1.3 間距系統（Spacing Tokens）

| Token | 數值 | 使用場景 |
|-------|------|---------|
| spacing.xs | 2px | FileUploadRow 上下 margin |
| spacing.sm | 5px | List item padding、button spacing（小） |
| spacing.md | 10px | 容器內部間距、部分 Padding |
| spacing.lg | 15px | 區塊內部間距（Device Panel、Custom Model Block） |
| spacing.xl | 20px | 頁面主要 Margin（Popup、MainWindow canvas） |
| spacing.xxl | 30px | 表單容器 Padding（Login、SelectionScreen） |
| spacing.form | 40px | SelectionScreen 主要 Margin |
| spacing.card | 40px | SelectionScreen 兩張卡片之間的間距 |
| spacing.nav | 10px | Header 導航按鈕之間的間距 |

---

### 1.4 圓角系統（Border Radius Tokens）

| Token | 數值 | 使用場景 |
|-------|------|---------|
| radius.sm | 3px | 檔案上傳標籤、小型 UI 元素 |
| radius.md | 5px | 按鈕（UtilitiesScreen）、輸入框、表格 |
| radius.lg | 8px | 卡片區塊（Device Section、Purchased Items、Status Section） |
| radius.xl | 10px | 主要卡片容器（SelectionScreen、LoginScreen form） |
| radius.xxl | 15px | 選項卡片（SelectionScreen）、側邊欄元件（Device Panel、Custom Model Block） |
| radius.pill | 20px | Popup、Media Panel（大圓角） |

---

### 1.5 字型系統（Typography Tokens）

> **注意**：程式碼中未定義全域字型 family，使用 PyQt5 系統預設字型（Windows 環境下通常為 Segoe UI）。以下為從程式碼提取的字型大小與字重規格。

| Token | 數值 | 使用場景 |
|-------|------|---------|
| font.size.xs | 10px | 檔案名稱標籤（FileUploadRow）、ComboBox 箭頭 |
| font.size.sm | 11px | Custom Model 小型標籤、狀態訊息、Run 按鈕文字 |
| font.size.body | 12px | Footer 文字、Device Popup 狀態標籤 |
| font.size.md | 14px | 表單標籤、描述文字、按鈕文字（UtilitiesScreen）、輸入框、KN 號碼標籤 |
| font.size.lg | 16px | 選項卡片描述、Device 標題標籤、Device Label（Popup 中）、Custom Model title |
| font.size.xl | 18px | 區塊標題（Device Connection、Device Status、Purchased Items） |
| font.size.xxl | 20px | Device Panel 標題 |
| font.size.xxxl | 22px | 選項卡片標題 |
| font.size.display | 24px | Canvas 載入文字、UtilitiesScreen Header title |
| font.size.h2 | 28px | LoginScreen title、SelectionScreen APP title |
| font.size.h1 | 32px | Device Popup title |
| font.weight.normal | normal | 一般文字 |
| font.weight.bold | bold | 標題、按鈕文字、重要標籤 |

---

### 1.6 按鈕狀態樣式（Button State Tokens）

#### 全域按鈕樣式（`BUTTON_STYLE` — 深色背景通用）

```
背景：透明（transparent）
文字顏色：白色
邊框：2px solid white
圓角：15px
Padding：5px 10px

Hover：background-color: rgba(255, 255, 255, 50)（約 20% 白色透明）
Pressed：background-color: rgba(255, 255, 255, 100)（約 39% 白色透明）
```

#### 主要 CTA 按鈕（藍色，淺色背景場景）

```
背景：#3498DB
文字：白色
邊框：none（或 2px solid #2980B9）
圓角：5px
MinHeight：40-45px
Padding：10px 15px

Hover：#2980B9
Pressed：#1F618D
Disabled：#3498DB（同 Default，視覺不變）⚠️
```

#### 成功/下載按鈕（綠色）

```
背景：#2ECC71
文字：白色
邊框：2px solid #27AE60
圓角：5px

Hover：#27AE60
Pressed：#1E8449
```

#### 警告按鈕（橘色 Firmware Update）

```
背景：#F39C12
文字：白色
邊框：2px solid #D35400
圓角：5px

Hover：#D35400
Pressed：#A04000
```

#### 特殊功能按鈕（紫色 Install Driver）

```
背景：#9B59B6
文字：白色
邊框：2px solid #8E44AD
圓角：5px

Hover：#8E44AD
Pressed：#7D3C98
```

#### 中性返回按鈕（灰色）

```
背景：#95A5A6
文字：白色
圓角：5px

Hover：#7F8C8D
Pressed：#616A6B
```

#### Custom Model — Run 按鈕（綠色半透明）

```
背景：rgba(76, 175, 80, 0.3)
文字：白色
邊框：1px solid #4CAF50
圓角：8px
高度：32px

Hover：rgba(76, 175, 80, 0.5)
Disabled：rgba(128, 128, 128, 0.2)，文字 #666，邊框 #666
```

#### Custom Model — Stop 按鈕（紅色透明）

```
背景：透明
文字：#ff6b6b
邊框：1px solid #ff6b6b
圓角：8px
高度：32px

Hover：rgba(255, 107, 107, 0.2)
```

#### Media Panel 圖示按鈕

```
背景：透明
邊框：1px transparent
圓角：10px
尺寸：50×50px

Hover：rgba(255, 255, 255, 50)
Pressed：rgba(255, 255, 255, 100)
```

#### Header Back 按鈕（圖示透明按鈕）

```
背景：透明
邊框：none
尺寸：40×40px

Hover：rgba(255, 255, 255, 0.1)，圓角 20px
```

---

## ② UI 資源清單

> 路徑：`uxui/`

### 2.1 PNG 圖片（`Assets_png/`）

| 檔名 | 推斷用途 | 使用位置 |
|------|---------|---------|
| `kneron_logo.png` | Kneron / Innovedus 品牌 Logo | MainWindow 歡迎畫面、所有頁面 Header、MainWindow 左側面板 |
| `ic_dongle_520.png` | KL520 Dongle 裝置圖示 | Device Popup、Device List（裝置列表項） |
| `ic_dongle_720.png` | KL720 Dongle 裝置圖示 | Device Popup、Device List（裝置列表項） |

> **⚠️ 待確認**：程式碼中 `create_header()` 呼叫 `Assets_png/back_arrow.png` 作為 Back 按鈕圖示，但此檔案**不在 `Assets_png/` 目錄中**。此按鈕目前可能顯示為空白或破圖。

---

### 2.2 SVG 圖示（`Assets_svg/`）

#### 功能按鈕圖示（`bt_function_*`）

| 檔名 | 狀態 | 推斷用途 |
|------|------|---------|
| `bt_function_camera_disabled.svg` | disabled | 相機功能按鈕（停用） |
| `bt_function_mic_disabled.svg` | disabled | 麥克風功能按鈕（停用） |
| `bt_function_mic_hover.svg` | hover | 麥克風功能按鈕 |
| `bt_function_mic_normal.svg` | normal | 麥克風功能按鈕 |
| `bt_function_mic_pressed.svg` | pressed | 麥克風功能按鈕 |
| `bt_function_recording_hover.svg` | hover | 錄製功能按鈕 |
| `bt_function_recording_normal.svg` | normal | 錄製功能按鈕 |
| `bt_function_recording_pressed.svg` | pressed | 錄製功能按鈕 |
| `bt_function_screencapture_disabled.svg` | disabled | 螢幕截圖按鈕（停用） |
| `bt_function_screencapture_hover.svg` | hover | 螢幕截圖按鈕 |
| `bt_function_screencapture_normal.svg` | normal | 螢幕截圖按鈕（Media Panel 第一個按鈕） |
| `bt_function_screencapture_pressed.svg` | pressed | 螢幕截圖按鈕 |
| `bt_function_upload_disabled.svg` | disabled | 上傳檔案按鈕（停用） |
| `bt_function_upload_hover.svg` | hover | 上傳檔案按鈕 |
| `bt_function_upload_normal.svg` | normal | 上傳檔案按鈕（Media Panel 第二個按鈕） |
| `bt_function_upload_pressed.svg` | pressed | 上傳檔案按鈕 |
| `bt_function_video_hover.svg` | hover | 影片/恢復播放按鈕（暫停→恢復時切換） |
| `bt_function_video_normal.svg` | normal | 影片按鈕 |
| `bt_function_video_pressed.svg` | pressed | 影片按鈕 |

> **⚠️ 待確認**：目前 Media Panel「暫停/恢復」按鈕使用 `btn_result_image_delete_hover.svg` 作為暫停狀態圖示，切換後顯示 `bt_function_video_hover.svg`。此對應關係看起來不是最終設計，圖示使用可能有誤。

#### 對話框按鈕（`btn_dialog_*`）

| 檔名 | 狀態 | 推斷用途 |
|------|------|---------|
| `btn_dialog_customization_delete_hover.svg` | hover | 自定義對話框刪除按鈕 |
| `btn_dialog_customization_delete_normal.svg` | normal | 自定義對話框刪除按鈕 |
| `btn_dialog_customization_delete_pressed.svg` | pressed | 自定義對話框刪除按鈕 |
| `btn_dialog_customization_upload_hover.svg` | hover | 自定義對話框上傳按鈕 |
| `btn_dialog_customization_upload_normal.svg` | normal | 自定義對話框上傳按鈕 |
| `btn_dialog_customization_upload_pressed.svg` | pressed | 自定義對話框上傳按鈕 |
| `btn_dialog_device_disconnect_hover.svg` | hover | 裝置斷線按鈕 |
| `btn_dialog_device_disconnect_normal.svg` | normal | 裝置斷線按鈕 |
| `btn_dialog_device_disconnect_pressed.svg` | pressed | 裝置斷線按鈕 |

> **⚠️ 待確認**：`btn_dialog_*` 系列圖示在目前的程式碼中**找不到對應的呼叫位置**（自定義對話框的刪除/上傳、裝置斷線按鈕），可能屬於尚未實作的功能 UI，或被移除但資源保留。

#### 結果區域按鈕（`btn_result_*`）

| 檔名 | 狀態 | 推斷用途 |
|------|------|---------|
| `btn_result_edit_hover.svg` | hover | 推論結果編輯按鈕 |
| `btn_result_edit_normal.svg` | normal | 推論結果編輯按鈕 |
| `btn_result_edit_pressed.svg` | pressed | 推論結果編輯按鈕 |
| `btn_result_image_delete_hover.svg` | hover | 推論結果圖片刪除按鈕（目前被借用為暫停圖示） |
| `btn_result_image_delete_normal.svg` | normal | 推論結果圖片刪除按鈕 |
| `btn_result_image_delete_pressed.svg` | pressed | 推論結果圖片刪除按鈕 |

> **⚠️ 待確認**：`btn_result_*` 在程式碼中僅 `btn_result_image_delete_hover.svg` 被使用（且用途有疑問），其他均未見使用。

#### 設定與下載（單一圖示）

| 檔名 | 推斷用途 | 使用位置 |
|------|---------|---------|
| `btn_setting.svg` | 設定按鈕 | ⚠️ 程式碼中未見呼叫 |
| `ic_result_download_diabled.svg` | 結果下載（停用） | ⚠️ 程式碼中未見呼叫 |
| `ic_result_download_hover.svg` | 結果下載 Hover | ⚠️ 程式碼中未見呼叫 |
| `ic_result_download_normal.svg` | 結果下載 Normal | ⚠️ 程式碼中未見呼叫 |
| `ic_result_download_pressed.svg` | 結果下載 Pressed | ⚠️ 程式碼中未見呼叫 |
| `ic_result_folder_hover.svg` | 結果資料夾 Hover | ⚠️ 程式碼中未見呼叫（除被借用為 ComboBox 下拉箭頭） |
| `ic_result_folder_normal.svg` | 結果資料夾 Normal | 被用作 LoginScreen QComboBox 下拉箭頭 |
| `ic_result_folder_pressed.svg` | 結果資料夾 Pressed | ⚠️ 程式碼中未見呼叫 |

#### 通用圖示（`ic_*`）

| 檔名 | 推斷用途 | 使用位置 |
|------|---------|---------|
| `ic_customization_upload_folder.svg` | 自定義模型上傳資料夾圖示 | ⚠️ 程式碼中未見呼叫 |
| `ic_dialog_customization.svg` | 自定義對話框圖示 | ⚠️ 程式碼中未見呼叫 |
| `ic_dialog_device.svg` | 裝置對話框圖示 | SelectionScreen Utilities 卡片圖示 |
| `ic_dialog_missing_camera.svg` | 找不到攝影機圖示 | ⚠️ 程式碼中未見呼叫（應用於相機找不到的提示） |
| `ic_dongle_520.svg` | KL520 Dongle 圖示（SVG 版） | ⚠️ 程式碼中未見呼叫（PNG 版本被使用） |
| `ic_recording_camera.svg` | 攝影機/錄影圖示 | SelectionScreen Demo App 卡片圖示；Media Panel 第五個按鈕（錄影） |
| `ic_recording_voice.svg` | 錄音圖示 | Media Panel 第四個按鈕（錄音） |
| `ic_window_customization.svg` | 自定義視窗圖示 | ⚠️ 程式碼中未見呼叫 |
| `ic_window_device.svg` | 裝置視窗圖示 | Device Popup 標題列；Device Panel 標題列 |
| `ic_window_toolbox.svg` | 工具箱視窗圖示 | Custom Model Block 標題列 |

---

### 2.3 動態圖（`Assets_gif/`）

| 檔名 | 用途 | 使用位置 |
|------|------|---------|
| `no_device_temp.gif` | 無裝置狀態動態提示圖 | `MainWindow.show_no_device_gif()`（無裝置時在主視窗顯示） |

---

### 2.4 根目錄 SVG 資源

| 檔名 | 推斷用途 | 使用位置 |
|------|---------|---------|
| `canvas_background.svg` | 攝影機畫布背景 SVG | ⚠️ 程式碼中未見呼叫 |
| `usb_dongle.svg` | USB Dongle 圖示 | ⚠️ 程式碼中未見呼叫 |

---

## ③ 頁面元件清單

### 3.1 SelectionScreen（首頁選擇畫面）

**背景色**：`#F8F9FA`（淺灰白）
**佈局**：QVBoxLayout，Margin 40px 全周，Spacing 20px

| 元件 | Class/類型 | 尺寸/規格 | 樣式摘要 |
|------|-----------|---------|---------|
| 頁面背景 | QWidget | 1200×900px | `background: #F8F9FA` |
| Header Frame | QFrame | 全寬 × 100px 固定高 | `background: #34495E; border-radius: 10px` |
| Kneron Logo | QLabel + QPixmap | 縮放至 150×60px | 水平居中 |
| 內容容器 | QFrame | 彈性高（填充剩餘空間）| `background: white; border-radius: 10px; border: 1px solid #E0E0E0`，Padding 30px |
| APP 名稱標題 | QLabel | — | `font-size: 28px; font-weight: bold; color: #34495E`，水平居中 |
| 副標題 | QLabel | — | `font-size: 16px; color: #7F8C8D`，水平居中，文字：「請選擇您要使用的功能」 |
| 按鈕容器 | QWidget + QHBoxLayout | — | Margin 20px 左右，Spacing 40px |
| **Utilities 卡片** | QFrame | min 300×250px | `background: white; border-radius: 15px; border: 1px solid #E0E0E0`；Hover：`background: #F5F9FF; border: #5DADE2`；cursor: PointingHand |
| Utilities 卡片圖示 | QLabel + QPixmap | 64×64px | `ic_dialog_device.svg`，水平居中 |
| Utilities 卡片標題 | QLabel | — | `font-size: 22px; font-weight: bold; color: #34495E`，居中 |
| Utilities 卡片說明 | QLabel | — | `font-size: 14px; color: #7F8C8D`，居中，換行 |
| **Demo App 卡片** | QFrame | min 300×250px | `background: white; border-radius: 15px; border: 1px solid #E0E0E0`；Hover：`background: #F5FFF7; border: #7DCEA0`；cursor: PointingHand |
| Demo App 卡片圖示 | QLabel + QPixmap | 64×64px | `ic_recording_camera.svg`，水平居中 |
| Demo App 卡片標題 | QLabel | — | `font-size: 22px; font-weight: bold; color: #34495E`，居中 |
| Demo App 卡片說明 | QLabel | — | `font-size: 14px; color: #7F8C8D`，居中，換行 |
| Footer | QLabel | — | `font-size: 12px; color: #95A5A6`，居中，文字：「© 2025 Innovedus Inc. All rights reserved.」 |

---

### 3.2 LoginScreen（登入畫面）

**背景色**：`#F5F7FA`（淺灰）
**佈局**：QVBoxLayout，Margin 40px 全周，Spacing 20px

| 元件 | Class/類型 | 尺寸/規格 | 樣式摘要 |
|------|-----------|---------|---------|
| 頁面背景 | QWidget | 1200×900px | `background: #F5F7FA` |
| Header Frame | QFrame | 全寬 × 100px 固定高 | `background: #2C3E50; border-radius: 10px` |
| Kneron Logo | QLabel + QPixmap | 縮放至 150×60px | 水平居中 |
| 表單容器 | QFrame | 彈性高（填充剩餘空間）| `background: white; border-radius: 10px; border: 1px solid #E0E0E0`，Padding 30px |
| 登入標題 | QLabel | — | `font-size: 28px; font-weight: bold; color: #2C3E50; margin-bottom: 10px`，居中，文字："Login" |
| Server 驗證標籤 | QLabel | — | `font-size: 14px; font-weight: bold; color: #2C3E50`，文字："Server Authentication Type" |
| **驗證類型 ComboBox** | QComboBox | min-height 40px | `border: 1px solid #E0E0E0; border-radius: 5px; padding: 5px 10px; font-size: 14px; color: #2C3E50`；下拉箭頭使用 `ic_result_folder_normal.svg` 12×12px |
| 帳號標籤 | QLabel | — | `font-size: 14px; font-weight: bold; color: #2C3E50`，文字："Username" |
| **帳號輸入框** | QLineEdit | min-height 40px | `border: 1px solid #E0E0E0; border-radius: 5px; padding: 5px 10px; font-size: 14px; color: #2C3E50`；Focus：`border: 1px solid #3498DB`；Placeholder："Enter your username" |
| 密碼標籤 | QLabel | — | `font-size: 14px; font-weight: bold; color: #2C3E50`，文字："Password" |
| **密碼輸入框** | QLineEdit | min-height 40px | 同帳號輸入框；EchoMode: Password；Placeholder："Enter your password" |
| 錯誤訊息 | QLabel | — | `color: #E74C3C; font-size: 14px`；預設隱藏（`hide()`），驗證失敗時顯示 |
| Back 按鈕 | QPushButton | min-height 45px | `background: #95A5A6; color: white; border-radius: 5px; font-size: 14px; font-weight: bold`；Hover：`#7F8C8D`；Pressed：`#616A6B` |
| Login 按鈕 | QPushButton | min-height 45px | `background: #3498DB; color: white; border-radius: 5px; font-size: 14px; font-weight: bold`；Hover：`#2980B9`；Pressed：`#1F618D` |
| Footer | QLabel | — | `font-size: 12px; color: #95A5A6`，居中 |

---

### 3.3 UtilitiesScreen（裝置管理工具）

**背景色**：`#F5F7FA`（淺灰）
**佈局**：QVBoxLayout，Margin 20px 全周，Spacing 20px

#### 3.3.1 Header

| 元件 | 類型 | 尺寸/規格 | 樣式摘要 |
|------|------|---------|---------|
| Header Frame | QFrame | 全寬 × 60px 固定高 | `background: #2C3E50; border-radius: 0px` |
| Back 按鈕 | QPushButton | 40×40px | 圖示按鈕（`Assets_png/back_arrow.png`⚠️ 檔案缺失）；Hover：`rgba(255,255,255,0.1) border-radius 20px` |
| 頁面標題 | QLabel | — | `color: white; font-size: 24px; font-weight: bold`，文字："Utilities" |
| **Utilities 導航按鈕**（選中） | QPushButton | padding 5px 10px | `background: #3498DB; color: white; border: none; border-radius: 5px; font-weight: bold` |
| **Purchased Items 導航按鈕**（未選） | QPushButton | padding 5px 10px | `background: transparent; color: #BDC3C7; border: none; border-radius: 5px; font-weight: bold`；Hover：`color: white` |
| Kneron Logo | QLabel + QPixmap | 縮放至 104×40px | 靠右對齊 |

#### 3.3.2 Utilities 子頁面 — 裝置管理區塊

| 元件 | 類型 | 規格 | 樣式摘要 |
|------|------|------|---------|
| 區塊容器 | QFrame | — | `background: white; border-radius: 8px; border: 1px solid #E0E0E0`，Padding 15px |
| 區塊標題 | QLabel | — | `font-size: 18px; font-weight: bold; color: #2C3E50`，文字："Device Connection" |
| 區塊說明 | QLabel | — | `font-size: 14px; color: #7F8C8D`，文字："Connect and manage your Kneron devices" |
| **裝置資料表** | QTableWidget | min-height 可捲動 | 6 欄：Device Type / Port ID / Firmware Version / KN Number / Link Speed / Status；Header `background: #3498DB; color: white; font-weight: bold; padding: 8px`；Item padding 8px；Selected `background: #3498DB; color: white`；gridline `#E0E0E0` |
| Refresh Devices 按鈕 | QPushButton | min-height 40px | `background: #3498DB; border: 2px solid #2980B9; border-radius: 5px; font-size: 14px; font-weight: bold`；狀態色如前 |
| Register Device 按鈕 | QPushButton | min-height 40px | `background: #2ECC71; border: 2px solid #27AE60`；狀態色如前 |
| Update Firmware 按鈕 | QPushButton | min-height 40px | `background: #F39C12; border: 2px solid #D35400`；狀態色如前 |
| Install Driver 按鈕 | QPushButton | min-height 40px | `background: #9B59B6; border: 2px solid #8E44AD`；狀態色如前 |

#### 3.3.3 Utilities 子頁面 — 狀態區塊

| 元件 | 類型 | 規格 | 樣式摘要 |
|------|------|------|---------|
| 區塊容器 | QFrame | — | `background: white; border-radius: 8px; border: 1px solid #E0E0E0`，Padding 15px |
| 區塊標題 | QLabel | — | `font-size: 18px; font-weight: bold; color: #2C3E50`，文字："Device Status" |
| 狀態訊息 | QLabel | — | `font-size: 14px; color: #7F8C8D`，預設文字："No devices found" |
| 進度區塊（隱藏） | QFrame | — | `background: #F8F9FA; border-radius: 5px; border: 1px solid #E0E0E0; padding: 10px`；預設 `setVisible(False)` |
| 進度標題 | QLabel | — | `font-size: 14px; font-weight: bold; color: #2C3E50` |
| **進度條** | QProgressBar | height 20px | `border: 1px solid #E0E0E0; border-radius: 5px; background: white; text-align: center`；Chunk：`background: #3498DB; border-radius: 5px` |

#### 3.3.4 Purchased Items 子頁面

| 元件 | 類型 | 規格 | 樣式摘要 |
|------|------|------|---------|
| 區塊容器 | QFrame | — | `background: white; border-radius: 8px; border: 1px solid #E0E0E0`，Padding 15px |
| 區塊標題 | QLabel | — | `font-size: 18px; font-weight: bold; color: #2C3E50`，文字："Your Purchased Items" |
| 區塊說明 | QLabel | — | `font-size: 14px; color: #7F8C8D`，文字："Select items to download to your device" |
| **已購項目表格** | QTableWidget | min-height 300px | 5 欄：Select（Checkbox）/ Product / Model / Current Version / Compatible Dongles；樣式同裝置表格（藍色 Header，選中藍色） |
| Refresh Items 按鈕 | QPushButton | min-height 40px | `background: #3498DB; border: none; border-radius: 5px; font-size: 14px; font-weight: bold`；Hover：`#2980B9`；Pressed：`#1F618D` |
| Download Selected 按鈕 | QPushButton | min-height 40px | `background: #2ECC71; border: none; border-radius: 5px; font-size: 14px; font-weight: bold`；Hover：`#27AE60`；Pressed：`#1E8449` |

---

### 3.4 MainWindow（AI Demo 推論主視窗）

**背景色**：`#143058`（深海軍藍）
**佈局**：QVBoxLayout 外層，啟動時先顯示歡迎畫面（Logo），500ms 後切換至主頁面

#### 3.4.1 歡迎畫面（500ms 轉場）

| 元件 | 類型 | 規格 | 說明 |
|------|------|------|------|
| 歡迎 Logo | QLabel + QPixmap | 原始尺寸 | `kneron_logo.png`，水平居中 |

#### 3.4.2 主頁面佈局（QHBoxLayout）

左右兩欄佈局：
- **左欄**：固定寬度 260px，QVBoxLayout，Margin 10px，Spacing 10px
- **右欄**：彈性寬度（stretch factor 2），QGridLayout，Margin 0px

#### 3.4.3 左欄元件

| 元件 | 類型 | 規格 | 樣式摘要 |
|------|------|------|---------|
| Kneron Logo | QLabel + QPixmap | 縮放至 104×40px | — |
| **Device Panel** | QFrame | 240×200px 固定 | `background: #005ED7; border-radius: 15px; border: none` |
| — Device 圖示 | QSvgWidget | 20×20px | `ic_window_device.svg` |
| — Device 標題 | QLabel | — | `color: white; font-size: 20px; font-weight: bold` |
| — 裝置列表 | QListWidget | — | 透明背景；Item：padding 5px，Selected：`rgba(255,255,255,0.2)`；無 Scrollbar |
| — Details 按鈕 | QPushButton | 72×30px | 全域 `BUTTON_STYLE`（透明背景、白色邊框） |
| **Custom Model Block** | QFrame | 240×270px 固定 | `background: #005ED7; border-radius: 15px; border: none` |
| — 工具箱圖示 | QSvgWidget | 28×28px | `ic_window_toolbox.svg` |
| — Custom Model 標題 | QLabel | — | `color: white; font-size: 16px; font-weight: bold` |
| — 分隔線 | QFrame HLine | 1px 高 | `background: rgba(255,255,255,0.2)` |
| — Model 上傳列（.nef） | FileUploadRow | — | 標籤 50px 寬；檔案框 22px 高；上傳按鈕 28×22px |
| — SCPU 上傳列（.bin） | FileUploadRow | — | 同上 |
| — NCPU 上傳列（.bin） | FileUploadRow | — | 同上 |
| — Labels 上傳列（.txt） | FileUploadRow | — | 同上 |
| — 狀態標籤 | QLabel | — | `color: #4CAF50; font-size: 11px`；成功綠色，錯誤時 `#ff6b6b` |
| — Stop 按鈕 | QPushButton | 高 32px | 透明背景，紅色邊框文字（`#ff6b6b`） |
| — Run Inference 按鈕 | QPushButton | 高 32px | 半透明綠色（`rgba(76,175,80,0.3)`），綠色邊框 |

#### 3.4.4 右欄元件

| 元件 | 類型 | 規格 | 樣式摘要 |
|------|------|------|---------|
| **Canvas Area** | QFrame | 900×750px 固定 | `border: 1px solid gray; background: black; border-radius: 20px`，Padding 10px |
| Canvas Label（顯示區）| QLabel | 880×730px 最小 | 黑色背景，透明邊框；顯示攝影機 QImage 或靜態圖片 |
| **Media Panel**（浮動右下）| QFrame | 90×290px 固定 | `background: #005ED7; border-radius: 20px`；使用 `Qt.AlignBottom | Qt.AlignRight` 疊加在 Canvas 右下 |
| — 截圖按鈕 | QPushButton | 50×50px | 圖示 `bt_function_screencapture_normal.svg`，40×40px |
| — 上傳按鈕 | QPushButton | 50×50px | 圖示 `bt_function_upload_normal.svg`，40×40px |
| — 暫停/恢復按鈕 | QPushButton | 50×50px | 暫停時：`btn_result_image_delete_hover.svg`；恢復時：`bt_function_video_hover.svg` |
| — 錄音按鈕 | QPushButton | 50×50px | 圖示 `ic_recording_voice.svg`，40×40px |
| — 錄影按鈕 | QPushButton | 50×50px | 圖示 `ic_recording_camera.svg`，40×40px |

#### 3.4.5 Device Popup（蒙版彈出視窗）

| 元件 | 類型 | 規格 | 樣式摘要 |
|------|------|------|---------|
| 蒙版 Overlay | QWidget | 1200×900px（全視窗） | `background: rgba(0, 0, 0, 0.7)` |
| **Device Popup** | QWidget | 804×603px（視窗 × 0.67） | `background: #005ED7; border-radius: 20px; padding: 20px` |
| — 裝置圖示 | QSvgWidget | 35×35px | `ic_window_device.svg` |
| — 彈窗標題 | QLabel | — | `color: white; font-size: 32px; font-weight: bold`，文字："Device Connection" |
| — 裝置列表（Popup） | QListWidget | min-height 250px | `background: rgba(255,255,255,0.1); border-radius: 10px; color: white`；Item Selected：`rgba(52,152,219,0.5)` |
| — 裝置列表項 | 自訂 QWidget | 60px 固定高 | 圖示容器 30×30px（`#182D4B` 背景，border-radius 5px）+ 裝置名（16px bold）+ KN 號碼（14px）+ 狀態（12px 右對齊） |
| — Refresh 按鈕 | QPushButton | 150×45px | 全域 `BUTTON_STYLE` |
| — Done 按鈕 | QPushButton | 150×45px | 全域 `BUTTON_STYLE` |

---

## ④ 互動規格

### 4.1 頁面切換方式（Signal/Slot）

```
SelectionScreen.open_utilities  → 主程式切換到 LoginScreen
SelectionScreen.open_demo_app   → 主程式切換到 MainWindow

LoginScreen.login_success       → 主程式切換到 UtilitiesScreen
LoginScreen.back_to_selection   → 主程式切換到 SelectionScreen

UtilitiesScreen.back_to_selection → 主程式切換到 SelectionScreen
```

> **⚠️ 待確認**：頁面切換的具體實作（是否使用 QStackedWidget，還是直接 hide/show）需查看 `main.py` 或應用程式進入點。

### 4.2 MainWindow 啟動流程

```
1. 顯示歡迎畫面（Kneron Logo）
2. 500ms 後 → 清除歡迎畫面，建立主頁面
3. 100ms 後 → 呼叫 device_controller.refresh_devices()
4. 顯示 Device Popup（蒙版覆蓋主頁面）
5. 500ms 後 → 自動啟動攝影機（auto_start_camera）
```

### 4.3 按鈕 Enabled/Disabled 條件

| 按鈕 | 停用條件 | 啟用條件 |
|------|---------|---------|
| Media Panel 圖示按鈕（相機） | 相機功能不可用時（`bt_function_camera_disabled.svg` 存在暗示） | ⚠️ 未在程式碼中找到明確的 setEnabled 邏輯 |
| Custom Model — Run Inference | 無（任何時候都可點擊，但點擊後會驗證檔案） | 有效檔案選擇後 |
| Custom Model — Stop | 無推論進行時重置檔案選擇 | — |
| UtilitiesScreen 操作按鈕 | ⚠️ 未找到明確的停用條件（選取裝置後才應啟用的邏輯有待確認） | — |

### 4.4 對話框觸發條件

| 對話框 | 觸發條件 | 類型 |
|--------|---------|------|
| Device Popup | MainWindow 啟動時自動顯示 | 自訂 QWidget 蒙版 |
| Inference Result | 推論回傳非 Bounding Box 結果（分類等）時 | QMessageBox |
| Device 相容性警告 | 選擇不相容裝置的 AI 工具時 | QMessageBox（推斷） |
| 無裝置 GIF | 推斷：無裝置連接時 | QLabel + QMovie |
| Download Complete | 所有選中項目下載完成 | QMessageBox.information |
| No Selection 警告 | 點擊 Download 但未勾選任何項目 | QMessageBox.warning |
| 相機失敗提示 | 相機開啟失敗 | ⚠️ 程式碼中有 `ic_dialog_missing_camera.svg` 資源，但未見對應邏輯 |

### 4.5 UtilitiesScreen 頁面切換

| 觸發 | 行為 |
|------|------|
| 點擊「Utilities」導航按鈕 | `utilities_page.show()`；`purchased_items_page.hide()`；Utilities 按鈕樣式變為選中（`#3498DB`）；Purchased 按鈕變為未選中（透明） |
| 點擊「Purchased Items」導航按鈕 | `purchased_items_page.show()`；`utilities_page.hide()` |

> **⚠️ 待確認**：目前程式碼中未見導航按鈕選中/未選中狀態的動態切換邏輯（按鈕樣式可能沒有在切換時更新）。

### 4.6 Custom Model 檔案上傳互動

| 步驟 | 互動 | 視覺變化 |
|------|------|---------|
| 點擊「...」按鈕 | 開啟系統檔案選擇器 | — |
| 選擇檔案成功 | 顯示檔案名稱（超過 15 字截斷加「...」） | 標籤顏色從 `#aaa` 變為 `#4CAF50`；邊框 `#4CAF50`；背景 `rgba(76,175,80,0.1)` |
| 點擊 Run Inference（缺少必要檔案） | — | 狀態標籤文字更新為錯誤提示，顏色變為 `#ff6b6b` |
| 點擊 Run Inference（所有必要檔案已選） | 啟動推論 | 狀態標籤顯示 "Running: {model_name}"，顏色 `#4CAF50` |
| 點擊 Stop（有推論進行中） | 停止推論 | 狀態標籤顯示 "Stopped & Disconnected"，顏色 `#ff6b6b` |
| 點擊 Stop（無推論） | 重置所有檔案選擇 | 所有 FileUploadRow 回復到「未選擇」狀態 |

---

## ⑤ 缺失的設計規格

### 5.1 互動細節（程式碼中看不出）

| 項目 | 說明 |
|------|------|
| Bounding Box 繪製樣式 | 推論結果繪製在 Canvas 上的 Bounding Box 顏色、線條粗細、Label 字型樣式均無 Design Spec；從程式碼僅知座標格式 |
| 相機找不到時的 UI | 有 `ic_dialog_missing_camera.svg` 資源，但找不到對應的顯示邏輯 |
| 推論進行中的 Loading 狀態 | Canvas 載入文字為 "Starting camera..."，但推論進行中是否有 Loading indicator 不清楚 |
| UtilitiesScreen 導航按鈕切換動態 | 頁面切換時按鈕選中狀態的樣式切換邏輯不完整 |
| 相機暫停後的 Canvas 顯示 | 暫停時 Canvas 顯示最後一幀還是空白？未知 |
| MSE 幀差異偵測的視覺提示 | 技術機制存在，但使用者是否看到任何提示？未知 |
| 推論 Queue 滿時的提示 | Queue 最大 5 幀，滿時的行為是靜默丟棄，無視覺提示 |

### 5.2 未完整實作的 UI 功能

| 項目 | 說明 |
|------|------|
| Driver 安裝 UI | `Install Driver` 按鈕存在，但 `install_drivers()` 方法的實際 UI 流程未見完整實作 |
| Register Device UI | `Register Device` 按鈕存在，`register_device()` 方法實作未確認 |
| Dongle 授權管理 UI | PRD 中有完整描述，但 UtilitiesScreen 中未見對應 UI 元素 |
| Toolbox（原始工具箱）| `create_ai_toolbox()` 元件存在但在 MainWindow 中已被 `CustomModelBlock` 取代，Toolbox 功能未整合 |
| 購買模型下載（真實 API）| 目前為 Mock 資料，`populate_mock_purchased_items()` 方法，無真實下載邏輯 |
| 自定義對話框 UI | `btn_dialog_customization_*` 和 `ic_dialog_customization.svg` 資源存在，但無對應 UI 元件 |
| 裝置斷線按鈕 UI | `btn_dialog_device_disconnect_*` 資源存在，但無對應 UI 元件 |
| 結果下載/資料夾 UI | `ic_result_download_*`、`ic_result_folder_*`、`btn_result_edit_*` 資源存在，但程式碼中大多未呼叫 |
| 設定頁面 | `btn_setting.svg` 存在，但無對應的設定頁面 |

### 5.3 設計一致性問題（觀察到的設計債）

| 問題 | 說明 | 嚴重程度 |
|------|------|---------|
| 兩種截然不同的設計語言 | MainWindow 使用深海軍藍（`#143058`）為主的深色設計；SelectionScreen、LoginScreen、UtilitiesScreen 使用淺色（`#F5F7FA`）設計。同一個應用存在兩套視覺語言，缺乏統一感 | High |
| Back 按鈕圖示資源缺失 | UtilitiesScreen Header 使用的 `Assets_png/back_arrow.png` 不存在於 `uxui/Assets_png/` 目錄，按鈕為空白 | High |
| 暫停按鈕圖示錯誤 | Media Panel 暫停按鈕使用 `btn_result_image_delete_hover.svg`（刪除圖示）作為暫停狀態，語意不正確 | Medium |
| 未定義系統字型 | 無明確的 `font-family` 定義，依賴 Windows 系統預設字型，跨平台（若未來支援）可能不一致 | Low |
| Dark Mode 未規劃 | 完全無 Dark Mode 設計 | Low |
| Disabled 按鈕視覺未完整定義 | UtilitiesScreen 按鈕幾乎未定義 Disabled 狀態樣式 | Medium |
| Focus 狀態不完整 | 大多數按鈕無 Focus ring 設計（僅 LoginScreen QLineEdit 有 Focus 邊框） | Medium |

---

*本文件由 Design Agent 從既有程式碼反向整理，版本日期：2026-04-04*