# Component Patterns

## tailwind-variants (tv)

Type-safe component variants with slots, composition, and responsive support.

### Slots API

```typescript
import { tv } from "tailwind-variants";

const card = tv({
  slots: {
    base: "rounded-lg border shadow-sm",
    header: "flex flex-col space-y-1.5 p-6",
    title: "text-2xl font-semibold leading-none tracking-tight",
    content: "p-6 pt-0",
    footer: "flex items-center p-6 pt-0",
  },
  variants: {
    elevated: { true: { base: "shadow-lg border-0" } },
  },
});

const { base, header, title, content, footer } = card({ elevated: true });
```

### Composition

```typescript
const baseButton = tv({ base: "rounded-lg font-medium transition-colors" });

const iconButton = tv({
  extend: baseButton,
  base: "inline-flex items-center justify-center",
  variants: {
    size: { sm: "size-8", md: "size-10", lg: "size-12" },
  },
});
```

### Responsive Variants

```typescript
const grid = tv({
  base: "grid gap-4",
  variants: {
    cols: { 1: "grid-cols-1", 2: "grid-cols-2", 3: "grid-cols-3", 4: "grid-cols-4" },
  },
  responsiveVariants: ["sm", "md", "lg"],
});

// Usage: <div className={grid({ cols: { initial: 1, sm: 2, lg: 4 } })} />
```

## CVA (class-variance-authority)

Alternative to tailwind-variants — simpler API, no slots.

```typescript
import { cva, type VariantProps } from "class-variance-authority";

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        outline: "border border-border bg-background hover:bg-accent",
        ghost: "hover:bg-accent hover:text-accent-foreground",
      },
      size: {
        sm: "h-9 rounded-md px-3",
        default: "h-10 px-4 py-2",
        lg: "h-11 rounded-md px-8",
        icon: "size-10",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
);

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

export function Button({ className, variant, size, ...props }: ButtonProps) {
  return <button className={cn(buttonVariants({ variant, size, className }))} {...props} />;
}
```

## Compound Components (React 19)

React 19 passes ref as a regular prop — no `forwardRef` needed.

```typescript
export function Card({ className, ref, ...props }: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
  return <div ref={ref} className={cn("rounded-lg border bg-card text-card-foreground shadow-sm", className)} {...props} />;
}

export function CardHeader({ className, ref, ...props }: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
  return <div ref={ref} className={cn("flex flex-col space-y-1.5 p-6", className)} {...props} />;
}
```

## ESLint Integration

Use `eslint-plugin-better-tailwindcss` for v4 class validation:

| Rule | Purpose |
|------|---------|
| `no-conflicting-classes` | Detect classes that override each other |
| `no-unknown-classes` | Flag classes not registered with Tailwind |
| `enforce-shorthand-classes` | `size-6` not `w-6 h-6`; `p-6` not `px-6 py-6` |
| `no-deprecated-classes` | Catch v3 class names used in v4 projects |

# Layout Patterns

## Grid Template Areas

Define reusable grid areas with `@utility`:

```css
@utility grid-areas-dashboard {
  grid-template-areas: "header header header" "nav main aside" "nav footer footer";
}
@utility area-header { grid-area: header; }
@utility area-nav { grid-area: nav; }
@utility area-main { grid-area: main; }
```

```html
<div class="grid grid-areas-dashboard grid-cols-[200px_1fr_250px] grid-rows-[60px_1fr_40px]">
  <header class="area-header">Header</header>
  <nav class="area-nav">Nav</nav>
  <main class="area-main">Content</main>
</div>
```

## Auto-Responsive Grids

```html
<!-- Auto-fit: cards stretch to fill -->
<div class="grid grid-cols-[repeat(auto-fit,minmax(280px,1fr))] gap-6">

<!-- Auto-fill: maintains track size, leaves empty space -->
<div class="grid grid-cols-[repeat(auto-fill,minmax(200px,1fr))] gap-4">

<!-- Safe minimum (handles container < minmax min) -->
<div class="grid grid-cols-[repeat(auto-fill,minmax(min(100%,300px),1fr))] gap-4">
```

## Z-Index Management

Define a z-index scale in `@theme` tokens instead of arbitrary numbers:

```css
@theme {
  --z-dropdown: 100;
  --z-sticky: 200;
  --z-fixed: 300;
  --z-modal-backdrop: 400;
  --z-modal: 500;
  --z-popover: 600;
  --z-tooltip: 700;
  --z-toast: 800;
}
```

Reference with `z-(--z-modal)` syntax — never use `z-[9999]`.

## Container Queries

Component-level responsiveness independent of viewport.

```css
@plugin "@tailwindcss/container-queries";
```

```html
<article class="@container">
  <div class="flex flex-col @sm:flex-row gap-4">
    <img class="w-full @sm:w-32 @lg:w-48 aspect-video @sm:aspect-square object-cover" />
    <div class="flex-1 min-w-0">
      <h3 class="text-base @md:text-lg @lg:text-xl font-semibold truncate">Title</h3>
      <p class="text-sm @md:text-base line-clamp-2 @lg:line-clamp-3">Description</p>
    </div>
  </div>
</article>
```

| Use Container Queries | Use Viewport Queries |
|----------------------|---------------------|
| Reusable components | Page-level layouts |
| Sidebar widgets | Navigation bars |
| Card grids | Hero sections |
| Embedded/CMS content | Full-width sections |

Named containers scope queries: `@container/sidebar` with `@lg/sidebar:flex-row`.

## Fluid Typography

Eliminate breakpoint jumps with `clamp()`:

```css
@theme {
  --text-fluid-base: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
  --text-fluid-xl: clamp(1.25rem, 1rem + 1.25vw, 1.5rem);
  --text-fluid-3xl: clamp(1.875rem, 1.2rem + 3.375vw, 2.5rem);
}
```

Always combine `vw` with `rem` — pure `vw` breaks when users zoom (WCAG violation).

## Custom Utilities

```css
@utility scrollbar-none {
  scrollbar-width: none;
  -ms-overflow-style: none;
}

@utility text-gradient {
  @apply bg-linear-to-r from-primary to-accent bg-clip-text text-transparent;
}
```

## Native CSS Animations (v4)

Define keyframes inside `@theme` and reference with `--animate-*` tokens:

```css
@theme {
  --animate-slide-up: slide-up 0.3s ease-out;
  @keyframes slide-up {
    from { opacity: 0; transform: translateY(20px); }
    to { opacity: 1; transform: translateY(0); }
  }
}
```

Use `@starting-style` for entry animations on native popovers/dialogs:

```css
[popover]:popover-open { opacity: 1; transform: scale(1); }
@starting-style { [popover]:popover-open { opacity: 0; transform: scale(0.95); } }
```

Respect motion preferences: `motion-safe:animate-bounce motion-reduce:animate-none`.

## Safe Area Handling (Notched Devices)

```css
@utility safe-area-pt { padding-top: env(safe-area-inset-top); }
@utility safe-area-pb { padding-bottom: env(safe-area-inset-bottom); }
```

Apply to fixed headers/footers on mobile.