Tailwind CSS (v4+)

Overview

Tailwind CSS v4 skill covering CSS-first configuration, design tokens, component patterns, shadcn/ui integration, dark mode, container queries, migration from v3, and custom utilities.

When to use: Configuring Tailwind themes, building utility-first components, implementing dark mode, using container queries, migrating from v3, integrating shadcn/ui, troubleshooting build errors.

When NOT to use: Tailwind v3 legacy projects that will not upgrade, projects using a different styling approach (CSS Modules, styled-components) without plans to adopt Tailwind.

Quick Reference

Pattern	API	Key Points
CSS-first config	`@theme { --color-brand: oklch(...); }`	All config in CSS, no `tailwind.config.js`
Import entry	`@import "tailwindcss";`	Replaces `@tailwind base/components/utilities`
Custom utilities	`@utility name { ... }`	Replaces `@layer utilities`, works with variants
Functional utilities	`@utility tab-* { tab-size: --value(--tab-size-*); }`	Accept dynamic values via `--value()`
Plugin loading	`@plugin "@tailwindcss/typography";`	Replaces `require()` in config
Container queries	`@container` parent + `@md:` child	Built-in, no plugin needed
Named containers	`@container/sidebar` + `@md/sidebar:`	Scope queries to specific containers
Dark mode variant	`@custom-variant dark (&:where(.dark, .dark *));`	Class-based dark mode override
Theme inline	`@theme inline { --color-bg: var(--bg); }`	Inlines values at build, single-theme only
Source detection	`@source "../node_modules/my-lib";`	Explicitly add scan paths
Reference import	`@reference "../../app.css";`	Use theme in Vue/Svelte scoped styles
Override defaults	`--color-*: initial;` inside `@theme`	Reset a category before redefining
Dynamic values	`grid-cols-(--my-var)`	Use CSS variables in utility values
Text shadows	`text-shadow-*`	Built-in text shadow utilities
Starting styles	`starting:opacity-0`	`@starting-style` variant for entry animations
Masks	`mask-*`	CSS mask utilities for image/gradient masking
Field sizing	`field-sizing-content`	Auto-sizing textareas and inputs
Inset shadows	`inset-shadow-`, `inset-ring-`	Inner shadow and ring utilities
User validation	`user-valid:`, `user-invalid:`	Form validation after user interaction
Pointer queries	`pointer-fine:`, `pointer-coarse:`	Target input device precision
Inert	`inert:opacity-50`	Style inert elements
Logical spacing	`pbs-`, `pbe-`, `mbs-`, `mbe-`	Block-direction padding/margin (v4.2)
Logical sizing	`inline-`, `block-`, `min-inline-`, `max-block-`	Logical width/height utilities (v4.2)
Logical inset	`inset-s-`, `inset-e-`, `inset-bs-`, `inset-be-`	Logical positioning; replaces `start-`/`end-`
Logical borders	`border-bs-`, `border-be-`	Block-direction border utilities (v4.2)
Font features	`font-features-['smcp']`	OpenType `font-feature-settings` (v4.2)
New color palettes	`mauve`, `olive`, `mist`, `taupe`	Additional neutral palettes (v4.2)
Webpack integration	`@tailwindcss/webpack`	Run Tailwind as a webpack plugin (v4.2)
Color space	OKLCH	Default in v4, sRGB fallbacks generated

Common Mistakes

Mistake	Correct Pattern
Using `tailwind.config.js` in v4	Configure via `@theme { ... }` in CSS
`hsl(var(--background))` double-wrap	Reference directly: `var(--background)`
`:root`/`.dark` inside `@layer base`	Define at root level, outside any `@layer`
`@apply` with `@layer components` classes	Use `@utility` directive for custom utilities
`@theme inline` for multi-theme switching	Use `@theme` without `inline` for dynamic themes
Raw colors like `bg-blue-500` everywhere	Semantic tokens (`bg-primary`) that auto-adapt
`require()` or `@import` for plugins	Use `@plugin "package-name";`
`tailwindcss-animate` in v4	Use `tw-animate-css` instead
Missing `@theme inline` with shadcn/ui	Map all CSS variables in `@theme inline` block
Using `theme('colors.brand')` in CSS	Use `var(--color-brand)` native CSS variables
Using deprecated `start-`/`end-` inset	Use `inset-s-`/`inset-e-` logical utilities

Delegation

Class pattern discovery and usage examples: Use Explore agent
v3 to v4 migration across multiple files: Use Task agent
Design token hierarchy and theming architecture: Use Plan agent

If the motion skill is available, delegate complex animation patterns (spring physics, gestures, scroll-linked) to it.

References