Semantic color
Semantic color 指的是將特定的顏色與特定的意義或功能綁定為顏色語意，例如紅色代表取消、黃色代表警告，一個顏色語意可以同時表示 Dark Mode 和 Light Mode，在開發時使用可以提高介面的可用性和一致性。
⚡️ 開發與設計文件：
→ Semantic Colors_Master存放於 google drive 的 Semantic color 主要文件，是所有 Semantic 衍伸文件的唯一資料來源，內容紀錄所有 Semantic color 名稱和色碼。
→ Figma Design Library設計師在 Figma 中使用的顏色系統是一種設計工具，用於專案檔的物件顏色設定，資料來源為 Semantic Colors_Master。
Intro
簡介
KKBOX 在 2022 年開始導入 Semantic 的顏色結構應用於設計交付和開發，並且讓所有設計師與各平台的開發者使用共通的文件，提升開發效率。此後，工程師拿到設計稿時不需將顏色轉譯成各自不同的 Semantic；設計師也可以透過調整 Semantic，一次性調整某種情境的顏色，同時可以間接控管顏色的使用規則，幫助人數較多的設計團隊維持設計一致性。顏色轉譯過程
設計師在 Figma 進行設計時，會套用已建立好的 Semantic Color System，工程師使用 Figma 點擊物件後，即可在右側欄的 Inspect 看到該物件使用的 Semantic。
Naming Structure of Semantic
命名規則
Guideline
顏色的語意名稱需依照規範命名，幫助夥伴管理與辨識。
Sequence
設計時，Sequence 最多不超過四層（Quaternary），讓使用者容易分辨資訊層級。
TOKEN | DESCRIPTION |
Primary | 第一層級 |
Secondary | 第二層級 |
Tertiary | 第三層級 |
Quaternary | 第四層級 |
Assistive
當顏色規則在應用時，因應某些原因產生特殊規則時，需使用 Assistive （輔助）。
舉例來說，主要的填充色在 light mode 時使用 White，但如果應用於小物件上再加上陰影，會容易影響閱讀，所以須改成 Gray5，此時使用「primaryAltContainer」。
TOKEN | DESCRIPTION |
Alt (Alternative) | 可替代的選擇 |
Characteristic
Characteristic 用來表示該顏色是否有特殊意涵，例如：紅色會被用來作為否定的意思
TOKEN | DESCRIPTION |
Negative | 否定 |
Accent | 強調 |
Brand | 品牌 |
OnDark | 在暗色之上，通常在不同主題 (Theme) 中使用相同顏色 |
OnBrand | 在品牌色之上，通常在不同主題 (Theme) 中使用相同顏色 |
OnImage | 在圖片之上，例如：圖片遮罩 (onImageOverlay)、圖片框線 (onImageBorder) |
Interactive | 可互動的 |
transparent | 半透明的 |
placeholder | 預先載入用來墊底的填充物 |
States
表示某物件在狀態中的顏色，必須要能夠與 Characteristic 並存。
TOKEN | DESCRIPTION |
Pressed | 手指點擊 |
Disabled | 不可訪問 |
Hovered | 鼠標懸浮 |
Core
Core token 是可以汎用於產品中的核心基底，設計基本需遵循 Core token 的顏色規則進行設計。
TOKEN | DESCRIPTION |
Text | 文字 |
Bg (Background) | 頁面背景色，命名時使用簡寫 |
Container | 重疊的區塊或元件背景色，例如：Card、Modal 或 Popover |
Icon | 圖標 |
Border | 元件外框線 |
Separator | 分隔線 |
Overlay | 覆蓋物 |
Components
Components token 僅用於特定元件，不可用於他處。
並非只要是 Components 就使用 Components token，而是當特定 Components 需使用特殊的顏色規則時，才會建立新的 Components token 。
TOKEN | DESCRIPTION |
Button | 按鍵 |
Banner | 橫幅 |
Bottom Navigation | 底部導航列 |
Toolbar | 工具列 |
Core Token
01 Text
primaryText / secondaryText / tertiaryText
primaryText 為主要層級的文字，可使用在標題或較需要被閱讀的文字，使用時需注意層級劃分，避免過度使用 primaryText 讓畫面資訊量過大。 secondaryText 較少單獨使用，經常依附在 primaryText 之下。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryText | Gray90 | Gray5 | 主要文字 | 頁面標題、列表、卡片標題、內文，方便用戶閱讀的主要資訊 |
primaryTextPressed | PreGray90 | PreGray5 | 主要文字點擊狀態 | |
secondaryText | Gray70 | Gray20 | 次要文字 | 頁面標題下的副標
|
secondaryTextPressed | PreGray70 | PreGray20 | 次要文字點擊狀態 | |
tertiaryText | Gray40 | Gray50 | 第三級文字 | 列表、卡片副標題，用戶想看再仔細看的次要資訊、輸入框的預設文字 |
tertiaryTextPressed | PreGray40 | PreGray50 | 第三級文字點擊狀態 |
primaryOnDarkText / tertiaryOnDarkText
onDarkText 是應用於任何模式下都是「深色底色」之上的文字，所以無論在 light / dark mode 之下文字都會顯示相同的顏色。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryOnDarkText | Gray5 | Gray5 | 應用於深色底色的主要文字 | 排行榜卡片標題文字 |
tertiaryOnDarkText | Gray50 | Gray50 | 應用於深色底色的第三級文字 | 排行榜卡片副標題文字
|
accentText
畫面中需強調的文字。文字本身不可點擊，和 Button 不同，經常用於標題或字串中。若文字右側有箭頭連接，箭頭也使用 accentText。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
accentText | StdBlueHC70 | StdBlueHC60 | 強調文字 | 延伸歌單、卡片中引導點擊的文字 |
textDisabled
表示不可訪問狀態的文字時使用 textDisabled，但「僅用於灰階文字」，不可用於表示彩色文字的不可訪問狀態。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
textDisabled | Gray20 | Gray70 | 不可訪問的文字 | 列表未授權歌曲 |
interactiveText
interactiveText 為最高層級的文字，可使用在本身可點擊的文字/標籤或較需要被閱讀的文字，通用於複雜組成的模組中，或文字段落之中。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
interactiveText | StdBlueHC70 | StdBlueHC60 | 最高層級文字 | 連結、一起聽跟聽數 |
interactiveTextPressed | PreBlueHC70 | PreBlueHC60 | 最高層級文字點擊狀態 | |
interactiveTextDisabled | PdBlueHC30 | PdBlueHC95 | 最高層級文字不可訪問狀態 |
OnBrandText
onBrandText 是應用於品牌色底色之上的文字。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
OnBrandText | Gray90 | Gray90 | 應用於品牌色底色的主要文字 | 按鈕、重要通知卡片（未開發） |
OnBrandTextDisabled | Gray20 | Gray20 | 應用於品牌色底色的主要文字不可訪問狀態 | 按鈕、重要通知卡片（未開發） |
placeholderText
應用於輸入框未輸入文字狀態的提示文字，目前僅使用於 primaryBg 上的輸入框。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
placeholderText | Gray20 | Gra70 | 輸入框提示文字 | 分類名稱輸入框 |
02 Background (Bg)
primaryBg
預設的一般頁面背景色。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryBg | White | Gray95 | 主要背景 | 畫面底色、列表背景 |
primaryBgPressed | PreWhite | PreGray95 | 主要背景點擊狀態 | 列表背景點擊狀態 |
brandBg
用於展示品牌色的頁面背景色，在 Dark mode 時轉為灰階。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
brandBg | StdBlueHC60 | Gray95 | 品牌色背景 | App 開啟畫面背景 |
03 Container
一般情況下僅使用 PrimaryContainer，疊層設計最多不超過三層（Tertairy Container）。
參考章節 Layout / Hierarchy
primaryContainer / primaryAltContainer
應用於卡片的填充色，一般情況使用 primaryContainer，小型卡片使用 primaryAltContainer。
由於 primaryContainer 在 Light mode 時與 primaryBg 顏色相同，所以應用時需使用陰影。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryContainer | White | Gray90 | 主要區塊背景 | 一起聽、Podcast、紛絲/活動徽章、新聞、Uni 歌單卡片，更多內頁卡片 |
primaryContainerPressed | PreWhite | PreGray90 | 主要區塊背景點擊狀態 | |
primaryAltContainer | Gray5 | Gray90 | 可替代的主要區塊背景
⚠️ 不可置於 primaryContainer 上 | 最近播放小卡、個人頁聆聽成就區塊 |
primaryAltContainerPressed | PreGray5 | PreGray90 | 次要區塊背景點擊狀態 |
secondaryContainer / secondaryAltContainer
SecondaryContainer 在 light mode 時顏色較淺，可以作為區塊底色，使用於物件底色時需特別注意是否會顏色過淡。 若應用於小型物件，需使用 SecondaryAltContainer 提升 light mode 能見度。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
secondaryContainer | Gray5 | Gray80 | 第二級區塊背景
⚠️ 可置於 primaryContainer 上 | 更多頁上半部底色 |
secondaryContainerPressed | PreGray5 | PreGray80 | 第二級區塊背景點擊狀態 | |
secondaryAltContainer | Gray10 | Gray80 | 可替代的第二級區塊背景
⚠️ 不可置於 SecondaryContainer 上 | Pill Tab, Search Bar |
secondaryAltContainerPressed | PreGray10 | PreGray80 | 第二級區塊背景點擊狀態 |
TertiaryContainer
應用於 Secondary Container 之上的物件填充色，一般不會單獨使用。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
tertiaryContainer | White | Gra70 | 第三級區塊背景
⚠️ 可置於 SecondaryContainer 上 | 更多頁上半部小卡底色 |
tertiaryContainerPressed | PreWhite | PreGray70 | 第三級區塊背景點擊狀態 |
brandContainer
品牌色填充色用來展示品牌設計，在 dark mode 時會轉為灰階設計。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
brandContainer | StdBlueHC20 | Gray90 | 品牌色塊 | 花生背景 |
accentContainer
用於重要提示訊息的背景色。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
accentContainer | StdBlueHC20 | PdBlueHC95 | 重要提示訊息 | 底色蓋板訊息 |
negativeContainer
否定性質的物件填充色。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
negativeContainer | RedHC60 | RedHC60 | 否定色塊 | 左滑刪除按鈕 |
interactiveContainer
表示互動性質的物件填充色，常見於 Control 類型的物件中。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
interactiveContainer | StdBlueHC60 | StdBlueHC60 | 帶有互動性質的元件 | Toggle button、Slider |
interactiveContainerPressed | PreBlueHC60 | PreBlueHC60 | 帶有互動性質的元件點擊狀態 | |
interactiveContainerDisabled | PdBlueHC30 | PdBlueHC95 | 帶有互動性質的元件不可訪問狀態 |
transparentContainer
半透明的填充色，通常用於「前景」物件的背景色，因半透明特性讓使用者可以看到原頁面的狀態。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryTransparentContainer | Black
85% | Black
85% | 深半透明背景色 | Toast |
secondaryTransparentContainer | Black
40% | Black
40% | 中深半透明背景色 | Icon Button 底色 |
tertiaryTransparentContainer | Black
20% | Black
20% | 淺半透明背景色 | 半透明 Search Bar 填充色 |
placeholderContainer
圖片載入前預先顯示的預設圖填充色。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
placeholderContainer | Gray20 | Gray70 | 內容載入前的填充色 | Default Image、Loading Logo |
04 Border
Border
預設的物件框線，使用於不需特別凸顯的物件，通常物件無填充色，顏色與 primaryBg 相同。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
Border | Gray10 | Gray80 | 主要邊框 | AD banner |
onImageBorder
應用於圖片的框線。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
onImageBorder | Black
10% | White
10% | 圖片邊框 | 專輯、歌單封面、藝人圖等內框線 |
05 Separator
Separator
預設的物件分隔線，通常用於區隔列表或物件區塊。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
Separator | Gray10 | Gray80 | 分隔線 | 列表、區塊分隔線 |
06 Icon
primaryIcon / secondaryIcon
primaryIcon 為主要的圖標顏色，應用於需要讓使用者注意的按鈕類型圖標；secondaryIcon 則應用於輔助類型的圖標，例如：列表中的引導箭頭或更多 (3 more)。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryIcon | Gray70 | Gray20 | 主要圖標 | 頂部導航列、列表標題前的圖標 |
primaryIconPressed | PreGray70 | PreGray20 | 主要圖標點擊狀態 | |
secondaryIcon | Gray40 | Gray50 | 次要圖標 | 更多箭頭、列表 action icon、等待下載狀態 |
secondaryIconPressed | PreGray40 | PreGray50 | 次要圖標點擊狀態 |
PrimaryOnDarkIcon / SecondaryOnDarkIcon
onDarkIcon 是應用於任何模式下都是「深色底色」之上的圖標，所以無論在 light / dark mode 之下圖標都會顯示相同的顏色。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryOnDarkIcon | Gray5 | Gray5 | 應用在深色底色上的主要圖標 | Top Navigation |
primaryOnDarkIconPressed | PreGray5 | PreGray5 | 應用在深色底色上的主要圖標點擊狀態 | |
secondaryOnDarkIcon | Gray20 | Gray20 | 應用在深色底色上的次要圖標 | 刪除 Icon (垃圾桶)、歌單上半部、Uni hover |
secondaryOnDarkIconPressed | PreGray20 | PreGray20 | 應用在深色底色上的次要圖標點擊狀態 | |
tertiaryOnDarkIcon | Gray50 | Gray50 | 應用在深色底色上的第三級圖標 | 半透明 search bar |
tertiaryOnDarkIconPressed | PreGray50 | PreGray50 | 應用在深色底色上的第三級圖標點擊狀態 |
onBrandIcon
onBrandIcon 應用於底色是 StdBlueHC60 或StdBlueHC50 的圖標。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
onBrandIcon | Gray90 | Gray90 | 至於品牌色之上的圖標顏色 | primary pill button |
onBrandIconDisabled | Gray20 | Gray90 | 至於品牌色之上的圖標顏色不可訪問狀態 |
interactiveIcon
表示活躍狀態或選取狀態若文字右側有箭頭連接，「箭頭使用文字的顏色」。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
interactiveIcon | StdBlueHC60 | StdBlueHC60 | 活躍狀態、選取狀態的圖標 | 收藏、追蹤、關注 |
interactiveIconPressed | PreBlueHC60 | PreBlueHC60 | 活躍狀態、選取狀態的圖標點擊狀態 | |
interactiveIconDisabled | PdBlueHC15 | PdBlueHC95 | 活躍狀態、選取狀態的圖標不可訪問狀態 |
negativeIcon
否定性質的圖標。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
negativeIcon | RedHC60 | RedHC60 | 否定圖標 | 刪除 Icon (禁止符號)、下載錯誤 |
iconDisabled
表示不可訪問狀態的圖標時使用 iconDisabled，但「僅用於灰階圖標」，「不可」用於表示 interactiveIcon 的不可訪問狀態。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
iconDisabled | Gray20 | Gray70 | 不可訪問的圖標 | 不可訪問的圖標、已下載 |
placeholderIcon
圖片載入前，預先顯示的預設圖上的圖標顏色
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
placeholderIcon | Gray10 | Gray50 | 照片預設圖的圖標顏色 | Default Image |
07 Overlay
Overlay
顯示對話框或其他視窗時，覆蓋全頁的半透明填充色。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
Overlay | Black
70% | Black
70% | 半透明背景色 | Dialog、Action Sheet 等背景遮罩 |
primaryOnImageOverlay / secondarOnImageOverlay
覆蓋在圖片上方的填充色，一般為帶有透明度的遮罩。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryOnImageOverlay | Black
70% | Black
70% | 主要遮罩 | 歌單內頁封面圖背景，排行榜內頁卡片上半部背景，曲風情境卡片底色 |
secondaryOnImageOverlay | Black
50% | Black
50% | 次要遮罩 | 正在播放的歌曲列表封面圖 |
Components Tokens
01 Btn
應用於 Button 元件，不可使用他處。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
primaryBtn | StdBlueHC50 | StdBlueHC60 | 主要按鈕 | PrimaryPillBtn, PrimaryBlockBtn |
primaryBtnPressed | PreBlueHC50 | PreBlueHC60 | 主要按鈕點擊狀態 | |
primaryBtnDisabled | PdBlueHC15 | PdBlueHC95 | 主要按鈕不可訪問狀態 | |
secondaryBtn | Gray90 | Gray5 | 次要按鈕 | SecondaryPillBtn, SecondaryBlockBtn |
secondaryBtnPressed | PreGray90 | PreGray5 | 次要按鈕點擊狀態 | |
secondaryBtnDisabled | Gray20 | Gray70 | 次要按鈕不可訪問狀態 | |
tertiaryBtn | Gray90 | Gray5 | 第三級按鈕 | tertiaryPillBtn, tertiaryBlockBtn |
tertiaryBtnPressed | PreGray90 | PreGray5 | 第三級按鈕點擊狀態 | |
tertiaryBtnDisabled | Gray20 | Gray70 | 第三級按鈕不可訪問狀態 | |
tertiaryAccentBtn | StdBlueHC70 | StdBlueHC60 | 第三級強調按鈕（無外框或底色） | tertiaryAccentPillBtn, tertiaryAccentBlockBtn |
tertiaryAccentBtnPressed | PreBlueHC70 | PreBlueHC60 | 第三級強調按鈕點擊狀態 | |
tertiaryAccentBtnDisabled | PdBlueHC30 | PdBlueHC95 | 第三級強調按鈕不可訪問狀態 |
02 Banner
應用於 Fix Banner 元件，不可使用他處。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
banner | StdBlueHC10 | Gray80 | 固定橫幅 | 離線模式我的頁 Banner |
03 Bottom Navigation
應用於底部導航列。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
bottomNav | Gray50 | Gray40 | 底部導航列 | Bottom Navigation icon & Text |
04 Toolbar
iOS 應用於底部工具列；Android 應用於頂部導航列。
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
toolbar (iOS) | Gray10 | Gray80 | iOS 工具列 | tool bar (⚠️ iOS only) |
SEMANTIC | LIGHT | DARK | DESCRIPTION | USAGE |
toolbar (iOS) | StdBlueHC20 | PdBlueHC95 | Android 工具列 | Android Edit Mode (⚠️ Android only) |