Skip to content

安装 ​

安装方式取决于运行环境是否使用 UnoCSS。两者的 Token 完全一致,只是注入手段不同。

环境要求 ​

依赖版本说明
Node.js22.12+ 或 24+构建期要求
pnpm12.11.2仓库已用 packageManager 固定
UnoCSS>=66.0.0peer 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/tabler
ts
// 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/tabler
ts
// 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/ui
ts
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,需要等待人工确认。