Appearance
基础 Token
颜色之外的排版、间距、圆角、阴影、动效与层级。本页数值由 packages/ui 直接渲染,因此文档与发布包不会漂移。
两种真源,一条链路
设计 Token 分两层,业务只接触上层:
text
Wind4 原生阶梯(primitive)→ --pd-* 变量(semantic)→ Utility → Application- primitive 由 UnoCSS Wind4 提供:间距、字号原始档位、断点、容器宽度。它们已经是变量驱动的,我们不再复制一份。
- semantic 由本包提供:排版角色、圆角、阴影、动效、层级。每个值都是一个
--pd-*CSS 变量,可被运行时覆盖或跨框架复用。
两类 Token 的差别决定接入方式:
| 家族 | UnoCSS 里的命名空间 | 本包如何接入 |
|---|---|---|
| 颜色 | theme.colors | var(--pd-color-*, oklch(...)),带静态 fallback |
| 字体 | theme.font | var(--pd-font-*) |
| 排版角色 | theme.text | var(--pd-text-*-fontSize/lineHeight/letterSpacing) |
| 圆角 | theme.radius | var(--pd-radius-*) |
| 阴影 | theme.shadow | var(--pd-shadow-*) |
| 缓动 | theme.ease | var(--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。
| 角色 | Utility | font-size | line-height | letter-spacing | 样本 |
|---|---|---|---|---|---|
display | text-display | 2.25rem | 2.5rem | -0.02em | 中英混排 Ag |
title | text-title | 1.5rem | 2rem | -0.01em | 中英混排 Ag |
heading | text-heading | 1.125rem | 1.75rem | — | 中英混排 Ag |
body | text-body | 1rem | 1.5rem | — | 中英混排 Ag |
label | text-label | 0.875rem | 1.25rem | — | 中英混排 Ag |
caption | text-caption | 0.75rem | 1rem | — | 中英混排 Ag |
overline | text-overline | 0.6875rem | 1rem | 0.08em | 中英混排 Ag |
层级 z-index
刻意留出巨大间隙,避免局部新增浮层时发生层叠冲突。裸数值 z-10 仍可用,但不表达用途。
| 层 | Utility | 值 | 用途 |
|---|---|---|---|
base | z-base | 0 | 页面常规内容 |
dropdown | z-dropdown | 1000 | 下拉、菜单、Tooltip |
sticky | z-sticky | 1020 | 吸顶栏与侧边导航 |
overlay | z-overlay | 1040 | 模态遮罩 |
modal | z-modal | 1050 | 对话框、命令面板 |
toast | z-toast | 1090 | 全局通知 |
圆角
| Token | Utility | 值 |
|---|---|---|
xs | rounded-xs | 4px |
sm | rounded-sm | 6px |
md | rounded-md | 8px |
lg | rounded-lg | 12px |
xl | rounded-xl | 16px |
full | rounded-full | 9999px |
阴影
亮色以 Latte 文字色为投影基色,暗色使用纯黑并提高不透明度,两套值互相独立。
| Token | Utility | Latte | Macchiato |
|---|---|---|---|
xs | shadow-xs | 0 1px 2px rgb(76 79 105 / 0.08) | 0 1px 2px rgb(0 0 0 / 0.24) |
sm | shadow-sm | 0 2px 6px rgb(76 79 105 / 0.10) | 0 3px 8px rgb(0 0 0 / 0.28) |
md | shadow-md | 0 8px 20px rgb(76 79 105 / 0.12) | 0 10px 24px rgb(0 0 0 / 0.34) |
lg | shadow-lg | 0 16px 36px rgb(76 79 105 / 0.16) | 0 18px 44px rgb(0 0 0 / 0.42) |
overlay | shadow-overlay | 0 24px 64px rgb(76 79 105 / 0.22) | 0 28px 72px rgb(0 0 0 / 0.52) |
动效
| Token | Utility | 值 |
|---|---|---|
duration-fast | duration-fast | 120ms |
duration-normal | duration-normal | 200ms |
duration-slow | duration-slow | 320ms |
ease-standard | ease-standard | cubic-bezier(0.2, 0, 0, 1) |
ease-emphasized | ease-emphasized | cubic-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>