色彩模式(淺色/深色)
UIKit 內建淺色(預設)與深色兩種色彩模式。原則是:只有語意色和陰影會換。 基礎 Foundations 的色票(所有網站共用)不會變;元件只使用語意色和元件 token。所以深色模式只需要重新指定語意色和陰影,所有元件就會自動跟著變。
「色彩模式」和「主題」是兩回事:主題是一組有名字的外觀設定(Default、Green Natural…),一個網站選用一個主題;色彩模式決定淺色或深色。兩者可以自由組合,每個主題都有淺色和深色。詳見主題總覽。
目前主題的色彩(淺色/深色)
章節連結:目前主題的色彩(淺色/深色)目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題
下表跟著頁首的「主題」選單變。每一列是一個顏色用途(語意色),左邊是淺色模式用的顏色,右邊是深色模式用的顏色。標「這個主題改過」的列,是這個主題和預設主題(Default)不同的地方;標「示意」的主題,顏色不是正式的值。
| 用途 | 變數名稱(工程用) | 淺色 | 深色 |
|---|---|---|---|
| 主色 | --tc-color-brand-primary | #1B2D58 | #A9C2EA |
| 主色(滑鼠移上時;連結文字也用它) | --tc-color-brand-primary-hover | #30559F | #C2D4F2 |
| 品牌底色(襯在內容後的品牌色塊) | --tc-color-brand-surface | #E8EEFE | #1B2D58 |
| 品牌底色(滑鼠移上時) | --tc-color-brand-surface-hover | #D1DEFF | #30559F |
| 中性底色 | --tc-color-neutral-surface | #F2F2F2 | #333333 |
| 中性底色(滑鼠移上時) | --tc-color-neutral-surface-hover | #E0E0E0 | #4F4F4F |
| 文字 | --tc-color-text-default | #333333 | #F2F2F2 |
| 次要文字 | --tc-color-text-muted | #828282 | #B3B3B3 |
| 停用文字 | --tc-color-text-disabled | #B3B3B3 | #828282 |
| 主色上的文字 | --tc-color-text-on-brand | #FFFFFF | #1B2D58 |
| 背景 | --tc-color-surface-default | #FFFFFF | #1C1C1E |
| 淡背景 | --tc-color-surface-subtle | #F8F8F8 | #161618 |
| 邊框 | --tc-color-border-default | #BDBDBD | #6B6B6E |
| 強調邊框 | --tc-color-border-strong | #828282 | #95969B |
| 焦點框(用鍵盤選到時的外框) | --tc-color-border-focus | #4F7BBE | #A9C2EA |
| 錯誤提示 | --tc-color-feedback-error | #D4494F | #F08A8E |
| 成功提示 | --tc-color-feedback-success | #168967 | #3FBF8F |
| 警告提示 | --tc-color-feedback-warning | #B45309 | #FBBF24 |
| 資訊提示 | --tc-color-feedback-info | #1B2D58 | #A9C2EA |
| 用途 | 變數名稱(工程用) | 淺色 | 深色 |
|---|---|---|---|
| 主色 這個主題改過 | --tc-color-brand-primary | #0F4A37 | #8FD8B5 |
| 主色(滑鼠移上時;連結文字也用它) 這個主題改過 | --tc-color-brand-primary-hover | #16704F | #ACE3C8 |
| 品牌底色(襯在內容後的品牌色塊) 這個主題改過 | --tc-color-brand-surface | #E6F4EC | #0F4A37 |
| 品牌底色(滑鼠移上時) 這個主題改過 | --tc-color-brand-surface-hover | #CDEBDB | #16704F |
| 中性底色 | --tc-color-neutral-surface | #F2F2F2 | #333333 |
| 中性底色(滑鼠移上時) | --tc-color-neutral-surface-hover | #E0E0E0 | #4F4F4F |
| 文字 | --tc-color-text-default | #333333 | #F2F2F2 |
| 次要文字 | --tc-color-text-muted | #828282 | #B3B3B3 |
| 停用文字 | --tc-color-text-disabled | #B3B3B3 | #828282 |
| 主色上的文字 這個主題改過 | --tc-color-text-on-brand | #FFFFFF | #0F4A37 |
| 背景 | --tc-color-surface-default | #FFFFFF | #1C1C1E |
| 淡背景 | --tc-color-surface-subtle | #F8F8F8 | #161618 |
| 邊框 | --tc-color-border-default | #BDBDBD | #6B6B6E |
| 強調邊框 | --tc-color-border-strong | #828282 | #95969B |
| 焦點框(用鍵盤選到時的外框) 這個主題改過 | --tc-color-border-focus | #2E9E74 | #8FD8B5 |
| 錯誤提示 | --tc-color-feedback-error | #D4494F | #F08A8E |
| 成功提示 | --tc-color-feedback-success | #168967 | #3FBF8F |
| 警告提示 | --tc-color-feedback-warning | #B45309 | #FBBF24 |
| 資訊提示 這個主題改過 | --tc-color-feedback-info | #0F4A37 | #8FD8B5 |
試試看
章節連結:試試看按頁首的「色彩模式」按鈕(淺色時是月亮,深色時是太陽),或下面的切換鈕,下面的範例會即時換成淺色或深色。這裡同時有頁首的按鈕和下面的切換鈕,只是為了示範;正式網站一頁只放一個切換鈕。
運作原理:三層怎麼接起來
章節連結:運作原理:三層怎麼接起來這裡的三層是:基礎 Foundations → 語意色 → 元件 token。主題和色彩模式改的都是中間那一層(語意色)。
以實心按鈕為例:按鈕的底色是元件 token button.filled.bg,它指向語意色 color.brand.primary(品牌主色);品牌主色在淺色模式指向基礎色 color.blue.900,在深色模式改指向較亮的 color.blue.300。按鈕本身完全不用改,深色模式只換了中間那一層的指向。
深色色票對照
章節連結:深色色票對照下表直接從設計數值(token)的原始檔產生(基礎 Foundations 的色票+淺色語意色+深色覆寫)。一般文字的對比值至少要 4.5 : 1(WCAG 2.1 的 AA 級)才算容易閱讀;目前淺色的次要文字 color.text.muted 在白底還不到 4.5 : 1,正等美編(設計)修正。
--tc-color-brand-primary #1B2D58 #A9C2EA --tc-color-brand-primary-hover #30559F #C2D4F2 --tc-color-brand-surface #E8EEFE #1B2D58 --tc-color-brand-surface-hover #D1DEFF #30559F --tc-color-neutral-surface #F2F2F2 #333333 --tc-color-neutral-surface-hover #E0E0E0 #4F4F4F --tc-color-text-default #333333 #F2F2F2 --tc-color-text-muted #828282 #B3B3B3 --tc-color-text-disabled #B3B3B3 #828282 --tc-color-text-on-brand #FFFFFF #1B2D58 --tc-color-surface-default #FFFFFF #1C1C1E --tc-color-surface-subtle #F8F8F8 #161618 --tc-color-border-default #BDBDBD #6B6B6E --tc-color-border-strong #828282 #95969B --tc-color-border-focus #4F7BBE #A9C2EA --tc-color-feedback-error #D4494F #F08A8E --tc-color-feedback-success #168967 #3FBF8F --tc-color-feedback-warning #B45309 #FBBF24 --tc-color-feedback-info #1B2D58 #A9C2EA 給工程師
章節連結:給工程師以下是給工程師的啟用方式和設計決策,美編(設計)、網站的編輯和致遠(廠商)可以略過。
啟用方式
章節連結:啟用方式深色色票包在兩個選擇器(selector)內,由 @tzuchi/tokens/tokens.css 一併提供:
:root { /* 淺色:primitives + 語意 + 元件 */ }
[data-theme='dark'] { /* 語意色和陰影的覆寫 */ }
@media (prefers-color-scheme: dark) { :root:not([data-theme='light']) { /* 系統自動,除非明確選擇淺色 */ }}- 手動:在
<html>設定data-theme="dark"或"light"。 - 系統自動:未設定
data-theme時,跟隨作業系統prefers-color-scheme。 - 元件:用
<tc-theme-toggle>切換並記憶選擇。
三層在 CSS 裡是 var() 串接,Shadow DOM 裡面也一樣:
--tc-button-filled-bg → var(--tc-color-brand-primary)--tc-color-brand-primary → var(--tc-color-blue-300) (僅深色區塊覆寫此行)關鍵設計決策
章節連結:關鍵設計決策- 品牌色反轉(Material-3 tonal):深色模式的
color.brand.primary由深靛藍color.blue.900改指向較亮的color.blue.300,在深色面上才讀得清楚。連帶地color.text.on-brand由白色翻轉為深靛藍(白字在淺藍底對比不足),因此實心按鈕在深色模式是「淺藍底+深藍字」。 - 表面分層:深色模式的
color.surface.subtle比color.surface.default更深,讓卡片以色階浮起,不全靠陰影。 - 陰影加強:深色模式
--tc-elevation-*提高黑色不透明度(純黑陰影在深色面上幾乎不可見)。 - 回饋色提亮:
color.feedback.error/color.feedback.success在深色改用較亮的基礎色,作為深色面上的前景文字仍達 AA。
擴充:新增元件時
章節連結:擴充:新增元件時引用語意色(--tc-color-surface-default、--tc-color-text-default、--tc-color-brand-primary…)
而非 primitive 或寫死色碼,元件即自動支援深色。勿將 color-mix(... , white) 寫死白色作為底色,
請改用 var(--tc-color-surface-default),使色調隨色彩模式調整。