# Tailwind V4 Best Practices

> Expert guidance for writing production-grade Tailwind CSS v4 code with design system thinking. Use this skill when users mention Tailwind CSS, CSS styling, design systems, theme configuration, design tokens, OKLCH colors, component styling, or migrating from Tailwind v3 to v4. Also trigger when writing or reviewing any CSS in a Tailwind project, even if "Tailwind" isn't explicitly mentioned. Covers @theme configuration, semantic utilities, and modern CSS patterns.

- Skill: `jenishshrestha/tailwind-v4-best-practices` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add jenishshrestha/tailwind-v4-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jenishshrestha/tailwind-v4-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: jenishshrestha (https://skillmd.com/u/jenishshrestha)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jenishshrestha/tailwind-v4-best-practices

---


# Tailwind CSS v4 Best Practices

Production-grade Tailwind CSS v4 with a focus on design system thinking, maintainability, and performance.

## Core Principles

### 1. Design Tokens, Not Direct Colors

Use semantic tokens instead of Tailwind's default color palette. This enables theme switching without touching components.

```html
<!-- ❌ Direct colors — breaks when you rebrand -->
<button class="bg-blue-500 text-white hover:bg-blue-600">
<span class="text-red-600">Error</span>

<!-- ✅ Semantic tokens — theme-aware -->
<button class="bg-primary text-primary-foreground hover:bg-primary-hover">
<span class="text-error">Error</span>
```

### 2. Semantic Utilities Over Arbitrary Values

Use the built-in scale. Reserve arbitrary values for true one-offs.

```html
<!-- ❌ Arbitrary when a utility exists -->
<h1 class="text-[20px]">
<div class="p-[16px] gap-[24px]">

<!-- ✅ Use the scale -->
<h1 class="text-2xl">
<div class="p-4 gap-6">
```

### 3. Complete Class Names Only

Tailwind's compiler needs full class names at build time. Never construct them dynamically.

```jsx
// ❌ Tailwind can't detect these
<div className={`bg-${color}-500`}>

// ✅ Complete class names or CSS variables
<div className={color === 'blue' ? 'bg-blue-500' : 'bg-red-500'}>
<div className="bg-[var(--dynamic-color)]">
```

### 4. Avoid @apply

Tailwind v4 discourages `@apply`. Use utility classes directly in templates, or use `theme()` in CSS when you need custom component classes.

```css
/* ❌ v3 pattern */
.button { @apply px-4 py-2 bg-blue-500 text-white rounded; }

/* ✅ v4 — use theme() if you need CSS */
.button {
  padding-inline: theme(spacing.4);
  background-color: theme(colors.primary);
}
```

## @theme Configuration

Tailwind v4 moves config from JavaScript to CSS. Define design tokens with `@theme`:

```css
@import "tailwindcss";

@theme {
  /* Semantic colors using OKLCH */
  --color-primary: oklch(0.55 0.25 250);
  --color-primary-hover: oklch(0.50 0.25 250);
  --color-primary-foreground: oklch(0.98 0 0);

  --color-error: oklch(0.60 0.22 25);
  --color-success: oklch(0.65 0.18 145);

  /* Surface colors */
  --color-background: oklch(1.0 0 0);
  --color-foreground: oklch(0.20 0.01 250);
  --color-surface: oklch(0.98 0.01 250);
  --color-border: oklch(0.90 0.01 250);

  /* Typography */
  --font-family-heading: "Inter", sans-serif;
  --font-family-body: "Inter", sans-serif;
  --font-family-mono: "Fira Code", monospace;
}
```

For full token architecture (Primitive → Semantic → Component layers), see [references/design-tokens.md](./references/design-tokens.md).

## OKLCH Colors

Tailwind v4 defaults to OKLCH for better perceptual uniformity.

```
oklch(lightness chroma hue / alpha)
```

- **Lightness**: 0 (black) to 1 (white)
- **Chroma**: 0 (gray) to ~0.4 (vivid)
- **Hue**: 0-360 degrees
- **Alpha**: 0-1 (optional)

```css
--color-brand: oklch(0.55 0.25 270);      /* vivid purple */
--color-subtle: oklch(0.96 0.02 250);     /* muted gray */
--color-overlay: oklch(0.0 0 0 / 0.5);   /* translucent black */
```

## v3 → v4 Class Name Renames

```
v3                     →  v4
───────────────────────────────
bg-gradient-to-r       →  bg-linear-to-r
bg-gradient-to-br      →  bg-linear-to-br
flex-shrink-0          →  shrink-0
flex-grow              →  grow
decoration-clone       →  box-decoration-clone
decoration-slice       →  box-decoration-slice
```

Run the automated upgrade: `npx @tailwindcss/upgrade`

## Vite Setup (Fastest)

```js
import tailwindcss from '@tailwindcss/vite'

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

v4 auto-detects content — no need to configure content paths. Unused utilities are tree-shaken automatically in production.

## References

Load only what you need for the current task:

| Reference | Load When |
|-----------|-----------|
| [design-tokens.md](./references/design-tokens.md) | Setting up token architecture, component tokens, status color patterns |
| [theming.md](./references/theming.md) | Dark mode, runtime theme switching, brand variants, user preference detection |
| [advanced-patterns.md](./references/advanced-patterns.md) | Animations, grid layouts, container queries, custom utilities, plugins, performance |
| [migration.md](./references/migration.md) | Migrating a project from Tailwind v3 to v4 |