Skip to content

UnoCSS 集成 ​

接入方式 ​

ts
import { defineConfig, presetIcons, presetWind4 } from 'unocss'
import { presetPotato } from '@potato-forge/ui/preset'

export default defineConfig({
  presets: [presetWind4(), presetIcons(), presetPotato()],
})

presetWind4() 必须排在前面:它提供 Tailwind v4 语法的原子类,presetPotato() 负责把这些原子类接到语义 Token 上。

注册后即可直接使用语义 utility,不需要再引入任何样式表:

html
<button class="bg-primary text-primary-foreground focus-visible:ring-ring">
  保存
</button>
<aside class="bg-tip-subtle text-tip-subtle-foreground border-tip-border">
  推荐使用快捷键
</aside>

preset 做了什么 ​

presetPotato() 不是只提供颜色,它一并接管了四件事:

能力实现
Token 变量preflight 注入 theme 层:颜色、字体、排版角色、圆角、阴影、动效、层级
元素默认值preflight 注入 base 层:html/body 的主题落地与 prefers-reduced-motion 降级
原子类映射theme.colors / text / font / radius / shadow / ease
命名档位补充自定义 rule:duration-fast|normal|slow、z-dropdown|sticky|overlay|modal|toast

因此接入只有「注册 preset」一步。需要自行控制样式表加载顺序、或想并行引入 styles.css 时,可以关掉注入:

ts
presetPotato({ preflight: false })

preflight 与 styles.css 由同一份源码渲染,内容完全等价,任选其一即可。

preset 选项 ​

选项默认说明
previewTheme'latte'供 UnoCSS resolver 与编辑器取色使用的静态 OKLCH fallback
preflighttrue是否注入 Token 变量与元素默认值
ts
presetPotato({ previewTheme: 'macchiato' })

Color Preview 方案 ​

preset 的颜色值形如:

css
var(--pd-color-primary, oklch(...))

CSS Variable 负责运行时主题,静态 OKLCH fallback 让 UnoCSS resolver 和编辑器能获得真实颜色。仓库根部保留独立 uno.config.ts,并推荐 UnoCSS 官方扩展、开启 unocss.colorPreview。

浏览器构建和 utility 解析可自动验证;VS Code gutter 中最终是否显示色块会受扩展版本影响,发布前需在实际编辑器执行一次人工验收。

字体 utility ​

sans / serif / mono 三个角色全部指向运行时变量。

正文与界面固定使用系统默认无衬线(font-sans),不下载也不依赖任何字体包。霞鹜文楷属于强调字体,只在需要突出或需要衬线气质时通过 font-serif 主动调用:

html
<p>普通正文走系统无衬线。</p>
<p class="font-serif">需要强调或衬线气质时,才使用霞鹜文楷。</p>

font-serif 的值已定稿为「霞鹜文楷 → 系统衬线」。若本机未安装霞鹜文楷,会落到系统衬线而不是无衬线。它不提供运行时切换;需要重新比较方案时,按 Playground 的约定另开临时实验页。

包内不含 @font-face,也不依赖任何字体 npm 包。需要统一渲染效果时,由应用自行安装霞鹜文楷或引入子集化 WebFont。

图标 ​

图标不在本包内封装组件,直接使用 UnoCSS presetIcons 与 Tabler 集合:

sh
pnpm add -D @iconify-json/tabler
ts
import { defineConfig, presetIcons, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [presetWind4(), presetIcons(), presetPotato()],
})
html
<span class="i-tabler-circle-check text-success" />
<button class="bg-primary text-primary-foreground">
  <span class="i-tabler-plus" /> 新建项目
</button>

图标颜色来自语义色 utility,尺寸通过 h-* w-* 控制;presetIcons 会从已安装的 @iconify-json/* 集合自动解析类名。

排版、动效与层级 ​

这三个家族同样全部指向 --pd-* 变量。完整数值见基础 Token。

html
<h2 class="text-title">项目概览</h2>
<p class="text-label text-muted-foreground">持续跟踪中的工作流</p>
<div class="pd-overline">Workspace</div>

pd-overline 是眉标 shortcut,等价于 text-overline font-bold uppercase text-muted-foreground。

动效与层级的命名档位由本包补充,因为 Wind4 对它们只有裸数值:

html
<button class="pd-control-transition rounded-md bg-primary px-4 py-2 text-label font-semibold text-primary-foreground">
  保存
</button>

<div class="z-modal fixed inset-0 grid place-items-center bg-black/45">…</div>
<div class="z-toast fixed bottom-5 right-5">…</div>
命名档位编译结果裸数值是否仍可用
duration-fast|normal|slowvar(--pd-duration-*)是,duration-200 不变
ease-standard|emphasizedvar(--ease-*) → var(--pd-ease-*)是,ease-in / ease-out 不变
z-base|dropdown|sticky|overlay|modal|toastvar(--pd-z-*)是,z-50 不变

预设的自定义 rule 只匹配命名档位,因此不会与 Wind4 的裸数值解析争抢。

预设自检 ​

presetPotato() 的接入断点集中在 theme 键名上。Wind4 的动效命名空间是 ease,写成 easing 不会报错,只会让 ease-* 静默失效;duration 与 z-index 则根本没有主题命名空间。单元测试对这三处都有断言,改动预设时请一并运行 pnpm test。