Tailwindcss

Tailwind CSS v4 — Claude Code Skill

Tailwind CSS v4 (released January 2025, current stable v4.2) uses a CSS-first configuration approach. This skill covers v4 exclusively. All theme customization happens in CSS via @theme, not in tailwind.config.js.

Critical: v3 → v4 Breaking Changes

Do NOT use these v3 patterns — they are wrong for v4:

Setup

CSS Entry Point

/* app.css — the single import replaces all v3 @tailwind directives */
@import "tailwindcss";

/* Optional modifiers: */
@import "tailwindcss" prefix(tw);        /* Prefix all classes: tw:flex */
@import "tailwindcss" important;          /* All utilities get !important */
@import "tailwindcss" source("../src");   /* Set source scanning root */

Vite Setup

npm install -D tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [tailwindcss()],
})

PostCSS Setup (Alternative)

npm install -D tailwindcss @tailwindcss/postcss autoprefixer

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
    autoprefixer: {},
  },
}

CLI Setup (No Bundler)

npm install -D tailwindcss @tailwindcss/cli
npx @tailwindcss/cli -i app.css -o dist/app.css --watch

Reference Material

A comprehensive Tailwind CSS v4.2 reference document is available at:

../../guides/tailwindcss-v4/reference.md

(Relative to this SKILL.md file.)

When to consult the reference:

• You need the exact list of values for a specific utility (e.g., all blur-* sizes, all cursor-* options)
• You're unsure whether a utility exists in v4 or was removed/renamed from v3
• You need the precise @theme namespace for a category (e.g., which variable prefix generates which utilities)
• You want to verify the correct syntax for a v4 directive (@utility, @custom-variant, @source, @variant)
• You encounter an unfamiliar v4 feature (container queries, field-sizing, text-shadow, mask utilities, @reference)

When you don't need it:

• Standard layout, spacing, typography, color, and responsive patterns are covered in this SKILL.md
• Common component patterns (cards, navs, forms, grids) are already here
• The v3→v4 migration table at the top of this file covers the most common pitfalls

Read the reference with the view tool if you need detail beyond what this skill file provides.

Theme System (@theme)

Theme variables are special CSS variables defined with @theme that create corresponding utility classes. They are not just CSS variables — they instruct Tailwind to generate utilities.

Defining Theme Variables

@import "tailwindcss";

@theme {
  /* Colors → bg-brand, text-brand, border-brand, ring-brand, etc. */
  --color-brand-50: oklch(0.97 0.02 264);
  --color-brand-500: oklch(0.55 0.22 264);
  --color-brand-900: oklch(0.25 0.15 264);

  /* Fonts → font-display, font-body utilities */
  --font-display: "Satoshi", "Inter", sans-serif;
  --font-body: "Inter", system-ui, sans-serif;

  /* Font sizes → text-display utility */
  --text-display: 3rem;

  /* Font weights → font-heading utility */
  --font-weight-heading: 700;

  /* Letter spacing → tracking-wide utility */
  --tracking-wide: 0.025em;

  /* Line height → leading-relaxed utility */
  --leading-relaxed: 1.75;

  /* Breakpoints → 3xl: responsive variant */
  --breakpoint-3xl: 120rem;

  /* Container sizes → @8xl: container query variant + max-w-8xl */
  --container-8xl: 96rem;

  /* Border radius → rounded-xl utility */
  --radius-xl: 0.75rem;

  /* Shadows → shadow-soft utility */
  --shadow-soft: 0 2px 8px rgba(0, 0, 0, 0.08);

  /* Inset shadows → inset-shadow-deep utility */
  --inset-shadow-deep: inset 0 4px 8px rgba(0, 0, 0, 0.15);

  /* Drop shadows → drop-shadow-hard utility */
  --drop-shadow-hard: 0 2px 4px rgba(0, 0, 0, 0.3);

  /* Blur → blur-heavy utility */
  --blur-heavy: 40px;

  /* Perspective → perspective-dramatic utility */
  --perspective-dramatic: 200px;

  /* Aspect ratio → aspect-golden utility */
  --aspect-golden: 1.618 / 1;

  /* Easing → ease-snappy utility */
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);

  /* Animations → animate-fade-in utility */
  --animate-fade-in: fade-in 0.3s ease-out;
  @keyframes fade-in {
    from { opacity: 0; }
    to { opacity: 1; }
  }
}

Namespace → Utility Mapping

Overriding & Removing Defaults

@theme {
  /* Override one value */
  --breakpoint-sm: 30rem;

  /* Remove entire namespace, then redefine */
  --color-*: initial;
  --color-white: #fff;
  --color-black: #000;
  --color-primary: oklch(0.6 0.2 260);

  /* Remove a single default */
  --breakpoint-2xl: initial;

  /* Reset everything (for fully custom themes) */
  --*: initial;
}

Referencing Other Variables (use inline)

@theme inline {
  --font-sans: var(--font-inter);
}

The inline option inlines the value rather than referencing the theme variable, avoiding CSS variable resolution scope issues.

CSS Directives

@source — Register Additional Scan Paths

@source "../node_modules/@my-company/ui-lib";
@source "../../packages/shared-components";

@source not() — Ignore Paths

@source not("./src/legacy");

@source inline() — Safelist Classes

@source inline("underline bg-red-500 lg:flex");

@utility — Custom Utilities

/* Simple utility */
@utility content-auto {
  content-visibility: auto;
}

/* With nesting */
@utility scrollbar-hidden {
  &::-webkit-scrollbar {
    display: none;
  }
}

/* Functional utility (accepts values) */
@utility tab-* {
  tab-size: --value(--tab-size-*);  /* Match theme keys */
}

@utility tab-* {
  tab-size: --value(integer);        /* Bare integer values: tab-4 */
}

/* Multiple resolvers (first match wins) */
@utility tab-* {
  tab-size: --value(--tab-size-*, integer, "inherit", "initial");
}

@custom-variant — Custom Variants

/* Class-based dark mode (replaces v3 darkMode: 'class') */
@custom-variant dark (&:where(.dark, .dark *));

/* Data attribute dark mode */
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

/* Custom theme variant */
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

@variant — Apply Variants in Custom CSS

.my-element {
  background: white;
  @variant dark {
    background: black;
  }
  @variant hover {
    @variant dark {
      background: #333;
    }
  }
}

@layer — Custom CSS in Layers

@layer base {
  h1 { font-size: var(--text-2xl); }
  h2 { font-size: var(--text-xl); }
}

@layer components {
  .card {
    background-color: var(--color-white);
    border-radius: var(--radius-lg);
    padding: calc(var(--spacing) * 6);
    box-shadow: var(--shadow-xl);
  }
  .btn-primary {
    @apply rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white;
    @apply hover:bg-blue-700 active:bg-blue-800;
    @apply focus:outline-2 focus:outline-offset-2 focus:outline-blue-500;
  }
}

@reference — For Vue/Svelte <style> Blocks

<style>
  @reference "../../app.css";
  h1 {
    @apply text-2xl font-bold text-red-500;
  }
</style>

@apply — Inline Utility Classes in CSS

.select2-dropdown {
  @apply rounded-b-lg shadow-md;
}

Legacy Compatibility

@config "../../tailwind.config.js";   /* Load v3 JS config */
@plugin "@tailwindcss/typography";     /* Load JS plugin */

CSS Functions

/* Adjust color opacity at build time */
.element { color: --alpha(var(--color-lime-300) / 50%); }

/* Generate spacing from theme multiplier */
.element { margin: --spacing(4); }  /* = calc(var(--spacing) * 4) */

/* In arbitrary values: */
<div class="py-[calc(--spacing(4)-1px)]">

Responsive Design

Default Breakpoints (Mobile-First)

Max-Width & Range Queries

<div class="max-md:flex">          <!-- Below 768px only -->
<div class="md:max-xl:flex">       <!-- Between 768px and 1280px -->
<div class="min-[900px]:flex">     <!-- Arbitrary min-width -->
<div class="max-[600px]:hidden">   <!-- Arbitrary max-width -->

Mobile-First Pattern

<!-- CORRECT: style mobile first, override upward -->
<div class="text-center sm:text-left">

<!-- WRONG: don't use sm: to "target mobile" -->
<div class="sm:text-center">  <!-- This only applies at 640px+ -->

Responsive Example

<div class="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
  <div class="rounded-lg bg-white p-4 shadow">Item</div>
  <!-- ... -->
</div>

<h1 class="text-2xl font-bold md:text-4xl lg:text-6xl">
  Responsive heading
</h1>

<div class="hidden lg:block">Desktop only</div>
<div class="lg:hidden">Mobile/tablet only</div>

Container Queries (Built-In)

<!-- Mark parent as container -->
<div class="@container">
  <!-- Style based on container width, not viewport -->
  <div class="flex flex-col @md:flex-row @md:items-center gap-4">
    <img class="w-full @md:w-48 rounded-lg" src="..." alt="">
    <div>
      <h3 class="text-lg font-bold">Title</h3>
      <p class="text-sm text-gray-500">Description</p>
    </div>
  </div>
</div>

<!-- Named containers for nested queries -->
<div class="@container/main">
  <div class="@sm/main:flex-row flex flex-col">...</div>
</div>

<!-- Max-width container queries -->
<div class="@container">
  <div class="flex flex-row @max-md:flex-col">...</div>
</div>

<!-- Range queries -->
<div class="@container">
  <div class="@sm:@max-md:flex-col">Between sm and md container</div>
</div>

Dark Mode

Automatic (System Preference — Default)

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  Switches with OS setting
</div>

Manual Toggle (Class-Based)

/* In your CSS */
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

<html class="dark">
  <body>
    <div class="bg-white dark:bg-gray-900">Now class-controlled</div>
  </body>
</html>

// Toggle in JS
document.documentElement.classList.toggle('dark',
  localStorage.theme === 'dark' ||
  (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)
);

Data Attribute Approach

@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

<html data-theme="dark">...</html>

State Variants

Interactive States

<button class="bg-blue-600 hover:bg-blue-700 active:bg-blue-800
               focus:outline-2 focus:outline-offset-2 focus:outline-blue-500
               disabled:opacity-50 disabled:cursor-not-allowed
               transition-colors">
  Button
</button>

<a class="text-blue-600 hover:text-blue-800 hover:underline
          focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500
          visited:text-purple-600">
  Link
</a>

Form States

<input class="border border-gray-300 rounded-lg px-3 py-2
              focus:border-blue-500 focus:ring-2 focus:ring-blue-200
              invalid:border-red-500 focus:invalid:ring-red-200
              disabled:bg-gray-100 disabled:cursor-not-allowed
              placeholder:text-gray-400 placeholder:italic
              read-only:bg-gray-50"
       required />

<input type="checkbox" class="checked:bg-blue-500 indeterminate:bg-gray-300" />

Structural (Children)

<ul>
  {items.map(item => (
    <li class="py-4 first:pt-0 last:pb-0 odd:bg-gray-50 even:bg-white">
      {item.name}
    </li>
  ))}
</ul>

<div class="nth-3:underline">3rd child underlined</div>
<div class="empty:hidden">Hidden when empty</div>

Group (Parent State)

<a href="#" class="group block rounded-lg p-6 hover:bg-gray-50">
  <h3 class="font-semibold group-hover:text-blue-600">Title</h3>
  <p class="text-gray-500 group-hover:text-gray-700">Description</p>
  <svg class="hidden group-has-[a]:block">...</svg>
</a>

<!-- Named groups for nesting -->
<div class="group/card">
  <div class="group/button">
    <span class="group-hover/card:text-blue-500
                 group-hover/button:underline">Text</span>
  </div>
</div>

Peer (Sibling State)

<label class="block">
  <input type="email" class="peer rounded border px-3 py-2" required />
  <p class="invisible mt-1 text-sm text-red-500 peer-invalid:visible">
    Please enter a valid email.
  </p>
</label>

<!-- Named peers -->
<input id="draft" class="peer/draft" type="radio" name="status" checked />
<div class="hidden peer-checked/draft:block">Draft selected</div>

Implicit Group (in-*)

<!-- No need to add "group" class to parent -->
<div tabindex="0">
  <div class="opacity-50 in-focus:opacity-100">
    Responds to any parent's focus
  </div>
</div>

Has (Descendant State)

<label class="has-checked:bg-indigo-50 has-checked:ring-indigo-200">
  <input type="radio" class="checked:border-indigo-500" />
  Google Pay
</label>

Not

<button class="bg-indigo-600 hover:not-focus:bg-indigo-700">
  Only hover styles when NOT focused
</button>

Pseudo-Elements

<div class="before:content-[''] before:absolute before:inset-0 before:bg-black/50">
  Overlay
</div>
<blockquote class="after:content-[attr(data-cite)]">Quote</blockquote>
<input class="placeholder:text-gray-400" placeholder="Search..." />
<li class="marker:text-blue-500">List item</li>
<p class="selection:bg-yellow-200">Selectable text</p>
<input type="file" class="file:mr-4 file:rounded-lg file:border-0 file:bg-blue-50 file:px-4 file:py-2" />

Media & Feature Queries

<div class="motion-safe:animate-bounce">Respects reduced motion</div>
<div class="motion-reduce:transition-none">No transitions if reduced motion</div>
<div class="contrast-more:border-2">Higher contrast borders</div>
<div class="print:hidden">Hidden when printing</div>
<div class="portrait:flex-col landscape:flex-row">Orientation-aware</div>
<div class="supports-[display:grid]:grid">Feature detection</div>
<div class="forced-colors:border">Forced colors mode</div>

Data & ARIA Attributes

<div class="data-[state=open]:bg-blue-50" data-state="open">Open</div>
<div class="aria-expanded:rotate-180" aria-expanded="true">Chevron</div>
<div class="aria-busy:opacity-50" aria-busy="true">Loading</div>
<details class="open:bg-gray-50" open>Expandable</details>

Stacking Variants

<button class="dark:md:hover:bg-indigo-600">
  Dark mode + medium screen + hover
</button>

<div class="dark:lg:data-[active]:hover:bg-fuchsia-600">
  Four stacked variants
</div>

Arbitrary Variants

<div class="[&>p]:mt-4">Direct child p tags</div>
<div class="[&_p]:mt-4">Any descendant p tags</div>
<div class="lg:[&:nth-child(-n+3)]:hover:underline">Complex selector</div>
<div class="[@supports(display:grid)]:grid">@supports</div>

Spacing System

In v4, spacing uses a single --spacing multiplier (default 0.25rem):

p-0    → padding: 0
p-px   → padding: 1px
p-0.5  → padding: calc(var(--spacing) * 0.5)  = 0.125rem
p-1    → padding: calc(var(--spacing) * 1)    = 0.25rem
p-2    → padding: calc(var(--spacing) * 2)    = 0.5rem
p-4    → padding: calc(var(--spacing) * 4)    = 1rem
p-8    → padding: calc(var(--spacing) * 8)    = 2rem
p-16   → 4rem, p-24 → 6rem, p-32 → 8rem, p-64 → 16rem, p-96 → 24rem

Any number works: p-3.5, p-7, p-18, p-72. The same scale applies to margin, gap, width, height, inset, translate, scroll-margin, scroll-padding, space-between, text-indent, border-spacing, and all spacing-based utilities.

Arbitrary Values

<div class="top-[117px]">               <!-- Any CSS value -->
<div class="bg-[#bada55]">              <!-- Hex color -->
<div class="text-[22px]">               <!-- Font size -->
<div class="grid-cols-[1fr_500px_2fr]"> <!-- Underscores = spaces -->
<div class="bg-[url('/img.png')]">      <!-- URLs -->
<div class="before:content-['Hello']">  <!-- Content strings -->
<div class="max-h-[calc(100dvh-4rem)]"> <!-- calc() -->
<div class="[mask-type:luminance]">     <!-- Arbitrary CSS property -->
<div class="[--my-var:1rem]">           <!-- CSS variable -->

<!-- CSS variable shorthand (v4): adds var() automatically -->
<div class="fill-(--my-brand-color)">   <!-- = fill-[var(--my-brand-color)] -->

<!-- Type hints for ambiguous variables -->
<div class="text-(length:--my-var)">    <!-- Force font-size interpretation -->
<div class="text-(color:--my-var)">     <!-- Force color interpretation -->

Important Modifier

<!-- v4: suffix ! -->
<div class="bg-red-500!">

<!-- v3 (WRONG in v4): prefix ! -->
<!-- <div class="!bg-red-500"> -->

Opacity Modifier

<div class="bg-red-500/50">        <!-- 50% opacity -->
<div class="bg-red-500/[.15]">    <!-- Arbitrary opacity -->
<div class="text-black/75">        <!-- 75% opacity text -->

Negative Values

<div class="-mt-4">                <!-- Negative margin -->
<div class="-translate-x-1/2">    <!-- Negative translate -->
<div class="-rotate-45">           <!-- Negative rotation -->

Color System

Default Palette

22 color families, each with shades 50–950: slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.

Plus: black, white, transparent, current, inherit.

All default colors use oklch color space.

Custom Colors

@theme {
  --color-brand-50: oklch(0.97 0.02 264);
  --color-brand-500: oklch(0.55 0.22 264);
  --color-brand-900: oklch(0.25 0.15 264);
}

Now bg-brand-500, text-brand-50, border-brand-900, etc. all work.

Complete Utility Reference

Layout

Flexbox & Grid

Sizing

Typography

Backgrounds

Borders

Effects

Filters

Tables

Transitions & Animations

Transforms

Interactivity

SVG

Accessibility

Source Detection Rules

Never construct class names dynamically:

// ❌ WRONG — Tailwind cannot detect these
<div className={`bg-${color}-500`} />
<div className={`text-${size}`} />

// ✅ CORRECT — use complete class name strings
const colorMap = {
  red: "bg-red-500 text-white",
  blue: "bg-blue-500 text-white",
  green: "bg-green-500 text-white",
};
<div className={colorMap[color]} />

// ✅ CORRECT — ternary with complete strings
<div className={isActive ? "bg-blue-600 text-white" : "bg-gray-100 text-gray-700"} />

Component Patterns

Responsive Card

<div class="mx-auto max-w-sm rounded-xl bg-white p-6 shadow-lg
            sm:max-w-md sm:p-8
            dark:bg-gray-800 dark:shadow-none
            dark:ring-1 dark:ring-white/10">
  <h2 class="text-xl font-bold text-gray-900 dark:text-white">Title</h2>
  <p class="mt-2 text-gray-600 dark:text-gray-400">Description.</p>
  <button class="mt-4 rounded-lg bg-blue-600 px-4 py-2 text-sm font-semibold text-white
                  hover:bg-blue-700 active:bg-blue-800
                  focus:outline-2 focus:outline-offset-2 focus:outline-blue-500
                  disabled:opacity-50 disabled:cursor-not-allowed
                  transition-colors">
    Action
  </button>
</div>

Navigation Bar

<nav class="sticky top-0 z-50 bg-white/80 backdrop-blur-md border-b border-gray-200
            dark:bg-gray-900/80 dark:border-gray-800">
  <div class="mx-auto flex max-w-7xl items-center justify-between px-4 py-3 sm:px-6 lg:px-8">
    <a href="/" class="text-xl font-bold text-gray-900 dark:text-white">Logo</a>
    <div class="hidden gap-6 sm:flex">
      <a href="#" class="text-gray-700 hover:text-gray-900 dark:text-gray-300 dark:hover:text-white transition-colors">Home</a>
      <a href="#" class="text-gray-700 hover:text-gray-900 dark:text-gray-300 dark:hover:text-white transition-colors">About</a>
    </div>
    <button class="sm:hidden rounded-md p-2 hover:bg-gray-100 dark:hover:bg-gray-800">
      <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16" />
      </svg>
    </button>
  </div>
</nav>

Form with Validation States

<form class="mx-auto max-w-md space-y-6 rounded-xl bg-white p-8 shadow-lg dark:bg-gray-800">
  <div>
    <label class="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300" for="email">Email</label>
    <input type="email" id="email" required
           class="w-full rounded-lg border border-gray-300 px-4 py-2
                  focus:border-blue-500 focus:ring-2 focus:ring-blue-200 focus:outline-none
                  invalid:border-red-500 focus:invalid:ring-red-200
                  disabled:bg-gray-100 disabled:cursor-not-allowed
                  placeholder:text-gray-400
                  dark:border-gray-600 dark:bg-gray-700 dark:text-white dark:placeholder:text-gray-500"
           placeholder="you@example.com" />
  </div>
  <button type="submit"
          class="w-full rounded-lg bg-blue-600 py-3 font-bold text-white
                 hover:bg-blue-700 active:bg-blue-800 transition-colors
                 disabled:opacity-50 disabled:cursor-not-allowed">
    Sign In
  </button>
</form>

Responsive Grid

<div class="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
  {items.map(item => (
    <div class="rounded-lg bg-white p-6 shadow-md hover:shadow-lg transition-shadow
                dark:bg-gray-800">
      {item.name}
    </div>
  ))}
</div>

Best Practices

1. Use @theme for all design tokens — don't scatter arbitrary values; define them as theme variables
2. Mobile-first always — base styles are mobile, add sm:, md:, lg: for larger screens
3. Dark mode from the start — add dark: variants as you go, not as an afterthought
4. Complete class strings only — never interpolate partial class names
5. Prefer utility classes over @apply — extract components in your framework, not in CSS
6. Use semantic color names — --color-primary, --color-danger over raw palette references
7. Keep spacing consistent — use the spacing scale, reach for arbitrary values sparingly
8. Accessibility always — add focus:, focus-visible:, sr-only, forced-color-adjust as needed
9. Use @layer components for complex reusable styles — maintains proper specificity ordering
10. Use container queries for truly portable components that respond to their parent, not the viewport