Wot UnoCSS Preset 使用指南

适用场景

• 如何安装

  @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 ...

<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（可选）

presetWot({
  baseTokens: true,
})

wot-base-black

theme.colors

轻量提醒

• 历史项目若仍使用

  w-

  前缀，可通过

  prefix: 'w'

  兼容。
• 若 playground/子包构建异常，优先检查是否：
  • 使用包名导入（如

    @wot-ui/unocss-preset

    ）
  • 在依赖主包产物的场景下先执行主包构建
• 若需要同步上游 wot-ui 变量，可使用：

  • pnpm generate:css-vars:clone

常见问题排查

1. 类名不生效

• 确认项目已启用 UnoCSS 且

  presetWot()

  已加入

  presets

  。
• 确认类名前缀与配置一致（默认

  wot-

  ）。

1. VS Code 没有自动补全

• 确认安装 UnoCSS 官方扩展。
• 确认编辑器能定位到项目

  unocss.config.ts

  。
• 确认类名写在扩展可扫描的文件类型内。

1. CI 能复现但本地不复现（或反过来）

• 对齐 Node/pnpm 版本与锁文件。
• 对齐执行顺序（例如先构建主包，再构建依赖主包产物的 playground）。

响应风格要求

• 输出简洁、可执行，优先给“可复制配置 + 最短排查路径”。
• 当用户目标明确时，先给结论和配置，再补充原因说明。
• 不擅自引入本项目未使用的额外工具链或复杂抽象。