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 { }
```

css

@import "tailwindcss";

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

Critical Breaking Changes (v3 → v4)

Renamed Utilities

v3 (deprecated)	v4 (use instead)
`bg-gradient-*`	`bg-linear-*`
`shadow-sm`	`shadow-xs`
`shadow`	`shadow-sm`
`blur-sm`	`blur-xs`
`blur`	`blur-sm`
`rounded-sm`	`rounded-xs`
`rounded`	`rounded-sm`
`outline-none`	`outline-hidden`
`ring`	`ring-3`
`drop-shadow-sm`	`drop-shadow-xs`
`drop-shadow`	`drop-shadow-sm`
`backdrop-blur-sm`	`backdrop-blur-xs`
`backdrop-blur`	`backdrop-blur-sm`

Removed Utilities

Deprecated	Replacement
`bg-opacity-*`	Use opacity modifier: `bg-black/50`
`text-opacity-*`	Use opacity modifier: `text-black/50`
`border-opacity-*`	Use opacity modifier: `border-black/50`
`flex-shrink-*`	`shrink-*`
`flex-grow-*`	`grow-*`
`overflow-ellipsis`	`text-ellipsis`

Gradient Syntax

Use v4 gradient syntax:

html

<!-- 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

html

<!-- 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

html

<!-- 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

html

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

Typography

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

html

<!-- 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:

css

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

Use

--spacing()

function for calculations:

css

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

tailwind-variants Quick Start

Type-safe component variants with automatic class conflict resolution:

typescript

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

Topic	Pattern
Gradients	`bg-linear-*` , `bg-radial` , `bg-conic`
Opacity	`bg-red-500/50` (not `bg-opacity-*` )
Line height	`text-base/7` (not `leading-*` )
Spacing	Use `gap-*` in flex/grid
Equal size	`size-10` (not `w-10 h-10` )
Full height	`min-h-dvh` (not `min-h-screen` )
Component variants	`tv()` from tailwind-variants

Common Tasks

Creating a component with variants:

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

Debugging styles:

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

tailwind-css

NPX Install

Tags

SKILL.md Content

Tailwind CSS v4 & tailwind-variants

Your Role

Reference Documentation

Core Principles

Configuration Method

Critical Breaking Changes (v3 → v4)

Renamed Utilities

Removed Utilities

Gradient Syntax

Responsive Design (Mobile-First)

Layout Best Practices

Always use gap for flex/grid spacing

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

Use
`size-*`
for equal width/height

Typography

CSS Variables

tailwind-variants Quick Start

Quick Reference

Common Tasks