Design tokens
用語義命名的 token，theme 切換只換 value，元件永遠不寫死。
互動示範（與本規範網站人類閱讀版相同）：
/docs/design-tokens
示範對應規則
以下章節與人類版頁面互動示範所涵蓋的規則一致（文字版，供 Agent 複製）。
A. 語意 token
設計時「選值」用的語意尺度。先在這段挑 token，元件只引用 token，不寫死。
Color
不要寫死顏色（#3498DB），用語義 token：
| Token | 用途 | Light value | Dark value |
|---|---|---|---|
bg-default | 主要背景 | #FFFFFF | #0F1115 |
bg-subtle | 次要背景（卡片、區塊） | #F7F8FA | #1A1D23 |
bg-muted | 更次要的背景 | #EDF0F4 | #252830 |
text-default | 主要文字 | #1F2328 | #E6E8EB |
text-muted | 次要文字 | #6E7681 | #A0A6AD |
text-subtle | 三級文字 | #8B94A0 | #7A828B |
text-on-primary | 在 primary 底色上的文字 | #FFFFFF | #FFFFFF |
border-default | 一般 border | #E1E4E8 | #363B45 |
border-emphasis | 強調 border / divider | #D0D7DE | #444B57 |
interactive-primary | Primary button、link | #4F46E5 | #818CF8 |
interactive-primary-hover | hover | #4338CA | #A5B4FC |
interactive-secondary | Secondary button | #6E7681 | #9CA3AF |
status-success | Success | #16A34A | #22C55E |
status-warning | Warning | #CA8A04 | #EAB308 |
status-error | Error / Destructive | #DC2626 | #EF4444 |
status-info | Info | #4F46E5 | #818CF8 |
status-neutral | Neutral / muted | #6E7681 | #9CA3AF |
semantic-ink | 文字／segment active | #111111 | #E6E8EB |
semantic-sustain | 永續／碳排（非 primary） | #2D5A42 | #4ADE80 |
semantic-kraft | 輔助／圖表 accent | #B8956A | #C4A882 |
每個狀態色提供 3 階：
subtle（背景 / tag bg）：淡色，不刺眼。default（icon、文字、border）：標準色。emphasis（強調 button background）：深色，對比強。
status-success-subtle: #E6F7EC
status-success-default: #16A34A
status-success-emphasis: #15803D
Typography
| Token | Size | Weight | Line-height | 用途 |
|---|---|---|---|---|
display | 36 / 48 | 700 | 1.1 | 行銷頁標題 |
heading-1 | 24–32 | 700 | 1.2 | Page title |
heading-2 | 20 | 600 | 1.3 | Section title |
heading-3 | 16 | 600 | 1.4 | Section / 小卡標題 |
widget-title | 18 | 600 | 1.3 | 儀表板／後台白卡標題（dashboard widget） |
body-large | 16 | 400 | 1.5 | 重要正文、詳情頁內文 |
body / ui-small | 14 | 400 | 1.5 | 預設正文、KPI 列名、可讀副標 |
body-small | 13 | 400 | 1.5 | 次要正文 |
detail-data | 20 | 600 | 1.2 | 詳情 aside 大數值 |
caption | 12 | 400 | 1.4 | 麵包屑、表頭 uppercase、meta（不可當 KPI 列名） |
code | 13 | 400 | 1.5 | 等寬字 |
Dashboard 字級必守
- 儀表板／後台白卡標題必須 18px（
widget-title）。禁止用body（14px）或caption（12px）當 widget 主標題。 - 需使用者閱讀的「小字」必須 14px（
ui-small/body）。禁止把 KPI 列名、widget 副標設成caption。 - 12px（caption）僅用於麵包屑、表格欄位表頭（uppercase）、時間戳、hint 等不需長時間閱讀的 meta。
- 示範常數：
GUIDE_WIDGET_TITLE、GUIDE_KPI_LABEL（見guide-dashboard-styles.ts）。
- Line-height：Body 1.5、Heading 1.2–1.3、Code 1.5。
- Letter spacing：大標題微負 -0.02em；全大寫小字（標籤）+0.05em。
- Font family · Sans：System default 優先（San Francisco / Segoe UI / Roboto / -apple-system）→ Inter / Helvetica → sans-serif。
- Font family · Mono：SF Mono / Menlo / Consolas / monospace。
- Font family · 中文：PingFang TC / Noto Sans TC / 微軟正黑體。
- 本指南網站字體：Inter（
next/font+--font-inter）。
Spacing
space-1 = 4px
space-2 = 8px
space-3 = 12px
space-4 = 16px
space-5 = 24px
space-6 = 32px
space-7 = 48px
space-8 = 64px
使用慣例：
- icon ↔ text：8–12（space-2/3）。
- input ↔ input 同欄：12–16（space-3/4）。
- 同 section 內群組間距：16–24（space-4/5）。
- section ↔ section：24–32（space-5/6）。
- page padding（內邊距）：24–32（space-5/6）。
- card padding：16–24（space-4/5）。
- button padding：水平 12–16、垂直 6–10。
Border Radius
radius-none = 0
radius-sm = 4px input、small card
radius-md = 8px card、modal、button
radius-lg = 12px large card
radius-xl = 16px feature card
radius-full = 9999px pill、avatar
Icon System
icon-xs = 12px 小 status dot 旁
icon-sm = 16px 表格 row、inline
icon-md = 20px 按鈕、nav item（常用）
icon-lg = 24px page header、空狀態
icon-xl = 32px feature highlight
icon-2xl = 48px+ empty state 插圖
- Stroke / style：Outlined stroke 1.5–2px（跨 size 一致粗細）；Filled 用在 active / selected 狀態；同產品不混 outline 跟 filled（除非有設計理由）。
- Icon size 對應 text：16 / 20 icon → 配 14 / 16 body text；24 / 32 icon → 配標題或獨立使用。
- 禁止：用 emoji（🎨 🔔 ✓ 等）作為導覽、按鈕、狀態、空狀態的結構性圖示。
- 必須：SVG 向量圖示（
currentColor、固定 stroke 粗細）；本指南網站示範使用 Untitled UI Icons（@untitledui/icons）。 - 推薦：Lucide / Heroicons / Phosphor / Tabler（outline-based）；Material Symbols；Carbon / Atlassian / Polaris 官方 set。
Shadow / Elevation
shadow-xs : 0 1px 2px rgb(15 23 42 / 0.05)
shadow-sm : 0 1px 3px + 0 1px 2px -1px（卡片、示範框）
shadow-md : 0 4px 12px -2px（dropdown）
shadow-lg : 0 12px 28px -6px（modal、popover）
- Light mode 用陰影；Dark mode 提高 opacity（見
styles/globals.css）。 - Dark mode 亦可用「越高越亮」（surface tone）輔助層次（見
20-dark-mode-i18n.md）。
Z-index
由低到高（與 01-layout.md 同步）：
z-base = 0
z-sticky = 100
z-dropdown = 1000
z-drawer = 1100
z-modal = 1200
z-toast = 1300
z-tooltip = 1400
Motion / Duration
duration-fast = 150ms hover、focus、按鈕
duration-base = 220ms 開合 dropdown、tab 切換
duration-slow = 300ms modal、drawer
duration-slower = 500ms page transition
- Easing：
ease-out進場（cubic-bezier(0, 0, 0.2, 1)）、ease-in離場（cubic-bezier(0.4, 0, 1, 1)）、ease-in-out雙向。 - 本指南網站：
--duration-fast: 150ms、--ease-standard: cubic-bezier(0.2, 0, 0, 1)。 - 須支援
prefers-reduced-motion（關閉非必要動效）。
延伸與補充
B. 套用：把語意 token 接到實作
A 段是「規範層」（要選哪些值）；這段是「落地模式」（怎麼接到產品）。各產品把語意 token 綁到自己的 CSS 變數或 design-token 系統，變數命名隨產品慣例，元件只引用變數／utility，勿寫死色碼。
Binding pattern（與框架無關）
- 定義：每個語意 token 建一個 CSS 變數，light / dark 各給值。
- 綁定：元件用
var()或 utility 引用，不寫死 hex。 - 切主題：只換變數值，元件一行不動。
通用範例（變數名換成你產品的命名）：
:root {
--color-interactive-primary: #4f46e5; /* = 語意 interactive-primary */
--color-text-default: #1f2328; /* = 語意 text-default */
}
[data-theme="dark"] {
--color-interactive-primary: #818cf8;
--color-text-default: #e6e8eb;
}
<!-- Tailwind 任意值；其他框架用 var() 同理 -->
<button class="bg-[var(--color-interactive-primary)] text-[var(--color-on-primary)]">Save</button>
底色 ↔ 文字配對（通用規則）
選前景色看「底是什麼」，不是沿用 body 預設灰階：
- 品牌／飽和底色 → 用
text-on-primary（高對比白／淺），勿沿用 body 灰階字色。 - 淺色品牌底（如 brand-subtle）→ 用品牌色系文字，勿用一般
text-muted灰階。 - 白底／一般 surface → 用標準文字灰階系（
text-default/text-muted）。 - 浮層（dropdown / popover）在帶色容器內展開時，須重設自身前景／背景，切斷父層色繼承。