Tailwind

Tailwind CSS

Intro

Tailwind v4 is CSS-first: install the package, @import "tailwindcss" once, and declare design tokens inside a @theme block. Compose styles directly in markup with utility classes, extract components in your framework (not with @apply), and lean on semantic tokens so dark mode and theming don't fight you.

Overview

Project setup (v4)

Install tailwindcss plus the appropriate adapter (@tailwindcss/postcss or @tailwindcss/vite). The CSS entry point only needs:

@import "tailwindcss";

@theme {
  --color-brand-500: oklch(0.65 0.19 260);
  --font-heading: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

There's no tailwind.config.js. Content detection is automatic (respecting .gitignore); override it with @source when you need to include extra files. For Vite projects, prefer the first-party Vite plugin over PostCSS.

Utility-first principles

Compose styles in markup and avoid premature abstraction. Group classes by concern (layout → spacing → typography → color) to keep long class lists scannable. Tailwind v4 accepts any integer spacing (mt-13, w-17) without configuration — arbitrary values like w-[347px] should be a code smell that signals a missing design token.

Component extraction

Extract in your UI framework (React/Vue/Svelte), not with @apply. @apply still works and remains appropriate when you need real CSS (e.g., styling HTML rendered from markdown), but prefer framework components for everything else. Keep extracted components small — a button or card, not an entire page section.

Responsive design

Mobile-first: base styles apply to all sizes; add breakpoints upward with sm:, md:, lg:, xl:, 2xl:. For component-level responsiveness, use container queries:

<div class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-4">

Constrain content with max-w-* + mx-auto. Test at 320px wide to stay WCAG 1.4.10 compliant.

Dark mode

Use the dark: variant with either the default prefers-color-scheme strategy or a .dark class. Best pattern: define semantic tokens once and override them in .dark, then apply token-based classes without any dark: prefix:

@theme {
  --color-surface: oklch(0.99 0 0);
  --color-on-surface: oklch(0.15 0 0);
}
.dark {
  --color-surface: oklch(0.15 0 0);
  --color-on-surface: oklch(0.95 0 0);
}

Then write bg-surface text-on-surface everywhere and both modes follow automatically.

Colors and theming

Tailwind v4 uses OKLCH, which is more vibrant and perceptually uniform than sRGB. Opacity modifiers work via color-mix(): bg-blue-500/50. Define brand colors in @theme rather than scattering hex values through markup. Multi-brand apps can swap CSS variables at the [data-theme] level at runtime without a rebuild.

Performance

The v4 engine is Rust-based: full builds run in around 100ms and incremental rebuilds in single-digit ms. Unused CSS is eliminated automatically. Never build class names dynamically (`text-${color}-500`) — the scanner can't see them. Use a lookup map or safelist the class with @source.

Gotchas

Agent-specific failure modes — provider-neutral pause-and-self-check items:

• Building class names dynamically with template literals. Tailwind's scanner detects class names by static string matching. A class like `text-${color}-500` or "bg-" + shade is invisible to the scanner and will be missing from the production build. Use a lookup object with full class name strings, or add the generated classes to a safelist.
• Overusing arbitrary values. w-[347px] or text-[13px] signals a design token that is missing from @theme. One arbitrary value is a problem to fix; many arbitrary values mean the design system has diverged from the implementation. Add the value to @theme and reference it by name.
• Using @apply for everything instead of component extraction. @apply scatters styles across CSS files and breaks the direct relationship between markup and styling that makes Tailwind easy to maintain. Extract reusable patterns as framework components (React, Vue, Svelte), not as CSS utilities.
• Not using focus-visible: for focus styles. focus:outline-none removes focus styles for all users, including keyboard users who depend on them. Use focus-visible:ring-2 focus-visible:ring-blue-500 to show focus indicators for keyboard navigation while hiding them for mouse users.
• Skipping @theme and hardcoding colors inline. Using arbitrary color values like text-[#3b82f6] instead of defining --color-brand-primary in @theme makes dark mode and multi-brand theming require global search-and-replace instead of a single token change.
• Not testing at 320px viewport width. Tailwind's mobile-first default base styles apply at all widths. A layout that works at 375px may break at 320px, which is the WCAG 1.4.10 (Reflow) minimum. Always check that no horizontal scrolling appears at 320px.
• Using the v3 tailwind.config.js pattern with v4. Tailwind v4 removes tailwind.config.js; configuration moves to CSS @theme blocks. Mixing v3 config with v4 styles causes tokens to be silently ignored. Check the version and use the appropriate configuration pattern.

Full reference

Layout utilities

Spacing and sizing

In v4, any integer works: p-13, mt-17, gap-22 — no config.

Typography

Backgrounds and borders

v4 renamed bg-gradient-* to bg-linear-*.

Effects and motion

Breakpoints

State variants

Accessibility utilities

Always include focus-visible: ring/outline styles on interactive elements. Use sr-only for labels on icon-only buttons. Text on colored backgrounds must meet WCAG AA contrast (4.5:1 normal, 3:1 large). Click targets should be at least 24×24 CSS pixels (WCAG 2.5.8).

Anti-patterns

• Class string builders (`text-${size}`) — the scanner can't detect them; use a lookup map
• Overusing arbitrary values — treat w-[347px] as a missing token and add it to @theme
• Nesting utilities in CSS — defeats the utility-first approach
• Ignoring accessibility — skipping focus states, contrast, or motion-reduce: will come back as audits
• Not using @theme — scattered hardcoded values destroy consistency and make dark mode painful

Further reading

• Tailwind CSS v4 announcement
• Official documentation