tailwindcss

# TailwindCSS v4 Patterns

## Overview

TailwindCSS v4 introduces a CSS-first approach, eliminating the need for JavaScript configuration files. All customization happens directly in CSS using new directives.

## Key Changes from v3 to v4

| Feature | v3 | v4 |
|---------|-----|-----|
| Configuration | `tailwind.config.js` | CSS `@theme` directive |
| Content detection | JS array | `@source` directive |
| Plugin loading | `require()` in JS | `@plugin` directive |
| Custom variants | JS API | `@custom-variant` directive |
| Custom utilities | JS API | `@utility` directive |

## Browser Support

TailwindCSS v4 requires modern browsers:
- Safari 16.4+
- Chrome 111+
- Firefox 128+

**Important**: No CSS preprocessors (Sass/Less) needed - Tailwind IS the preprocessor.

---

## Documentation Index

### Core Documentation

| Topic | URL | Description |
|-------|-----|-------------|
| Installation | https://tailwindcss.com/docs/installation | Setup guides by framework |
| Using Vite | https://tailwindcss.com/docs/installation/vite | Vite integration (recommended) |
| Editor Setup | https://tailwindcss.com/docs/editor-setup | VS Code IntelliSense |
| Upgrade Guide | https://tailwindcss.com/docs/upgrade-guide | v3 to v4 migration |
| Browser Support | https://tailwindcss.com/docs/browser-support | Compatibility requirements |

### Configuration Reference

| Directive | URL | Description |
|-----------|-----|-------------|
| @theme | https://tailwindcss.com/docs/theme | Define design tokens |
| @source | https://tailwindcss.com/docs/content-configuration | Content detection |
| @import | https://tailwindcss.com/docs/import | Import Tailwind layers |
| @config | https://tailwindcss.com/docs/configuration | Legacy JS config |

### CSS Features

| Feature | URL | Description |
|---------|-----|-------------|
| Dark Mode | https://tailwindcss.com/docs/dark-mode | Dark mode strategies |
| Responsive Design | https://tailwindcss.com/docs/responsive-design | Breakpoint utilities |
| Hover & Focus | https://tailwindcss.com/docs/hover-focus-and-other-states | State variants |
| Container Queries | https://tailwindcss.com/docs/container-queries | Component-responsive design |

### Customization

| Topic | URL | Description |
|-------|-----|-------------|
| Theme Configuration | https://tailwindcss.com/docs/theme | Token customization |
| Adding Custom Styles | https://tailwindcss.com/docs/adding-custom-styles | Extending Tailwind |
| Functions & Directives | https://tailwindcss.com/docs/functions-and-directives | CSS functions |
| Plugins | https://tailwindcss.com/docs/plugins | Plugin system |

---

## CSS-First Configuration

### Basic Setup

```css
/* src/index.css */
@import "tailwindcss";
```

This single import replaces the v3 directives (`@tailwind base`, `@tailwind components`, `@tailwind utilities`).

### @theme Directive - Design Tokens

The `@theme` directive defines design tokens as CSS custom properties:

```css
@import "tailwindcss";

@theme {
  /* Colors */
  --color-primary: hsl(221 83% 53%);
  --color-primary-dark: hsl(224 76% 48%);
  --color-secondary: hsl(215 14% 34%);
  --color-accent: hsl(328 85% 70%);

  /* With oklch (modern color space) */
  --color-success: oklch(0.723 0.191 142.5);
  --color-warning: oklch(0.828 0.189 84.429);
  --color-error: oklch(0.637 0.237 25.331);

  /* Typography */
  --font-display: "Satoshi", "sans-serif";
  --font-body: "Inter", "sans-serif";
  --font-mono: "JetBrains Mono", "monospace";

  /* Spacing */
  --spacing-page: 2rem;
  --spacing-section: 4rem;

  /* Custom breakpoints */
  --breakpoint-xs: 480px;
  --breakpoint-3xl: 1920px;

  /* Animation timing */
  --ease-spring: cubic-bezier(0.68, -0.55, 0.265, 1.55);
  --duration-fast: 150ms;
  --duration-normal: 300ms;
}
```

**Generated utilities from above:**
- Colors: `bg-primary`, `text-primary-dark`, `border-accent`
- Fonts: `font-display`, `font-body`, `font-mono`
- Animations: `ease-spring`, `duration-fast`

### @theme inline Pattern

Use `@theme inline` to reference existing CSS variables without generating new utilities:

```css
/* Define CSS variables normally */
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --primary: oklch(0.205 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
}

/* Map to Tailwind utilities */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-primary: var(--primary);
}
```

**When to use `@theme inline`:**
- Theming with CSS variables (light/dark mode)
- Shadcn/ui integration
- Dynamic theme switching

### @source Directive - Content Detection

```css
@import "tailwindcss";

/* Default: Tailwind scans all git-tracked files */

/* Add additional sources */
@source "../node_modules/my-ui-library/src/**/*.{html,js}";
@source "../shared-components/**/*.tsx";

/* Safelist specific utilities */
@source inline("bg-red-500 text-white p-4");
```

### @custom-variant - Custom Variants

```css
@import "tailwindcss";

/* Dark mode variant (class-based) */
@custom-variant dark (&:is(.dark *));

/* RTL variant */
@custom-variant rtl ([dir="rtl"] &);

/* Print variant */
@custom-variant print (@media print { & });

/* Hover on desktop only */
@custom-variant hover-desktop (@media (hover: hover) { &:hover });
```

### @utility - Custom Utilities

```css
@import "tailwindcss";

/* Text balance utility */
@utility text-balance {
  text-wrap: balance;
}

/* Scrollbar hide */
@utility scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

/* Flex center shorthand */
@utility flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}
```

### @plugin - Plugin Configuration

```css
@import "tailwindcss";

/* Load a plugin */
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin "@tailwind