Appearance
安装
安装方式取决于运行环境是否使用 UnoCSS。两者的 Token 完全一致,只是注入手段不同。
环境要求
| 依赖 | 版本 | 说明 |
|---|---|---|
| Node.js | 22.12+ 或 24+ | 构建期要求 |
| pnpm | 12.11.2 | 仓库已用 packageManager 固定 |
| UnoCSS | >=66.0.0 | peer dependency,仅 UnoCSS 路径需要 |
浏览器需要支持 OKLCH。所有颜色都是 oklch(...) 值,且带静态 fallback;不支持 OKLCH 的环境只会丢失颜色精度,不会导致布局问题。
Vue 3 + Vite(推荐)
sh
pnpm add @potato-forge/ui
pnpm add -D unocss @unocss/preset-wind4 @unocss/preset-icons @unocss/vite @iconify-json/tablerts
// uno.config.ts
import { defineConfig, presetIcons, presetWind4 } from 'unocss'
import { presetPotato } from '@potato-forge/ui/preset'
export default defineConfig({
presets: [presetWind4(), presetIcons(), presetPotato()],
})ts
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import UnoCSS from 'unocss/vite'
export default defineConfig({ plugins: [vue(), UnoCSS()] })ts
// src/main.ts
import { createApp } from 'vue'
import 'virtual:uno.css'
import App from './App.vue'
createApp(App).mount('#app')无需引入样式表:presetPotato() 的 preflights 已经注入 Token 变量与元素默认值。
Nuxt
sh
pnpm add @potato-forge/ui
pnpm add -D @unocss/nuxt @iconify-json/tablerts
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@unocss/nuxt'],
app: {
head: {
htmlAttrs: { 'data-theme': 'latte' },
},
},
})uno.config.ts 与 Vue 的写法相同。Nuxt 模块会自动加载 virtual:uno.css,不需要手动引入。
其他 UnoCSS 环境
Astro、SvelteKit、 SolidStart 等只需注册同一个 preset。@unocss/preset-wind4 提供 Tailwind v4 语法的原子类,presetPotato() 负责把它们接到语义 Token 上,顺序必须是 wind4 在前。
不使用 UnoCSS
纯 CSS、微信小程序、H5 内嵌页等环境直接引入静态样式表:
sh
pnpm add @potato-forge/uits
import '@potato-forge/ui/styles.css'然后手写 var(--pd-*):
css
.card {
background: var(--pd-color-card);
color: var(--pd-color-card-foreground);
border: 1px solid var(--pd-color-border);
border-radius: var(--pd-radius-lg);
box-shadow: var(--pd-shadow-xs);
font-family: var(--pd-font-sans);
}这条路径下没有原子类,但 Token 名称、值与主题切换行为完全一致。小程序中把 :root 换成 page 选择器即可:
css
page {
--pd-color-background: oklch(0.9578 0.0058 264.53);
/* 其余变量同 styles.css */
}两种路径的取舍
| preset(preflight) | styles.css | |
|---|---|---|
| 接入步骤 | 注册 preset 即可 | 需要额外 import |
| 适用环境 | 任意 UnoCSS 项目 | 任意环境,含小程序与纯 CSS |
| 样式位置 | 编译进 virtual:uno.css | 独立文件 |
| 关掉方式 | presetPotato({ preflight: false }) | 不引入即可 |
| 能否拿到原子类 | 能 | 不能 |
两者产出的 CSS 完全等价(同一份源码渲染),可以放心任选。
版本与发布通道
包以 alpha dist-tag 发布,安装时需显式指定:
sh
pnpm add @potato-forge/ui@alpha发布流程为「CI 打包并提交到 npm staging 队列 → 维护者 2FA 确认后正式公开」。因此 tag 推出后包不会立即出现在 registry,需要等待人工确认。