Appearance
快速开始
Potato Design 是一个框架无关的设计底座:用语义 Token 描述界面,用 CSS Custom Properties 承载运行时,用 UnoCSS preset 连接应用。它不包含组件库,也不绑定 Vue 或 React。
前置要求
| 依赖 | 版本 |
|---|---|
| Node.js | 22.12+ 或 24+ |
| pnpm | 12.11.2(仓库内已用 packageManager 固定) |
| UnoCSS | 66.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 }) 关掉注入。
下一步
- 安装:各框架与运行环境的完整接入方式
- 使用规范:每类 Token 该在什么场景使用
- Semantic Token:49 个语义色的完整参考