Design tokens

Token 就是一層「語意命名」:元件只說「我要主要文字色」,不說「我要 #1F2328」。這樣換主題、做深色,只改 token 的值,元件一行都不用動。當你發現自己想直接貼一個 hex、或在猶豫某個間距該抓多少時,翻這頁拿定稿單值,別自己發明。

色彩 Token

這是什麼

顏色用語意名稱(品牌色、次要文字、成功色等);深淺模式只換變數值,元件不寫死色碼。

什麼時候用

建立或擴充設計 token,確保換主題時整站一致更新。

預覽依本指南規則實作

Brand · 品牌

隨 Mobbin preset 換 value

50

brand-subtle

500

brand

700

brand-hover

Surface · 背景

content

bg-default

surface

bg-elevated

muted

bg-muted

sidebar

bg-subtle

Fills · 主色透明度

text-primary 由 100% 到 10%

100%

text-primary

85%

primary/85

70%

primary/70

55%

primary/55

40%

primary/40

25%

primary/25

10%

primary/10

Labels · 文字灰階

default

text-primary

muted

text-secondary

subtle

text-tertiary

Grays · 中性色階

由浅到深

0

content

100

surface-hover

200

sidebar-border

400

text-tertiary

600

text-secondary

900

text-primary

Border · 邊框

default

sidebar-border

table

table-border

ring

focus-ring

Status · 狀態色

subtle / default / emphasis

success

subtle

success

default

success

emphasis

warning

subtle

warning

default

warning

emphasis

error

subtle

error

default

error

emphasis

info

subtle

info

default

info

emphasis

neutral

subtle

neutral

default

neutral

emphasis

  • bg-defaulttext-mutedstatus-success 等語意 token。
  • 每個狀態色提供 subtle / default / emphasis 三階。
  • 不要寫死 #3498DB;切換 Mobbin 風格或 dark mode 時色值即時更新。

字型 Token

這是什麼

從大型展示標題到說明小字的字級階梯;內文預設約 14px、行高 1.5 倍較易讀。

什麼時候用

統一全站標題、內文、輔助說明的字級與行距。

預覽依本指南規則實作
displayDisplay 36/48
heading-1Page title
heading-2Section title
body內文 14px / 1.5
captionHelper text
TokenSize用途
display36/48行銷標題
heading-124–32Page title
body14預設正文
caption12Helper

間距 Token

這是什麼

間距以 4 像素為基礎倍數,從 4 到 64 形成固定階梯,用於內距、區塊間距、圖文間距。

什麼時候用

排版時用同一套間距 token,避免各處硬編不同像素值。

預覽依本指南規則實作
4
8
12
16
24
32
48
64
space-1 = 4px … space-8 = 64px
  • icon ↔ text:8–12;section 間:24–32;page padding:24–32。

圖示系統

這是什麼

圖示尺寸從 12 到 48 像素分級;線條粗細一致;結構性圖示用 SVG,不用 emoji 代替。

什麼時候用

按鈕、選單、表格等處選擇圖示大小,並與旁邊文字協調。

預覽依本指南規則實作
12px
16px
20px
24px
32px
48px
  • 必須 SVG(currentColor);本指南用 Untitled UI Icons
  • 16/20 icon → 配 14/16 body text。
  • 同產品不混 outline 跟 filled(除非有理由)。

圓角 Token

這是什麼

小圓角用於輸入框(約 4px)、中圓角用於卡片與按鈕(約 8px)、全圓角用於 pill 與頭像。

什麼時候用

統一各元件外框圓潤程度,讓介面風格一致。

預覽依本指南規則實作
sm 4
md 8
lg 12
full
radius-sm = 4px   input
radius-md = 8px   card, button
radius-full = 9999px   pill, avatar

陰影/層級 Token

這是什麼

淺色模式用陰影表現層級;深色模式則提高陰影透明度或改用較亮的表面色區分高低。

什麼時候用

卡片、下拉、對話框等需要表現「浮起」層級時,深淺模式各有一套做法。

預覽依本指南規則實作
shadow-xs
shadow-sm
shadow-md
shadow-lg
shadow-xs / sm / md / lg
  • Light mode 用陰影;Dark mode 提高 opacity(見 globals.css)。

本指南網站 CSS 變數

這是什麼

網站外殼與示範元件使用的 CSS 變數,須與 globals.css 定義的語意 token 一致。

什麼時候用

在本指南站內實作或更新元件時,避免另起一套硬編色值。

預覽依本指南規則實作
--color-brand
--color-sidebar
--color-content
--color-text-primary
--color-ring
CSS 變數用途
--sidebar-width左導覽 240px
--color-brand品牌主色
--color-content主內容底
--shadow-sm陰影階梯

字體:Inter;動效 --duration-fast: 150ms

顏色系統 · 複製即用

這是什麼

選語意色 token 與用途(背景/文字/邊框/status pill),產生 CSS 變數用法。

什麼時候用

套用 design token 時複製正確 var() 組合到專案。

語意色示範

字體系統 · 複製即用

這是什麼

display 到 caption 的字級 scale;切換 scale 或文案看預覽。

什麼時候用

需要複製 Tailwind class 組合到專案時。

SaaS 後台預設內文 14px / line-height 1.5

規格速查

類別定稿值
語意色bg / text / border / interactive / status,各有用途,元件不寫死 hex
狀態色階每個狀態色提供 subtle(底)/ default(icon、文字)/ emphasis(強調底)
字級 H124–32(700)
字級 H220(600)
字級 H316(600)
Widget 標題18(600) — 儀表板白卡標題,勿降為 14/12
Body / ui-small14(400)— KPI 列名、可讀副標
Detail 數值20(600)— 詳情 aside 大數
Caption12(400)— 僅 meta/表頭 uppercase,不可當 KPI 列名
Spacing4 / 8 / 12 / 16 / 24 / 32 / 48 / 64
Radiussm 4 / md 8(card、button)/ full 9999(pill、avatar)
Icon size12 / 16 / 20 / 24 / 32,outlined stroke 1.5–2px 跨 size 一致

語意 token 的「落地綁定模式」與「底色 ↔ 文字配對」通用規則在 Agent 版

常見做錯

做錯正確
元件裡寫死 hex(如 #3498DB引用語意 token / CSS 變數,換主題只改值
灰黑字配在紫色品牌底上紫底用 text-on-primary,勿沿用 body 的灰階字色
深色模式直接把淺色 invert用 dark 專屬 token 值,降飽和、不純黑純白
用 emoji 當結構性圖示用 SVG 向量圖(currentColor、固定 stroke),如 Untitled UI

相關章節