Tailwind V4 Pro -- Styling for Next.js 16

When to Use

Trigger on any mention of: tailwind, tailwind v4, css styling, @theme, design tokens, dark mode, postcss, tailwind classes, tailwind migration, css variables, color system, responsive design.

Reference Files

File	Description
references/setup.md	Version compatibility (stack, browser support, removed features, build perf) + PostCSS config, CSS entry point, layers, package deps, content detection
references/migration-v3-v4.md	Automated upgrade tool, renamed/removed utilities, default behavior changes, syntax changes, restoring v3 defaults, custom utilities migration
references/design-tokens.md	@theme directive (bare/inline/static), 17 namespace reference, extending vs replacing, animations with keyframes, sharing tokens across projects
references/color-system.md	Opacity modifiers (slash syntax), color-mix(), custom color palette, arbitrary values, OKLch palette
references/typography.md	Font registration, Vietnamese text support (diacriticals, subset), text size customization, responsive typography
references/dark-mode.md	System preference, class-based toggle, data attribute strategy, three-way toggle (light/dark/system), CSS variable approach, @variant directive
references/components.md	Button (primary/secondary/ghost), Card, Input, Badge (Pro/Free/Status), Sidebar navigation -- all CViet patterns
references/vscode.md	IntelliSense extension, activation for v4, settings (classRegex for clsx/cn), NODE_ENV fix, restart procedure, file associations
references/errors.md	20 errors (TW-001 through TW-020) with exact messages, causes, and fixes
references/performance.md	Tree shaking, content auto-detection, spacing scale (single variable), dynamic utility values, production build, anti-patterns
references/cviet-design-system.md	Current globals.css, design token mapping table, spacing system, border radius, shadow scale, standard layout/form/card/flex patterns, interaction patterns
references/directives.md	All 13 directives (@import, @theme, @utility, @variant, @custom-variant, @layer, @apply, @source, @reference, @config, @plugin) + 3 functions (--alpha, --spacing, theme) + using vars in CSS/JS
references/new-utilities.md	Container queries, 3D transforms, gradient angles, stacked shadows, field-sizing, color-scheme, not-/in-/nth-* variants, @starting-style, dynamic data attributes, sources list

Error Quick Lookup

ID	Error	Fix
TW-001	PostCSS plugin not found	Use @tailwindcss/postcss (not tailwindcss)
TW-002	@tailwind directive deprecated	Replace with @import "tailwindcss"
TW-003	No styles in development	cross-env NODE_ENV=development next dev --webpack
TW-004	Duplicate PostCSS config	Delete .js, keep ONLY .mjs
TW-005	Google Fonts @import ignored	Must be BEFORE @import "tailwindcss"
TW-006	Custom classes not generating	Use @theme not :root for utility generation
TW-007	shadow-sm not working	Renamed: use shadow-xs (v4 scale shift)
TW-008	outline-none not working	Use outline-hidden for v3 behavior
TW-009	Ring width too thin	ring is now 1px; use ring-3 for v3 behavior
TW-010	Border color unexpected	Default changed to currentColor; specify explicitly
TW-011	Dark mode not toggling	Use @custom-variant dark (&:where(.dark, .dark *))
TW-012	Hover not working on mobile	v4 guards with @media (hover: hover)
TW-013	@layer utilities ignored	Use @utility directive instead
TW-014	@apply fails in scoped styles	Use @reference "../../app.css"
TW-015	tailwind.config.js ignored	Use @config or migrate to @theme
TW-016	Button cursor:default	Add cursor-pointer explicitly
TW-017	Webpack HMR not detecting changes	Use --webpack flag + NODE_ENV=development
TW-018	@theme inside media query fails	@theme must be top-level; use :root for scoped vars
TW-019	Sass/Less conflicts	Remove Sass/Less; Tailwind v4 IS your preprocessor
TW-020	Content detection missing files	Add @source directives for non-auto-detected paths

MANDATORY: Canonical Token Classes

NEVER write arbitrary hex classes when a @theme token exists. Always use canonical names:

Hex	Token Class
#1B4FD8	brand (bg-brand, text-brand, border-brand)
#1440A8	brand-dark
#0F172A	text (text-text, bg-text)
#64748B	muted (text-muted)
#E2E8F0	border (border-border)
#FAFAF8	background (bg-background)
#10B981	success (bg-success, text-success)
#0EA5E9	accent (bg-accent)

Opacity: bg-brand/10 not bg-[#1B4FD8]/10. Exception: react-pdf StyleSheet (inline CSS, not Tailwind).

Key Patterns

PostCSS Config (Required)

// postcss.config.mjs -- MUST be .mjs, not .js
export default { plugins: { "@tailwindcss/postcss": {} } }

CSS Entry Point

/* globals.css -- @import order matters! */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
@import "tailwindcss";

@theme inline {
  --color-brand: #1B4FD8;
  --color-accent: #0EA5E9;
  --color-surface: #FFFFFF;
  --color-background: #FAFAF8;
  --font-sans: 'Inter', system-ui, sans-serif;
}

Dev Script (VSCode Fix)

{ "scripts": { "dev": "cross-env NODE_ENV=development next dev --webpack" } }