Wot UnoCSS Preset 使用指南
适用场景
当用户询问安装 @wot-ui/unocss-preset、在 unocss.config.ts 中配置 presetWot、prefix/preflight/baseTokens 的用法，或排查类名不生效、自动补全不出现、CI 与本地结果不一致等问题时，优先使用本 Skill。目标是给出可直接复制的最佳实践，帮助用户快速完成接入并稳定运行。
最小安装步骤
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
上手示例（可复制）
- 一个“卡片”示例（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>
- 间距/布局示例（常见组合）
外边距：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
- 语义色示例（背景/文字/边框）
背景：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
- 暗黑模式示例
预设会输出暗色变量选择器 .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>
- 打开 baseTokens（可选）
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）。