Design Tokens 设计令牌

🎨 Color Palette 色板

ZC UI 提供五组语义化色板，每组包含 50–950 共 11 个色阶。点击色块可复制对应的 CSS 变量名。

Primary主色

50#ecf5ff

100#d9ecff

200#c6e2ff

300#a0cfff

400#79bbff

500#409eff

600#337ecc

700#2a6cb3

800#1d4f7f

900#0d2640

950#06121e

Success成功

50#f0f9eb

100#e1f3d8

200#cfe8c3

300#b3e19d

400#95d575

500#67c23a

600#529b2e

700#427a27

800#325a1c

900#1f3a10

950#0e1d07

Warning警告

50#fdf6ec

100#faecd8

200#f8e3c5

300#f3d19e

400#ecbe77

500#e6a23c

600#b88230

700#946626

800#6f4c1c

900#4a3212

950#241907

Danger危险

50#fef0f0

100#fde2e2

200#fcd3d3

300#fab6b6

400#f78989

500#f56c6c

600#c45656

700#9d4444

800#763231

900#4f211f

950#2a1010

Info信息

50#f4f4f5

100#e9e9eb

200#dedfe0

300#c8c9cc

400#a6a9ad

500#909399

600#73767a

700#5c5e62

800#45474a

900#2e3032

950#171819

🌙 暗色模式对比

暗色模式下的语义化令牌对比。切换文档站的亮/暗模式可查看实际效果。

主要文字

亮色

暗色

--color-zc-text-primary

#303133#e5eaf3

常规文字

亮色

暗色

--color-zc-text-regular

#606266#cfd3dc

次要文字

亮色

暗色

--color-zc-text-secondary

#909399#a3a6ad

占位文字

亮色

暗色

--color-zc-text-placeholder

#a8abb2#8d9095

基础边框

亮色

暗色

--color-zc-border-base

#dcdfe6#4c4d4f

浅色边框

亮色

暗色

--color-zc-border-light

#e4e7ed#414243

基础填充

亮色

暗色

--color-zc-fill-base

#f0f2f5#303030

基础背景

亮色

暗色

--color-zc-bg-base

#ffffff#1d1d1d

🎛️ Theme Editor 主题编辑器

实时调整品牌色和圆角，预览效果。点击「应用到全局」可在整个文档站生效。

品牌色设置

Primary 主色

Success 成功

Warning 警告

Danger 危险

Info 信息

圆角设置

4px

实时预览

Buttons

📐 Spacing 间距

超小间距

--spacing-zc-xs

4px

小间距

--spacing-zc-sm

8px

基础间距

--spacing-zc-base

12px

中间距

--spacing-zc-md

16px

大间距

--spacing-zc-lg

24px

超大间距

--spacing-zc-xl

32px

📐 Typography 字号

辅助文字

--text-zc-xs

12px

小号文字

--text-zc-sm

13px

正文（默认）

--text-zc-base

14px

中号标题

--text-zc-md

16px

大号标题

--text-zc-lg

18px

超大标题

--text-zc-xl

20px

📐 Radius 圆角

小圆角

--radius-zc-sm

2px

基础圆角

--radius-zc-base

4px

中圆角

--radius-zc-md

6px

大圆角

--radius-zc-lg

8px

圆角按钮

--radius-zc-round

20px

圆形

--radius-zc-circle

50%

📐 Shadow 阴影

微小阴影

--shadow-zc-sm

0 1px 2px 0 rgba(0, 0, 0, 0.05)

基础阴影

--shadow-zc-base

0 2px 8px 0 rgba(0, 0, 0, 0.08)

中等阴影

--shadow-zc-md

0 4px 12px 0 rgba(0, 0, 0, 0.1)

大阴影

--shadow-zc-lg

0 8px 24px 0 rgba(0, 0, 0, 0.12)

超大阴影

--shadow-zc-xl

0 16px 48px 0 rgba(0, 0, 0, 0.16)

深色阴影

--shadow-zc-dark

0 4px 12px 0 rgba(0, 0, 0, 0.5)

📐 Transition 过渡

快速过渡

--transition-duration-zc-fast

0.15s

基础过渡

--transition-duration-zc-base

0.25s

慢速过渡

--transition-duration-zc-slow

0.35s

缓入

--ease-zc-in

cubic-bezier(0.4, 0, 1, 1)

缓出

--ease-zc-out

cubic-bezier(0, 0, 0.2, 1)

缓入缓出

--ease-zc-in-out

cubic-bezier(0.4, 0, 0.2, 1)

使用指南

CSS 变量

ZC UI 的所有设计令牌都以 CSS 自定义属性（CSS Custom Properties）的形式提供，可直接在样式中使用：

css

.my-button {
  background-color: var(--color-zc-primary-500);
  border-radius: var(--radius-zc-base);
  padding: var(--spacing-zc-sm) var(--spacing-zc-md);
  font-size: var(--text-zc-base);
  box-shadow: var(--shadow-zc-base);
  transition: all var(--transition-duration-zc-base) var(--ease-zc-out);
}

Tailwind CSS

如果项目集成了 Tailwind CSS v4，所有令牌已映射到 Tailwind 主题：

html

<div class="bg-zc-primary-500 text-white rounded-zc-base p-zc-md">Hello ZC UI</div>

运行时主题切换

使用 @zc-ui/theme 提供的运行时 API 可以在运行时动态修改令牌：

import { setBrandColor, toggleDark, applyTheme, darkTheme, lightTheme } from '@zc-ui/theme'

// 修改品牌色（自动生成完整色阶）
setBrandColor('primary', '#722ed1')

// 切换暗色模式
toggleDark()

// 应用完整主题预设
applyTheme(darkTheme)
applyTheme(lightTheme)

暗色模式

暗色模式通过在 <html> 上添加 .dark 类触发。色阶会自动反转：

50–400：深色背景上的微妙色调
500：保持品牌色不变
600–950：提亮以保证暗色背景上的可读性

import { toggleDark, setTheme, getTheme } from '@zc-ui/theme'

// 手动切换
toggleDark()

// 显式设置
setTheme('dark')
setTheme('light')

// 查询当前模式
console.log(getTheme()) // 'light' | 'dark'

Design Tokens 设计令牌 ​