Tailwind CSS v4

Tailwind CSS v4 introduces CSS-first configuration, OKLCH colors, and improved performance. This skill provides comprehensive patterns for building modern UIs.

Core Concepts

CSS-First Configuration

Tailwind v4 uses CSS variables and @theme directive instead of tailwind.config.js:

/* app.css */
@import 'tailwindcss';

@theme {
  /* Colors using OKLCH for better perceptual uniformity */
  --color-primary-50: oklch(0.97 0.01 250);
  --color-primary-100: oklch(0.93 0.03 250);
  --color-primary-500: oklch(0.55 0.2 250);
  --color-primary-900: oklch(0.25 0.1 250);

  /* Typography */
  --font-family-sans: 'Inter', system-ui, sans-serif;
  --font-family-mono: 'JetBrains Mono', monospace;

  /* Spacing scale */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;

  /* Border radius */
  --radius-xl: 1rem;
  --radius-2xl: 1.5rem;

  /* Shadows */
  --shadow-soft: 0 2px 15px -3px oklch(0 0 0 / 0.1);

  /* Animations */
  --animate-fade-in: fade-in 0.3s ease-out;
}

@keyframes fade-in {
  from {
    opacity: 0;
    transform: translateY(-4px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

New Variant Syntax

<!-- Container queries -->
<div class="@container">
  <div class="@sm:grid-cols-2 @lg:grid-cols-3">
    <!-- Responsive to container, not viewport -->
  </div>
</div>

<!-- New `not-*` variants -->
<div class="not-first:mt-4">...</div>
<div class="not-last:border-b">...</div>

<!-- Group/Peer with named groups -->
<div class="group/sidebar">
  <div class="group-hover/sidebar:visible">...</div>
</div>

<!-- `has-*` for parent selection -->
<div class="has-[:checked]:bg-blue-100">
  <input type="checkbox" />
</div>

Component Patterns

Card Component

<div
  class="rounded-2xl bg-white p-6 shadow-soft
            ring-1 ring-black/5
            dark:bg-gray-900 dark:ring-white/10"
>
  <h3 class="text-lg font-semibold text-gray-900 dark:text-white">Card Title</h3>
  <p class="mt-2 text-gray-600 dark:text-gray-400">Card description text</p>
</div>

Button Variants

<!-- Primary -->
<button
  class="rounded-lg bg-primary-500 px-4 py-2
               font-medium text-white
               hover:bg-primary-600
               focus-visible:outline-2 focus-visible:outline-offset-2
               focus-visible:outline-primary-500
               active:scale-[0.98] transition-all"
>
  Primary Button
</button>

<!-- Secondary -->
<button
  class="rounded-lg bg-gray-100 px-4 py-2
               font-medium text-gray-900
               hover:bg-gray-200
               dark:bg-gray-800 dark:text-white dark:hover:bg-gray-700"
>
  Secondary Button
</button>

<!-- Outline -->
<button
  class="rounded-lg border border-gray-300 px-4 py-2
               font-medium text-gray-700
               hover:bg-gray-50
               dark:border-gray-600 dark:text-gray-300 dark:hover:bg-gray-800"
>
  Outline Button
</button>

Form Input

<div>
  <label class="block text-sm font-medium text-gray-700 dark:text-gray-300"> Email </label>
  <input
    type="email"
    class="mt-1 block w-full rounded-lg border-gray-300
           shadow-sm focus:border-primary-500 focus:ring-primary-500
           dark:border-gray-600 dark:bg-gray-800 dark:text-white
           invalid:border-red-500 invalid:ring-red-500"
    placeholder="you@example.com"
  />
</div>

Responsive Design

Breakpoint Reference

• sm: 640px
• md: 768px
• lg: 1024px
• xl: 1280px
• 2xl: 1536px

Mobile-First Grid

<div
  class="grid grid-cols-1 gap-6
            sm:grid-cols-2
            lg:grid-cols-3
            xl:grid-cols-4"
>
  <!-- Items -->
</div>

Container Queries

<div class="@container">
  <article class="flex flex-col @md:flex-row @md:items-center gap-4">
    <img class="w-full @md:w-48 rounded-lg" />
    <div class="flex-1">
      <h2>Title</h2>
      <p class="hidden @lg:block">Extended description</p>
    </div>
  </article>
</div>

Animation Patterns

Hover Effects

<a class="group relative inline-block">
  <span class="relative z-10">Hover me</span>
  <span
    class="absolute inset-0 -z-10 scale-x-0 bg-primary-100
               transition-transform origin-left
               group-hover:scale-x-100 rounded-lg"
  />
</a>

Loading States

<!-- Spinner -->
<div
  class="animate-spin h-5 w-5 border-2 border-primary-500
            border-t-transparent rounded-full"
/>

<!-- Skeleton -->
<div class="animate-pulse space-y-3">
  <div class="h-4 bg-gray-200 rounded w-3/4" />
  <div class="h-4 bg-gray-200 rounded w-1/2" />
</div>

<!-- Shimmer -->
<div class="relative overflow-hidden bg-gray-200 rounded">
  <div
    class="absolute inset-0 -translate-x-full
              bg-gradient-to-r from-transparent via-white/50 to-transparent
              animate-[shimmer_2s_infinite]"
  />
</div>

Dark Mode

<!-- System preference -->
<html class="dark:bg-gray-950">
  <!-- With dark mode toggle -->
  <html class="dark">
    <body class="bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-100"></body>
  </html>
</html>

@theme {
  /* Semantic color tokens */
  --color-surface: white;
  --color-on-surface: oklch(0.2 0 0);
}

@media (prefers-color-scheme: dark) {
  @theme {
    --color-surface: oklch(0.15 0 0);
    --color-on-surface: oklch(0.9 0 0);
  }
}

Accessibility

Focus Styles

<button
  class="focus:outline-none
               focus-visible:ring-2
               focus-visible:ring-primary-500
               focus-visible:ring-offset-2"
>
  Accessible Button
</button>

Screen Reader Only

<span class="sr-only">Navigation menu</span>

Motion Preferences

<div class="animate-bounce motion-reduce:animate-none">Respects reduced motion</div>

References

• references/theming.md - Theme customization
• references/components.md - Component library
• references/responsive.md - Responsive patterns

Assets

• assets/globals.css - Global CSS template