Tailwind CSS v4 & tailwind-variants

Your Role

You are an expert in Tailwind CSS v4. You understand CSS-first configuration, modern utility patterns, and type-safe component styling with tailwind-variants.

Reference Documentation

• Tailwind v4 Rules & Best Practices: ./references/TAILWIND_V4_RULES.md
  • Breaking changes, removed/renamed utilities, layout rules, typography, gradients, CSS variables, new v4 features, common pitfalls
• tailwind-variants Patterns: ./references/TAILWIND_VARIANTS.md
  • Component variants, slots API, composition, TypeScript integration, responsive variants

Core Principles

• Always use Tailwind CSS v4.1+
• Do not use deprecated or removed utilities – Use the replacement
• Never use @apply – Use CSS variables, the --spacing() function, or framework components instead
• Check for redundant classes – Remove any classes that aren’t necessary

Configuration Method

Tailwind CSS v4 uses CSS-only configuration:

• No tailwind.config.ts file needed
• Define theme tokens with @theme { } or @theme static { }
• Create custom utilities with @utility { }
• Define custom variants with @custom-variant { }

@import "tailwindcss";

@theme {
  --color-primary: oklch(0.72 0.11 178);
  --spacing-edge: 1.5rem;
}

Critical Breaking Changes (v3 → v4)

Renamed Utilities

Removed Utilities

Gradient Syntax

Use v4 gradient syntax:

<!-- Linear gradients -->
<div class="bg-linear-to-br from-violet-500 to-fuchsia-500"></div>

<!-- Radial gradients -->
<div class="bg-radial-[at_50%_75%] from-sky-200 to-indigo-900"></div>

<!-- Conic gradients -->
<div class="bg-conic-180 from-indigo-600 via-indigo-50 to-indigo-600"></div>

<!-- Deprecated syntax -->
<div class="bg-gradient-to-br ..."></div>
<!-- Wrong! -->

Responsive Design (Mobile-First)

Tailwind is mobile-first:

• Default classes (no prefix) apply to all screen sizes
• Breakpoint prefixes (md:, lg:) apply at that breakpoint and above
• Never use sm: for mobile – it’s redundant

<!-- Correct: Mobile first, then scale up -->
<div class="text-sm md:text-base lg:text-lg">
  <div class="flex-col md:flex-row">
    <div class="px-4 md:px-6 lg:px-8">
      <!-- Hide on mobile, show on desktop -->
      <div class="hidden lg:block"></div>
    </div>
  </div>
</div>

Layout Best Practices

Always use gap for flex/grid spacing

<!-- Don't use space utilities in flex/grid -->
<div class="flex space-x-4">...</div>
<!-- Wrong! -->

<!-- Use gap -->
<div class="flex gap-4">...</div>
<!-- Correct -->

Use min-h-dvh instead of min-h-screen

min-h-screen is buggy on mobile Safari.

Use size-* for equal width/height

<div class="w-10 h-10">...</div>
<!-- Verbose -->
<div class="size-10">...</div>
<!-- Preferred -->

Typography

Use line-height modifiers, not leading-* classes:

<!-- Don't use separate leading classes -->
<p class="text-base leading-7">...</p>
<!-- Wrong! -->

<!-- Use line-height modifiers -->
<p class="text-base/7">...</p>
<!-- Correct -->

CSS Variables

Tailwind v4 exposes theme values as CSS variables:

.custom-element {
  background: var(--color-red-500);
  padding: var(--spacing-4);
  border-radius: var(--radius-lg);
}

Use --spacing() function for calculations:

.custom-class {
  margin-top: calc(100vh - --spacing(16));
}

tailwind-variants Quick Start

Type-safe component variants with automatic class conflict resolution:

import { tv, type VariantProps } from "tailwind-variants";

const button = tv({
  base: "font-medium rounded-lg transition-colors",
  variants: {
    color: {
      primary: "bg-blue-500 text-white hover:bg-blue-600",
      secondary: "bg-gray-500 text-white hover:bg-gray-600"
    },
    size: {
      sm: "text-sm px-3 py-1.5",
      md: "text-base px-4 py-2",
      lg: "text-lg px-6 py-3"
    }
  },
  defaultVariants: {
    color: "primary",
    size: "md"
  }
});

type ButtonVariants = VariantProps<typeof button>;

// Usage
button(); // Uses defaults
button({ color: "secondary", size: "lg" });

See ./references/TAILWIND_VARIANTS.md for:

• Slots API for multi-part components
• Compound variants
• Component composition with extend
• TypeScript integration patterns

Quick Reference

Common Tasks

Creating a component with variants:

1. Read ./references/TAILWIND_VARIANTS.md for patterns
2. Use tv() for type-safe variants
3. Extract types with VariantProps<typeof component>

Debugging styles:

1. Check ./references/TAILWIND_V4_RULES.md for breaking changes
2. Verify gradient syntax (bg-linear-*, not bg-gradient-*)
3. Check opacity syntax (bg-red-500/50, not bg-opacity-*)