tailwind

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

• Configuration -- CSS-first config, @theme, @theme inline, @utility, @plugin, @source, @reference, @variant directives
• Design Tokens -- OKLCH token system, brand scales, semantic tokens, shadows, z-index, fluid typography
• Component Patterns -- Layouts, grids, container queries, 3D transforms, subgrid, CVA variants
• UI Patterns -- Buttons, forms, navigation, cards, typography with variants, states, accessibility
• Dark Mode -- Class-based dark mode, multi-theme systems, ThemeProvider, @custom-variant
• shadcn/ui Integration -- Four-step architecture, components.json, tw-animate-css, Vite setup
• Migration -- v3 to v4 migration steps, breaking changes, upgrade tool, common gotchas
• Troubleshooting -- Common errors, build fixes, CSS layer issues, PostCSS problems