Appearance
使用规范
本页按 Token 类别说明「该用哪个、怎么用、不要怎么用」。完整数值见基础 Token,颜色清单见 Semantic Token。
总原则
- 只使用语义名。业务代码里不应出现
latte-blue、catppuccin、#008080这类底层命名,Catppuccin 只是 palette provider。 - 每个值都来自 Token。需要新颜色时先补语义 Token 与释义,而不是在业务里写死
text-[#6c6f85]。 - 不用
dark:写颜色分支。主题切换由 CSS 变量完成,bg-primary在亮暗两套主题下自动取到对应值。 - 尺寸类可以用 Wind4 原生档位(字号原始档、间距、断点、容器宽度),语义 Token 负责表达用途与视觉决策。
颜色
49 个语义色分四组。选择顺序是:先定位「这是哪一层」,再定位「这是什么状态」。
表面与画布
| Token | 用途 |
|---|---|
bg-background | 页面最底层画布 |
bg-surface | 侧栏、面板、分组区域 |
bg-surface-subtle | 表头、分组、禁用区域 |
bg-card | 内容卡片 |
bg-surface-elevated / bg-popover | 菜单、对话框、浮层 |
每一层都有配套前景色,必须成对使用:
html
<section class="bg-card text-card-foreground">…</section>
<aside class="bg-surface text-surface-foreground">…</aside>
<div class="bg-popover text-popover-foreground">…</div>不要在卡片里再嵌一层同级卡片,也不要用
background模拟浮层——层级同时靠 tone、border 与 shadow 表达。
交互色
| Token | 用途 | 注意 |
|---|---|---|
bg-primary | 最高优先级行为、品牌表达 | 不要铺满大面积背景 |
bg-secondary | 次按钮、弱选中态 | 不要与 primary 竞争 |
bg-accent | hover、selection、active | 不等同于品牌主色 |
bg-muted | 占位、禁用、辅助区域 | 不要用于关键状态 |
html
<button class="bg-primary text-primary-foreground hover:bg-primary-strong">保存</button>
<button class="bg-secondary text-secondary-foreground">取消</button>
<li class="hover:bg-accent hover:text-accent-foreground">…</li>文本类交互色各自独立,不要互相替代:
html
<p class="text-foreground">正文</p>
<p class="text-muted-foreground">说明、时间戳、次要元信息</p>状态色
五种状态各有三件套:实心、浅底、描边。
html
<!-- 实心:徽标、危险按钮 -->
<span class="bg-error text-error-foreground">失败</span>
<!-- 浅底 + 描边:提示条、状态卡片(推荐,正文可读性最好) -->
<div class="border border-warning-border bg-warning-subtle text-warning-subtle-foreground p-3">
本月配额即将达到上限。
</div>状态语义不可混用:
info是明确的系统信息(同步、运行、版本),tip是无状态的建议与技巧。warning表示"需要注意但仍可继续",error才表示已经失败。success只用于完成态,不要拿它做品牌强调。- 组件层的
destructive行为应映射到error,不要新造颜色。
边界与焦点
| Token | 用途 |
|---|---|
border-border | 卡片、分隔、控件边缘 |
border-border-muted | 表格行之间的浅分隔 |
border-border-strong | 需要明确分界的容器 |
border-input | 表单控件静止态 |
ring-ring | 键盘焦点,仅 focus-visible |
html
<input class="border border-input focus-visible:ring-2 focus-visible:ring-ring" />不要用
border承担焦点指示,也不要用 hover 样式代替 focus。现成的 shortcut 是pd-focus-ring。
排版
用角色,不用尺寸
| 角色 | 用途 |
|---|---|
text-display | 首页/空状态的大标题 |
text-title | 页面或区块标题 |
text-heading | 卡片标题、对话框标题 |
text-body | 正文 |
text-label | 按钮、表单标签、次要正文 |
text-caption | 元信息、时间戳、辅助说明 |
text-overline | 大写微型标签 |
html
<h2 class="text-title">项目概览</h2>
<p class="text-label text-muted-foreground">持续跟踪中的工作流</p>
<span class="text-caption text-muted-foreground">2 分钟前</span>角色内部已经包含字号、行高与字间距,不要再叠加 leading-* 或 tracking-*,除非有明确的排版理由。
text-body与text-base数值相同,但前者表达用途。业务代码优先用角色名,需要精细控制时再用 Wind4 原始档位。
字重只有三档
html
<strong class="font-semibold">强调</strong> <!-- 600 -->
<h3 class="font-bold">标题</h3> <!-- 700 -->
<span class="font-medium">次级强调</span> <!-- 500 -->不要写
font-650、font-720这类任意值。任意字重会破坏层级可预测性,也让主题无法统一调整。
眉标用 shortcut
html
<div class="pd-overline">Workspace</div>等价于 text-overline font-bold uppercase text-muted-foreground。眉标只承载大写短标签,不要放句子。
正文字号下限
text-caption(12px)是正文的最小值。text-overline(11px)只用于大写微型标签,不承载句子级内容。
三个字体角色
| 角色 | 用途 |
|---|---|
font-sans | 全局默认,正文与界面 |
font-serif | 强调与衬线排版,霞鹜文楷 |
font-mono | 代码、数字对齐、Token 名 |
html
<p>正文使用系统默认无衬线。</p>
<blockquote class="font-serif">需要强调或衬线气质时才使用霞鹜文楷。</blockquote>
<code class="font-mono">var(--pd-radius-lg)</code>霞鹜文楷是楷体,不要用于大段正文——会显著降低阅读效率。它适合标题、引用和短强调句。未安装该字体的环境会回退到系统衬线。
间距
间距由 Wind4 提供,表达为 calc(var(--spacing) * N),--spacing 默认 0.25rem。
html
<div class="p-4 gap-3"> <!-- 16px / 12px -->
<div class="p-1.5"> <!-- 6px,支持小数 -->不要自行定义间距 Token,也不要写
p-[17px]这类任意值。需要整体缩放间距体系时改--spacing一个变量即可。
圆角
| Token | 值 | 用途 |
|---|---|---|
rounded-xs | 4px | 徽标、小色块 |
rounded-sm | 6px | 标签、紧凑控件 |
rounded-md | 8px | 按钮、输入框 |
rounded-lg | 12px | 卡片、面板 |
rounded-xl | 16px | 对话框、大容器 |
rounded-full | 9999px | 胶囊、头像 |
外层容器的圆角应大于等于内层元素,避免视觉上「内圆角比外圆角还大」。应用可通过根节点 data-radius="6|8|10" 整体调整基准(当前基准为 8px)。
阴影
| Token | 用途 |
|---|---|
shadow-xs | 卡片静止态、极轻浮起 |
shadow-sm | 面板、次级容器 |
shadow-md | 强调卡片、拖拽中 |
shadow-lg | 大型浮层 |
shadow-overlay | 对话框、菜单 |
层级主要靠表面 tone 与边框表达,阴影只做辅助:
html
<article class="rounded-lg border border-border bg-card shadow-xs">…</article>不要只用阴影表达层级——在暗色主题下阴影对比度很低。
动效
html
<button class="pd-control-transition hover:bg-primary-strong">保存</button>pd-control-transition = 颜色过渡 + duration-normal + ease-standard + reduced-motion 降级。
| Token | 值 | 用途 |
|---|---|---|
duration-fast | 120ms | hover、颜色变化 |
duration-normal | 200ms | 大部分过渡 |
duration-slow | 320ms | 位移、展开 |
ease-standard | cubic-bezier(0.2, 0, 0, 1) | 默认 |
ease-emphasized | cubic-bezier(0.2, 0, 0, 1.2) | 需要回弹感时 |
裸数值 duration-200 与 Wind4 原生 ease-in / ease-out 同样可用。所有动效都应尊重 prefers-reduced-motion——styles.css 与 preflight 已内置全局降级。
层级
用语义层级,不要用裸数值去猜:
| Token | 值 | 用途 |
|---|---|---|
z-base | 0 | 常规内容 |
z-dropdown | 1000 | 下拉、菜单、Tooltip |
z-sticky | 1020 | 吸顶栏、侧边导航 |
z-overlay | 1040 | 模态遮罩 |
z-modal | 1050 | 对话框、命令面板 |
z-toast | 1090 | 全局通知 |
html
<header class="sticky top-0 z-sticky">…</header>
<div class="fixed inset-0 z-modal">…</div>
<div class="fixed bottom-5 right-5 z-toast">…</div>数值之间刻意留了大间隙,新增浮层时插入到合适的档位即可,不必重新编号。裸数值 z-50 仍可用,但它不表达用途。
图标
html
<span class="i-tabler-circle-check text-success" />
<button class="bg-primary text-primary-foreground">
<span class="i-tabler-plus" /> 新建项目
</button>
<span class="h-5 w-5 i-tabler-trash text-muted-foreground" />- 类名形如
i-tabler-<name>,来源是已安装的@iconify-json/tabler。 - 颜色一律走语义色 utility,不要给图标单独设色值。
- 尺寸用
h-* w-*,并与同行文字基线对齐。 - 纯装饰图标加
aria-hidden="true";承载语义的图标按钮必须有aria-label。
主题切换
html
<html data-theme="latte"> <!-- 亮色(默认) -->
<html data-theme="macchiato"> <!-- 暗色 -->
<html class="dark"> <!-- 兼容既有暗色工具链 -->ts
// 运行时切换
document.documentElement.dataset.theme = isDark ? 'macchiato' : 'latte'
document.documentElement.classList.toggle('dark', isDark)data-theme 与 .dark 应保持一致,避免出现属性与类互相矛盾的状态。
组合示例
html
<article class="rounded-xl 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>
<div class="mt-4 flex gap-2">
<button class="pd-focus-ring pd-control-transition rounded-md bg-primary px-4 py-2 text-label font-semibold text-primary-foreground hover:bg-primary-strong">
新建项目
</button>
<button class="rounded-md border border-border bg-secondary px-4 py-2 text-label text-secondary-foreground">
导入
</button>
</div>
<div class="mt-4 rounded-lg border border-tip-border bg-tip-subtle p-3 text-label text-tip-subtle-foreground">
使用快捷键 ⌘ K 可以快速搜索。
</div>
</article>一眼可核对:表面与前景成对、交互色各司其职、状态用浅底三件套、字号用角色、间距用 Wind4 档位、过渡用 shortcut、焦点用 ring。