Appearance
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 |
preflight | true | 是否注入 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/tablerts
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|slow | var(--pd-duration-*) | 是,duration-200 不变 |
ease-standard|emphasized | var(--ease-*) → var(--pd-ease-*) | 是,ease-in / ease-out 不变 |
z-base|dropdown|sticky|overlay|modal|toast | var(--pd-z-*) | 是,z-50 不变 |
预设的自定义 rule 只匹配命名档位,因此不会与 Wind4 的裸数值解析争抢。
预设自检
presetPotato() 的接入断点集中在 theme 键名上。Wind4 的动效命名空间是 ease,写成 easing 不会报错,只会让 ease-* 静默失效;duration 与 z-index 则根本没有主题命名空间。单元测试对这三处都有断言,改动预设时请一并运行 pnpm test。