跳到內容
開始使用

色彩模式(淺色/深色)

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),使色調隨色彩模式調整。