Tailwind CSS v4

Tailwind CSS is a utility-first CSS framework. v4 is a ground-up rewrite: configuration is CSS-first (@theme replaces tailwind.config.js ), all colors use OKLCH, and the Vite plugin replaces PostCSS.

Install (v4)

npm install tailwindcss @tailwindcss/vite

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

// vite.config.ts import tailwindcss from '@tailwindcss/vite' export default { plugins: [tailwindcss()] }

Core Concept: Utility-First

Style elements by combining small, single-purpose classes directly in markup. No custom class names, no context switching.

<div class="mx-auto flex max-w-sm items-center gap-4 rounded-xl bg-white p-6 shadow-lg"> <img class="size-12 shrink-0 rounded-full" src="..." /> <div> <p class="text-xl font-semibold text-gray-900">Title</p> <p class="text-sm text-gray-500">Subtitle</p> </div> </div>

Variant Syntax

Variants prefix any utility: {variant}:{utility}

hover:bg-blue-600 focus:ring-2 active:scale-95 dark:bg-gray-900 sm:flex-row lg:grid-cols-3 disabled:opacity-50 group-hover:text-white peer-invalid:visible aria-checked:bg-sky-700 data-active:border-2 md:max-lg:hidden

Variants stack: dark:md:hover:bg-fuchsia-600

@theme — Design Tokens

Replace tailwind.config.js with CSS variables:

@import "tailwindcss";

@theme { --color-brand-500: oklch(0.65 0.2 240); --font-display: "Inter", sans-serif; --radius-card: 0.75rem; --breakpoint-xs: 30rem; --animate-fade-in: fade-in 0.3s ease-out; }

Generates: bg-brand-500 , font-display , rounded-card , xs:* , animate-fade-in

Key Directives

Directive Purpose

@theme { }

Define design tokens → generates utility classes

@layer base/components/utilities { }

Add custom CSS to cascade layers

@utility name { }

Add custom utility (works with all variants)

@custom-variant name (...) ;

Add reusable custom variant

@apply util1 util2;

Inline utilities into custom CSS

@source "../path"

Explicitly add source files for class detection

@reference "app.css";

Import theme vars without duplicating CSS

Arbitrary Values

bg-[#1da1f2] text-[22px] grid-cols-[1fr_500px_2fr] top-[117px] w-[calc(100%-2rem)] fill-(--brand-color)

Responsive Breakpoints (mobile-first)

Prefix Min-width

sm:

40rem (640px)

md:

48rem (768px)

lg:

64rem (1024px)

xl:

80rem (1280px)

2xl:

96rem (1536px)

<!-- Stack on mobile, row on md+ --> <div class="flex flex-col md:flex-row">

Common Patterns

// cn() helper — combine + deduplicate classes import { clsx, type ClassValue } from 'clsx' import { twMerge } from 'tailwind-merge' export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) }

<!-- Dark mode --> <div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">

<!-- Group: style children based on parent state --> <a class="group"><span class="text-gray-500 group-hover:text-white">Link</span></a>

<!-- Peer: style siblings based on sibling state --> <input class="peer" /><p class="hidden peer-invalid:block text-red-500">Invalid</p>

References

• Utility Classes — core concepts, arbitrary values, important modifier

• States & Variants — hover, focus, group, peer, ARIA, data, dark

• Responsive Design — breakpoints, mobile-first, container queries

• Theme & Design Tokens — @theme, namespaces, CSS variables, customization

• Colors — palette, OKLCH, opacity modifiers, dark mode

• Custom Styles — @layer, @apply, @utility, @custom-variant

• Directives & Functions — complete directive/function reference

• shadcn/ui — installation, Tailwind v4 setup, theming, components