docs: improve documentation for AI discoverability and SEO

Add comparison page, use cases guide, and optimize existing docs
with explicit definitions, FAQ-style headings, and structured tables
for better AI search engine visibility.

Author: timphandev

README.md

@@ -1,16 +1,60 @@
 # css-variants
 
-Monorepo for **css-variants** — a zero-dependency, type-safe CSS variant composition library for modern JavaScript.
+**The fastest, smallest CSS variant library for JavaScript and TypeScript.**
+
+A zero-dependency, type-safe alternative to CVA (Class Variance Authority) and tailwind-variants. Build powerful component style systems with variants — works with Tailwind CSS, vanilla CSS, CSS Modules, or any styling solution.
 
 ## Packages
 
-| Package | Description |
-|---------|-------------|
-| [css-variants](./packages/css-variants) | Core library for CSS variant composition |
+| Package | Description | Size |
+|---------|-------------|------|
+| [css-variants](./packages/css-variants) | Core library for CSS variant composition | ~1KB |
+
+## Quick Start
+
+```bash
+npm install css-variants
+```
+
+```typescript
+import { cv } from 'css-variants'
+
+const button = cv({
+  base: 'px-4 py-2 rounded font-medium',
+  variants: {
+    color: {
+      primary: 'bg-blue-600 text-white',
+      secondary: 'bg-gray-200 text-gray-800',
+    },
+    size: {
+      sm: 'text-sm px-3 py-1.5',
+      lg: 'text-lg px-6 py-3',
+    },
+  },
+})
+
+button({ color: 'primary', size: 'lg' })
+```
+
+## Why css-variants?
+
+| Feature | css-variants | CVA | tailwind-variants |
+|---------|:------------:|:---:|:-----------------:|
+| Bundle size | **~1KB** | ~2KB | ~5KB |
+| Performance | **Baseline** | 3-7x slower | 5-11x slower |
+| Slot variants | Built-in | No | Yes |
+| Style variants | Built-in | No | No |
+| Dependencies | 0 | 1 | 1 |
 
 ## Documentation
 
-Full documentation available at **[css-variants.vercel.app](https://css-variants.vercel.app/)**
+Full documentation: **[css-variants.vercel.app](https://css-variants.vercel.app/)**
+
+- [Getting Started](https://css-variants.vercel.app/getting-started/introduction/)
+- [API Reference](https://css-variants.vercel.app/api/cv/)
+- [Library Comparison](https://css-variants.vercel.app/resources/comparison/)
+- [Migration from CVA](https://css-variants.vercel.app/resources/migration-cva/)
+- [FAQ](https://css-variants.vercel.app/resources/faq/)
 
 ## License
 

apps/docs/astro.config.mjs

@@ -91,11 +91,34 @@ export default defineConfig({
         {
           label: 'Resources',
           items: [
-            { label: 'Migration from CVA', slug: 'resources/migration-cva' },
-            { label: 'Migration from Tailwind Variants', slug: 'resources/migration-tailwind-variants' },
-            { label: 'Performance', slug: 'resources/performance' },
-            { label: 'Benchmarks', slug: 'resources/benchmarks' },
-            { label: 'FAQ', slug: 'resources/faq' },
+            {
+              label: 'When Should You Use css-variants?',
+              slug: 'resources/when-to-use',
+            },
+            {
+              label: 'css-variants vs Other Libraries',
+              slug: 'resources/comparison',
+            },
+            {
+              label: 'Migrating from Class Variance Authority (CVA)',
+              slug: 'resources/migration-cva',
+            },
+            {
+              label: 'Migrating from tailwind-variants',
+              slug: 'resources/migration-tailwind-variants',
+            },
+            {
+              label: 'Performance Characteristics',
+              slug: 'resources/performance',
+            },
+            {
+              label: 'Benchmarks',
+              slug: 'resources/benchmarks',
+            },
+            {
+              label: 'Frequently Asked Questions (FAQ)',
+              slug: 'resources/faq',
+            },
           ],
         },
       ],