Windi CSS — On-Demand Utility-First CSS Framework

Introduction

Windi CSS pioneered the on-demand approach to utility CSS, generating only the classes used in your source files at dev time rather than scanning a full prebuilt stylesheet. This approach later influenced Tailwind CSS v3's JIT mode and UnoCSS. Windi CSS adds several developer ergonomics on top of standard utility classes, including variant groups and an attributify mode.

What Windi CSS Does

• Scans your source files and generates only the utility classes you actually use
• Supports variant groups like hover:(bg-blue-500 text-white) to reduce repetition
• Provides attributify mode where utilities can be written as HTML attributes instead of class names
• Includes a CSS directives system with @apply, @screen, and @variants
• Offers integrations for Vite, Webpack, Rollup, Nuxt, Next.js, and Svelte

Architecture Overview

Windi CSS operates as a build-time tool that parses source files (HTML, Vue, JSX, Svelte, etc.) to extract utility class usage. Its compiler maps each detected class to the corresponding CSS rule and outputs a minimal stylesheet. The compiler is written in TypeScript and runs as either a standalone CLI, a PostCSS plugin, or a bundler plugin. In dev mode, it watches files and incrementally updates the generated CSS. The design system configuration mirrors Tailwind's tailwind.config.js format for easy migration.

Self-Hosting & Configuration

• Create a windi.config.ts file to customize theme, colors, fonts, and breakpoints
• Use the Vite plugin for zero-config integration with hot module replacement
• Enable attributify mode in config with attributify: true
• Add @apply directives in CSS files to compose utility classes into custom classes
• Configure safelist patterns for dynamically generated class names

Key Features

• Variant groups that reduce class attribute length by grouping variants: sm:(p-4 text-lg)
• Attributify mode that moves utilities to HTML attributes for cleaner markup
• Shortcuts system for defining reusable utility combinations in config
• Full compatibility with Tailwind CSS utility class names and configuration format
• Design-time analyzer that visualizes utility usage across your project

Comparison with Similar Tools

• Tailwind CSS — the most popular utility-first framework; Windi CSS adds variant groups and attributify mode with a compatible API
• UnoCSS — instant atomic CSS engine inspired by Windi CSS; UnoCSS is more extensible via presets but less opinionated
• Tachyons — an earlier functional CSS library with a fixed class set; Windi CSS generates classes on demand with customizable design tokens
• Bootstrap — component-based CSS framework; Windi CSS is utility-first and generates no unused styles

FAQ

Q: Can I migrate from Tailwind CSS to Windi CSS? A: Yes, Windi CSS is largely compatible with Tailwind CSS configuration and class names. Most projects can switch by changing the build plugin.

Q: Is Windi CSS still maintained? A: The project is in maintenance mode. The maintainer recommends UnoCSS as the spiritual successor for new projects.

Q: Does Windi CSS support dark mode? A: Yes, via the dark: variant, with support for both class-based and media-query-based dark mode.

Q: How does on-demand generation improve performance? A: Instead of shipping a multi-megabyte CSS file and purging unused styles, Windi CSS generates only what is used, resulting in faster dev server startup and smaller production bundles.

Sources

• https://github.com/windicss/windicss
• https://windicss.org