# 等公務園＋學習平臺 — 設計系統規範
全站以**繁體中文**為主：介面文字、文件、元件變體命名一律繁中，
僅程式識別碼（class、data 屬性值、變數名）保持 ASCII 以維持穩定。
---
## 0. 權威順序
衝突時一律由高到低：
| 順位 | 來源 | 說明 |
| --- | --- | --- |
| **1** | **客戶定案頁面** | `homepage-lime.html`（入口網站）與學習環境（應用介面）。
**這兩處的既有數值是視覺契約，不得更動。** |
| 2 | 官方 Figma | `color_theme_e等公務園+.fig`、`💎e+_通用前台UI.fig`。
原訂基準，提供「結構」：狀態色、互動狀態階、表面階、透明度階、字級階梯、light/dark、元件變體字彙。 |
| 3 | 本系統推導 | 收斂後的新階，僅適用於尚未設計的新頁面。 |
> 設計系統的工作是**描述**定案頁面並補齊結構，不是修正它們。
### 檔案地圖
| 檔案 | 角色 |
| --- | --- |
| `homepage-lime.html` | 入口網站參考實作（定案，唯讀） |
| `design-system.html` | 樣式指南，可即時切換介面與明暗 |
| `assets/design-tokens.css` | **統整版 token（唯一數值來源）** |
| `assets/design-components.css` | 元件層，採官方變體字彙 |
| `assets/design-tokens.figma.css` | 官方 Figma 變數原始萃取（對照用，不直接使用） |
| `assets/offline-fonts.css` | 全站共用字型（666KB，勿再內嵌到個別頁面） |
| `design-system-alignment.md` | 與官方 .fig 的落差分析 |
| `design-qa.md` | RWD 斷點系統與逐斷點驗收紀錄 |
---
## 1. 三層架構
首頁與學習環境都是定案且看起來不同——因為任務不同：一個要**吸引與導覽**，
一個要支撐**長時間專注操作**。統整的做法不是把它們變成一樣，而是分層。
```
第 0 層 核心 三方一致，任何介面都不得分歧
中性色階、狀態色、字型、字級、間距、觸控與無障礙
第 1 層 介面主題 允許分歧，但必須登記在 design-tokens.css
[data-surface="portal"] 入口網站
[data-surface="learning"] 應用介面
兩者皆可再套 [data-theme="dark"]
第 2 層 元件 只寫一次，靠主題變數自動換裝
```
用法：
```html
```
未指定時預設 `portal` + 淺色。
---
## 2. 兩種介面的差異（唯一允許分歧的六項）
以 CIE Lab ΔE 三方比對後，**中性色階完全一致（ΔE ≤ 2）**，
**狀態色學習環境 100% 命中官方值（ΔE = 0）**。真正的歧異只有：
| 面向 | 入口網站 `portal` | 應用介面 `learning` | 為什麼不同 |
| --- | --- | --- | --- |
| 頁面底色 | `#fbfef6` 淡綠白 | `#eef3f8` 藍灰 | 入口強調品牌溫度；應用降低長時間閱讀的亮度負擔 |
| 主行動色 | `#007eb2` | `#5d6bc0` | 兩處皆為客戶定案值 |
| 連結色 | 同主行動色 | `#236bb3` 獨立 | 應用介面內文連結多，需與按鈕區隔避免誤點 |
| 卡片圓角 | 24px | 16px | 入口走大圓角親和感；應用走中圓角資訊密度 |
| 容器寬度 | 1920px | 1376px | 入口滿版展示；應用固定閱讀寬度 |
| 頭部高度 | 86px | 60px | 應用要把垂直空間留給內容 |
**識別漸層只屬於入口網站。** 萊姆→天藍的 `--grad-accent` 是首頁招牌語彙，
在應用介面會自動換成主色漸層，避免在操作介面裡喧賓奪主。
---
## 3. Token 使用原則
**元件只使用語意層。** 基礎色票（`--ink-*`、`--surface-*`）只在 token 檔內部被語意層引用。
```css
/* ✅ 正確 */
.my-card{ color:var(--color-fg); border:1px solid var(--color-border); border-radius:var(--r-card); }
/* ❌ 跳過語意層 */
.my-card{ color:var(--ink-750); }
/* ❌ 寫死數值 */
.my-card{ color:#24364d; border-radius:24px; }
```
深色模式的 `--color-accent` 是**淺色**，因此 accent 底上的文字一律用
`--color-on-accent`，不可寫死 `var(--white)`——否則深色模式會出現白字壓淺紫的對比災難。
### 字級
採官方 Typography 12 階：11 · 13 · 14 · 16 · **18**（內文預設）· 20 · 23 · 26 · 29 · 32 · 36 · 41。
**新頁面的字級上限是 `--fs-7xl`（41px）。** `--fs-display`（52px）不是階梯值，
是首頁統計帶的流體上限——`--fs-stat` 為 `clamp(31px,3.2vw,52px)`，在 xl（1280）時
剛好落在官方最高階 41px，只有 ≥1280 的寬桌機才會超出，屬滿版展示的合理放大。
新頁面不得直接引用 `--fs-display`。
定案頁面的既有字級不動，對照表見 `design-system-alignment.md`。
---
## 4. 元件變體字彙
沿用官方「通用前台UI」的五維矩陣。屬性值 ASCII，介面文字繁中。
| 屬性 | 選項 |
| --- | --- |
| `data-type` 類型 | `primary` 主要按鈕｜`secondary` 次要按鈕｜`tonal` 虛框按鈕｜`outlined` 線框按鈕｜`text` 文字按鈕 |
| `data-kind` 種類 | `standard` 標準｜`danger` 危險｜`success` 成功｜`warning` 警告 |
| `data-size` 尺寸 | `xs` 迷你｜`sm` 小｜`md` 中（預設）｜`lg` 大 |
| `data-shape` 形狀 | 預設全圓角｜`rect` 長方形｜`square` 方形｜`circle` 圓形 |
| 狀態 | 預設｜`:hover` 停留｜`:focus-visible` 聚焦｜`[aria-pressed]` 啟用｜`:disabled` 停用 |
```html
```
**首頁還沒用到的元件（表格、對話框、Toast、下拉、麵包屑、分頁導覽）一律照官方 kit 實作，不要自創。**
> ⚠️ 官方 .fig 內的變體標籤是**簡體中文**（默认／悬停／线框按钮），已在本系統統一為繁體。
> 請回饋設計端修正原檔。
---
## 5. RWD
採**官方六級命名**。px 定義取自 UI kit「主頁框架RWD規範」分區的規範畫板
（`主頁框架_1_xs` 360×640、`_sm` 560×996、`_md` 768×1024，以及 lg/xl/xxl 的框架尺寸）。
完整驗收見 `design-qa.md`。
| 級別 | 官方基準寬 | 實作範圍 | 裝置 | 策略 |
| --- | --- | --- | --- | --- |
| `xs` | 360 | ≤ 559 | 手機 | 單欄；列表改「縮圖左·資訊右」；統計 2 欄格線 |
| `sm` | 560 | 560–767 | 大手機 | 卡片 2 欄；數據卡維持單欄保留插圖 |
| `md` | 768 | 768–1023 | 平板直式 | 卡片 2–3 欄；欄寬不足時**隱藏裝飾插圖**而非縮小文字 |
| `lg` | 1024 | 1024–1279 | 平板橫式 | 卡片 3–4 欄；插圖回歸但縮小 |
| `xl` | 1280 | 1280–1439 | 桌機 | 原始設計基準線，不做覆寫 |
| `xxl` | 1440 | ≥ 1440 | 寬桌機 | 流體尺寸持續放大至 1920 設計稿原生寬 |
我方既有的 560 / 768 / 1024 / 1280 與官方**完全一致**，本次只對齊命名並補上 xxl。
1920 是設計稿原生寬度（`--container-max`），不是斷點。
### 三條硬規則
1. **任何寬度都不得出現水平捲動。** 固定寬度元素要設成可壓縮，不要靠斷點硬算尺寸。
2. **固定高度一律改最小高度。** `height:205px` 在窄欄一定會被內容撐破。
3. **斷點處不要跳動。** 跨斷點連續變化的尺寸用線性式，例如 `calc(7.4vw + 154px)`。
---
## 6. 無障礙
平臺掛有無障礙 2.1 AA 標章。以下為底線，**不因介面主題或明暗模式而放寬**。
| 項目 | 要求 |
| --- | --- |
| 觸控目標 | ≥ 44×44px（`--tap-min`） |
| 焦點樣式 | `3px solid var(--color-focus)` + 2px offset，不得移除 outline |
| 文字對比 | `--color-fg` 對白底 11.7:1；`--color-fg-muted` 7.5:1；`--color-fg-subtle` 僅限 ≥18px 或非文字圖示 |
| 狀態語意 | 用 `aria-selected`／`aria-expanded`／`aria-current`／`aria-pressed` 驅動樣式 |
| 動態 | 尊重 `prefers-reduced-motion`，token 已內建自動歸零 |
| 深色模式 | 切換後語意 token 自動翻轉，不需為深色另寫元件 |
| 圖片 | 裝飾性 `alt="" aria-hidden="true"`；內容性必須有實質 alt |
---
## 7. 新頁面起手式
```html
頁面標題
```
### 檢查清單
- [ ] `` 有指定 `data-surface`
- [ ] 沒有寫死的 hex、px 字級、px 圓角——全部走 token
- [ ] accent 底上的文字用 `--color-on-accent`，不是 `--white`
- [ ] 每個 `` 有 `data-od-id`
- [ ] 圖示鈕 ≥ 44px 且有 `aria-label`
- [ ] 固定高度都改成 `min-height`
- [ ] 360／390／768／1024／1280／1920 皆無水平捲動
- [ ] 淺色與深色模式都檢查過
- [ ] 入口網站的重點色出現 ≤ 2 次／畫面
---
## 8. 已知待辦
- ~~圖示改用 kit SVG~~ **已決定保留 Material Icons Outlined 字型。**
代價是 `offline-fonts.css` 內有 185KB 的圖示字型而實際只用約 20 個字符；
換得的是圖示用法統一（`name`）、不需維護 SVG 資產、
也不必處理多尺寸與著色。此決定不再重新評估，除非檔案體積成為實際問題。
- ~~斷點命名~~ **已完成**，見第 5 節，px 定義來自 UI kit 規範畫板。
- ~~入口網站深色模式~~ **已完成**，`design-tokens.css` 有專屬區塊，對比全數通過 AA。
- ~~統計帶 52px~~ **已處置**，見第 3 節：非階梯值，新頁面上限 41px。
- **對比模式**：官方 `theme-e+park` 另有 Medium / High Contrast 兩級，尚未納入。
若無障礙稽核要求提供高對比模式，可再從 .fig 萃取。