# UI_DESIGN.md — 方寸仙門 介面框架 完整 spec

> **這是 UI / UX 的 single source of truth** — 視窗結構、面板布局、組件清單、視覺語言、互動規範、響應式策略、無障礙(a11y)、PixiJS canvas 整合、桌寵互動。
>
> 對應 milestone:M2 + M9 + M19 + M25 + M27 + M65(一鏡到底)+ M77(視覺迭代)。

---

## 📑 目錄

1. [UI 設計 12 條原則](#1-ui-設計-12-條原則)
2. [視窗系統(3 windows + 1 floating)](#2-視窗系統)
3. [主管理面板 布局(grid 12-column)](#3-主管理面板-布局)
4. [視覺語言(設計 tokens)](#4-視覺語言)
5. [組件庫(40+ 組件清單)](#5-組件庫)
6. [Modal / Drawer / Toast 系統](#6-modal--drawer--toast-系統)
7. [PixiJS canvas 整合(桌寵 + 山門 vista)](#7-pixijs-canvas-整合)
8. [桌寵 互動 規範](#8-桌寵-互動-規範)
9. [動畫 / Transition spec](#9-動畫--transition-spec)
10. [響應式 + 多分辨率(720p → 4K)](#10-響應式--多分辨率)
11. [無障礙 a11y(M77 補)](#11-無障礙-a11y)
12. [Localization(zh-TW / zh-CN / en)](#12-localization)
13. [UI 性能 budget](#13-ui-性能-budget)
14. [User flow map(主要 14 條 flow)](#14-user-flow-map)

---

## 1. UI 設計 12 條原則

| # | 原則 | 為什麼 | 違反 → |
|---|---|---|---|
| 1 | **永不重置感**:UI 不顯 「Reset / Wipe」按鈕 | 「永不重置」是核心哲學 | 玩家失去 信 任 |
| 2 | **數字 用 文字 + Big Number** | 1e30 → 「1 沙 河」 | 玩家 認 知 過 載 |
| 3 | **桌寵 永遠 在 前 景** | 桌寵 是 陪伴 主角 | 失 去 「陪 伴」 感 |
| 4 | **每 個 數字 都 可 hover 解 釋** | 修仙 idle 數字 過 多 | 玩家 看 不 懂 |
| 5 | **所有 重要 行 動 必 有 確認** | 防 誤 觸 (永 不 重 置 系 統) | 失 去 進 度 |
| 6 | **顏 色 不 是 唯 一 訊號** (a11y) | 色 盲 玩家 | failing a11y |
| 7 | **任 何 操 作 ≤ 2 次 點 擊 到 達** | UI 簡 潔 | 玩家 暈 眩 |
| 8 | **載入 ≤ 200ms 必 有 skeleton** | 玩家 感 知 流 暢 | 玩家 以 為 卡 |
| 9 | **錯 誤 訊 息 必 有 「下 一 步」 建 議** | 玩家 不 知 道 怎 麼 修 | 玩家 棄 遊 |
| 10 | **任 何 modal 必 有 ESC 關 閉** | 鍵 盤 玩家 | failing 鍵 盤 |
| 11 | **任 何 列 表 ≥ 50 項 必 虛 擬 化** | 性 能 budget | 卡 頓 |
| 12 | **任 何 動 畫 必 有 prefers-reduced-motion 開 關** | a11y | failing a11y |

---

## 2. 視窗系統

### 3 個 BrowserWindow + 1 floating

```
┌─────────────────────────────────────────┐
│ 1. 主視窗 (mainWindow)                  │
│    1920×1080 default,可 縮 放         │
│    管 理 介面 React + 14 系統頁         │
└─────────────────────────────────────────┘

┌──────────┐
│ 2. 桌寵   │  300×300,透 明 背 景
│  Window  │  always-on-top: true (主視窗 關閉時)
│  PixiJS  │  click-through: 透 過 / 不 透 過 切 換
└──────────┘

┌──────────┐
│ 3. 通知   │  400×200,右下 角
│  Window  │  彈 出 5s 後 fade 消
│  (toast) │  桌寵 重要 事件 (突破 / 飛升)
└──────────┘

┌──────────┐
│ 4. (M65)  │  全 屏 一 鏡 到 底 開 場
│  Cinema  │  16:9 強 制
│  (PixiJS)│  60 fps 6 min 過 場
└──────────┘
```

### 視窗切換規則

| 場景 | 桌寵 視窗 | 主視窗 | 通知 |
|---|---|---|---|
| 玩家 點 桌寵 → 開 管理 | hidden | show | - |
| 玩家 關 管理 | show + always-on-top | hidden | - |
| 突破 事件 | freeze | - | popup |
| M65 開場 | hidden | hidden | hidden + cinema show |
| 設定 → 隱 藏 桌寵 | hidden(永 久)| show | - |

---

## 3. 主管理面板 布局

### 12-column grid(響應式)

```
┌─────────────────────────────────────────────────────────────────────┐
│                     Header (60px)                                    │
│  [Logo] [境界] [靈氣 ×e30] [道學點 ×1e6] [心境 ★★★] [⚙ 設定]      │
├──────────────┬───────────────────────────────────────┬──────────────┤
│              │                                       │              │
│  左 側 欄     │           中 央 內 容 區              │  右 側 欄     │
│  (3 cols)    │           (6 cols)                    │  (3 cols)    │
│              │                                       │              │
│  ▌ 弟子 (8) │  ▌ 主面板:聚靈殿 (Lv.25)            │  ▌ 今 日 摘 要 │
│  ▌ 殿堂(21)│   - rate: 3.2e6 /s                   │  - 修為 +2.4e9│
│  ▌ 道學       │   - 編制: 3/7                       │  - 突破: 1   │
│  ▌ 任務       │   - 升級 cost: 1.5e7 靈氣          │              │
│  ▌ 自動化     │   - 協同: 大羅丹房 +20%            │  ▌ 託 夢      │
│  ▌ 福地       │  ──────────────────────────         │  - 紫氣東來   │
│  ▌ 天機       │  [升 級] [編 制] [自 動 化] [協 同] │              │
│              │                                       │  ▌ 通 知 (3) │
│              │                                       │  - 蒼雲 升 級 │
│              │                                       │  - 紫嵐 心 境 │
│              │                                       │  - 突 破 機 會│
│              │                                       │              │
│              │                                       │              │
├──────────────┴───────────────────────────────────────┴──────────────┤
│  Footer (40px)                                                       │
│  [Save Status: ✓ 5s 前] [FPS: 60] [Tick: 250ms]  [桌寵切換]         │
└─────────────────────────────────────────────────────────────────────┘
```

### Breakpoint(響應式)

| 寬度 | 布局 | 左欄 | 右欄 |
|---|---|---|---|
| ≥ 1920 | 12 col | 3 col 展開 | 3 col 展開 |
| 1280-1920 | 12 col | 3 col 摺 疊 標 籤 | 3 col 摺 疊 |
| 1024-1280 | 8 col | 2 col 圖 標 only | 抽 屜 |
| 720-1024 | 6 col | 漢 堡 選 單 | 抽 屜 |
| < 720 | 強 制 提 示 「請 放 大 視 窗」 | - | - |

### 主面板 標 籤 (14 頁)

```
1. 山門 概 覽 (default,匯 總 14 頁 摘 要)
2. 弟子 管 理
3. 殿堂 管 理
4. 道學 樹
5. 任務
6. 自動化 規則
7. 福地 探 索
8. 天機 子 系 統
9. 統計 / dashboard
10. 抽卡 / 招募
11. 配方 / 鍛造
12. 成就
13. 設定
14. 雲端 / 存檔
```

---

## 4. 視覺語言

### 色彩 tokens(M77 修仙風 dark theme)

```css
/* 主色 — 修仙四大色 */
--color-jade:    #5FE8C2;  /* 翡翠玉 — 主強調色,境界 / 突破 */
--color-gold:    #E8C972;  /* 鎏金 — 進度 / 收益 */
--color-plum:    #B85B6E;  /* 紫梅 — 道學 / 心境 */
--color-vermil:  #D14B3D;  /* 朱砂 — 警告 / 戰鬥 */

/* 背景 */
--bg-deep:       #0A0E1A;  /* 子夜 — 主背景 */
--bg-mid:        #141A2B;  /* 山影 — panel 背景 */
--bg-soft:       #1F2740;  /* 雲 — card 背景 */
--bg-glow:       #2B3654;  /* 光暈 — hover */

/* 文字 */
--text-primary:  #E8E6D5;  /* 月光 — 主文字 */
--text-secondary:#A8A797;  /* 銀霜 — 次文字 */
--text-muted:    #6A6960;  /* 灰雲 — 註釋 */
--text-disabled: #3A3935;  /* 暗灰 — 不可用 */

/* 狀態 */
--state-success: #5FE8A8;  /* 翠 — 成功 */
--state-warning: #E8C972;  /* 金 — 警告 */
--state-error:   #D14B3D;  /* 朱 — 錯誤 */
--state-info:    #5FBDE8;  /* 青 — 訊息 */

/* 修仙 特色 — 境界 漸層 */
--realm-mortal:    #6A6960;  /* 凡 — 灰 */
--realm-qi:        #5FBDE8;  /* 鍊氣 — 青 */
--realm-found:     #5FE8A8;  /* 築基 — 翠 */
--realm-core:      #E8C972;  /* 金丹 — 金 */
--realm-nascent:   #B85B6E;  /* 元嬰 — 紫 */
--realm-spirit:    #E89272;  /* 化神 — 橙 */
--realm-trib:      #D14B3D;  /* 渡劫 — 朱 */
--realm-immortal:  #FFF7DD;  /* 飛升 — 銀光 */
```

### 字體 stack

```css
--font-display: "AR PL UMing TW", "Noto Serif TC", serif;     /* 標題 — 楷書感 */
--font-body:    "Inter", "Noto Sans TC", sans-serif;          /* 主文字 */
--font-mono:    "JetBrains Mono", "Courier New", monospace;    /* 數字 */
--font-narr:    "Source Han Serif TC", "AR PL UMing TW", serif;/* 敘事 */
```

### 字體大小 + 字重

| token | size | weight | 用 途 |
|---|---|---|---|
| `--text-xs` | 10px | 400 | 註釋 |
| `--text-sm` | 12px | 400 | 次文字 |
| `--text-base` | 14px | 400 | 主文字 |
| `--text-md` | 16px | 500 | 重要 |
| `--text-lg` | 20px | 600 | 標題 |
| `--text-xl` | 28px | 700 | 大標題 |
| `--text-2xl` | 40px | 700 | 啟 動 標題 |
| `--text-3xl` | 64px | 700 | 開 場 標題 |

### 間距(spacing scale)

```
4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 px
```

### 圓角 + 陰影

```css
--radius-sm: 4px;   /* button */
--radius-md: 8px;   /* card */
--radius-lg: 16px;  /* modal */
--radius-pill: 999px;  /* tag */

--shadow-soft: 0 2px 8px rgba(0,0,0,0.3);
--shadow-glow: 0 0 16px rgba(95, 232, 194, 0.4);  /* jade glow */
--shadow-elev: 0 8px 24px rgba(0,0,0,0.5);
```

---

## 5. 組件庫(40+ 組件清單)

> 完整組件清單 + 各自的 spec。

### 5.1 基礎 (12 個)

| 組件 | 用 途 | Props |
|---|---|---|
| `<Button>` | 主按鈕 | variant: primary/secondary/ghost, size, loading |
| `<IconButton>` | 圖標按鈕 | icon, tooltip, size |
| `<Input>` | 輸入框 | type, placeholder, error |
| `<Select>` | 下拉選單 | options, value |
| `<Checkbox>` | 勾選框 | checked, label |
| `<Radio>` | 單選 | value, options |
| `<Slider>` | 滑桿(用於 數值 設定)| min, max, step |
| `<Switch>` | 開關 | checked, onChange |
| `<Badge>` | 標籤 | variant, count |
| `<Tag>` | tag | label, color |
| `<Progress>` | 進度條 | value, max, variant |
| `<Avatar>` | 弟子頭像 | src, rank, realm |

### 5.2 數字顯示 (6 個)

| 組件 | 用 途 |
|---|---|
| `<BigNumber>` | 大數字 (1e30 → 「1 沙 河」)|
| `<RateDisplay>` | 速率顯示 (/s, /h) |
| `<Currency>` | 貨幣顯示 (靈氣 / 道學點 / 靈晶) |
| `<RealmBadge>` | 境界徽章 |
| `<Affinity>` | 親和度條 (0-1) |
| `<Mood>` | 心境顯示 (★★★) |

### 5.3 弟子 / 殿堂 卡片 (6 個)

| 組件 | 用 途 |
|---|---|
| `<DiscipleCard>` | 弟子卡 (8 屬性 + 裝備 4 槽 + skill tree 連結) |
| `<DiscipleListItem>` | 弟子列表 簡版 |
| `<BuildingCard>` | 殿堂卡 (rate / upgrade / 編制) |
| `<BuildingTile>` | 殿堂縮圖 (山門 vista) |
| `<DaoNodeCard>` | 道學節點卡 |
| `<EquipmentSlot>` | 裝備槽 (4 槽 × 弟子) |

### 5.4 列表 / 表格 (4 個)

| 組件 | 用 途 |
|---|---|
| `<VirtualList>` | 虛擬列表(≥ 50 項)|
| `<Table>` | 資料表(統計 / dashboard) |
| `<Pagination>` | 分頁 |
| `<SortControls>` | 排序 |

### 5.5 模 態 / Layer (5 個)

| 組件 | 用 途 |
|---|---|
| `<Modal>` | 主模 態 |
| `<Drawer>` | 抽屜(右 / 下)|
| `<Toast>` | 提示彈窗 |
| `<Tooltip>` | hover 提示 |
| `<Popover>` | 點擊 彈出 |

### 5.6 敘事 / 對話 (4 個)

| 組件 | 用 途 |
|---|---|
| `<DialogBubble>` | 弟子對話氣泡 |
| `<NarrativePanel>` | 旁白 / 心境試煉 panel |
| `<ChoiceList>` | 抉擇 選項 列表 |
| `<LetterCard>` | 告別信 卡 |

### 5.7 圖表 / 視覺化 (3 個)

| 組件 | 用 途 |
|---|---|
| `<RealmGraph>` | 7 境界進度圖 |
| `<DaoTree>` | 道學樹 (230 節點 SVG) |
| `<TimelineChart>` | 統計 圖 (修為 / time)  |

### 5.8 自動化 / 規則 (3 個)

| 組件 | 用 途 |
|---|---|
| `<RuleBuilder>` | 自動化 規則 builder |
| `<ConditionPicker>` | 條件選擇器 |
| `<ActionPicker>` | 動作選擇器 |

---

## 6. Modal / Drawer / Toast 系統

### Modal 三種尺寸

```
sm:  400×300  (確認 / 簡單 表單)
md:  600×500  (弟子詳細 / 建築詳細)
lg:  900×700  (心境試煉 / 抽卡 / 道學樹)
xl:  全屏     (M65 開場 / 飛升 cinema)
```

### Modal 規範

- 必有 close button(右上 X)
- 必有 ESC 關閉
- 必有 backdrop click 關閉(可由 prop disable)
- 進入 animation:fade + scale (200ms)
- 退出 animation:fade (150ms)
- 多 modal 堆疊:後一個 z-index +10

### Drawer 規範

- 右側 抽屜(主):弟子 詳細 / 殿堂 詳細
- 下側 抽屜(次):自動化 規則 builder
- 寬度 / 高度:固定 400px / 60vh
- 進入:slide-in 250ms ease-out

### Toast 規範

- 位置:右下角
- 持續:5s(error 8s)
- 堆疊:最多 5 個,新的 在 下
- 類型:info / success / warning / error
- 必有 close 按鈕
- 重要事件(突破 / 飛升)→ 不 用 toast,用 通知視窗

---

## 7. PixiJS canvas 整合

### Canvas 用 處 3 場景

#### 1. 桌寵 視窗(`pet/`)

```
Canvas: 300×300 透明
60 fps
Pixi Application:
  - antialias: true
  - resolution: window.devicePixelRatio
  - autoDensity: true

物件:
  - 桌寵 sprite (idle / wave / pose)
  - 紫氣 particle (突破 時)
  - 點擊 ripple (玩家 點 桌寵)
  - 桌寵 待辦氣泡 (M79 idle profile)
```

#### 2. 山門 vista (主面板 「山門概覽」頁)

```
Canvas: 1200×600
30 fps (背景 不 需 60)
Pixi Application:
  - alpha 背景

物件:
  - 21 殿堂 縮圖 (各 BuildingTile sprite)
  - 連線 (synergyAdjacent 視覺化)
  - 弟子 sprite (在 各 殿堂 走 動)
  - 天 氣 layer (春雨 / 夏雷 / 秋葉 / 冬雪)
```

#### 3. M65 開場 cinema

```
Canvas: 1920×1080 全屏
60 fps
6 min 過 場 動畫:
  - 山霧 → 山門 顯 現
  - 「方寸仙門」 字 由 紫氣 凝 成
  - 第一弟子 走入
  - 心境試煉 1 觸 發
```

### React ↔ Pixi 通信

```typescript
// React 通過 ref 取 PixiApp
const pixiRef = useRef<PIXI.Application>()

// Zustand 訂 閱 → Pixi 動 畫
useSectStore.subscribe((state) => {
  const realm = state.realm
  pixiRef.current.stage.tint = REALM_TINT[realm]
})
```

### 性能 budget

- 桌寵 canvas:< 16ms / frame (60 fps)
- 山門 vista:< 33ms / frame (30 fps)
- 桌寵 待 機 → GPU < 5%
- 突破 動 畫 → GPU < 30%

---

## 8. 桌寵 互動 規範

### 滑鼠互動

| 行動 | 效果 |
|---|---|
| **左鍵 點擊 桌寵** | 觸 發 採集 (+1e3 靈氣) + 桌寵 wave 動 畫 |
| **左鍵 雙擊** | 開啟 主視窗 |
| **右鍵 點擊** | 右鍵 選單:主視窗 / 設定 / 暫停 / 離開 |
| **拖 拽 桌寵** | 移 動 桌寵 位 置 |
| **滾 輪** | 桌寵 sprite 切 換 (idle / pose / wave) |

### 桌寵 待 辦 氣泡 (M79 OVERTURN #1A)

```
條件觸發 → 桌寵 頭 上 出 現 「氣 泡」 圖 標
氣泡 內 容:
  - 「主上,弟子 蒼雲 即 將 突破」 (5s 後 fade)
  - 「百草園 草藥 已 滿」 (採集 提 醒)
  - 「天機 機 緣 出 現」 (rare event)
  - 「靈晶 自動 出 售 入 帳」 (合約)

點 擊 氣泡 → 開 啟 主視窗 + 跳 到 對 應 頁
```

### 桌寵 主動 say(M77 新增)

每 30 min 桌寵 隨 機 說 一 句(從 100 條 池 抽):
- 「主上,弟子 想 喝 茶。」
- 「主上,今 日 風 起,弟子 想 飛。」
- 「主上,弟子 想 您 了。」
- ... (詳 見 [GAME_CONTENT.md §13](GAME_CONTENT.md))

### 設定 → 桌寵 控制

```
- 桌寵 顯 隱:[切換]
- 桌寵 always-on-top:[切換]
- 桌寵 click-through:[切換]
- 桌寵 自動 say 頻率:[1/h / 30 min / 10 min / off]
- 桌寵 待辦 氣泡:[on / off]
```

---

## 9. 動畫 / Transition spec

### 5 種基礎 transition

| 名稱 | duration | easing | 用 處 |
|---|---|---|---|
| `fast` | 100ms | ease-out | hover / click feedback |
| `base` | 200ms | ease-in-out | modal open / close |
| `slow` | 350ms | cubic-bezier(0.2, 0.6, 0.2, 1) | drawer / page transition |
| `epic` | 800ms | spring(stiffness=100) | 突破 / 飛升 |
| `cinema` | 2000ms+ | 自 訂 | M65 開場 |

### 修仙特色 動 畫

#### 紫氣東來 (突破 動畫)

```
1. 弟子 卡 片 開 始 微 微 顫 動 (10ms)
2. 卡 片 邊 緣 出 現 紫 色 光 暈 (300ms 漸 現)
3. 卡 片 中央 噴 發 紫 氣 particles (500ms)
4. 紫 氣 散 開,弟子 境界 +1 顯 示
5. 全屏 短 暫 紫 色 閃 光 (100ms)
6. 整 個 動 畫 結 束 約 1.5s
```

#### 雷劫 動 畫

```
1. 螢幕 變 暗 (200ms)
2. 雲 出 現 (500ms)
3. 一道 紫雷 從 雲 中 落 下 (200ms)
4. 雷 劈 中 弟子 → 螢幕 抖 動 + 白 光 閃 (100ms)
5. 玩家 抉 擇:擋 雷 / 不 擋
6. 結果 顯 示 + 動 畫 結束 (3s+)
```

#### 飛升 動 畫

```
1. 弟子 緩緩 上 飄 (3s)
2. 全屏 出 現 金 光 (2s)
3. 弟子 化 為 一 個 字 → 飛 升 殘影 顯 現 (1s)
4. 殘影 自 動 進 入 「殘影 槽」 (1s)
5. 整 個 動 畫 7s
```

### prefers-reduced-motion 規則

所有 animation 必須 respect `prefers-reduced-motion`:

```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

---

## 10. 響應式 + 多分辨率

### 支援分辨率

| 分辨率 | scale | 主面板 | 桌寵 | 備註 |
|---|---|---|---|---|
| 4K (3840×2160) | 2x | 12 col 大字 | 600×600 | high-DPI 玩家 |
| 2K (2560×1440) | 1.5x | 12 col | 450×450 | |
| 1080p (1920×1080) | 1x | 12 col | 300×300 | **default** |
| 768p (1366×768) | 0.9x | 12 col 小 字 | 250×250 | 老 筆 電 |
| 720p (1280×720) | 0.8x | 8 col | 200×200 | 最 低 支 援 |

### Steam Deck (1280×800)

- 強 制 8 col 模 式
- 文 字 +10% 大 小
- 觸控 友 善 (button ≥ 44px)
- 桌寵 視窗 預 設 隱 (Deck 沒 multi-window)

---

## 11. 無障礙 a11y

### M77 a11y 補完

1. **色 盲 友 善**:不 用 純 顏 色 區 分 狀 態,必 配 icon / pattern
2. **鍵 盤 navigation**:所有 互動 元 件 可 Tab 到 達,Enter 觸 發
3. **screen reader**:所有 image 必 有 alt,icon 必 有 aria-label
4. **focus 視 覺 化**:焦 點 必 有 2px jade 邊框
5. **對 比 度**:文字 對 比 度 ≥ 4.5:1 (WCAG AA)
6. **可 縮 放**:文字 可 縮 放 至 200% 不 破 版

### 鍵 盤 快 捷 鍵

| 快捷鍵 | 動作 |
|---|---|
| `Tab` | 下 一 互 動 元 件 |
| `Shift+Tab` | 上 一 |
| `Enter` | 觸 發 |
| `ESC` | 關 閉 modal / drawer |
| `Ctrl+S` | 立 即 存 檔 |
| `Ctrl+,` | 設 定 |
| `Ctrl+1-9` | 切 換 主面板 標 籤 1-9 |
| `Ctrl+/` | 顯 示 所有 快 捷 鍵 |
| `Space` | 桌寵 採集 (主視窗 focus 時) |
| `F11` | 全 屏 切 換 |

---

## 12. Localization

### 3 語言 支援

```
zh-TW (default):繁體中文 (台灣)
zh-CN:           簡體中文 (中國大陸)
en:              English
```

### i18next 結構

```
src/locales/
  ├── zh-TW/
  │   ├── common.json
  │   ├── disciples.json
  │   ├── buildings.json
  │   ├── dao.json
  │   ├── narrative.json   ← 主線敘事
  │   ├── ui.json          ← UI 文 字
  │   └── numbers.json     ← 中文 大 數 字 單 位
  ├── zh-CN/
  └── en/
```

### 中文 大 數 字 單 位 (M27)

```
1e4  → 萬
1e8  → 億
1e12 → 兆
1e16 → 京
1e20 → 垓
1e24 → 秭
1e28 → 穰
1e32 → 溝
1e36 → 澗
1e40 → 正
1e44 → 載
1e48 → 極
1e52 → 恆河沙
1e56 → 阿僧祇
1e60 → 那由他
1e64 → 不可思議
1e68 → 無量大數
1e80+ → 「道」+ 數字  (修仙特色)
```

### English equivalent

```
1e3  → K
1e6  → M
1e9  → B
1e12 → T
1e15 → Qa
1e18 → Qi
... (standard idle game scale)
```

---

## 13. UI 性能 budget

### M25 baseline

| 場景 | budget | 實 際 (v1.1.0) |
|---|---|---|
| 主視窗 idle | < 5% CPU | 2% ✓ |
| 主視窗 tick | < 15% CPU | 10% ✓ |
| 桌寵 idle | < 3% CPU | 1% ✓ |
| 桌寵 突破 | < 30% CPU | 22% ✓ |
| 山門 vista 30fps | < 25% GPU | 18% ✓ |
| 首次載入 | < 2s | 1.5s ✓ |
| Hot reload | < 200ms | 150ms ✓ |

### 性能優化策略

1. **虛擬列表**:弟子 ≥ 50 / 福地事件 ≥ 50 / 配方 ≥ 100 → react-window
2. **Lazy load**:14 標 籤 按 需 載 入
3. **Memo**:`<BigNumber>` `<DiscipleCard>` 必 React.memo
4. **Subscribe selector**:Zustand subscribe 用 selector,不 訂 整 store
5. **Pixi off-tab pause**:窗 口 失 焦 → Pixi ticker pause
6. **Sprite atlas**:所有 sprites 打 包 為 一 個 atlas
7. **Web Worker**:大數字計算 / save migration → worker

---

## 14. User flow map(主要 14 條 flow)

> 每 條 flow 從 「玩家動機」 到 「完成」 的 完 整 路 徑。

### Flow 1:新玩家 首 次 啟 動

```
1. App 啟 動 → M65 開場 cinema (可 skip)
2. 主視窗 顯 示 → 山門 概 覽 (空)
3. 桌寵 出 現 → 「主上,弟子 願 拜入山門」(對話氣泡)
4. 玩家 點 桌寵 → 採集 1e3 靈氣
5. 主面板 紫 字 提示:「下 一 步:升級 聚靈殿」
6. 玩家 升 級 聚靈殿 Lv.1 → Lv.2
7. 第一 弟子 加 入 → 蒼雲 對話 (心境試煉 1)
8. 玩家 選 抉擇 ① ② ③ ④
9. 主面板 「山門概覽」 顯 示 完 整
10. 完 成 onboarding (5 min)
```

### Flow 2:弟子招募

```
1. 主面板 → 招募 標 籤
2. 三 選 項:免費(rare)/ 靈晶(common)/ 抽卡(rare event)
3. 玩家 點 一 個 → 抽卡 動 畫 (3s)
4. 弟子 顯 現 → 弟子 詳 細 modal
5. 玩家 選 「收 留」 / 「不 收」
6. 收留 → 加 入 弟子 列表 + 編制 提 示
7. 不 收 → 弟子 自 走 (旁 白:「他 走 了」)
```

### Flow 3:殿堂 升 級

```
1. 主面板 → 殿堂 標 籤
2. 選 一 個 殿堂 → 殿堂 詳 細 panel
3. 看 升 級 cost (靈氣 / 道學點)
4. 點 「升 級」 → 確 認 modal
5. 升 級 動 畫 (1s) → narrative 顯 現 (若 是 milestone)
6. rate 即 時 更 新
```

### Flow 4:弟子 編制

```
1. 弟子 詳 細 → 「指 派 殿堂」
2. 顯 示 推 薦 殿堂 (按 親和 排 序)
3. 玩家 點 一 個 殿堂 → 確 認
4. 編 制 即 時 生 效 → rate 即 時 更 新
```

### Flow 5:道學節點 解 鎖

```
1. 主面板 → 道學樹 標 籤
2. 顯 示 230 節點 SVG 樹
3. 玩家 點 一 個 節點 → 節點 詳 細
4. cost 顯 示 (道學點 + 修為)
5. 點 「解 鎖」 → 確 認 → 解 鎖 動 畫 → 效果 即 時
```

### Flow 6:突破 境界

```
1. 弟子 修為 達 → 弟子卡 紫氣 邊 框
2. 桌寵 待 辦 氣泡 提 示
3. 玩家 點 弟子卡 → 「突 破」 按 鈕 亮 起
4. 點 「突 破」 → 抉擇 modal (境界 narrative)
5. 玩家 選 → 紫氣東來 動 畫
6. 境界 +1 → 弟子卡 邊 框 顏 色 升 級
```

### Flow 7:自動化 規則

```
1. 主面板 → 自動化 標 籤
2. 「新增規則」 → RuleBuilder modal
3. ConditionPicker:選 「弟子 心境 < 50」
4. ActionPicker:選 「移 至 靜室」
5. 「儲 存」 → 規則 加 入 列表
6. tick 觸 發 → 規則 執 行 + toast 提 示
```

### Flow 8:福地 探索

```
1. 雲遊閣 → 「派出 弟子」
2. 選 一 弟子 + 一 福地 地圖
3. 動 畫 (10s)
4. 結果 modal:事件 narrative + reward
5. 玩家 點 「收 下」 → reward 入 庫
```

### Flow 9:心境試煉

```
1. 弟子 卡 → 心境試煉 機 會 圖標 (per 月 一 次)
2. 點 → NarrativePanel 顯 示
3. ChoiceList 顯 示 抉擇 (3-4 選 項)
4. 選 → 結果 narrative (心境 / 道基 / ability 變化)
```

### Flow 10:飛 升

```
1. 弟子 達 渡劫期 + 飛升台 解 鎖
2. 弟子卡 「飛 升」 按 鈕 亮
3. 渡 劫 動 畫 (9 雷 玩家 擋 不 擋)
4. 渡 劫 成 功 → 飛 升 動 畫
5. 全屏 cinema (7s)
6. 該弟子 進 入 仙界 (M99+) + 飛升殘影 顯 現
```

### Flow 11:存檔 / 載入

```
- Auto save 每 30s (M11)
- Manual save:Ctrl+S → toast 「✓ 存 檔 完 成」
- Load:啟動 自動 載 入,失敗 → 提 示 + 載 入 上 一 個
```

### Flow 12:設定

```
1. Header → ⚙ 設定
2. modal 顯 示 8 分 類:
   - 一般 (語言 / 主題)
   - 音 效 / 音 樂
   - 桌寵 (顯隱 / always-on-top / 頻率)
   - 動 畫 (reduced motion)
   - 自 動 化 (規則上限)
   - 鍵 盤 快 捷 鍵
   - 雲端 (Steam Cloud)
   - 開發者 (debug)
```

### Flow 13:成就

```
1. 主面板 → 成就 標 籤
2. 顯 示 33 成就 + 進 度
3. 達 成 → toast + 動 畫
4. 點 成就 → 詳 細 (narrative + reward)
```

### Flow 14:M99 仙界 解 鎖

```
1. 玩家 自 身 達 化神 期
2. 全屏 過 場 動 畫 (2 min)
3. 主面板 多 一 個 「仙界」 標 籤
4. 仙界 8 殿堂 解 鎖 提 示
5. 山門 vista 加 「仙界 影 像」
```

---

## 📚 結 語

本檔 涵 蓋 UI / UX 從 **視窗 → 布局 → 視覺 → 組件 → 互動 → 動畫 → a11y → flow** 完 整 spec。

### 待 擴(後續 patch)

- 各 組件 完整 props / state spec(對應 Storybook 文檔)
- 14 user flow 對應 wireframe 圖
- 4K / Steam Deck 個別 layout 截圖
- 桌寵 100 條 自 主 say 文 案(對 應 GAME_CONTENT.md §13 託夢補充)
- M65 開場 cinema 完整 storyboard

---

**Author**:綜合 M2-M77 UI 演進 + 修仙美學 + Steam EA 玩家 需求
**Date**:2026-05-14
**對應 milestone**:M2 主面板 + M9 桌寵 + M19 i18n + M25 性能 + M27 中文 大 數 字 + M65 開場 + M77 視覺 迭代