Tailwind v4 + shadcn/ui Production Stack

Production-tested

WordPress Auditor (

https://wordpress-auditor.webfonts.workers.dev

)

Last Updated

2026-01-20

Versions

tailwindcss@4.1.18, @tailwindcss/vite@4.1.18

Status

Production Ready ✅ Quick Start (Follow This Exact Order)

1. Install dependencies

pnpm add tailwindcss @tailwindcss/vite pnpm add -D @types/node tw-animate-css pnpm dlx shadcn@latest init

2. Delete v3 config if exists

rm tailwind.config.ts

v4 doesn't use this file

vite.config.ts

:

import

{

defineConfig

}

from

'vite'

import

react

from

'@vitejs/plugin-react'

import

tailwindcss

from

'@tailwindcss/vite'

import

path

from

'path'

export

default

defineConfig

(

{

plugins

:

[

react

(

)

,

tailwindcss

(

)

]

,

resolve

:

{

alias

:

{

'@'

:

path

.

resolve

(

__dirname

,

'./src'

)

}

}

}

)

components.json

(CRITICAL):

{

"tailwind"

:

{

"config"

:

""

,

// ← Empty for v4

"css"

:

"src/index.css"

,

"baseColor"

:

"slate"

,

"cssVariables"

:

true

}

}

The Four-Step Architecture (MANDATORY)

Skipping steps will break your theme. Follow exactly:

Step 1: Define CSS Variables at Root

/ src/index.css /

@import

"tailwindcss"

;

@import

"tw-animate-css"

;

/ Required for shadcn/ui animations /

:root

{

--background

:

hsl

(

0

0

%

100

%

)

;

/ ← hsl() wrapper required /

--foreground

:

hsl

(

222.2

84

%

4.9

%

)

;

--primary

:

hsl

(

221.2

83.2

%

53.3

%

)

;

/ ... all light mode colors /

}

.dark

{

--background

:

hsl

(

222.2

84

%

4.9

%

)

;

--foreground

:

hsl

(

210

40

%

98

%

)

;

--primary

:

hsl

(

217.2

91.2

%

59.8

%

)

;

/ ... all dark mode colors /

}

Critical

Define at root level (NOT inside

@layer base

). Use

hsl()

wrapper.

Step 2: Map Variables to Tailwind Utilities

@theme

inline

{

--color-background

:

var

(

--background

)

;

--color-foreground

:

var

(

--foreground

)

;

--color-primary

:

var

(

--primary

)

;

/ ... map ALL CSS variables /

}

Why

Generates utility classes (

bg-background

,

text-primary

). Without this, utilities won't exist.

Step 3: Apply Base Styles

@layer

base

{

body

{

background-color

:

var

(

--background

)

;

/ NO hsl() wrapper here /

color

:

var

(

--foreground

)

;

}

}

Critical

Reference variables directly. Never double-wrap:

hsl(var(--background))

.

Step 4: Result - Automatic Dark Mode

<

div

className

=

"

bg-background text-foreground

"

>

{

/ No dark: variants needed - theme switches automatically /

}

</

div

>

Dark Mode Setup

1. Create ThemeProvider

(see

templates/theme-provider.tsx

)

2. Wrap App

:

// src/main.tsx

import

{

ThemeProvider

}

from

'@/components/theme-provider'

ReactDOM

.

createRoot

(

document

.

getElementById

(

'root'

)

!

)

.

render

(

<

ThemeProvider defaultTheme

=

"dark"

storageKey

=

"vite-ui-theme"

>

<

App

/

>

<

/

ThemeProvider

>

)

3. Add Theme Toggle

:

pnpm

dlx shadcn@latest

add

dropdown-menu

See

reference/dark-mode.md

for ModeToggle component.

Critical Rules

✅ Always Do:

Wrap colors with

hsl()

in

:root

/

.dark

:

--bg: hsl(0 0% 100%);

Use

@theme inline

to map all CSS variables

Set

"tailwind.config": ""

in components.json

Delete

tailwind.config.ts

if exists

Use

@tailwindcss/vite

plugin (NOT PostCSS)

❌ Never Do:

Put

:root

/

.dark

inside

@layer base

(causes cascade issues)

Use

.dark { @theme { } }

pattern (v4 doesn't support nested @theme)

Double-wrap colors:

hsl(var(--background))

Use

tailwind.config.ts

for theme (v4 ignores it)

Use

@apply

directive (deprecated in v4, see error #7)

Use

dark:

variants for semantic colors (auto-handled)

Use

@apply

with

@layer base

or

@layer components

classes (v4 breaking change - use

@utility

instead) |

Source

Wrap ANY styles in

@layer base

without understanding CSS layer ordering (see error #8) |

Source

Common Errors & Solutions

This skill prevents

8 documented errors

.

1. ❌ tw-animate-css Import Error

Error

"Cannot find module 'tailwindcss-animate'"

Cause

shadcn/ui deprecated tailwindcss-animate for v4. Solution :

✅ DO

pnpm add -D tw-animate-css

Add to src/index.css:

@import "tailwindcss" ; @import "tw-animate-css" ;

❌ DON'T

npm install tailwindcss-animate

v3 only

1. ❌ Colors Not Working

   Error

   :

   bg-primary

   doesn't apply styles

   Cause

   Missing @theme inline mapping Solution : @theme inline { --color-background : var ( --background ) ; --color-foreground : var ( --foreground ) ; --color-primary : var ( --primary ) ; / ... map ALL CSS variables / }

2. ❌ Dark Mode Not Switching

   Error

   Theme stays light/dark

   Cause

   Missing ThemeProvider Solution : Create ThemeProvider (see templates/theme-provider.tsx ) Wrap app in main.tsx Verify .dark class toggles on