tailwind-css

Tailwind CSS v4 patterns: CSS-first config, utility classes, component variants, v3 migration. Use when styling with Tailwind, configuring @theme tokens, usi...

Security Scan

Instruction-only Tailwind v4 guidance that is internally consistent with its stated purpose and does not request credentials, installs, or unexpected system access.

Purpose & Capability

Name/description (Tailwind CSS v4 patterns and migration guidance) matches the content of SKILL.md and reference docs. There are no unrelated dependencies, env vars, or binaries requested.

Instruction Scope

Runtime instructions are limited to guidance about CSS-first config, utilities, variants, lint rules, and migration steps. The doc only suggests checking current docs via a tool named `search_docs` before implementing; it does not instruct reading unrelated files, accessing secrets, or posting data to external endpoints.

Install Mechanism

No install spec and no code files—this is instruction-only, so nothing will be written to disk or fetched at install time.

Credentials

The skill declares no required environment variables, credentials, or config paths. Nothing requested is disproportionate to a styling/migration guidance skill.

Persistence & Privilege

always is false and the skill does not request persistent or elevated privileges. It does not modify other skills or system-wide settings.

Assessment

This skill is instruction-only and appears coherent and low-risk: it doesn't request secrets, install code, or access files. Before using it: (1) confirm your project actually uses Tailwind v4 (the guidance is v4-specific); (2) review any automated suggestions before applying them (lint/codemods can change many files); (3) be aware the skill asks you to 'search_docs'—if your agent has a tool that fetches external docs, that tool may perform network requests (the skill itself does not specify endpoints); and (4) test changes in a branch/CI to avoid regressions. If you need additional assurance, request the author/source or a provenance link for the patterns.

Tailwind CSS v4

Verify before implementing: For v4-specific syntax (@theme, @variant, CSS-first config), search current docs via search_docs before writing code. Tailwind v4 changed significantly from v3 and training data may be stale.

CSS-First Configuration

v4 eliminates tailwind.config.ts. All configuration lives in CSS.

Directive	Purpose
@import "tailwindcss"	Entry point (replaces @tailwind base/components/utilities)
@theme { }	Define/extend design tokens -- auto-generates utility classes
@theme inline { }	Map CSS variables to Tailwind utilities without generating new vars
@theme static { }	Define tokens that don't generate utilities
@utility name { }	Create custom utilities (replaces @layer components + @apply)
@custom-variant name (selector)	Define custom variants

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.72 0.11 178);
  --font-display: "Inter", sans-serif;
  --animate-fade-in: fade-in 0.2s ease-out;
  @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
}

@custom-variant dark (&:where(.dark, .dark *));

Tokens defined with @theme become utilities automatically: --color-brand produces bg-brand, text-brand, border-brand. Define z-index as tokens (--z-modal: 50) and reference via z-(--z-modal) instead of arbitrary z-50.

CSS Modules: when using .module.css with Tailwind v4, add @reference "#tailwind"; at the top of the module file to enable theme token access inside the module.

Animations (tw-animate-css): use animate-in/animate-out base classes combined with effect classes (fade-in, slide-in-from-top). Decimal spacing gotcha: use bracket notation [0.625rem] instead of fractional values like 2.5.

v3 to v4 Breaking Changes

v3	v4	Notes
tailwind.config.ts	@theme in CSS	Delete config file
@tailwind base/components/utilities	@import "tailwindcss"	Single import
darkMode: "class"	@custom-variant dark (...)	CSS-only
bg-gradient-to-r	bg-linear-to-r	Also: bg-radial, bg-conic
bg-opacity-60	bg-red-500/60	All *-opacity-* removed
rounded-sm	rounded-xs	Radius scale shifted down one step
rounded	rounded-sm	(run @tailwindcss/upgrade codemod)
rounded-md (6px)	rounded (6px)
rounded-lg	rounded-md
rounded-xl	rounded-lg
min-h-screen	min-h-dvh	dvh handles mobile browser chrome
w-6 h-6	size-6	Size shorthand for equal w/h
space-x-4	gap-4	Gap handles flex/grid wrapping correctly
text-base leading-7	text-base/7	Inline line-height modifier
require("tailwindcss-animate")	tw-animate-css	CSS-only animations

Coding Rules

• gap over space-x/space-y -- gap handles wrapping; space-* breaks on wrap
• size-* over w-* h-* -- for equal dimensions
• min-h-dvh over min-h-screen -- dvh accounts for mobile browser chrome
• Opacity modifier (bg-black/50) -- *-opacity-* utilities are removed in v4
• Design tokens over arbitrary values -- check @theme before using [#hex]
• Never construct classes dynamically -- text-${color}-500 won't be detected; use complete class names
• @utility over @apply with @layer -- @apply on @layer classes fails in v4
• Parent padding over last-child margin -- use padding on containers instead of bottom margins on the last child

ESLint Integration

Use eslint-plugin-better-tailwindcss for automated class validation:

• no-conflicting-classes -- catches text-red-500 text-blue-500
• no-unknown-classes -- flags typos
• enforce-canonical-classes -- normalizes shorthand
• no-duplicate-classes -- removes redundant entries
• no-deprecated-classes -- catches v3 classes removed in v4
• useSortedClasses -- enforces canonical class order; configure attributes: ["classList"] and functions: ["clsx", "cva", "cn", "tv", "tw"] to cover JSX utility functions

Class Merging

Use cn() combining clsx + tailwind-merge for conditional/dynamic classes. Use plain strings for static className attributes.

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }

// Static: plain string
<button className="rounded-lg px-4 py-2 font-medium bg-blue-600">

// Conditional: use cn()
<button className={cn("rounded-lg px-4 py-2", isActive ? "bg-blue-600" : "bg-gray-700")} />

Component Variants

Use tailwind-variants (tv()) for type-safe variant components. Alternative: class-variance-authority (cva()).

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

See tailwind-variants patterns for slots, composition, and responsive variants.

Common Errors

Symptom	Fix
bg-primary doesn't work	Add @theme inline { --color-primary: var(--primary); }
Colors all black/white	Double hsl() wrapping -- use var(--color) not hsl(var(--color))
@apply fails on custom class	Use @utility instead of @layer components
Build fails after migration	Delete tailwind.config.ts
Animations broken	Replace tailwindcss-animate with tw-animate-css
.dark { @theme { } } fails	v4 does not support nested @theme -- use :root/.dark CSS vars mapped via @theme inline

Dark Mode (v4 Pattern)

:root { --background: hsl(0 0% 100%); --foreground: hsl(222 84% 4.9%); }
.dark { --background: hsl(222 84% 4.9%); --foreground: hsl(210 40% 98%); }
@theme inline { --color-background: var(--background); --color-foreground: var(--foreground); }

Semantic classes (bg-background, text-foreground) auto-switch -- no dark: variants needed for themed colors.

Verify

• Build passes with zero errors (npm run build or equivalent)
• No v3 class names remain in changed files (check with @tailwindcss/upgrade --dry-run if available)
• No conflicting classes on the same element

References

• Component patterns -- tailwind-variants slots, CVA, compound components
• Layout patterns -- grid areas, container queries, z-index management, fluid typography