wot-ui-unocss-preset-guide

Wot UnoCSS Preset Usage Guide

Applicable Scenarios

When users ask about the following, prioritize this Skill:

• How to install @wot-ui/unocss-preset
• How to configure unocss.config.ts in presetWot
• prefix、preflight、baseTokens how to use
• Why class names do not take effect, autocomplete does not appear, CI and local results are inconsistent

The goal is to provide directly copyable best practices to help users quickly complete integration and run stably.

Minimal Installation Steps

pnpm add -D unocss
pnpm add @wot-ui/unocss-preset

Recommended Configuration (Complete Example)

import { presetWot } from '@wot-ui/unocss-preset'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetWot({
      prefix: 'wot',
      preflight: true,
      baseTokens: false,
    }),
  ],
})

Configuration Item Description

• prefix: Utility class prefix, default wot. Example:wot-text-primary、wot-m-main。
• preflight: Whether to inject wot-ui CSS variables, default true。
• baseTokens: Whether to expose the base palette and raw token class names, default false。

Common Class Name Examples

• Color:wot-text-primary、wot-bg-danger-surface、wot-border-border-main
• Spacing:wot-m-main、wot-gap-tight、wot-gap-x-loose
• Padding:wot-p-main、wot-px-tight、wot-pb-loose
• Rounded corners:wot-rounded-md、wot-rounded-full
• Font weight:wot-font-medium、wot-font-semibold
• Typography:wot-text-body-main、wot-text-title-large
• Opacity:wot-opacity-disabled
• Border:wot-border-stroke-main

Getting Started Examples (Copyable)

1) A "card" example (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) Spacing/layout example (common combinations)

• Margin:wot-mt-tight、wot-mt-main、wot-mt-super-loose
• Padding:wot-p-loose、wot-px-main、wot-py-extra-tight
• Horizontal/vertical combinations:wot-mx-main、wot-my-loose
• gap：wot-gap-tight、wot-gap-x-main、wot-gap-y-loose

3) Semantic color examples (background/text/border)

• Background:wot-bg-primary、wot-bg-success-surface、wot-bg-warning-surface、wot-bg-danger-surface
• Text:wot-text-text-main、wot-text-text-secondary、wot-text-primary、wot-text-success-main
• Border:wot-border-border-main、wot-border-success-main、wot-border-warning-main、wot-border-danger-main

4) Dark mode example

The preset outputs a dark variable selector .wot-theme-dark ..., you only need to add the class on the root node:

<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) Enable baseTokens (optional)

Enable when you want to use the base palette/raw tokens:

presetWot({
  baseTokens: true,
})

After enabling, additional tokens like wot-base-black will be provided (used for theme.colors matching with color rules).

Lightweight Reminders

• If a historical project still uses the w- prefix, it can be made compatible via prefix: 'w' .
• If the playground/subpackage build is abnormal, first check whether:
  • Package name import is used (such as @wot-ui/unocss-preset）
  • In scenarios depending on the main package's build output, run the main package build first
• If you need to sync upstream wot-ui variables, you can use:
  • pnpm generate:css-vars:clone

Common Troubleshooting

1. Class names do not take effect

• Confirm the project has enabled UnoCSS and presetWot() has been added to presets。
• Confirm the class name prefix matches the configuration (default wot-）。

1. VS Code has no autocomplete

• Confirm the official UnoCSS extension is installed.
• Confirm the editor can locate the project unocss.config.ts。
• Confirm the class names are written within file types that the extension can scan.

1. CI can reproduce but local cannot (or vice versa)

• Align Node/pnpm versions and lockfiles.
• Align execution order (for example, first build the main package, then build the playground that depends on the main package's build output).

Response Style Requirements

• Output should be concise and executable, prioritizing "copyable configuration + shortest troubleshooting path".
• When the user's goal is clear, provide the conclusion and configuration first, then add the reason explanation.
• Do not introduce additional toolchains or complex abstractions not used by this project without authorization.