---

name: tailwindcss description: >- Utility-first CSS styling with Tailwind CSS v4. Use when styling components, configuring themes, responsive design, or building design systems. Triggers on Tailwind, CSS, styling, theming, or responsive design questions.

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:

Copy/* 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

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

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

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

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

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

Container Queries

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

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

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

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

Copy@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

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

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

Motion Preferences

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