# 設計系統對齊分析 — 官方 .fig vs 首頁萃取版

我把兩份 .fig 解開實際讀過（ZIP → `canvas.fig` → fig-kiwi，資料區塊是 zstd 壓縮），
以下數據都是從變數與節點圖直接解出來的，不是目測。

---

## 1. 兩份檔案裡實際有什麼

### `color_theme_e等公務園+.fig` — 四個變數集合

| 集合 | 變數數 | 模式 | 內容 |
| --- | --- | --- | --- |
| `color` | 79 | value | `material-theme/ref/*` 原始色階、`Muted-colors/*` |
| **`theme-color`** | **52** | **light / dark** | **語意色。UI kit 綁定的就是這一套** |
| `theme-e+park` | 196 | Light / Light Medium Contrast / Light High Contrast / Dark | 另一套 M3 主題（Schemes 49 + State Layers 147），主色是藍 `#236bb3` |
| `Typography` | 31 | 繁體中文 / 英文 / 英/數 / 多語系 | 字級、行高、字距，以及**依語言切換的字型** |

`Typography` 的字型模式：繁體中文 → Noto Sans TC｜英/數 → Inter｜英文 → Arial｜多語系 → Noto Sans。
這跟我們現行的 font stack `'Inter','Noto Sans','Noto Sans TC',Arial` 意圖完全一致，只是機制不同
（Figma 用模式切換，Web 用 fallback 鏈一次涵蓋，結果相同）。

### `💎e+_通用前台UI.fig` — 元件庫

- **2775 個元件**（803 個獨立元件名）、14 個頁面、60 個分區
- 綁定 `theme-color` + `Typography`，**沒有綁 `theme-e+park`**
- 涵蓋三條產品線：`💎Exam前台`、`⭐️Moocs後台`、`📌LMS_3.0後台`
- 通用元件分區：Buttons、Input、Switch、Tabs、Badges、Avatar、Dropdown Select List、
  Table、Modal、Toast、Tooltip、breadcrumb、backdrop、Pagination
- 圖示家族：User、Communication、Arrows、Interface、Navigation、Media、Files & Images、
  Formatting、Feather Icons
- 業務模組：exam_list、course_center、course_setting、discussion、correction、
  feedback、announcement、rating_scale、dashboard、invigilation
- 另有 **「主頁框架RWD規範」** 與 **「💠 Theme明暗切換」** 兩個規範頁

---

## 2. 落差有多大（量化）

### 色彩：32 個 token 對 `theme-color` light 模式做 CIE Lab ΔE 比對

**完全一致（ΔE < 1）— 6 個**

| 我的 token | 值 | 官方變數 |
| --- | --- | --- |
| `--ink-700` | `#24364d` | `on-surface` / `inverse-surface` |
| `--surface-100` | `#edf0f4` | `surface2` |
| `--red-600` | `#db352e` | `error` |
| `--amber-500` | `#ffc107` | `warning-container` |
| `--indigo-500` | `#5f5fb8` | `tertiary` |
| `--white` | `#ffffff` | `on-error` / `on-secondary` |

**近似（ΔE 1–3）— 3 個**：`--line-200`→`surface5`、`--surface-50`→`surface1`、`--canvas-lime`→`on-success`

**對不上（ΔE 8–42）— 23 個**，而且集中在同一族：

| 我的 token | 值 | 最接近的官方變數 | ΔE |
| --- | --- | --- | --- |
| `--blue-600`（主行動色） | `#007eb2` | `on-tertiary-container` `#4c4c87` | 30.0 |
| `--teal-600` | `#218553` | `on-success-container` `#005300` | 26.3 |
| `--lime-500`（識別色） | `#84cc16` | `success` `#088806` | 33.6 |
| `--sky-500` | `#0ea5e9` | `tertiary` `#5f5fb8` | 40.5 |
| `--orange-500` | `#ff7d00` | `secondary` `#e26414` | 14.8 |
| `--violet-600` | `#7d4cad` | `tertiary` `#5f5fb8` | 16.2 |

> **整個萊姆／青綠／天藍品牌家族，在官方色票裡完全不存在。**
> 官方 `primary` 是青綠 `#1f7a73`（另有 `primary-hover #4c958f`、`primary-pressed #19625c`），
> 我們的主行動色是藍 `#007eb2`，最接近的官方變數 ΔE 高達 30。

### 結構：這一項的落差比色值更關鍵

| 面向 | 官方 | 我們現行 |
| --- | --- | --- |
| 主題模式 | light + dark 完整成對 | 只有 light |
| 對比模式 | `theme-e+park` 另有 Medium / High Contrast | 無 |
| 互動狀態 | `primary-hover`、`primary-pressed` | 無，靠 `filter:brightness()` 硬幹 |
| 表面層級 | `surface1`–`surface5` 五階 | 只有 surface / surface-muted |
| 透明度 | `opacity-4/8/12/20/70/80/100` | 各處寫死 `rgba(0,0,0,.12)` |
| 文字強調 | `on-surface-high/medium-emphasis`、`on-surface-disabled` | 無 |

### 字級

| | 階梯 |
| --- | --- |
| 官方 | 11 · 13 · 14 · 16 · 18 · 20 · **23** · **26** · **29** · **32** · **36** · **41** |
| 我們 | 12 · 13 · 14 · 16 · 18 · 20 · **23** · **28** · **34** · **42** · **52** |

低到中段（13/14/16/18/20/23）完全吻合，**高段全部不同**。
另有 `1row-*` / `2row-*` 兩組單雙行專用字級（12/14/16/18）與八階行高
（100 / 125 / 130 / 140 / 146 / 148 / 150 / 170 %），我們只有四階。

---

## 3. 為什麼會有落差（診斷）

**最可能的情況：Lime 是視覺提案，設計師直接在頁面上塗了新的品牌色，但沒有把這組色升級進共用的 `theme-color` 變數集合。**

證據：頁面的中性色與狀態色（`#24364d`、`#edf0f4`、`#db352e`、`#ffc107`、`#5f5fb8`）
全部**精準命中**官方變數——如果是完全另起爐灶，不會這麼準。命不中的**只有品牌色家族**。

### ⚠️ 更正（2026-07-31）

先前判斷 `theme-e+park` 為「實驗性或待廢」是**錯的**。
比對客戶定案的學習環境後發現：學習環境的連結色 `#236bb3` 正是
`theme-e+park` 的 `Primary`（Light），而其 `outline`、`on-surface-variant`、
`surface container` 等值也大量出現在學習環境中。

因此兩個語意集合各有歸屬：

| 集合 | 主色 | 實際用在 |
| --- | --- | --- |
| `theme-color` | `#1f7a73` 青綠 | 通用前台 UI kit 綁定；狀態色為全站標準 |
| `theme-e+park` | `#236bb3` 藍 | 學習環境的連結色與中性/表面色 |

兩者**不衝突**，是不同介面的基準。詳見「7. 定案後的最終架構」。

---

## 4. 建議怎麼調整

### 方案比較

| | 做法 | 評估 |
| --- | --- | --- |
| A | 全面改用官方 `theme-color`，首頁重新上色 | 最正統，但 Lime 的識別漸層會消失，等於推翻剛定案的方向 |
| **B** | **結構立刻對齊，色值待設計端定案** | **推薦** |
| C | 兩套並存 | 最糟，分歧只會擴大 |

**推薦 B 的理由**：色值是設計決策（而且 Lime 才剛定案），結構不是。
結構對齊現在就能做，而且**不論最後哪組色勝出都不會白工**。

### 執行步驟

**現在就做（低風險、立即受益）**

1. 引入 `assets/design-tokens.figma.css`（已產出）——直接從 .fig 變數萃取的橋接檔，
   含 52 個語意色的 light/dark 雙模式與完整 Typography。設計端更新 .fig 後重跑萃取即可。
2. 把 `design-tokens.css` 的語意層改為引用 `--sys-*`：凡官方已有對應的
   （中性色、狀態色、表面層級）一律改指過去，不再自行寫死。
3. 補上結構缺口：state ramp、`surface1–5`、opacity scale、emphasis 三級、dark mode 骨架。
4. 字級高段改採官方的 26 / 29 / 32 / 36 / 41，取代我們的 28 / 34 / 42 / 52。
   （統計帶目前用到 52px，超出官方最大階 41px，需要設計端補一階或改用 41。）

**待設計端確認後才做**

5. 品牌色。請設計端在 `theme-color` 集合**新增一個 lime 模式**，或把 `primary` 改為
   Lime 的色值——這樣 Figma 與程式碼才共用同一個來源。
   在那之前，Lime 品牌色以 `--brand-*` 前綴獨立存放，並明確標記「尚未進入官方色票」。
6. 是否重新上色首頁——這是設計決策，不該由實作端片面決定。

---

## 5. 通用 UI kit 怎麼併進來

### 三層模型

```
第 1 層 · Token    color_theme.fig   →  assets/design-tokens.figma.css   (--sys-*)
第 2 層 · 元件     通用前台UI.fig     →  assets/design-components.css     (照官方變體字彙)
第 3 層 · 頁面     homepage-lime.html 與後續各頁
```

上層只能引用下層，不可反向。頁面不得自己發明顏色或元件。

### 關鍵：目前的 `design-components.css` 抽象層級是錯的

我從單一頁面反推出 `.ds-btn--primary / --login / --affil / --ghost`，
但官方按鈕是一個**五維矩陣**：

| 屬性 | 選項 |
| --- | --- |
| 类型 | 主要按钮 / 次要按钮 / 虚框按钮 / 线框按钮 / 文本按钮 |
| 种类 | 标准 / 危险 / 成功 / 警告 |
| 尺寸 | 迷你 / 小 / 中 / 大 |
| 状态 | 默认 / 悬停 / 聚焦 / 激活 / 禁用 |
| 形状 | 长方形 / 全圆角 / 方形 / 圆形 |

元件層應改採這套字彙，例如
`<button class="btn" data-type="primary" data-kind="standard" data-size="md" data-shape="pill">`，
未來設計交付與實作才對得上話。其他分區（Input / Switch / Tabs / Badges / Table /
Modal / Toast / Tooltip / Dropdown / Pagination / breadcrumb）同理，**首頁還沒用到的一律
直接照 kit 實作，不要再自創**。

### 三件可以立刻收割的事

1. ~~圖示改用 kit SVG~~ **已決定不換，保留 Material Icons Outlined 字型。**
   代價是 185KB 的圖示字型只用約 20 個字符；換得用法統一、不需維護 SVG 資產、
   不必處理多尺寸與著色。除非體積成為實際問題，否則不再重新評估。
2. ~~斷點~~ **已完成**，px 定義自 .fig 取得，見第 6 節第 4 點。
3. ~~深色模式~~ **已完成**，入口網站與應用介面各有專屬深色主題。

### 建議順序

1. 先接 token（低風險，立即受益）
2. 再把元件層重寫為官方字彙（中風險，需逐一比對）
3. 最後才決定是否重新上色首頁（高風險，需設計端拍板）

---

## 6. 需要你或設計端確認的三件事

1. ~~品牌色以哪一套為準？~~ **已定案：以客戶確認過的頁面為準。**
   入口網站用 Lime（`#007eb2` + 萊姆→天藍識別漸層），
   應用介面用學習環境的 `#5d6bc0` + 連結色 `#236bb3`。官方 .fig 降為「原訂基準」，
   提供結構而非色值。
2. ~~`theme-e+park` 是否已廢棄？~~ **未廢棄**，見上方更正。
3. ~~統計帶的 52px~~ **已處置**：非階梯值，是 `--fs-stat` 流體上限。
   `clamp(31px,3.2vw,52px)` 在 xl（1280）時剛好落在官方最高階 41px，
   只有 ≥1280 才超出。新頁面上限一律 41px，不得引用 `--fs-display`。
4. ~~官方六級斷點的 px 定義~~ **已自行從 .fig 取得**，不需向設計端索取：
   UI kit「主頁框架RWD規範」分區內的規範畫板名稱與尺寸直接給出答案——
   `主頁框架_1_xs` 360×640、`_sm` 560×996、`_md` 768×1024，
   另有 lg 1024 / xl 1280 / xxl 1440 的框架。
   **我方既有的 560 / 768 / 1024 / 1280 與官方完全一致**，只需對齊命名並補上 xxl。
5. ~~入口網站的深色模式~~ **已建立專屬主題**（不再沿用學習環境值）：
   由首頁品牌推導，深青藍底 `#061b2b`、主行動提亮為 `#3fb8e6`、
   萊姆識別色用 lime-400。對比實測內文 12.8:1、次要 7.4:1、主行動 7.0:1、
   accent 上文字 7.4:1，全數通過 AA。

### 順帶回報兩個小問題

- UI kit 的變體標籤是**簡體中文**（默认／悬停／禁用／线框按钮），但產品介面是繁體中文。
  若這份 kit 會交給外部團隊使用，建議請設計端統一。
- `Typography` 的 `letter-spacing/default = 0.14`，單位在 .fig 裡沒有明示。
  我暫時當作 px 處理（0.14px ≈ 0.008em，等於幾乎不加字距）。若原意是 0.14em 或 1.4%，請告知。


---

## 7. 定案後的最終架構

客戶已確認：**首頁與學習環境兩處定案頁面不可更動**，官方 .fig 為原訂基準。
據此，設計系統改為三層，實作於 `assets/design-tokens.css`：

```
第 0 層 核心      三方一致，不得分歧
                  中性色階（ΔE ≤ 2 三方一致）
                  狀態色（採官方值，學習環境已 100% 命中）
                  字型、字級（官方 12 階）、間距、觸控與無障礙
第 1 層 介面主題  允許分歧，必須登記
                  [data-surface="portal"]   入口網站 ← 首頁定案值
                  [data-surface="learning"] 應用介面 ← 學習環境定案值
                  兩者皆可再套 [data-theme="dark"]
第 2 層 元件      只寫一次，靠主題變數自動換裝
                  變體字彙採官方五維矩陣，全面繁中化
```

### 三方比對摘要

| 類別 | 結果 |
| --- | --- |
| 中性色階 | 首頁 / 學習環境 / 官方 fig **完全一致**（ΔE ≤ 2）→ 收進核心層 |
| 狀態色 | 學習環境六個值 **100% 命中官方**（ΔE = 0）→ 收進核心層。<br>首頁沒有狀態色，是因為它沒有表單與回饋訊息，不是刻意不同 |
| 品牌行動色 | **真歧異**：`#007eb2` vs `#5d6bc0`，兩者皆為定案 → 放進介面主題層 |
| 頁面底色 | **真歧異**：`#fbfef6` 淡綠白 vs `#eef3f8` 藍灰 → 放進介面主題層 |
| 尺度 | 圓角 24 vs 16、容器 1920 vs 1376、頭部 86 vs 60 → 放進介面主題層 |
| 深色模式 | 僅學習環境有定案設計，已納入；入口網站暫時沿用 |

### 這樣做的好處

- 兩處定案頁面**一個像素都不用改**
- 元件只寫一次，新頁面只要宣告 `data-surface` 就自動穿上正確外觀
- 未來要換色或做機關客製，只需改第 1 層，不動元件
- 深色模式免費取得