設計令牌

令牌（token）是設計語言的變數化：顏色、字級、間距、圓角、陰影、動畫時長都命名成 --lh-* CSS 變數，元件只消費名字、不寫死值。換膚就是換令牌。

三層令牌

層	位置	數量	求值時機	可覆蓋性
CSS 變數 · 明色	styles/theme/common/var.scss 的 :root	185 條	執行時	✅ 任意覆蓋
CSS 變數 · 暗色	styles/theme/common/var-dark.scss 的 [data-theme='dark'], .dark	118 條	執行時	✅
SCSS 變數	styles/theme/common/variables.scss	183 個	編譯期	⚠️ 只能改原始碼重編譯

明色令牌（var.scss）

:root {
  --lh-primary-color: #2B4C7C;
  --lh-text-primary: rgba(0, 0, 0, 0.88);
  --lh-bg-color: #FAF6F0;
  --lh-border-color: #e5e6eb;
  --lh-radius-base: 6px;
  --lh-spacing-base: 8px;
  // ... 185 條
}

暗色覆蓋（var-dark.scss）

[data-theme='dark'],
.dark {
  --lh-bg-color: #2A2520;
  --lh-text-primary: #E8E0D8;
  --lh-border-color: #3A3530;
  // ... 118 條
}

暗色是覆蓋層而非獨立一套：只寫需要翻轉的 118 條，其餘沿用明色值。

SCSS 變數（variables.scss）

$lh-primary-color: #2B4C7C !default;
$lh-border-radius-base: 6px !default;
// ... 183 個

SCSS 變數的用途是參與編譯期計算：顏色混合（mix() / shade()）、陰影合成（多層 shadow 相加）這類 CSS 變數做不到的事。代價是編譯期烤死——暗色下不會自動翻轉。

令牌的分層結構

令牌分三檔，前兩檔在全域主題檔案、第三檔在各元件自己的樣式裡：

// 1. SCSS 變數（variables.scss，編譯期）
$lh-primary: #2B4C7C !default;
$lh-text-primary: #2C2C2C !default;

// 2. 全域 CSS 變數（var.scss 的 :root，190 條）
--lh-primary-color: #{$lh-primary};
--lh-text-primary: #{$lh-text-primary};
--lh-bg-color: #FAF6F0;

// 3. 元件級變數（元件自身 scss，作用域是元件 BEM 根）
.lh-card {
  --lh-card-bg: var(--lh-bg-color, #FAF6F0);
  --lh-card-border-radius: calc(var(--lh-border-radius-base, 2px) + 2px);
}

關鍵機制：

• 第 1、2 檔之間是編譯期內插，不是 var() 引用鏈：--lh-primary-color 的值在構建時由 $lh-primary 烤進來，執行時改 SCSS 變數無效（得重編譯）。專案裡沒有「基礎調色盤」中間層——不存在 --lh-blue-6 這類色階變數，語義令牌直接由 SCSS 變數生成。
• 換膚的兩個槓桿點：改 variables.scss 的 SCSS 變數重編譯（影響全部語義令牌），或執行時覆蓋 :root 上的 CSS 變數（ConfigProvider 的 themeVars 走這條路，即時生效）。
• 第 3 檔預設引用第 2 檔：元件級變數的預設值通常是全域令牌的 var() 引用（帶回落），既保持主題連動，又能用 themeVars 定向覆蓋單個元件。

語義域

主要語義域（完整分組見下方令牌表）：

域	典型令牌	用途
主色	--lh-primary-color / -hover / -active / -bg / -border	品牌主色五件套
文字	--lh-text-primary / -secondary / -tertiary / -disabled	四級文字層級
背景	--lh-bg-color / -page / -secondary / -overlay	頁面 / 容器 / 遮罩
邊框	--lh-border-color / -light / -dark	描邊
狀態	--lh-success-color / -warning / -error / -danger / -info	五個語義色
圓角	--lh-radius-small / -base / -large / -circle	四檔圓角
間距	--lh-spacing-*	8px 基準刻度
字級	--lh-font-size-*	字級階梯
陰影	--lh-shadow-*	陰影層級
動畫	--lh-animation-duration-* / -timing-function	過渡節奏
裝飾	--lh-decoration-color	國風裝飾色

令牌全表

主色与衍生语义

令牌	明色	暗色	SCSS 源	备注
--lh-primary-color		#3D649E	$lh-primary
--lh-primary-color-hover		#5078AB	$lh-primary-hover
--lh-primary-color-active		#2B4C7C	$lh-primary-active
--lh-primary-color-bg		color-mix(in srgb, var(--lh-primary-color) 25%, transparent)	$lh-primary-light
--lh-primary-color-border		#2A3A4A	$lh-primary-lighter
--lh-color-on-primary		#fff	$lh-on-primary

状态

令牌	明色	暗色	SCSS 源	备注
--lh-hover-bg-color		rgba(255, 255, 255, 0.08)	$lh-hover-bg
--lh-selected-color		color-mix(in srgb, var(--lh-primary-color) 40%, #fff)	—

功能色

令牌	明色	暗色	SCSS 源	备注
--lh-success-color		#6FA36E	$lh-success
--lh-success-color-hover		#82B581	$lh-success-hover
--lh-success-color-active		#5B8C5A	$lh-success-active
--lh-success-color-bg		#1A2A1A	$lh-success-light
--lh-warning-color		#D4B76F	$lh-warning
--lh-warning-color-hover		#E0C680	$lh-warning-hover
--lh-warning-color-active		#C4A35A	$lh-warning-active
--lh-warning-color-bg		#2A251A	$lh-warning-light
--lh-danger-color		#C45050	$lh-danger
--lh-danger-color-hover		#D46060	$lh-danger-hover
--lh-danger-color-active		#B23A3A	$lh-danger-active
--lh-danger-color-bg		#2A1A1A	$lh-danger-light
--lh-info-color		#8F8F8F	$lh-info
--lh-info-color-hover		#A0A0A0	$lh-info-hover
--lh-info-color-active		#7A7A7A	$lh-info-active
--lh-info-color-bg		#1A1A1A	$lh-info-light

国风装饰色

令牌	明色	暗色	SCSS 源	备注
--lh-gold-color		#D4A843	$lh-gold
--lh-gold-color-hover		#E8C35C	$lh-gold-hover
--lh-gold-color-active		#B8860B	$lh-gold-active
--lh-gold-color-bg		#2A241A	$lh-gold-light
--lh-gold-color-border		#3A2E1A	$lh-gold-lighter
--lh-vermilion-color		#E85D4A	$lh-vermilion
--lh-vermilion-color-hover		#FF7B6B	$lh-vermilion-hover
--lh-vermilion-color-active		#C43A31	$lh-vermilion-active
--lh-vermilion-color-bg		#2A1A18	$lh-vermilion-light
--lh-jade-color		#7AAE7A	$lh-jade
--lh-jade-color-hover		#9CC89C	$lh-jade-hover
--lh-jade-color-active		#5B8C5A	$lh-jade-active
--lh-jade-color-bg		#1A2A1A	$lh-jade-light
--lh-decoration-color		rgba(212, 168, 67, 0.08)	$lh-decoration-color

文本

令牌	明色	暗色	SCSS 源	备注
--lh-text-primary		#E8E0D8	$lh-text-primary
--lh-text-regular		#C8C0B8	$lh-text-regular
--lh-text-secondary		#A09890	$lh-text-secondary
--lh-text-placeholder		#7A7270	$lh-text-placeholder
--lh-text-disabled		#5A5250	$lh-text-disabled

边框

令牌	明色	暗色	SCSS 源	备注
--lh-border-color-base		#3A3530	$lh-border-color-base
--lh-border-color-light		#302B28	$lh-border-color-light
--lh-border-color-lighter		#2A2520	$lh-border-color-lighter
--lh-border-color-extra-light		#242018	$lh-border-color-extra-light

圆角

令牌	明色	暗色	SCSS 源	备注
--lh-border-radius-base		沿用明色	$lh-border-radius-base
--lh-border-radius-small		沿用明色	$lh-border-radius-small
--lh-border-radius-round		沿用明色	$lh-border-radius-round
--lh-border-radius-circle		沿用明色	$lh-border-radius-circle

背景

令牌	明色	暗色	SCSS 源	备注
--lh-bg-color		#2A2520	$lh-bg-color
--lh-bg-color-page		#1E1A16	$lh-bg-color-page
--lh-bg-color-disabled		#242018	$lh-bg-color-disabled
--lh-bg-color-overlay		rgba(10, 8, 6, 0.7)	$lh-bg-color-overlay

阴影

令牌	明色	暗色	SCSS 源	备注
--lh-box-shadow-base		0 2px 12px 0 rgba(0, 0, 0, 0.5)	$lh-box-shadow-base
--lh-box-shadow-light		0 2px 4px 0 rgba(0, 0, 0, 0.4)	$lh-box-shadow-light
--lh-box-shadow-lighter		0 0 4px 0 rgba(0, 0, 0, 0.3)	$lh-box-shadow-lighter

字体

令牌	明色	暗色	SCSS 源	备注
--lh-font-family		沿用明色	$lh-font-family
--lh-font-size-extra-large		沿用明色	$lh-font-size-extra-large
--lh-font-size-large		沿用明色	$lh-font-size-large
--lh-font-size-medium		沿用明色	$lh-font-size-medium
--lh-font-size-base		沿用明色	$lh-font-size-base
--lh-font-size-small		沿用明色	$lh-font-size-small
--lh-font-size-extra-small		沿用明色	$lh-font-size-extra-small
--lh-font-weight-primary		沿用明色	$lh-font-weight-primary
--lh-font-weight-bold		沿用明色	$lh-font-weight-bold
--lh-font-line-height-primary		沿用明色	$lh-font-line-height-primary

组件级 · control

令牌	明色	暗色	SCSS 源	备注
--lh-control-height-mini		沿用明色	$lh-control-height-mini
--lh-control-height-small		沿用明色	$lh-control-height-small
--lh-control-height-medium		沿用明色	$lh-control-height-medium
--lh-control-height-large		沿用明色	$lh-control-height-large
--lh-control-height-x-large		沿用明色	$lh-control-height-x-large

间距

令牌	明色	暗色	SCSS 源	备注
--lh-spacing-xs		沿用明色	$lh-spacing-xs
--lh-spacing-sm		沿用明色	$lh-spacing-sm
--lh-spacing-md		沿用明色	$lh-spacing-md
--lh-spacing-base		沿用明色	$lh-spacing-base
--lh-spacing-lg		沿用明色	$lh-spacing-lg
--lh-spacing-xl		沿用明色	$lh-spacing-xl
--lh-spacing-xxl		沿用明色	$lh-spacing-xxl

层级

令牌	明色	暗色	SCSS 源	备注
--lh-z-index-normal		沿用明色	$lh-z-index-normal
--lh-z-index-dropdown		沿用明色	$lh-z-index-dropdown
--lh-z-index-sticky		沿用明色	$lh-z-index-sticky
--lh-z-index-fixed		沿用明色	$lh-z-index-fixed
--lh-z-index-modal-backdrop		沿用明色	$lh-z-index-modal-backdrop
--lh-z-index-modal		沿用明色	$lh-z-index-modal
--lh-z-index-popover		沿用明色	$lh-z-index-popover
--lh-z-index-tooltip		沿用明色	$lh-z-index-tooltip

过渡

令牌	明色	暗色	SCSS 源	备注
--lh-transition-duration-fast		沿用明色	$lh-transition-duration-fast
--lh-transition-duration-base		沿用明色	$lh-transition-duration-base
--lh-transition-duration-slow		沿用明色	$lh-transition-duration-slow
--lh-transition-function-ease-in-out		沿用明色	$lh-transition-function-ease-in-out

禁用态

令牌	明色	暗色	SCSS 源	备注
--lh-disabled-bg-color		#242018	$lh-disabled-bg-color
--lh-disabled-text-color		#5A5250	$lh-disabled-text-color
--lh-disabled-border-color		#302B28	$lh-disabled-border-color
--lh-disabled-opacity		0.5	$lh-disabled-opacity

组件级 · popover

令牌	明色	暗色	SCSS 源	备注
--lh-popover-bg-color		#2A2520	$lh-popover-bg-color
--lh-popover-border-color		#3A3530	$lh-popover-border-color
--lh-popover-border-radius		沿用明色	$lh-popover-border-radius
--lh-popover-padding		沿用明色	$lh-popover-padding
--lh-popover-title-color		#E8E0D8	$lh-popover-title-color
--lh-popover-content-color		#C8C0B8	$lh-popover-content-color
--lh-popover-arrow-size		沿用明色	$lh-popover-arrow-size

组件级 · popconfirm

令牌	明色	暗色	SCSS 源	备注
--lh-popconfirm-padding		沿用明色	$lh-popconfirm-padding
--lh-popconfirm-icon-size		沿用明色	$lh-popconfirm-icon-size

组件级 · drawer

令牌	明色	暗色	SCSS 源	备注
--lh-drawer-bg-color		#2A2520	$lh-drawer-bg-color
--lh-drawer-border-color		#3A3530	$lh-drawer-border-color
--lh-drawer-header-padding		沿用明色	$lh-drawer-header-padding
--lh-drawer-body-padding		沿用明色	$lh-drawer-body-padding
--lh-drawer-footer-padding		沿用明色	$lh-drawer-footer-padding
--lh-drawer-title-color		#E8E0D8	$lh-drawer-title-color
--lh-drawer-close-size		沿用明色	$lh-drawer-close-size

组件级 · dropdown

令牌	明色	暗色	SCSS 源	备注
--lh-dropdown-bg-color		#2A2520	$lh-dropdown-bg-color
--lh-dropdown-border-color		#3A3530	$lh-dropdown-border-color
--lh-dropdown-border-radius		沿用明色	$lh-dropdown-border-radius
--lh-dropdown-padding		沿用明色	$lh-dropdown-padding
--lh-dropdown-item-height		沿用明色	$lh-dropdown-item-height
--lh-dropdown-item-padding		沿用明色	$lh-dropdown-item-padding
--lh-dropdown-item-color		#C8C0B8	$lh-dropdown-item-color
--lh-dropdown-item-hover-bg-color		var(--lh-hover-bg-color)	$lh-dropdown-item-hover-bg-color
--lh-dropdown-divider-color		#302B28	$lh-dropdown-divider-color

组件级 · message

令牌	明色	暗色	SCSS 源	备注
--lh-message-bg		#2A2520	$lh-message-bg-color
--lh-message-border		#3A3530	$lh-message-border-color
--lh-message-color		#C8C0B8	$lh-message-content-color
--lh-message-shadow		沿用明色	$lh-message-shadow

组件级 · notification

令牌	明色	暗色	SCSS 源	备注
--lh-notification-bg		#2A2520	$lh-notification-bg-color
--lh-notification-border		#3A3530	$lh-notification-border-color
--lh-notification-title-color		#E8E0D8	$lh-notification-title-color
--lh-notification-content-color		#C8C0B8	$lh-notification-content-color
--lh-notification-width		沿用明色	$lh-notification-width
--lh-notification-gap		沿用明色	$lh-notification-gap
--lh-notification-shadow		沿用明色	$lh-notification-shadow

组件级 · loading

令牌	明色	暗色	SCSS 源	备注
--lh-loading-bg		rgba(10, 8, 6, 62%)	$lh-loading-bg-color
--lh-loading-text-color		#C8C0B8	$lh-loading-text-color

组件级 · timeline

令牌	明色	暗色	SCSS 源	备注
--lh-timeline-line		#302B28	$lh-timeline-line
--lh-timeline-dot		var(--lh-info-color)	$lh-timeline-dot
--lh-timeline-timestamp		var(--lh-text-secondary)	$lh-timeline-timestamp

组件级 · collapse

令牌	明色	暗色	SCSS 源	备注
--lh-collapse-border		#302B28	$lh-collapse-border

组件级 · rate

令牌	明色	暗色	SCSS 源	备注
--lh-rate-active		var(--lh-warning-color)	$lh-rate-active

组件级 · segmented

令牌	明色	暗色	SCSS 源	备注
--lh-segmented-bg		#242018	$lh-segmented-bg

组件级 · calendar

令牌	明色	暗色	SCSS 源	备注
--lh-calendar-border		var(--lh-border-color-lighter)	$lh-calendar-border

组件级 · affix

令牌	明色	暗色	SCSS 源	备注
--lh-affix-z-index		沿用明色	$lh-affix-z-index

组件级 · backtop

令牌	明色	暗色	SCSS 源	备注
--lh-backtop-z-index		沿用明色	$lh-backtop-z-index

组件级 · menu

令牌	明色	暗色	SCSS 源	备注
--lh-menu-bg		#242018	$lh-menu-bg
--lh-menu-padding		沿用明色	$lh-menu-padding
--lh-menu-border		#302B28	$lh-menu-border
--lh-menu-height		沿用明色	$lh-menu-height
--lh-menu-collapse-width		沿用明色	$lh-menu-collapse-width
--lh-menu-item-height		沿用明色	$lh-menu-item-height
--lh-menu-item-padding		沿用明色	$lh-menu-item-padding
--lh-menu-item-color		var(--lh-text-primary)	$lh-menu-item-color
--lh-menu-item-hover-bg		#302B28	$lh-menu-item-hover-bg
--lh-menu-item-active-color		var(--lh-selected-color)	$lh-menu-item-active-color
--lh-menu-item-active-bg		var(--lh-primary-color-bg)	$lh-menu-item-active-bg
--lh-menu-arrow-color		var(--lh-text-secondary)	$lh-menu-arrow-color
--lh-menu-z-index		沿用明色	$lh-menu-z-index

组件级 · table

令牌	明色	暗色	SCSS 源	备注
--lh-table-bg		#242018	$lh-table-bg
--lh-table-color		var(--lh-text-regular)	$lh-table-color
--lh-table-header-bg		#2A2420	$lh-table-header-bg
--lh-table-header-color		var(--lh-text-primary)	$lh-table-header-color
--lh-table-border		#302B28	$lh-table-border
--lh-table-row-hover-bg		#2A2420	$lh-table-row-hover-bg
--lh-table-stripe-bg		color-mix(in srgb, var(--lh-bg-color-page) 60%, transparent)	$lh-table-stripe-bg
--lh-table-cell-padding		沿用明色	$lh-table-cell-padding

组件级 · layout

令牌	明色	暗色	SCSS 源	备注
--lh-layout-header-height		沿用明色	$lh-layout-header-height
--lh-layout-header-bg		#242018	$lh-layout-header-bg
--lh-layout-aside-width		沿用明色	$lh-layout-aside-width
--lh-layout-aside-bg		#242018	$lh-layout-aside-bg
--lh-layout-main-bg		#1C1815	$lh-layout-main-bg
--lh-layout-border		#302B28	$lh-layout-border

组件级 · row

令牌	明色	暗色	SCSS 源	备注
--lh-row-gutter		沿用明色	$lh-row-gutter

组件级 · tree

令牌	明色	暗色	SCSS 源	备注
--lh-tree-color		#D8D0C8	$lh-tree-color
--lh-tree-padding		沿用明色	$lh-tree-padding
--lh-tree-node-height		沿用明色	$lh-tree-node-height
--lh-tree-node-hover-bg		#2A2420	$lh-tree-node-hover-bg
--lh-tree-node-selected-color		var(--lh-selected-color)	$lh-tree-node-selected-color
--lh-tree-node-selected-bg		var(--lh-primary-color-bg)	$lh-tree-node-selected-bg
--lh-tree-arrow-color		var(--lh-text-secondary)	$lh-tree-arrow-color

组件级 · transfer

令牌	明色	暗色	SCSS 源	备注
--lh-transfer-panel-width		沿用明色	$lh-transfer-panel-width
--lh-transfer-panel-height		沿用明色	$lh-transfer-panel-height
--lh-transfer-bg		#242018	$lh-transfer-bg
--lh-transfer-border		#302B28	$lh-transfer-border

组件级 · upload

令牌	明色	暗色	SCSS 源	备注
--lh-upload-bg		#242018	$lh-upload-bg
--lh-upload-border		var(--lh-border-color-base)	$lh-upload-border
--lh-upload-trigger-padding		沿用明色	$lh-upload-trigger-padding

组件级 · anchor

令牌	明色	暗色	SCSS 源	备注
--lh-anchor-color		var(--lh-text-regular)	$lh-anchor-color

组件级 · image

令牌	明色	暗色	SCSS 源	备注
--lh-image-viewer-mask		rgba(0, 0, 0, 80%)	—

无障碍焦点环

令牌	明色	暗色	SCSS 源	备注
--lh-focus-color		#7FA6D9	$lh-primary
--lh-focus-ring-width		沿用明色	—
--lh-focus-ring-offset		沿用明色	—

（資料由 scripts/gen-docs-data.mjs 解析三個令牌檔案生成，帶數量斷言：明色 190、暗色 118、SCSS 188，不匹配即報錯。）

覆蓋令牌

執行時（推薦）

// ConfigProvider 的 themeVars（簡寫鍵自動補 --lh- 前綴）
<lh-config-provider :theme-vars="{ 'primary-color': '#1677ff' }">

或在應用入口寫 CSS：

:root {
  --lh-primary-color: #1677ff;
  --lh-primary-color-hover: #4096ff;
  --lh-primary-color-active: #0958d9;
}

詳見 執行時客製。

編譯期（SCSS 變數）

// 專案入口 scss，在 @use 之前覆蓋
$lh-primary-color: #1677ff;

@use '@lh-ui/share/styles';

!default 的語義是「已有值就不覆蓋」，所以在 @use 之前賦值即可。注意：這只影響編譯期烤死的部分，執行時的 CSS 變數仍需另外覆蓋。

已知的令牌缺口

「高度令牌專項」已落地（新增 --lh-control-height-mini/small/medium/large/x-large， button / select / input-number / cascader / tree-select / date-picker / time-picker / input 全部改引令牌，input 由 padding 派生改為固定高度，has-label 的非對稱 padding-top: 16px、checkbox 打勾固定偏移、switch 的 translate(-50%,-50%) 重複 硬編碼一併修復）。仍待處理的：

1. spinner 與 icon 同名尺寸檔位不一致（small 16 vs 14、medium 24 vs 16 等）。改任一側都波及全庫（message / notification / loading / 全部圖示），觸發條件：同一槽位混用 LhIcon / LhSpinner 的視覺投訴，屆時單獨立項。
2. size 檔位不齊：select / switch 僅 3 檔，date / time-picker 的 validator 收窄，tree-select / rate / segmented / pagination 無 size，mini 與 x-large 在 CSS 層幾乎未畫（全庫僅 avatar 有 x-large）。屬 API 層改動，與高度令牌解耦。

注意事項

• 元件不許自行宣告 --lh-*：只能 var(--lh-*, fallback) 消費（根 AGENTS.md 紅線）。新增令牌加在 var.scss。
• fallback 必寫：var(--lh-primary-color, #1677ff)——令牌缺失時仍有可接受的預設值，verify:styles 第 2 項（var fallback）把關。
• 暗色完備性：新增令牌要問「暗色下要不要翻轉」，要的話在 var-dark.scss 補覆蓋，verify:styles 第 7 項把關。
• 值形如 #{$lh-foo} 的令牌是編譯期烤死的：暗色下不自動翻轉，必須顯式重指向（詳見 暗色模式）。

相關文件

• 主題系統總覽
• 主題預設
• 執行時客製
• 暗色模式
• 樣式源