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
Exploreagent - v3 to v4 migration across multiple files: Use
Taskagent - Design token hierarchy and theming architecture: Use
Planagent
If the
motionskill 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