Generated banner for Unocss
Generated logo for Unocss

Unocss

Anthony FuCommunityCreated by Anthony Fu

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found

From the author

UnoCSS instant atomic CSS engine, superset of Tailwind CSS. Use when configuring UnoCSS, writing utility rules, shortcuts, or working with presets like Wind, Icons, Attributify.
— the description by Anthony Fu

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

UnoCSS is an instant, atomic CSS engine that provides a highly flexible and extensible approach to styling. Unlike traditional CSS frameworks, it is un-opinionated and relies on presets to provide utility classes. It serves as a superset of Tailwind CSS, allowing developers to leverage existing knowledge while benefiting from advanced features like custom rules, shortcuts, and various integration presets. The engine operates by extracting utility classes from source files at build time to generate CSS on-demand, ensuring minimal bundle sizes.

What it does

  • Generates atomic CSS utilities on-demand based on project configuration.
  • Supports custom utility rules, shortcuts, and design tokens via a central configuration file.
  • Provides modular presets for features like icons, typography, web fonts, and attributify mode.
  • Integrates with build tools like Vite and frameworks like Nuxt for seamless development.
  • Allows fine-grained control over CSS generation through safelists, blocklists, and custom extractors.
  • Supports code transformation features like variant grouping and CSS directives.

When to use it

  • When you need a highly customizable and performant CSS solution for modern web applications.
  • When you want to use Tailwind-like syntax but require more flexibility or specific custom utilities.
  • When you need to integrate specialized features like Iconify icons or custom web fonts directly into your CSS workflow.
  • When you are working in a Vite or Nuxt environment and want optimized, build-time CSS generation.

Advantages

  • Extremely fast, on-demand CSS generation.
  • Highly extensible architecture through presets and custom rules.
  • Compatible with Tailwind CSS syntax.
  • Reduces CSS bundle size by only generating what is actually used.
  • Offers powerful configuration options for complex design systems.

Usage examples

“How do I define a custom shortcut in UnoCSS?”
You can add a 'shortcuts' object to your 'uno.config.ts' file, mapping a shorthand name to a string of utility classes, such as 'btn': 'py-2 px-4 rounded'.
“How can I ensure specific utility classes are always included in my build?”
Add the required classes to the 'safelist' array within your 'uno.config.ts' file to force UnoCSS to include them regardless of whether they are found in the source code.
“How do I add a custom rule for a specific margin value?”
In your 'uno.config.ts', add an entry to the 'rules' array, such as ['m-custom', { margin: '13px' }], to generate a new utility class.
“How do I enable attributify mode in my project?”
Install the 'preset-attributify' package and add 'presetAttributify()' to the 'presets' array in your 'uno.config.ts' file.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/antfu/unocss/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip unocss.zip -d .agents/skills

Documentation by Anthony Fu

UnoCSS is an instant atomic CSS engine designed to be flexible and extensible. The core is un-opinionated - all CSS utilities are provided via presets. It's a superset of Tailwind CSS, so you can reuse your Tailwind knowledge for basic syntax usage.

Important: Before writing UnoCSS code, agents should check for uno.config.* or unocss.config.* files in the project root to understand what presets, rules, and shortcuts are available. If the project setup is unclear, avoid using attributify mode and other advanced features - stick to basic class usage.

The skill is based on UnoCSS v66.10.5, generated at 2026-09-25.

Core

TopicDescriptionReference
ConfigurationConfig file setup and all configuration optionscore-config
RulesStatic and dynamic rules for generating CSS utilitiescore-rules
ShortcutsCombine multiple rules into single shorthandscore-shortcuts
ThemeTheming system for colors, breakpoints, and design tokenscore-theme
VariantsApply variations like hover:, dark:, responsive to rulescore-variants
ExtractingHow UnoCSS extracts utilities from source codecore-extracting
Safelist & BlocklistForce include or exclude specific utilitiescore-safelist
Layers & PreflightsCSS layer ordering and raw CSS injectioncore-layers
ProcessorsTransform generated CSS layers (incl. Lightning CSS)core-processors

Presets

Main Presets
TopicDescriptionReference
Preset Wind3Tailwind CSS v3 / Windi CSS compatible preset (most common)preset-wind3
Preset Wind4Tailwind CSS v4 compatible preset with modern CSS featurespreset-wind4
Preset MiniMinimal preset with essential utilities for custom buildspreset-mini
Feature Presets
TopicDescriptionReference
Preset IconsPure CSS icons using Iconify with any icon setpreset-icons
Preset AttributifyGroup utilities in HTML attributes instead of classpreset-attributify
Preset TypographyProse classes for typographic defaultspreset-typography
Preset Web FontsEasy Google Fonts and other web fonts integrationpreset-web-fonts
Preset TagifyUse utilities as HTML tag namespreset-tagify
Preset Rem to PxConvert rem units to px for utilitiespreset-rem-to-px

Transformers

TopicDescriptionReference
Variant GroupShorthand for grouping utilities with common prefixestransformer-variant-group
DirectivesCSS directives: @apply, @screen, theme(), icon()transformer-directives
Compile ClassCompile multiple classes into one hashed classtransformer-compile-class
Attributify JSXSupport valueless attributify in JSX/TSXtransformer-attributify-jsx

Integrations

TopicDescriptionReference
Vite IntegrationSetting up UnoCSS with Vite and framework-specific tipsintegrations-vite
Nuxt IntegrationUnoCSS module for Nuxt applicationsintegrations-nuxt

Files

references/core-safelist.md


name: unocss-safelist-blocklist description: Force include or exclude specific utilities

Safelist and Blocklist

Control which utilities are always included or excluded.

Safelist

Utilities always included, regardless of detection:

export default defineConfig({
  safelist: [
    'p-1', 'p-2', 'p-3',
    // Dynamic generation
    ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
  ],
})
Function Form
safelist: [
  'p-1',
  () => ['m-1', 'm-2'],
  (context) => {
    const colors = Object.keys(context.theme.colors || {})
    return colors.map(c => `bg-${c}-500`)
  },
]
Common Use Cases
safelist: [
  // Dynamic colors from CMS
  () => ['primary', 'secondary'].flatMap(c => [
    `bg-${c}`, `text-${c}`, `border-${c}`,
  ]),
  
  // Component variants
  () => {
    const variants = ['primary', 'danger']
    const sizes = ['sm', 'md', 'lg']
    return variants.flatMap(v => sizes.map(s => `btn-${v}-${s}`))
  },
]

Blocklist

Utilities never generated. Beyond excluding false positives, the blocklist enforces a single canonical syntax across a codebase (e.g. block border and border-1 so everyone writes b), keeping CSS output minimal. Combine with @unocss/eslint-plugin to surface the block messages during development — without it, blocked utilities are silently dropped.

Matcher Types

Three matcher types, each optionally wrapped in a [matcher, meta] tuple:

type BlocklistValue = string | RegExp | ((selector: string) => boolean | null | undefined)
type BlocklistRule = BlocklistValue | [BlocklistValue, BlocklistMeta]

interface BlocklistMeta {
  message?: string | ((selector: string) => string)
}
blocklist: [
  'p-1',                       // string: exact match
  /^p-[2-4]$/,                 // RegExp: pattern match (.test())
  s => s.endsWith('px'),       // function: returns truthy to block
]
Messages

A message (static or callback receiving the matched selector) explains why a utility is blocked:

blocklist: [
  [/^border$/, { message: 'use shorter "b"' }],
  // dynamic message from the blocked selector
  [/^border(?:-[btrlxy])?$/, {
    message: v => `use shorter "${v.replace(/^border/, 'b')}"`,
  }],
]

With @unocss/eslint-plugin this appears as "border" is in blocklist: use shorter "b".

Variant Awareness

The blocklist checks selectors before and after variant stripping — blocking p-1 also blocks hover:p-1, md:p-1, dark:p-1. Don't account for variant prefixes in patterns.

Merging

Blocklist arrays from all presets and user config are merged (accumulate, never override). A utility blocked by any source stays blocked.

Common Patterns
blocklist: [
  // enforce shorter aliases
  [/^flex-grow$/, { message: 'use shorter "grow"' }],

  // restrict to design system tokens via negative lookahead
  // (\$ allows CSS var references like font-$myVar to pass)
  [new RegExp(`^font-(?!(?:${Object.keys(theme.fontFamily).join('|')}|\\$)$).+$`), {
    message: 'use design system font families',
  }],

  // force separate utilities over slash opacity (better reuse, smaller bundle)
  [/^(c|bg)-.+\/\d+$/, { message: 'use "bg-red bg-op-50" instead of slash notation' }],

  // decompose shorthands: "size-4" → "w-4 h-4"
  [/^size-(.+)$/, {
    message: v => `use "w-${v.match(/^size-(.+)$/)?.[1]} h-${v.match(/^size-(.+)$/)?.[1]}"`,
  }],
]

Safelist vs Blocklist

FeatureSafelistBlocklist
PurposeAlways includeAlways exclude
Strings✅✅
Regex❌✅
Functions✅✅ (returns truthy to block)
Messages❌✅

Note: Blocklist wins if utility is in both.

Best Practice

Prefer static mappings over safelist:

// Better: UnoCSS extracts automatically
const sizes = {
  sm: 'text-sm p-2',
  md: 'text-base p-4',
}

// Avoid: Large safelist
safelist: ['text-sm', 'text-base', 'p-2', 'p-4']

<!-- Source references: - https://unocss.dev/config/safelist - https://unocss.dev/guide/extracting -->

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Anthony Fu
Publisher
Anthony Fu (Community)
Source
antfu/skills · skills/unocss · commit f63e9ec
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE.md)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Anthony Fu.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download unocss.zip