oakoss 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