跳转到内容
@lh-ui/share

设计令牌

令牌（token）是设计语言的变量化：颜色、字号、间距、圆角、阴影、动画时长都命名成 --lh-* CSS 变量，组件只消费名字、不写死值。换肤就是换令牌。

三层令牌

Section titled “三层令牌”
层 位置 数量 求值时机 可覆盖性
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）

Section titled “明色令牌（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）

Section titled “暗色覆盖（var-dark.scss）”
[data-theme='dark'],
.dark {
  --lh-bg-color: #2A2520;
  --lh-text-primary: #E8E0D8;
  --lh-border-color: #3A3530;
  // ... 118 条
}

暗色是覆盖层而非独立一套：只写需要翻转的 118 条，其余沿用明色值。

SCSS 变量（variables.scss）

Section titled “SCSS 变量（variables.scss）”
$lh-primary-color: #2B4C7C !default;
$lh-border-radius-base: 6px !default;
// ... 183 个

SCSS 变量的用途是参与编译期计算：颜色混合（mix() / shade()）、阴影合成（多层 shadow 相加）这类 CSS 变量做不到的事。代价是编译期烤死——暗色下不会自动翻转。

令牌的分层结构

Section titled “令牌的分层结构”

令牌分三档，前两档在全局主题文件、第三档在各组件自己的样式里：

// 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 定向覆盖单个组件。

语义域

Section titled “语义域”

主要语义域（完整分组见下方令牌表）：

域 典型令牌 用途
主色 --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 国风装饰色

令牌全表

Section titled “令牌全表”

主色与衍生语义

令牌明色暗色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，不匹配即报错。）

覆盖令牌

Section titled “覆盖令牌”

运行时（推荐）

Section titled “运行时（推荐）”
// 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 变量）

Section titled “编译期（SCSS 变量）”
// 项目入口 scss，在 @use 之前覆盖
$lh-primary-color: #1677ff;


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

!default 的语义是「已有值就不覆盖」，所以在 @use 之前赋值即可。注意：这只影响编译期烤死的部分，运行时的 CSS 变量仍需另外覆盖。

已知的令牌缺口

Section titled “已知的令牌缺口”

「高度令牌专项」已落地（新增 --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 层改动，与高度令牌解耦。

注意事项

Section titled “注意事项”
  • 组件不许自行声明 --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} 的令牌是编译期烤死的：暗色下不自动翻转，必须显式重指向（详见 暗色模式）。

相关文档

Section titled “相关文档”

Copyright © 2024-2026 风默文学 | 宁ICP备2024006574号 | 公安备案徽标苏公网安备32040002010537