Tailwind CSS patterns and conventions. Use when writing responsive designs, implementing dark mode, creating reusable component styles, configuring Tailwind, or migrating from v3 to v4. Triggers on tasks involving Tailwind classes, responsive design, dark mode, CSS styling, or "migrate to Tailwind v

Tailwind CSS Best Practices Comprehensive patterns for building consistent, maintainable interfaces with Tailwind CSS v3.4+ and v4. Contains 29 rules covering responsive design, dark mode, component patterns, configuration, and v4 migration. Metadata Version: 1.0.0 Framework: Tailwind CSS v3.4+ / v4.0+ Rule Count: 29 rules across 8 categories License: MIT Documentation: [tailwindcss.com/docs](https://tailwindcss.com/docs) Step 1: Detect Tailwind Version Always check the version before giving any advice. v3 and v4 are fundamentally different. Check package.json for the installed version: Also check for these signals: Signal Version tailwind.config.js exists v3 @import "tailwindcss" in CSS v4 @tailwindcss/vite in dependencies v4 @tailwindcss/postcss in dependencies v4 @theme {} block in CSS v4 If v3 : Apply resp , dark , comp , config rules. Note that v4 is available. If v4 : Apply v4 rules. tailwind.config.js patterns do NOT apply — use @theme {} instead. If migrating v3 → v4 : Follow v4 migration rules directly. When to Apply Reference these guidelines when: Writing responsive layouts Implementing dark mode Creating reusable component styles Configuring Tailwind (v3 or v4) Migrating a project from v3 to v4 Setting up a new project with v4 Rule Categories by Priority Priority Category Impact Prefix Version 1 Responsive Design CRITICAL resp v3 / v4 2 Dark Mode CRITICAL dark v3 / v4 3 Component Patterns HIGH comp v3 / v4 4 Custom Configuration HIGH config v3 5 V4 & Migration HIGH v4 v4 only 6 Spacing & Typography MEDIUM space v3 / v4 7 Animation MEDIUM anim v3 / v4 8 Performance LOW perf v3 / v4 Quick Reference 1. Responsive Design (CRITICAL) resp mobile first Mobile first approach resp breakpoints Use breakpoints correctly resp container Container patterns resp grid flex Grid vs Flexbox decisions resp hidden shown Conditional display 2. Dark Mode (CRITICAL) dark setup Configure dark mode dark classes Apply dark mode classes dark toggle Implement dark mode toggle dark system preference Respect system preference dark colors Design for both modes 3. Component Patterns (HIGH) comp clsx cn Conditional classes utility comp variants Component variants pattern comp slots Slot based components comp composition Composing utilities 4. Custom Configuration — v3 only (HIGH) config extend Extend vs override theme config colors Custom color palette config fonts Custom fonts config screens Custom breakpoints config plugins Using plugins 5. V4 & Migration (HIGH) v4 installation Install v4 with Vite or PostCSS, @source , @reference v4 theme configuration Replace tailwind.config.js with @theme {} in CSS v4 custom utilities @utility , @custom variant , @variant , @plugin v4 migration Step by step v3 → v4 migration with renamed utilities, starting: , forced colors: 6. Spacing & Typography (MEDIUM) space consistent Consistent spacing scale space margins Margin patterns space padding Padding patterns typo scale Typography scale typo line height Line height 7. Animation (MEDIUM) anim transitions Transition utilities anim keyframes Custom keyframes anim reduced motion Respect motion preferences 8. Performance (LOW) perf purge Content configuration perf jit JIT mode benefits perf arbitrary Arbitrary values usage Essential Patterns Mobile First Responsive Design Dark Mode Implementation v3 — tailwind.config.js : v4 — CSS only, no config file: Component — identical in both versions: Conditional Classes with clsx/cn Theme Configuration — v3 vs v4 v3 — tailwind.config.js : v4 — app.css only, no JS config: See v4 theme configuration and v4 migration rules for full details. Responsive Grid Layout Form Styling Animations with Reduced Motion How to Use Always run Step 1 (version detection) first, then read the relevant rule files: v3 projects: v4 projects: Migrating v3 → v4: References [Tailwind CSS Documentation](https://tailwindcss.com/docs) Official documentation [Responsive Design Guide](https://tailwindcss.com/docs/responsive design) Mobile first patterns [Dark Mode Guide](https://tailwindcss.com/docs/dark mode) Theme implementation [Configuration Guide](https://tailwindcss.com/docs/configuration) Customization [Tailwind UI](https://tailwindui.com) Official component library [Headless UI](https://headlessui.com) Accessible components [Heroicons](https://heroicons.com) Icon library Ecosystem Tools Tailwind CSS IntelliSense VS Code autocomplete and linting Prettier Plugin Automatic class sorting tailwind merge Conflict free class merging clsx Conditional class utility CVA Component variant system License MIT License See repository for full license text. This skill is part of the Agent Skills collection, providing AI powered development assistance with industry best practices.

tailwind-best-practices