@cwcss/crosswind 0.1.6 → 0.2.1

package/README.md

@@ -1,390 +1,596 @@
-<p align="center"><img src=".github/art/cover.jpg" alt="Social Card of this repo"></p>
+# @cwcss/crosswind
 
-[![npm version][npm-version-src]][npm-version-href]
-[![GitHub Actions][github-actions-src]][github-actions-href]
-[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
-<!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] -->
-<!-- [![Codecov][codecov-src]][codecov-href] -->
+A performant utility-first CSS engine, compatible with Tailwind CSS. Built with TypeScript and optimized for Bun.
 
-# crosswind
-
-A blazingly fast, utility-first CSS framework built with Bun. Crosswind generates only the CSS you need by scanning your files for utility classes, providing Tailwind CSS-compatible utilities with exceptional performance.
-
-## Features
-
-- ⚡️**Blazingly Fast**- Built with Bun for exceptional performance (1000+ utilities in <10ms)
-- 🎯**On-Demand Generation**- Only generates CSS for utilities you actually use
-- 🎨**Tailwind-Compatible**- Familiar utility classes and syntax
-- 💪**Fully Typed**- Complete TypeScript support with type-safe configuration
-- 🔧**Highly Configurable**- Customize theme, colors, spacing, variants, and more
-- 📦**Zero Runtime Dependencies**- Minimal footprint, maximum performance
-- 🔥**Hot Reload**- Watch mode for instant rebuilds during development
-- 🎭**Variant Support**- Responsive, state (hover, focus, etc.), dark mode, and custom variants
-- ✨**Modern CSS Features**- Grid, Flexbox, animations, transforms, filters, and more
-- 🔨**Class Compilation**- Optimize HTML by compiling utility groups into single class names
-- 🧪**Thoroughly Tested**- 1300+ tests including comprehensive performance benchmarks
-- 🚀**Production Ready**- Minification, preflight CSS, and optimized builds
-- ⌨️**CLI & API**- Use via command line or programmatic API
-
-## Get Started
-
-### Installation
+## Installation
 
 ```bash
-bun add crosswind
-
-# or
-
-npm install crosswind
-```### Quick Start
-
-1.**Initialize Crosswind**:```bash
-
-# Create a config file
-
-bunx crosswind init
-
-```This creates a`crosswind.config.ts`file:```typescript
-import type { CrosswindOptions } from 'crosswind'
-
-export default {
-  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
-  output: './dist/crosswind.css',
-  minify: false,
-} satisfies CrosswindOptions
-```1.**Add utility classes to your HTML**:```html
-
-<div class="flex items-center justify-between p-4 bg-blue-500 text-white rounded-lg shadow-md hover:bg-blue-600">
-  <h1 class="text-2xl font-bold">Hello Crosswind!</h1>
-</div>
-
-```1.**Build your CSS**:```bash
+bun add @cwcss/crosswind
+```
 
-# Build once
+## Quick Start
 
-bunx crosswind build
+### Programmatic API
 
-# Build and watch for changes
+```typescript
+import { CSSGenerator, defaultConfig } from '@cwcss/crosswind'
 
-bunx crosswind watch
+const gen = new CSSGenerator(defaultConfig)
+gen.generate('flex')
+gen.generate('items-center')
+gen.generate('gap-4')
+gen.generate('p-8')
+gen.generate('bg-blue-500')
+gen.generate('text-white')
+gen.generate('rounded-lg')
+gen.generate('hover:bg-blue-600')
+gen.generate('dark:bg-gray-900')
 
-# Build with options
+const css = gen.toCSS(true) // true = include preflight
+```
 
-bunx crosswind build --output ./dist/styles.css --minify
-```### Programmatic API
+### Build API
 
-You can also use Crosswind programmatically:```typescript
-import { build } from 'crosswind'
+```typescript
+import { build } from '@cwcss/crosswind'
 
 const result = await build({
-  content: ['./src/**/*.html'],
+  content: ['./src/**/*.html', './src/**/*.tsx'],
   output: './dist/styles.css',
   minify: true,
 })
+```
 
-console.log(`Generated ${result.classes.size} classes in ${result.duration}ms`)
+### CLI
 
-```## CLI Commands
+```bash
+crosswind build
+crosswind build --watch
+crosswind build --minify
+```
 
-Crosswind provides a comprehensive CLI:```bash
-crosswind build            # Build CSS once
-crosswind watch            # Build and watch for changes
-crosswind init             # Create config file
-crosswind analyze          # Analyze utility class usage
-crosswind clean            # Remove output CSS file
-crosswind preflight        # Generate preflight CSS only
-crosswind --version        # Show version
-crosswind --help           # Show help
-```## Configuration
+## Configuration
 
-Crosswind supports extensive configuration options:```typescript
-import type { CrosswindOptions } from 'crosswind'
+Create a `crosswind.config.ts` in your project root:
 
-export default {
-  // Content sources to scan for utility classes
-  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
+```typescript
+import type { CrosswindConfig } from '@cwcss/crosswind'
 
-  // Output CSS file path
+export default {
+  content: ['./src/**/*.{html,tsx,stx}'],
   output: './dist/styles.css',
-
-  // Minify output CSS
   minify: false,
 
-  // Enable watch mode
-  watch: false,
-
-  // Enable verbose logging
-  verbose: false,
-
-  // Theme customization
   theme: {
-    colors: {
-      primary: '#3b82f6',
-      secondary: '#10b981',
-      // ... extend or override default colors
-    },
-    spacing: {
-      // ... customize spacing scale
+    extend: {
+      colors: {
+        brand: {
+          50: '#eff6ff',
+          500: '#3b82f6',
+          900: '#1e3a5a',
+        },
+      },
+      spacing: {
+        '18': '4.5rem',
+        '112': '28rem',
+      },
     },
-    fontSize: {
-      // ... customize font sizes
-    },
-    // ... and more
   },
 
-  // Shortcuts (utility aliases)
-  shortcuts: {
-    btn: 'px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600',
-    card: 'p-6 bg-white rounded-lg shadow-md',
-  },
-
-  // Custom variants
-  variants: {
-    // ... configure breakpoints, states, etc.
-  },
-
-  // Safelist (always include these classes)
-  safelist: ['bg-red-500', 'text-green-500'],
+  safelist: ['bg-brand-500', 'text-white'],
+  blocklist: ['opacity-0'],
+} satisfies Partial<CrosswindConfig>
+```
 
-  // Blocklist (never include these classes)
-  blocklist: ['debug-*'],
+### Theme
+
+The default theme includes Tailwind-compatible values for:
+
+- **colors** - Full color palette (slate, gray, zinc, red, orange, yellow, green, blue, indigo, purple, pink, etc.) with 50-950 shades in oklch
+- **spacing** - 0 through 96, plus `px` (1px), fractional values
+- **fontSize** - xs through 9xl with line-height pairs
+- **fontFamily** - sans, serif, mono
+- **screens** - sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px)
+- **borderRadius** - none, sm, DEFAULT, md, lg, xl, 2xl, 3xl, full
+- **boxShadow** - sm, DEFAULT, md, lg, xl, 2xl, inner, none
+
+All theme values can be extended or overridden via `theme.extend`.
+
+## Utilities
+
+### Layout
+
+| Utility | CSS |
+|---------|-----|
+| `block`, `inline-block`, `flex`, `grid`, `hidden` | `display: *` |
+| `static`, `fixed`, `absolute`, `relative`, `sticky` | `position: *` |
+| `top-*`, `right-*`, `bottom-*`, `left-*`, `inset-*` | Positioning |
+| `z-*` | `z-index` |
+| `overflow-*`, `overflow-x-*`, `overflow-y-*` | Overflow |
+| `float-*`, `clear-*` | Float & clear (includes logical `start`/`end`) |
+| `isolate`, `isolation-auto` | Isolation |
+| `object-cover`, `object-contain`, `object-fill`, `object-none` | Object fit |
+| `object-top`, `object-center`, `object-bottom`, etc. | Object position |
+| `columns-*` | Multi-column layout |
+| `break-before-*`, `break-after-*`, `break-inside-*` | Break behavior |
+| `box-border`, `box-content` | Box sizing |
+| `aspect-auto`, `aspect-square`, `aspect-video` | Aspect ratio |
+| `visible`, `invisible`, `collapse` | Visibility |
+
+### Flexbox
+
+| Utility | CSS |
+|---------|-----|
+| `flex-row`, `flex-col`, `flex-row-reverse`, `flex-col-reverse` | Direction |
+| `flex-wrap`, `flex-nowrap`, `flex-wrap-reverse` | Wrap |
+| `flex-1`, `flex-auto`, `flex-initial`, `flex-none` | Flex shorthand |
+| `grow`, `grow-0`, `shrink`, `shrink-0` | Grow & shrink |
+| `basis-*` | Flex basis (supports fractions: `basis-1/2`) |
+| `justify-*`, `items-*`, `self-*` | Alignment |
+| `justify-items-*`, `justify-self-*` | Justify items/self |
+| `content-*` | Align content |
+| `order-*`, `order-first`, `order-last`, `order-none` | Order |
+
+### Grid
+
+| Utility | CSS |
+|---------|-----|
+| `grid-cols-*`, `grid-rows-*` | Template columns/rows (1-12, none, subgrid) |
+| `col-span-*`, `col-start-*`, `col-end-*` | Column placement |
+| `row-span-*`, `row-start-*`, `row-end-*` | Row placement |
+| `grid-flow-row`, `grid-flow-col`, `grid-flow-dense` | Auto flow |
+| `auto-cols-*`, `auto-rows-*` | Auto columns/rows |
+| `gap-*`, `gap-x-*`, `gap-y-*` | Gap |
+| `place-content-*`, `place-items-*`, `place-self-*` | Place shortcuts |
+
+Arbitrary grid templates use underscore-to-space conversion:
 
-  // Custom rules
-  rules: [],
+```html
+<div class="grid grid-cols-[120px_1fr_200px]">
+<!-- grid-template-columns: 120px 1fr 200px -->
+```
 
-  // Preflight CSS (normalize/reset styles)
-  preflights: [],
+### Spacing
 
-  // Presets
-  presets: [],
-} satisfies CrosswindOptions
+| Utility | CSS |
+|---------|-----|
+| `p-*`, `px-*`, `py-*`, `pt-*`, `pr-*`, `pb-*`, `pl-*` | Padding |
+| `ps-*`, `pe-*` | Padding inline start/end (logical) |
+| `m-*`, `mx-*`, `my-*`, `mt-*`, `mr-*`, `mb-*`, `ml-*` | Margin |
+| `ms-*`, `me-*` | Margin inline start/end (logical) |
+| `space-x-*`, `space-y-*` | Space between children |
 
-```For more configuration options, see the [Configuration Guide](https://crosswind.stacksjs.org/config).
+Negative values supported: `-m-4`, `-translate-x-1`.
 
-## Available Utilities
+### Sizing
 
-Crosswind provides a comprehensive set of utility classes compatible with Tailwind CSS:
+| Utility | CSS |
+|---------|-----|
+| `w-*`, `h-*` | Width & height |
+| `size-*` | Width + height shorthand |
+| `min-w-*`, `max-w-*`, `min-h-*`, `max-h-*` | Min/max sizing |
 
--**Layout**: display, position, overflow, z-index, etc.
--**Flexbox & Grid**: flex, grid, gap, align, justify, etc.
--**Spacing**: margin, padding with full scale support
--**Sizing**: width, height, min/max sizes
--**Typography**: font family, size, weight, line height, text alignment, etc.
--**Backgrounds**: colors, gradients, images, position, size
--**Borders**: width, color, radius, style
--**Effects**: shadow, opacity, blend modes, filters
--**Transforms**: translate, rotate, scale, skew
--**Transitions & Animations**: duration, timing, delay
--**Interactivity**: cursor, pointer events, user select, scroll behavior
--**Advanced**: mask utilities, backdrop filters, ring utilities
+Values: spacing scale, `auto`, `full` (100%), `screen` (100vw/vh), `min`, `max`, `fit`, fractions (`w-1/2`).
 
-### Variants
+### Colors
 
--**Responsive**:`sm:`, `md:`, `lg:`, `xl:`, `2xl:`-**State**:`hover:`, `focus:`, `active:`, `disabled:`, `visited:`, `checked:`-**Pseudo-elements**:`before:`, `after:`, `placeholder:`, `selection:`-**Group/Peer**:`group-hover:`, `peer-focus:`-**Dark mode**:`dark:`-**Positional**:`first:`, `last:`, `odd:`, `even:`-**Important**:`!`prefix (e.g.,`!text-red-500`)
+All color utilities support opacity modifiers:
 
-### Arbitrary Values
+```html
+<!-- Integer opacity (0-100 scale) -->
+<div class="bg-blue-500/50">       <!-- 50% opacity -->
+<div class="text-white/75">        <!-- 75% opacity -->
+<div class="border-black/10">      <!-- 10% opacity -->
+
+<!-- Arbitrary opacity (0-1 scale) -->
+<div class="bg-white/[0.04]">      <!-- 4% opacity -->
+<div class="text-black/[0.87]">    <!-- 87% opacity -->
+```
 
-Crosswind supports arbitrary values for maximum flexibility:
+| Utility | CSS |
+|---------|-----|
+| `bg-*` | Background color |
+| `text-*` | Text color |
+| `border-*` | Border color |
+| `ring-*` | Ring color |
+| `divide-*` | Divide color (supports opacity: `divide-white/10`) |
+| `placeholder-*` | Placeholder color |
+| `accent-*` | Accent color |
+| `caret-*` | Caret color |
+| `fill-*`, `stroke-*` | SVG fill & stroke |
+
+Special values: `current` (currentColor), `transparent`, `inherit`, `white`, `black`.
+
+### Typography
+
+| Utility | CSS |
+|---------|-----|
+| `text-xs` through `text-9xl` | Font size |
+| `font-thin` through `font-black` | Font weight |
+| `font-sans`, `font-serif`, `font-mono` | Font family |
+| `italic`, `not-italic` | Font style |
+| `tracking-*` | Letter spacing |
+| `leading-*` | Line height |
+| `text-left`, `text-center`, `text-right`, `text-justify` | Alignment |
+| `uppercase`, `lowercase`, `capitalize`, `normal-case` | Text transform |
+| `underline`, `overline`, `line-through`, `no-underline` | Decoration |
+| `decoration-*` | Decoration style, color, thickness |
+| `truncate`, `text-ellipsis`, `text-clip` | Text overflow |
+| `text-wrap`, `text-nowrap`, `text-balance`, `text-pretty` | Text wrap |
+| `line-clamp-*` | Line clamp |
+| `indent-*` | Text indent |
+| `antialiased`, `subpixel-antialiased` | Font smoothing |
+| `tabular-nums`, `lining-nums`, `oldstyle-nums`, etc. | Font variant numeric |
+| `hyphens-none`, `hyphens-manual`, `hyphens-auto` | Hyphens |
+| `whitespace-*` | White space |
+| `break-normal`, `break-words`, `break-all` | Word break |
+
+### Borders
+
+| Utility | CSS |
+|---------|-----|
+| `border`, `border-0`, `border-2`, `border-4`, `border-8` | Border width |
+| `border-t`, `border-r`, `border-b`, `border-l` | Side borders |
+| `border-s`, `border-e` | Logical side borders (inline-start/end) |
+| `border-x`, `border-y` | Axis borders |
+| `border-solid`, `border-dashed`, `border-dotted`, `border-double`, `border-none` | Style |
+| `rounded-*` | Border radius |
+| `rounded-s-*`, `rounded-e-*` | Logical border radius |
+| `rounded-ss-*`, `rounded-se-*`, `rounded-es-*`, `rounded-ee-*` | Corner-specific logical radius |
+| `outline-*` | Outline width, style, color |
+| `outline-offset-*` | Outline offset |
+| `ring-*`, `ring-offset-*` | Ring |
+| `divide-x`, `divide-y` | Divide width |
+| `divide-*` | Divide color, style, opacity |
+
+### Effects & Filters
+
+| Utility | CSS |
+|---------|-----|
+| `shadow-*` | Box shadow |
+| `shadow-{color}` | Shadow color |
+| `opacity-*` | Opacity (0-100) |
+| `mix-blend-*` | Mix blend mode |
+| `bg-blend-*` | Background blend mode |
+| `blur-*`, `brightness-*`, `contrast-*`, `grayscale-*` | Filters |
+| `invert-*`, `saturate-*`, `sepia-*`, `hue-rotate-*` | Filters |
+| `drop-shadow-*` | Drop shadow filter |
+| `backdrop-blur-*`, `backdrop-brightness-*`, etc. | Backdrop filters |
+
+### Backgrounds & Gradients
+
+| Utility | CSS |
+|---------|-----|
+| `bg-fixed`, `bg-local`, `bg-scroll` | Background attachment |
+| `bg-clip-border`, `bg-clip-padding`, `bg-clip-content`, `bg-clip-text` | Background clip |
+| `bg-top`, `bg-center`, `bg-bottom`, etc. | Background position |
+| `bg-repeat`, `bg-no-repeat`, `bg-repeat-x`, `bg-repeat-y` | Background repeat |
+| `bg-auto`, `bg-cover`, `bg-contain` | Background size |
+
+**Linear gradients:**
 
 ```html
+<div class="bg-gradient-to-r from-blue-500 via-purple-500 to-pink-500">
+```
 
-<div class="w-[500px] h-[calc(100vh-4rem)] bg-[#1da1f2] text-[clamp(1rem,5vw,3rem)]">
-  Custom values!
-</div>
+Directions: `bg-gradient-to-{t,tr,r,br,b,bl,l,tl}`.
 
-```### Compile Class (HTML Optimization)
+**Radial gradients:**
 
-Optimize your HTML by compiling utility groups into single class names:```html
-<!-- Before -->
-<div class=":hw: flex items-center justify-between px-4 py-2 bg-white rounded-lg shadow-md">
-  Content
-</div>
+```html
+<div class="bg-radial from-white to-blue-500">
+<div class="bg-radial-at-t from-yellow-200 to-orange-500">
+```
 
-<!-- After build -->
-<div class="hw-2k9d3a">
-  Content
-</div>
-```This reduces HTML file size by up to 60%. Learn more in the [Compile Class documentation](https://crosswind.stacksjs.org/features/compile-class).
+Positions: `bg-radial-at-{t,tr,r,br,b,bl,l,tl,c}`.
 
-## Testing
+**Conic gradients:**
 
-Crosswind includes a comprehensive test suite with 1300+ tests:```bash
+```html
+<div class="bg-conic from-red-500 via-yellow-500 to-green-500">
+<div class="bg-conic-from-r from-blue-500 to-purple-500">
+```
 
-# Run all tests
+Starting angles: `bg-conic-from-{t,tr,r,br,b,bl,l,tl}`.
+
+### Transforms & Transitions
+
+| Utility | CSS |
+|---------|-----|
+| `scale-*`, `scale-x-*`, `scale-y-*` | Scale |
+| `rotate-*` | Rotate |
+| `translate-x-*`, `translate-y-*` | Translate |
+| `skew-x-*`, `skew-y-*` | Skew |
+| `origin-*` | Transform origin |
+| `transition`, `transition-all`, `transition-colors`, `transition-opacity`, `transition-shadow`, `transition-transform` | Transition property |
+| `duration-*` | Transition duration |
+| `ease-linear`, `ease-in`, `ease-out`, `ease-in-out` | Timing function |
+| `delay-*` | Transition delay |
+| `animate-spin`, `animate-ping`, `animate-pulse`, `animate-bounce`, `animate-none` | Animation |
+| `perspective-*` | 3D perspective |
+| `backface-visible`, `backface-hidden` | Backface visibility |
+
+### Interactivity
+
+| Utility | CSS |
+|---------|-----|
+| `cursor-*` | Cursor style |
+| `pointer-events-none`, `pointer-events-auto` | Pointer events |
+| `resize`, `resize-x`, `resize-y`, `resize-none` | Resize |
+| `select-none`, `select-text`, `select-all`, `select-auto` | User select |
+| `scroll-auto`, `scroll-smooth` | Scroll behavior |
+| `scroll-m-*`, `scroll-p-*` | Scroll margin/padding |
+| `snap-x`, `snap-y`, `snap-both`, `snap-mandatory`, `snap-proximity` | Scroll snap |
+| `snap-start`, `snap-end`, `snap-center`, `snap-align-none` | Snap align |
+| `touch-auto`, `touch-none`, `touch-manipulation`, `touch-pan-*` | Touch action |
+| `will-change-auto`, `will-change-scroll`, `will-change-contents`, `will-change-transform` | Will change |
+| `appearance-none`, `appearance-auto` | Appearance |
+| `scrollbar-auto`, `scrollbar-thin`, `scrollbar-none` | Scrollbar width |
+
+### Content
 
-bun test
+```html
+<div class="before:content-['*'] before:text-red-500">Required</div>
+<div class="before:content-empty before:block before:h-4"></div>
+<div class="after:content-[attr(data-count)]"></div>
+```
 
-# Run specific test files
+| Utility | CSS |
+|---------|-----|
+| `content-none` | `content: none` |
+| `content-empty` | `content: ""` |
+| `content-['text']` | `content: 'text'` |
+| `content-[attr(data-*)]` | `content: attr(data-*)` |
 
-bun test test/performance.test.ts
+### SVG
 
-# Run tests in watch mode
+| Utility | CSS |
+|---------|-----|
+| `fill-none`, `fill-current`, `fill-{color}` | Fill |
+| `stroke-none`, `stroke-current`, `stroke-{color}` | Stroke color |
+| `stroke-0`, `stroke-1`, `stroke-2` | Stroke width |
 
-bun test --watch
+### Tables
 
-```### Test Coverage
+| Utility | CSS |
+|---------|-----|
+| `border-collapse`, `border-separate` | Border collapse |
+| `border-spacing-*` | Border spacing |
+| `table-auto`, `table-fixed` | Table layout |
+| `caption-top`, `caption-bottom` | Caption side |
 
--**Core Functionality**: Parser, generator, scanner, builder
--**Utilities**: Layout, typography, colors, spacing, grid, flexbox
--**Variants**: Responsive, state, pseudo-elements, combinations
--**Advanced Features**: Shortcuts, custom rules, arbitrary values
--**Performance**: Benchmarks for generation speed and memory efficiency
--**Edge Cases**: Invalid inputs, complex nesting, duplicate handling
+## Variants
 
-## Performance
+### Pseudo-class Variants
 
-Crosswind is designed for speed. We've benchmarked against other popular utility-first CSS frameworks to demonstrate our performance advantages.
+```html
+<div class="hover:bg-blue-600 focus:ring-2 active:scale-95">
+<div class="first:mt-0 last:mb-0 odd:bg-gray-50 even:bg-white">
+<div class="disabled:opacity-50 checked:bg-blue-500 required:border-red-500">
+<div class="focus-within:ring-2 focus-visible:outline-2">
+<div class="visited:text-purple-600 target:ring-2">
+<div class="open:rotate-180 empty:hidden">
+<div class="valid:border-green-500 invalid:border-red-500 read-only:opacity-75">
+<div class="autofill:bg-yellow-50 indeterminate:bg-gray-300">
+```
 
-### Benchmark Results
+### Negation Variants
 
-Our comprehensive benchmark suite (20 tests) compares Crosswind with UnoCSS, Tailwind CSS v3, and Tailwind CSS v4.
+```html
+<div class="not-first:mt-4 not-last:mb-4">
+<div class="not-disabled:cursor-pointer not-empty:block">
+<div class="not-checked:bg-gray-100 not-only:border-b">
+<div class="not-first-of-type:pt-4 not-last-of-type:pb-4">
+```
 
-| Scenario | Crosswind | UnoCSS | Tailwind v3 | Tailwind v4 | Winner |
-|----------|----------|--------|-------------|-------------|--------|
-|**Simple Utilities**(10 classes) |**2.75µs**| 31.58µs | 14.32ms | 46.47ms | Crosswind ⚡ |
-|**Complex Utilities**(11 classes) |**8.61µs**| 43.77µs | 14.25ms | 39.26ms | Crosswind ⚡ |
-|**Arbitrary Values**(10 classes) |**41.71µs**| 64.44µs | 15.52ms | - | Crosswind ⚡ |
-|**Real-world Components**(~60 classes) |**25.26µs**| 97.71µs | 16.12ms | 45.07ms | Crosswind ⚡ |
-|**Large Scale**(500 classes) |**94.89µs**| 201.30µs | 14.51ms | 40.06ms | Crosswind ⚡ |
-|**CSS Output**(1000 values) |**1.50ms**| 115.59ms | 16.03ms | - | Crosswind ⚡ |
-|**Color Utilities**(330 classes) |**100.85µs**| 526.82µs | 12.89ms | 37.27ms | Crosswind ⚡ |
-|**Responsive**(500 classes) |**100.16µs**| 211.39µs | 12.86ms | 41.07ms | Crosswind ⚡ |
-|**Interactive States**(440 classes) |**260.75µs**| 1.16ms | 13.84ms | 38.06ms | Crosswind ⚡ |
-|**Duplicate Handling**(6000 items) |**43.19µs**| 1.81ms | 18.47ms | 48.11ms | Crosswind ⚡ |
-|**Typography**(50 classes) |**16.06µs**| 94.37µs | 14.37ms | 39.33ms | Crosswind ⚡ |
-|**Flexbox**(50 classes) |**13.77µs**| 88.62µs | 13.04ms | 42.38ms | Crosswind ⚡ |
-|**Grid**(55 classes) |**59.89µs**| 118.31µs | 15.10ms | 39.00ms | Crosswind ⚡ |
-|**Stacked Variants**(40 classes) |**73.43µs**| 148.79µs | 15.65ms | 41.11ms | Crosswind ⚡ |
-|**Transforms**(55 classes) |**78.39µs**| 100.85µs | 13.76ms | 44.34ms | Crosswind ⚡ |
-|**Transitions**(30 classes) |**12.96µs**| 66.47µs | 14.38ms | 36.46ms | Crosswind ⚡ |
-|**Border & Ring**(45 classes) |**12.55µs**| 90.45µs | 10.52ms | 40.58ms | Crosswind ⚡ |
-|**Shadow & Effects**(35 classes) |**6.92µs**| 62.12µs | 10.89ms | 36.62ms | Crosswind ⚡ |
-|**Incremental Generation**(200 classes) |**73.91µs**| 196.35µs | 14.07ms | 35.58ms | Crosswind ⚡ |
-|**Full Project**(~800 classes) |**649.87µs**| 1.38ms | 14.41ms | - | Crosswind ⚡ |
+### Pseudo-element Variants
 
-### Highlights
+```html
+<div class="before:content-[''] before:block before:h-4">
+<div class="after:content-['*'] after:text-red-500">
+<li class="marker:text-blue-500">Item</li>
+<input class="placeholder:text-gray-400">
+<p class="selection:bg-blue-200">Selectable text</p>
+<input class="file:bg-blue-50 file:border-0" type="file">
+```
 
--**Crosswind wins 20/20 benchmarks**vs all competitors
--**Simple utilities**: 11x faster than UnoCSS, 5,200x faster than Tailwind v3
--**Typography**: 6x faster than UnoCSS
--**Flexbox**: 6.4x faster than UnoCSS
--**Shadow & Effects**: 9x faster than UnoCSS
--**Border & Ring**: 7x faster than UnoCSS
--**Color utilities**: 5x faster than UnoCSS
--**Interactive states**: 4.5x faster than UnoCSS
--**Duplicate handling**: 42x faster than UnoCSS
--**CSS output generation**: 77x faster than UnoCSS
--**Full project simulation**: 2.1x faster than UnoCSS, 22x faster than Tailwind v3
+### Responsive Variants
 
-### Running Benchmarks
+```html
+<div class="p-4 sm:p-6 md:p-8 lg:p-12 xl:p-16 2xl:p-20">
+```
 
-You can run the benchmarks yourself to see the performance on your hardware:```bash
+| Variant | Breakpoint |
+|---------|-----------|
+| `sm:` | 640px |
+| `md:` | 768px |
+| `lg:` | 1024px |
+| `xl:` | 1280px |
+| `2xl:` | 1536px |
 
-# Run the comprehensive benchmark suite
+### Dark & Light Mode
 
-bun run benchmark
+```html
+<div class="bg-white dark:bg-gray-900 light:bg-gray-50">
+<div class="text-gray-900 dark:text-white">
+```
 
-# Or run from the packages/crosswind directory
+Uses class-based strategy (`.dark`/`.light` parent class).
 
-cd packages/crosswind
-bun run benchmark
-```All benchmarks use [Mitata](https://github.com/evanwashere/mitata) for accurate measurements and run on Bun runtime. Results may vary based on your hardware.
+### Group & Peer Variants
 
-## Development
+```html
+<!-- Group: parent state affects children -->
+<div class="group">
+  <p class="group-hover:text-blue-500">Hovering parent</p>
+  <p class="group-focus:ring-2">Parent focused</p>
+  <p class="group-has-[:checked]:bg-blue-50">Parent has checked input</p>
+</div>
 
-To contribute to Crosswind development:```bash
+<!-- Named groups (for nesting) -->
+<div class="group/card">
+  <div class="group/button">
+    <span class="group-hover/card:text-blue-500">Card hovered</span>
+  </div>
+</div>
 
-# Clone the repository
+<!-- Peer: sibling state affects element -->
+<input class="peer" />
+<p class="peer-invalid:text-red-500">Error message</p>
+<p class="peer-has-[:checked]:text-green-500">Checked sibling</p>
+```
 
-git clone <https://github.com/cwcss/crosswind.git>
-cd crosswind
+### has: Variant
 
-# Install dependencies
+```html
+<div class="has-[:focus]:ring-2">         <!-- :has(:focus) -->
+<div class="has-[input:checked]:bg-blue-50"> <!-- :has(input:checked) -->
+<div class="has-[>img]:p-4">             <!-- :has(>img) -->
+```
 
-bun install
+### aria-* Variants
 
-# Run tests
+```html
+<div class="aria-disabled:opacity-50">          <!-- [aria-disabled="true"] -->
+<div class="aria-expanded:rotate-180">          <!-- [aria-expanded="true"] -->
+<div class="aria-[sort=ascending]:text-blue-500"> <!-- [aria-sort=ascending] -->
+```
 
-bun test
+### data-* Variants
 
-# Run tests in watch mode
+```html
+<div class="data-loading:opacity-50">           <!-- [data-loading] -->
+<div class="data-[state=active]:bg-white">       <!-- [data-state=active] -->
+<div class="data-[theme=dark]:bg-black">         <!-- [data-theme=dark] -->
+```
 
-bun test --watch
+### Media Query Variants
 
-# Run performance benchmarks
+```html
+<div class="landscape:flex-row portrait:flex-col">
+<div class="motion-safe:animate-bounce motion-reduce:animate-none">
+<div class="contrast-more:border-2 contrast-less:border-0">
+<div class="forced-colors:border print:hidden">
+```
 
-bun test test/performance.test.ts
+Media variants stack with responsive variants:
 
-# Type check
+```html
+<div class="lg:landscape:flex-row">
+<!-- @media (min-width: 1024px) and (orientation: landscape) -->
+```
 
-bun run typecheck
+### @supports Variant
 
-# Build the package
+```html
+<div class="supports-[display:grid]:grid">
+<div class="supports-[backdrop-filter:blur(0)]:backdrop-blur-sm">
+```
 
-bun run build
+### Container Queries
 
+```html
+<div class="@container">
+  <div class="@sm:flex @md:grid @lg:grid-cols-3">
+</div>
 ```
 
-## Documentation
+### Direction Variants
 
-For comprehensive documentation, visit [crosswind.stacksjs.org](https://crosswind.stacksjs.org)
+```html
+<div class="rtl:text-right ltr:text-left">
+```
 
-- [Installation Guide](https://crosswind.stacksjs.org/install)
-- [Usage Guide](https://crosswind.stacksjs.org/usage)
-- [Configuration](https://crosswind.stacksjs.org/config)
-- [CLI Reference](https://crosswind.stacksjs.org/features/cli)
-- [API Reference](https://crosswind.stacksjs.org/api-reference)
+## Arbitrary Values
 
-## Changelog
+Use brackets for any CSS value:
 
-Please see our [releases](https://github.com/cwcss/crosswind/releases) page for more information on what has changed recently.
+```html
+<div class="w-[350px] h-[calc(100vh-4rem)] p-[clamp(1rem,3vw,2rem)]">
+<div class="text-[#1a1a1a] bg-[rgb(255,0,0)] border-[oklch(50%_0.2_240)]">
+<div class="grid-cols-[120px_1fr_200px]">  <!-- underscores become spaces -->
+<div class="text-[clamp(1rem,3vw,2rem)]">
+<div class="font-[600]">
+<div class="tracking-[0.2em]">
+<div class="leading-[1.7]">
+```
 
-## Contributing
+### Arbitrary Properties
 
-Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
+```html
+<div class="[mask-type:luminance]">
+<div class="[text-wrap:balance]">
+```
 
-We welcome contributions! Whether it's:
+### Type Hints
 
-- 🐛 Bug reports and fixes
-- ✨ New utility classes or features
-- 📝 Documentation improvements
-- ⚡️ Performance optimizations
-- 🧪 Additional test coverage
+```html
+<div class="text-[color:var(--brand)]">
+<div class="text-[length:var(--size)]">
+```
 
-## Community
+## Important Modifier
 
-For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+Prefix with `!` to apply `!important`:
 
-[Discussions on GitHub](https://github.com/cwcss/crosswind/discussions)
+```html
+<div class="!p-4 !text-red-500">
+```
 
-For casual chit-chat with others using this package:
+## Presets
 
-[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+```typescript
+import type { Preset } from '@cwcss/crosswind'
 
-## Postcardware
+const myPreset: Preset = {
+  name: 'my-preset',
+  theme: {
+    extend: {
+      colors: {
+        brand: '#3b82f6',
+      },
+    },
+  },
+  shortcuts: {
+    btn: 'px-4 py-2 rounded font-semibold',
+  },
+}
 
-“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
+export default {
+  presets: [myPreset],
+}
+```
 
-Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
+## Shortcuts
 
-## Sponsors
+Define reusable class combinations:
 
-We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
+```typescript
+export default {
+  shortcuts: {
+    'btn': 'px-4 py-2 rounded-lg font-semibold transition-colors',
+    'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-600',
+    'card': 'rounded-xl border border-gray-200 p-6 shadow-sm',
+  },
+}
+```
 
-- [JetBrains](https://www.jetbrains.com/)
-- [The Solana Foundation](https://solana.com/)
+## Performance
 
-## License
+Crosswind uses several optimizations for fast CSS generation:
 
-The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
+- **O(1) static utility map** for ~80% of common utilities (display, flex, grid, transitions, etc.)
+- **Pre-computed color map** with flat cache for instant color lookups
+- **Class-level caching** prevents duplicate generation
+- **Selector caching** avoids rebuilding selectors with variants
+- **Media query caching** for responsive and feature variants
+- **Negative match cache** to skip known-unmatched utilities
 
-Made with 💙
+Benchmarks (1000 utilities):
+- Simple utilities: ~0.7ms
+- Complex utilities: ~4.5ms
+- Arbitrary values: ~0.6ms
 
-<!-- Badges -->
-[npm-version-src]: <https://img.shields.io/npm/v/crosswind?style=flat-square>
-[npm-version-href]: <https://npmjs.com/package/crosswind>
-[github-actions-src]: <https://img.shields.io/github/actions/workflow/status/cwcss/crosswind/ci.yml?style=flat-square&branch=main>
-[github-actions-href]: <https://github.com/cwcss/crosswind/actions?query=workflow%3Aci>
+## License
 
-<!-- [codecov-src]: <https://img.shields.io/codecov/c/gh/cwcss/crosswind/main?style=flat-square>
-[codecov-href]: <https://codecov.io/gh/cwcss/crosswind> -->
+MIT