Skip to content

使用规范 ​

本页按 Token 类别说明「该用哪个、怎么用、不要怎么用」。完整数值见基础 Token,颜色清单见 Semantic Token。

总原则 ​

  1. 只使用语义名。业务代码里不应出现 latte-blue、catppuccin、#008080 这类底层命名,Catppuccin 只是 palette provider。
  2. 每个值都来自 Token。需要新颜色时先补语义 Token 与释义,而不是在业务里写死 text-[#6c6f85]。
  3. 不用 dark: 写颜色分支。主题切换由 CSS 变量完成,bg-primary 在亮暗两套主题下自动取到对应值。
  4. 尺寸类可以用 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-accenthover、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-xs4px徽标、小色块
rounded-sm6px标签、紧凑控件
rounded-md8px按钮、输入框
rounded-lg12px卡片、面板
rounded-xl16px对话框、大容器
rounded-full9999px胶囊、头像

外层容器的圆角应大于等于内层元素,避免视觉上「内圆角比外圆角还大」。应用可通过根节点 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-fast120mshover、颜色变化
duration-normal200ms大部分过渡
duration-slow320ms位移、展开
ease-standardcubic-bezier(0.2, 0, 0, 1)默认
ease-emphasizedcubic-bezier(0.2, 0, 0, 1.2)需要回弹感时

裸数值 duration-200 与 Wind4 原生 ease-in / ease-out 同样可用。所有动效都应尊重 prefers-reduced-motion——styles.css 与 preflight 已内置全局降级。


层级 ​

用语义层级,不要用裸数值去猜:

Token值用途
z-base0常规内容
z-dropdown1000下拉、菜单、Tooltip
z-sticky1020吸顶栏、侧边导航
z-overlay1040模态遮罩
z-modal1050对话框、命令面板
z-toast1090全局通知
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。