# 好買市集設計系統

本文件是外觀改版的第二份基線，與[功能盤點](../functional-inventory/README.md)分工：功能盤點決定保留哪些資訊及操作，本文件決定共用元件、品牌色、字體、尺寸及主題切換方式。

依使用者指定切換至 [官方 Luma](https://ui.shadcn.com/docs/changelog/2026-03-luma)，採用較開放的間距、圓潤幾何與柔和表面。2026-11-20 透過 `npx shadcn@latest apply luma --yes` 更新，官方 CLI 更新了 56 個來源檔案；品牌色與示範行為保留。詳見[切換紀錄](research/luma-migration.json)。

採用 **Astro＋React＋Tailwind CSS v4＋官方 shadcn/ui Radix Luma**。兩套主題共用一份元件原始碼，只改色彩 token：

- **中華電信方向**：參考中華電信網路門市的品牌藍與深藍。
- **好買市集方向**：保留原站 Logo、綠色與金黃色，以及 Hami Point 點數圖示。

這是本專案建立的品牌適配，不是中華電信官方發布或認可的設計系統。「符合 shadcn/ui」指採用官方 registry 原始碼、preset、元件 API、組合及語意 token，不代表存在官方認證。

## 研究範圍與結論

研究日期：2026-11-19，US/Pacific。

搜尋包含「中華電信 官方 設計系統」「中華電信 design system」「Chunghwa design system」及 `site:cht.com.tw` 的設計規範。未找到能公開查閱、包含 UI 元件與 token 規範的官方設計系統。這不代表中華電信內部沒有設計系統。第三方彙整、求職作品與品牌個案不作官方規範依據。

因此以[中華電信網路門市](https://www.cht.com.tw/home/consumer)的公開 CSS 分析品牌線索；好買方向則以[好買市集首頁](https://www.hamimall.com.tw/index.php)、[原站主樣式](https://www.hamimall.com.tw/css/style.css?11)與原始素材交叉確認。

| 樣本 | 本次下載分析 | 用途與限制 |
| --- | --- | --- |
| 中華電信網路門市 | 13 份同網域 CSS | 包含多個年度及區塊樣式；只提取一致品牌線索，不匯入原樣式 |
| 好買市集 | 11 份同網域 CSS＋首頁 inline style 樣本 | 同網域內仍含第三方外掛；依 `style.css` 的品牌變數與 Logo 交叉判讀，不依整批色碼頻率直接選色 |
| 好買 Logo | 1 個原始 PNG | 核對尺寸、透明通道、留白及實色像素 |
| Hami Point | 1 個原始 SVG | 核對尺寸、漸層與貨幣意義 |
| shadcn/ui | CLI 4.23.0，Radix Luma | 官方 registry 64 項，其中 63 個有 UI 原始碼，`form` 只有空的 metadata |

CSS 分析採「移除註解後的宣告色碼統計」，會正規化三位 HEX；**不是畫面面積、可見程度、computed style 或官方色彩權威性的排名**。未遞迴追蹤 `@import` 及 JS 動態載入的 CSS，因此是可重跑的公開頁面樣本，不是整個網域的完整爬取。

原始 CSS 保留在本機 `.cache/cht-css/`、`.cache/haomai-css/` 作研究，不加入網站 bundle。每份下載的來源、bytes 與 SHA-256 記在研究 JSON。

## 中華電信方向

| 現站色彩線索 | 證據 | 本系統使用方式 |
| --- | --- | --- |
| `#209CFF` 藍 | 樣本中 150 次 HEX 宣告，分布於 10 份 CSS；出現在 `a`、`.button`、`.is-blue`、欄位 focus 等選擇器 | 保留為 `brand` 原色與品牌色樣 |
| `#0267B9` 深藍 | `.tag.tag-navy`、會員卡與部分 tab 狀態 | 作為淺色模式操作色的推導起點 |
| `#FF874D` 橘 | 在樣本中反覆出現的輔助色 | 僅作 `brand-secondary` 與色樣，避免把橘色誤當所有警告／促銷的統一規則 |

主互動色採 `#025AA3`，是本專案由現站深藍加深的適配色；它不是新發現的官方 token。原藍 `#209CFF` 搭配白字的對比約 2.89:1，不直接作白字主要按鈕底色。

值得保留的是可支援繁體中文的系統 sans-serif 字型回退概念。網路門市 CSS 中混合不同字級、年度樣式、膠囊按鈕、陰影及版面規則，不作本專案的尺寸與排版依據。

## 好買市集方向

### 原站 CSS 的品牌資訊

`style.css?11` 明確定義下列變數，可信度高於將舊 Bootstrap、外掛及全站樣式的所有色碼混合排序：

| 原站變數／線索 | 原值 | 決定 |
| --- | --- | --- |
| `--main` | `#58AC47` | 保留為 `brand` 市集綠 |
| `--second` | `#E3A21F` | 保留為 `brand-secondary` 市集金 |
| `--Orange_yellow` | `#FAB01B` | 不再增加相近的第三個品牌黃 |
| `--dark_green`／`--black` | `#112C1A` | 用作深色主題的主要按鈕文字與綠色原色上的文字 |
| `--light_green` | `#47D382` | 原站亮綠之一，不直接作主要操作色 |
| 商品點數 inline style | `#74B276` | 局部顯示色，沒有升格為另一套全域綠色 |
| 主樣式字體 | Noto Sans TC，載入 weight 300 | 保留繁中 sans-serif 方向，不沿用過細字重 |
| `html, body` 宣告 | 15px | 不繼承，使用標準 16px root |

綠色 `#58AC47` 與白字的對比約 2.84:1，金黃 `#E3A21F` 與白字約 2.22:1，因此原色適合識別、色樣及搭配深色文字。淺色主要按鈕採同系加深的 `#245F1E`，金黃色以低飽和的輔助表面用於 Secondary，不取代錯誤色或警告色。

原站的膠囊搜尋框、不同圓角、固定高度、浮動排版及多套第三方 reset 均不移植；由 shadcn/ui Luma 統一。

### Logo 分析

來源：[hami_logo2510.png](https://www.hamimall.com.tw/images/hami_logo2510.png)。本機原檔為 [haomai-logo.png](../../public/brand/haomai-logo.png)。

- 內容為綠色「好買」與金黃色「市集」的文字識別，並非只有舊 Hami 字樣；圖檔名稱仍保留 hami。
- 原圖 789 × 383，寬高比約 2.06:1；有透明通道，**但並非所有背景像素都透明**。
- 完全不透明像素統計中，主要品牌色為 `#E3A21F` 與 `#58AC47`，分別有 27,446 與 25,292 像素，與主 CSS 變數一致。白色有 65,115 像素；半透明及抗鋸齒像素不納入這項實色統計。
- 有色／非透明範圍集中於圖內，原圖本身有明顯上下留白。保留原圖，不自行裁切、重畫或以近似字型重製。
- 因含不透明白色，深色背景使用固定白色的 `brand-asset-surface` 作素材底板，避免透明區與白色區產生破碎視覺。

網站實作將這個 Logo 作為原站素材展示。頁首的購物袋是展示工具的通用圖示，不是新 Logo，也沒有假造中華電信官方標誌。未取得正式品牌手冊前，不宣稱最小尺寸、淨空距離或反白版為官方規範。

### 導覽圖示與活動圖片

首頁另引用 CHT／LINE 登入識別，以及 Search2、bell2、cart2、point-G 等 SVG；逐檔的尺寸、viewBox、色碼與來源記在[圖像清單](research/graphic-inventory.json)。五個登入／搜尋／通知／購物車圖示皆為 25 × 25，使用深綠 `#112C1A`；點數圖示另有自己的尺寸與漸層。

新版一般搜尋、通知、購物車等介面圖示統一使用 preset 的 Lucide；第三方登入識別與點數圖示保留品牌用途，不將通用圖示與品牌標誌混為同一套。首頁活動及商品圖多來自 `img.sopower.com.tw`，屬可更換的內容素材，不從檔期 Banner 抽取全域主題色。本次清單記錄 55 個不重複的 HTML img src，不包含 CSS background 或動態圖片。

### Hami Point 圖示

來源：[point.svg](https://www.hamimall.com.tw/images/point.svg)，原始尺寸／viewBox 為 16 × 16，漸層色為 `#47D382` 與 `#96D34F`。保留為貨幣識別素材，兩個品牌方向皆可出現。

點數圖示應搭配數字與「點」文字；不可與 NT$ 現金售價混淆，也不可把圖示綠色當作一般成功狀態。其圖像漸層僅用於原始素材，不擴散到 shadcn 按鈕背景。

## shadcn/ui 實作標準

官方有 [Astro 整合指南](https://ui.shadcn.com/docs/installation/astro)；本專案由官方 CLI 的 Astro template 建立，使用 React island 的 `client:load` 讓展示互動生效。

| 項目 | 採用規則 |
| --- | --- |
| 元件來源 | 官方 `@shadcn` registry，以 CLI 加入；沒有手刻外觀近似版 |
| Style／primitive | `radix-luma`／Radix UI |
| 色彩 | [官方 CSS variables／語意 token](https://ui.shadcn.com/docs/theming)，`cssVariables: true` |
| 原始碼 | `src/components/ui/` 保持本次 CLI 產生的版本；品牌不寫進元件 class |
| 元件尺寸 | 原生 variants、size、字級、間距及 focus／disabled／invalid 樣式 |
| 表單 | `FieldGroup`、`Field`、`FieldLabel`、`FieldError`；控制項配對 `aria-invalid` 與說明 |
| 組合 | `SelectItem` 在 `SelectGroup`、對話框帶 title／description、TabsTrigger 在 TabsList |
| 訊息 | Alert、Empty、Skeleton、Progress、Sonner，不自行重畫近似元件 |
| 圖示 | preset 的 Lucide；icon button 有名稱 |
| 深色模式 | `.dark` 覆寫同名 token；next-themes 管理模式 |
| 字型 | 官方 preset 的 Inter 保留，追加繁體中文系統字型 fallback |

上游 registry 的 `form` 回傳只有 name／type／schema，沒有 files 或 dependencies。本專案如實保留索引，不虛構 `form.tsx`，改用目前官方 `Field` 組合。可查 [registry 空項目紀錄](research/registry-empty-items.json)。

目前有 **63 個官方 UI 原始碼模組、64 個 registry 索引項目、29 種實際展示的 UI 模組**。其餘模組已加入，可按需求引用；不為了展示安裝數而將所有重型模組載進首頁。Typography 是使用文件與字級規則，並非獨立 `typography.tsx` registry 元件。

## 兩個主題的 token

唯一的品牌色彩資料來源為 [brand-themes.json](../../src/data/brand-themes.json)。執行 `npm run tokens` 產生 `src/styles/brand-themes.css`；不要手動修改產物。

官方 neutral 色系保留在 `src/styles/global.css`。除了下表色彩與 sidebar 對應 token，兩套主題共用 background、foreground、card、popover、muted、border、input、destructive 及 Luma 原始規則。

| Token | 中華電信 淺色 | 好買市集 淺色 | 中華電信 深色 | 好買市集 深色 |
| --- | --- | --- | --- | --- |
| `primary` | `#025AA3` | `#245F1E` | `#72BDFF` | `#8BD17C` |
| `primary-foreground` | `#FFFFFF` | `#FFFFFF` | `#08253B` | `#112C1A` |
| `secondary` | `#EDF6FF` | `#FCF3DF` | `#112F48` | `#3C3017` |
| `secondary-foreground` | `#024B88` | `#674800` | `#B8DFFF` | `#F0D393` |
| `accent` | `#EDF6FF` | `#EDF7EA` | `#112F48` | `#1D3420` |
| `accent-foreground` | `#024B88` | `#245F1E` | `#B8DFFF` | `#B7E1AD` |
| `ring` | `#025AA3` | `#245F1E` | `#72BDFF` | `#8BD17C` |
| `brand` | `#209CFF` | `#58AC47` | `#209CFF` | `#58AC47` |
| `brand-secondary` | `#FF874D` | `#E3A21F` | `#FF874D` | `#E3A21F` |
| `brand-asset-surface` | 白色 | 白色 | 白色 | 白色 |

`brand`、`brand-secondary`、`brand-asset-surface` 是本專案新增的有限品牌素材 token，不取代 shadcn 的 primary、secondary、destructive。原始品牌色之外的深淺色搭配是本專案的可讀性適配，沒有宣稱為官網原值。

品牌掛在 `<html data-brand="cht|haomai">`，深色模式使用 `.dark`。因此 portal 中的 Dialog、Select、Sheet 及通知也繼承主題，不會只切到外層容器。

品牌選擇與深淺色保存在本地瀏覽器。切換品牌不重建當前展示內容，因此表單或購物車狀態可以直接比較；切換展示分頁或重新整理則重設該示範內容，不做真實資料持久化。

## 字體、尺寸與間距

- root 保留瀏覽器／Tailwind 預設 1rem＝16px，沒有從舊站匯入 `html { font-size: 15px }`。
- 字型順序：Inter Variable、PingFang TC、Microsoft JhengHei、Noto Sans TC、system-ui、sans-serif。Inter 由本機套件提供，中文依使用者系統 fallback，沒有強制載入舊站 Google Fonts weight 300。
- 頁面展示標題使用 Tailwind 的 30／36px，章節標題 24px，正文 16px，元件多為 Luma 自帶 14px。12px 只作非關鍵註記。
- 不將某個字級強制套到所有 Button／Input／CardTitle；各元件保留 preset 定義。
- 保留 Luma 元件與官方 radius 倍率，依指定主題設定 `--radius: 0`。淺／深色中性色使用使用者提供的 OKLCH tokens；兩品牌既有配色維持不變。
- Button 在 Luma 的預設高度為 36px，small 32px、large 40px；這是所選官方 preset 的尺寸，不沿用舊站自訂膠囊。未宣稱所有尺寸都符合特定行動裝置觸控目標規範。
- 間距使用 Tailwind 標準 spacing，常用 gap-2／3／4／6；字級與間距不因品牌而改。

## 對比檢查與限制

依 sRGB 相對亮度計算主要按鈕文字對比；hover 依官方 `bg-primary/80` 疊在淺色白底或深色參考表面的情境計算：

| 主題 | 一般 | hover |
| --- | --- | --- |
| 中華電信 淺色 | 7.01:1 | 4.51:1 |
| 中華電信 深色 | 7.80:1 | 5.55:1 |
| 好買市集 淺色 | 7.69:1 | 4.69:1 |
| 好買市集 深色 | 8.23:1 | 5.80:1 |

這項檢查限定本表的前景、背景與 hover 情境，不代表已完成全部元件、focus ring、disabled、圖示、所有背景組合或整站 WCAG 稽核。檢查腳本同時確認官方元件檔案未被修改及主題產物同步。

## 展示頁內容

| 分頁 | 內容 |
| --- | --- |
| 基礎規範 | 可複製品牌色碼、語意色、字級、Logo 及點數素材 |
| 元件展示 | 按鈕各 variant／size、欄位驗證、選單、Checkbox／Switch／RadioGroup／Slider、Dialog／Sheet／AlertDialog、Tabs、Accordion、通知、載入、空狀態 |
| 商城組合 | 商品、點數、收藏、數量、加入購物車、折價券重算、訂單狀態表格 |
| 元件索引 | 可搜尋的官方 registry 清單，分開標示已展示、已安裝與上游空項目，附官方文件 |

商城組合是設計展示，部分控制及版型屬提案。它沒有完成首頁、搜尋、結帳等正式商城頁，也沒有會員、點數或金流串接；不能反向當作現站功能已確認的證據。

## 開發與維護

```sh
npm ci
npm run dev
```

使用終端機印出的本機網址。檢查與建置：

```sh
npm run tokens
npm run catalog
npm run check:design
npm run typecheck
npm run build
```

| 位置 | 責任 |
| --- | --- |
| `components.json` | 官方 preset、alias、icon 與語意色設定 |
| `src/components/ui/` | CLI 元件原始碼，品牌改版不修改此層 |
| `src/components/design-system/` | 展示組合與本地示範行為 |
| `src/styles/global.css` | 官方基礎 token、字型 fallback 與全域可及性設定 |
| `src/data/brand-themes.json` | 雙品牌色彩的唯一來源 |
| `src/styles/brand-themes.css` | 生成的雙品牌／深淺色 token |
| `public/brand/` | 未修改的原站 Logo 與點數素材 |
| `scripts/check-design-system.mjs` | 比較上游檔案指紋、缺少元件、token 同步與主要文字對比 |

更新 shadcn 時先檢查 diff，再重新驗證；`research/upstream-files.json` 是本次初始化的檔案指紋，不可為了讓檢查通過而任意覆蓋。需要更新時，應在確認上游變更後一起更新基準與版本紀錄。

## 研究資料與重跑方式

- [中華電信 CSS 分析與來源指紋](research/css-analysis.json)
- [好買市集 CSS 分析與來源指紋](research/haomai-css-analysis.json)
- [Logo 與 Hami Point 素材分析](research/brand-assets.json)
- [官方 registry 清單](research/shadcn-registry.json)
- [shadcn 專案設定快照](research/shadcn-info.json)
- [官方來源檔案指紋](research/upstream-files.json)
- [實際驗證紀錄](verification.md)

```sh
python3 scripts/research-cht.py --brand cht
python3 scripts/research-cht.py --brand haomai
```

本機原始 CSS 快取在 `.cache/`，不會進入網站。Logo 像素分析可用獨立 Python 環境執行 `scripts/analyze-brand-assets.py`，其唯一額外需求為 Pillow；此工具只讀圖，不修改圖檔。重新下載時應先確認素材是否變更，再更新研究紀錄。
