Skip to content

快速开始 ​

Potato Design 是一个框架无关的设计底座:用语义 Token 描述界面,用 CSS Custom Properties 承载运行时,用 UnoCSS preset 连接应用。它不包含组件库,也不绑定 Vue 或 React。

前置要求 ​

依赖版本
Node.js22.12+ 或 24+
pnpm12.11.2(仓库内已用 packageManager 固定)
UnoCSS66.0.0 及以上

安装 ​

sh
pnpm add @potato-forge/ui
pnpm add -D unocss

图标不在包内,按需安装 UnoCSS 的图标集合。本设计体系使用 Tabler:

sh
pnpm add -D @iconify-json/tabler

三步接入 ​

1. 注册 preset ​

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

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

presetPotato() 会通过 UnoCSS 的 preflight 机制注入全部 Token 变量与元素默认值,因此不需要再引入任何样式表。这是推荐的接入方式。

2. 启用 UnoCSS 插件 ​

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')

3. 在根节点声明主题 ​

html
<html lang="zh-CN" data-theme="latte">

latte 是亮色,macchiato 是暗色。不写该属性时 :root 默认即亮色;根节点加 .dark 类也会切到暗色,便于接入既有暗色工具链。

验证 ​

vue
<template>
  <button class="rounded-md bg-primary px-4 py-2 text-label font-semibold text-primary-foreground">
    保存
  </button>
</template>

构建后 bg-primary 应编译为 background-color: var(--pd-color-primary, oklch(...))。若颜色为空,检查 preset 是否注册在 presets 数组里。

另一种接入路径:直接引样式表 ​

不走 UnoCSS、或需要自行控制样式加载顺序时,引入静态样式表:

ts
import '@potato-forge/ui/styles.css'

它包含与 preflight 完全相同的 CSS,适合纯 CSS 项目、小程序与 H5 内嵌页。两者内容一致,任选其一即可;同时使用会造成重复声明(不影响渲染),此时可用 presetPotato({ preflight: false }) 关掉注入。

下一步 ​