Skip to content

基础 Token ​

颜色之外的排版、间距、圆角、阴影、动效与层级。本页数值由 packages/ui 直接渲染,因此文档与发布包不会漂移。

两种真源,一条链路 ​

设计 Token 分两层,业务只接触上层:

text
Wind4 原生阶梯(primitive)→ --pd-* 变量(semantic)→ Utility → Application
  • primitive 由 UnoCSS Wind4 提供:间距、字号原始档位、断点、容器宽度。它们已经是变量驱动的,我们不再复制一份。
  • semantic 由本包提供:排版角色、圆角、阴影、动效、层级。每个值都是一个 --pd-* CSS 变量,可被运行时覆盖或跨框架复用。

两类 Token 的差别决定接入方式:

家族UnoCSS 里的命名空间本包如何接入
颜色theme.colorsvar(--pd-color-*, oklch(...)),带静态 fallback
字体theme.fontvar(--pd-font-*)
排版角色theme.textvar(--pd-text-*-fontSize/lineHeight/letterSpacing)
圆角theme.radiusvar(--pd-radius-*)
阴影theme.shadowvar(--pd-shadow-*)
缓动theme.easevar(--pd-ease-*)
时长无(只有裸数值)自定义 rule → var(--pd-duration-*)
层级无(只有裸数值)自定义 rule → var(--pd-z-*)

最后两行是需要留意的部分:Wind4 的 duration-* 与 z-* 没有主题命名空间,只接受裸数值(duration-200、z-50)。因此命名档位由本包补充,且只匹配命名档位,裸数值行为完全不变。

排版角色

数值与 UnoCSS Wind4 的原生 text-* 阶梯一致,但角色名表达用途。字重不进入角色,请使用 font-medium / font-semibold / font-bold。

角色Utilityfont-sizeline-heightletter-spacing样本
displaytext-display2.25rem2.5rem-0.02em中英混排 Ag
titletext-title1.5rem2rem-0.01em中英混排 Ag
headingtext-heading1.125rem1.75rem—中英混排 Ag
bodytext-body1rem1.5rem—中英混排 Ag
labeltext-label0.875rem1.25rem—中英混排 Ag
captiontext-caption0.75rem1rem—中英混排 Ag
overlinetext-overline0.6875rem1rem0.08em中英混排 Ag

层级 z-index

刻意留出巨大间隙,避免局部新增浮层时发生层叠冲突。裸数值 z-10 仍可用,但不表达用途。

层Utility值用途
basez-base0页面常规内容
dropdownz-dropdown1000下拉、菜单、Tooltip
stickyz-sticky1020吸顶栏与侧边导航
overlayz-overlay1040模态遮罩
modalz-modal1050对话框、命令面板
toastz-toast1090全局通知

圆角

TokenUtility值
xsrounded-xs4px
smrounded-sm6px
mdrounded-md8px
lgrounded-lg12px
xlrounded-xl16px
fullrounded-full9999px

阴影

亮色以 Latte 文字色为投影基色,暗色使用纯黑并提高不透明度,两套值互相独立。

TokenUtilityLatteMacchiato
xsshadow-xs0 1px 2px rgb(76 79 105 / 0.08)0 1px 2px rgb(0 0 0 / 0.24)
smshadow-sm0 2px 6px rgb(76 79 105 / 0.10)0 3px 8px rgb(0 0 0 / 0.28)
mdshadow-md0 8px 20px rgb(76 79 105 / 0.12)0 10px 24px rgb(0 0 0 / 0.34)
lgshadow-lg0 16px 36px rgb(76 79 105 / 0.16)0 18px 44px rgb(0 0 0 / 0.42)
overlayshadow-overlay0 24px 64px rgb(76 79 105 / 0.22)0 28px 72px rgb(0 0 0 / 0.52)

动效

TokenUtility值
duration-fastduration-fast120ms
duration-normalduration-normal200ms
duration-slowduration-slow320ms
ease-standardease-standardcubic-bezier(0.2, 0, 0, 1)
ease-emphasizedease-emphasizedcubic-bezier(0.2, 0, 0, 1.2)

字体角色 ​

三个字体角色各自有明确分工,默认渲染不依赖任何字体包:

角色用途默认栈
font-sans正文与界面,全局默认操作系统默认无衬线
font-serif强调与衬线排版霞鹜文楷 → 系统衬线
font-mono代码与等宽数据操作系统默认等宽 → LXGW WenKai Mono

关键约定:霞鹜文楷是强调字体,不是默认字体。它是楷体,适合标题、引用和需要衬线气质的短文本;大段正文使用它会显著降低阅读效率,也会让整个界面被动带上书法气质。因此 font-sans 保持系统默认,需要时再显式调用 font-serif。

间距交还给 Wind4 ​

间距没有独立 Token 表。Wind4 已把它表达为单个运行时变量:

css
:root { --spacing: 0.25rem; }

p-4、gap-3、mt-5 都会编译成 calc(var(--spacing) * N)。改一个 --spacing 就能整体缩放间距体系,比一张静态 px 表更强。早期版本曾用静态表覆盖 spacing,但那既不生效(Wind4 只认乘法)又制造了「有 Token」的错觉,现已移除。

排版约定 ​

  • 角色而不是尺寸:业务写 text-title 表达"这是区块标题",而不是 text-2xl。两者当前等值,语义不同。
  • 字重不进入角色:只用 font-medium / font-semibold / font-bold 三档。任意值如 font-650、font-720 会破坏字重层级的可预测性。
  • 眉标用 pd-overline:text-overline + 加粗 + 大写 + 字间距的固定组合,替代散落的 text-[10px] font-bold uppercase tracking-widest。
  • 正文不小于 12px:text-caption 是正文下限。text-overline 只用于大写微型标签,不承载句子级内容。

使用示例 ​

html
<article class="rounded-lg border border-border bg-card p-6 text-card-foreground shadow-xs">
  <div class="pd-overline">Workspace</div>
  <h2 class="mt-2 text-title">项目概览</h2>
  <p class="mt-1 text-label text-muted-foreground">持续跟踪中的工作流</p>
  <button class="pd-focus-ring pd-control-transition mt-4 rounded-md bg-primary px-4 py-2 text-label font-semibold text-primary-foreground">
    新建项目
  </button>
</article>

<div class="z-modal fixed inset-0 grid place-items-center bg-black/45">
  <div role="dialog" class="rounded-xl border border-border bg-surface-elevated p-6 shadow-overlay">…</div>
</div>