Wot UnoCSS Preset 使用指南
适用场景
当用户询问以下内容时，优先使用本 Skill：
- 如何安装
@wot-ui/unocss-preset - 如何在
unocss.config.ts配置presetWot prefix、preflight、baseTokens怎么用- 为什么类名不生效、自动补全不出现、CI 与本地结果不一致
目标是给出可直接复制的最佳实践，帮助用户快速完成接入并稳定运行。
最小安装步骤
pnpm add -D unocss
pnpm add @wot-ui/unocss-preset推荐配置（完整示例）
import { presetWot } from '@wot-ui/unocss-preset'
import { defineConfig } from 'unocss'
export default defineConfig({
presets: [
presetWot({
prefix: 'wot',
preflight: true,
baseTokens: false,
}),
],
})配置项说明
prefix：工具类前缀，默认wot。示例：wot-text-primary、wot-m-main。preflight：是否注入 wot-ui CSS 变量，默认true。baseTokens：是否开放基础色板和原始 token 类名，默认false。
常用类名示例
- 颜色：
wot-text-primary、wot-bg-danger-surface、wot-border-border-main - 间距：
wot-m-main、wot-gap-tight、wot-gap-x-loose - 内边距：
wot-p-main、wot-px-tight、wot-pb-loose - 圆角：
wot-rounded-md、wot-rounded-full - 字重：
wot-font-medium、wot-font-semibold - 排版：
wot-text-body-main、wot-text-title-large - 透明度：
wot-opacity-disabled - 描边：
wot-border-stroke-main
上手示例（可复制）
1) 一个“卡片”示例（uni-app / Vue）
<template>
<view class="wot-bg-filled-oppo wot-rounded-2xl wot-p-super-loose wot-border-border-main wot-border-stroke-main">
<text class="wot-text-title-large wot-text-text-main wot-font-semibold">
Wot UnoCSS Preset
</text>
<view class="wot-mt-tight">
<text class="wot-text-body-main wot-text-text-secondary">
wot-text-body-main + wot-text-text-secondary
</text>
</view>
<view class="wot-mt-loose wot-bg-primary wot-rounded-full wot-px-main wot-py-extra-tight">
<text class="wot-text-label-large wot-text-text-white wot-font-semibold">
wot-bg-primary
</text>
</view>
</view>
</template>2) 间距/布局示例（常见组合）
- 外边距：
wot-mt-tight、wot-mt-main、wot-mt-super-loose - 内边距：
wot-p-loose、wot-px-main、wot-py-extra-tight - 横向/纵向组合：
wot-mx-main、wot-my-loose - gap：
wot-gap-tight、wot-gap-x-main、wot-gap-y-loose
3) 语义色示例（背景/文字/边框）
- 背景：
wot-bg-primary、wot-bg-success-surface、wot-bg-warning-surface、wot-bg-danger-surface - 文字：
wot-text-text-main、wot-text-text-secondary、wot-text-primary、wot-text-success-main - 边框：
wot-border-border-main、wot-border-success-main、wot-border-warning-main、wot-border-danger-main
4) 暗黑模式示例
预设会输出暗色变量选择器 .wot-theme-dark...，你只需要在根节点加 class：
<template>
<view :class="dark ? 'wot-theme-dark' : ''">
<view class="wot-bg-filled-oppo wot-p-main wot-rounded-lg">
<text class="wot-text-text-main">当前主题：{{ dark ? 'Dark' : 'Light' }}</text>
</view>
</view>
</template>5) 打开 baseTokens（可选）
当你希望使用基础色板/原始 token 时启用：
presetWot({
baseTokens: true,
})启用后会额外提供类似 wot-base-black 这类 token（用于 theme.colors 与颜色规则匹配）。
轻量提醒
- 历史项目若仍使用
w-前缀，可通过prefix: 'w'兼容。 - 若 playground/子包构建异常，优先检查是否：
- 使用包名导入（如 @wot-ui/unocss-preset） - 在依赖主包产物的场景下先执行主包构建
- 若需要同步上游 wot-ui 变量，可使用：
- pnpm generate:css-vars:clone
常见问题排查
- 类名不生效
- 确认项目已启用 UnoCSS 且
presetWot()已加入presets。 - 确认类名前缀与配置一致（默认
wot-）。
- VS Code 没有自动补全
- 确认安装 UnoCSS 官方扩展。
- 确认编辑器能定位到项目
unocss.config.ts。 - 确认类名写在扩展可扫描的文件类型内。
- CI 能复现但本地不复现（或反过来）
- 对齐 Node/pnpm 版本与锁文件。
- 对齐执行顺序（例如先构建主包，再构建依赖主包产物的 playground）。
响应风格要求
- 输出简洁、可执行，优先给“可复制配置 + 最短排查路径”。
- 当用户目标明确时，先给结论和配置，再补充原因说明。
- 不擅自引入本项目未使用的额外工具链或复杂抽象。