UnoCSS

UnoCSS

UnoCSS is an instant on-demand atomic CSS engine. It generates only the CSS for utility classes you actually use — no parsing, no AST, no scanning. 5x faster than Tailwind CSS JIT with ~6kb min+brotli and zero dependencies.

When to Use This Skill

Core Expertise

• Instant generation: No parsing or AST — direct regex-based class extraction
• Preset-driven: All utilities come from presets, fully customizable
• Framework-agnostic: Vite, Webpack, PostCSS, Nuxt, Astro, Svelte, CLI
• Extensible: Custom rules, variants, shortcuts, extractors, transformers
• Inspector: Built-in dev tool for debugging generated utilities

Installation

# Vite project (most common)
npm add -D unocss

# Bun
bun add -d unocss

# Standalone CLI
npm add -D @unocss/cli

Vite Integration

Basic Setup

// vite.config.ts
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [UnoCSS()]
})

// main.ts - import the virtual stylesheet
import 'virtual:uno.css'

Configuration File

// uno.config.ts
import { defineConfig, presetWind3 } from 'unocss'

export default defineConfig({
  presets: [presetWind3()]
})

With Lightning CSS (Recommended Combo)

// vite.config.ts
import UnoCSS from 'unocss/vite'
import browserslist from 'browserslist'
import { browserslistToTargets } from 'lightningcss'

export default defineConfig({
  plugins: [UnoCSS()],
  css: {
    transformer: 'lightningcss',
    lightningcss: {
      targets: browserslistToTargets(browserslist('>= 0.25%'))
    }
  },
  build: {
    cssMinify: 'lightningcss'
  }
})

Plugin Modes

Framework-Specific Plugin Order

CLI Usage

# Generate CSS from source files
unocss "src/**/*.{html,tsx,vue}" -o dist/uno.css

# Multiple glob patterns
unocss "src/**/*.tsx" "pages/**/*.vue" -o dist/uno.css

# Minified output
unocss "src/**/*.tsx" -o dist/uno.css --minify

# Output to stdout (pipe-friendly)
unocss "src/**/*.tsx" --stdout

# Watch mode for development
unocss "src/**/*.tsx" -o dist/uno.css --watch

# With specific config file
unocss "src/**/*.tsx" -o dist/uno.css --config uno.config.ts

# Include preflight styles
unocss "src/**/*.tsx" -o dist/uno.css --preflights

# Use specific preset without config
unocss "src/**/*.tsx" -o dist/uno.css --preset wind4

Configuration

Presets

// uno.config.ts
import {
  defineConfig,
  presetWind3,        // Tailwind CSS v3 compatible utilities
  presetIcons,        // Pure CSS icons from Iconify
  presetAttributify,  // Attributify mode (utilities as HTML attributes)
  presetTypography,   // Typography prose classes
  presetWebFonts,     // Web font loading
  presetMini,         // Minimal preset (subset of wind)
} from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(),
    presetIcons({
      scale: 1.2,
      cdn: 'https://esm.sh/'
    }),
    presetAttributify(),
    presetTypography(),
    presetWebFonts({
      provider: 'google',
      fonts: { sans: 'Inter', mono: 'Fira Code' }
    })
  ]
})

Wind3 vs Wind4

Custom Rules

// uno.config.ts
export default defineConfig({
  rules: [
    // Static rule
    ['custom-padding', { padding: '1rem' }],
    // Dynamic rule
    [/^m-(\d+)$/, ([, d]) => ({ margin: `${Number(d) / 4}rem` })],
  ]
})

Shortcuts

// uno.config.ts
export default defineConfig({
  shortcuts: {
    'btn': 'py-2 px-4 font-semibold rounded-lg shadow-md',
    'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-700',
    'card': 'p-4 rounded-lg shadow bg-white dark:bg-gray-800',
  }
})

Theme

// uno.config.ts
export default defineConfig({
  theme: {
    colors: {
      primary: '#3b82f6',
      secondary: '#64748b',
    },
    breakpoints: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
    }
  }
})

Safelist

// uno.config.ts — pre-generate classes not found in source scanning
export default defineConfig({
  safelist: [
    'bg-red-500',
    'text-white',
    ...Array.from({ length: 5 }, (_, i) => `p-${i + 1}`)
  ]
})

Layers

// uno.config.ts — control CSS specificity ordering
export default defineConfig({
  layers: {
    components: -1,  // Before utilities
    default: 1,      // Utilities
    utilities: 2,    // Higher specificity utilities
  }
})

Icons Preset

Pure CSS icons from any Iconify collection:

# Install icon collections
npm add -D @iconify-json/mdi @iconify-json/lucide

// uno.config.ts
import { presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      extraProperties: {
        'display': 'inline-block',
        'vertical-align': 'middle',
      }
    })
  ]
})

<!-- Usage in templates -->
<div class="i-mdi-home text-2xl" />
<div class="i-lucide-settings w-6 h-6" />

Inspector

The built-in inspector shows generated CSS in development:

// main.ts
import 'virtual:uno.css'

Visit /__unocss in your dev server to see the inspector with:

• Generated CSS rules
• Matched classes per file
• Config overview

DevTools Integration

// main.ts — enable class editing in browser DevTools
import 'virtual:uno.css'
import 'virtual:unocss-devtools'

Variant Groups

Shorthand for common prefixes:

<!-- Without variant groups -->
<div class="hover:bg-blue-500 hover:text-white hover:font-bold" />

<!-- With variant groups -->
<div class="hover:(bg-blue-500 text-white font-bold)" />

Enable with transformer:

import { transformerVariantGroup } from 'unocss'

export default defineConfig({
  transformers: [transformerVariantGroup()]
})

Agentic Optimizations

Quick Reference

References

• Official docs: https://unocss.dev
• Interactive playground: https://unocss.dev/play
• Vite integration: https://unocss.dev/integrations/vite
• CLI reference: https://unocss.dev/integrations/cli
• Presets: https://unocss.dev/presets