tailwind-best-practices

When to use

Use this skill when working with Tailwind CSS code. AI agents are trained on Tailwind v3 data and consistently generate outdated patterns - wrong config files, deprecated directives, removed utilities, and verbose class lists. This skill enforces Tailwind CSS v4 patterns.

Critical Rules

1. Use CSS @import Instead of @tailwind Directives

Wrong (agents do this):

@tailwind base;
@tailwind components;
@tailwind utilities;

Correct:

@import "tailwindcss";

Why: Tailwind v4 removed @tailwind directives entirely. Use a standard CSS @import statement.

2. Use CSS-First Configuration with @theme

Wrong (agents do this):

// tailwind.config.js
module

Correct:

Why: Tailwind v4 uses CSS-first configuration with the @theme directive. No tailwind.config.js needed for most projects.

3. Use @tailwindcss/postcss Plugin

Wrong (agents do this):

Correct:

Why: In v4, postcss-import and autoprefixer are handled automatically. The plugin is @tailwindcss/postcss, not tailwindcss.

4. Use Modern Opacity Syntax

Wrong (agents do this):

Correct:

Why: The bg-opacity-*, text-opacity-*, border-opacity-*, and placeholder-opacity-* utilities were removed in v4. Use the slash modifier syntax.

5. Use CSS Variables for Custom Colors

Wrong (agents do this):

Correct:

Why: Arbitrary values (bg-[#3b82f6]) should be rare. Define custom colors in @theme so they're reusable and consistent.

6. Use Container Queries with @container

Wrong (agents do this):

Correct (when sizing should be based on parent, not viewport):

Why: Tailwind v4 has built-in container query support. Use @container on the parent and @sm:, @md:, @lg: variants on children for component-level responsive design.

7. Use @utility for Custom Utilities

Wrong (agents do this):

Correct:

Why: Tailwind v4 uses @utility directive instead of @layer utilities for custom utilities.

8. Use Correct Important Modifier

Wrong (agents do this):

Correct:

Why: The important option moved from config to the CSS import statement in v4.

9. Use Renamed Utilities

Wrong (agents do this):

Correct:

Why: In v4, shadow-sm was renamed to shadow-xs, shadow to shadow-sm, blur-sm to blur-xs, rounded-sm to rounded-xs, etc. The old -sm values now map to what was previously the default.

10. Use Modern Gradient Syntax

Wrong (agents do this):

Correct:

Why: Tailwind v4 renamed bg-gradient-to-* to bg-linear-to-* and added support for other gradient types like bg-conic-* and bg-radial-*.

11. Use not-* Variant for Negation

Wrong (agents do this):

Correct:

Why: Tailwind v4 added the not-* variant for styling elements that do NOT match a condition.

12. Use @starting-style for Entry Animations

Wrong (agents do this):

Correct:

Why: Tailwind v4 supports @starting-style via the starting: variant for CSS-only entry animations without JavaScript.

Patterns

• Define all custom design tokens in @theme blocks
• Use @import "tailwindcss" as the single entry point
• Use container queries (@container + @md:) for component-level responsive design
• Use the slash modifier for opacity: bg-blue-500/50, text-gray-900/75
• Use @utility for custom utilities, @variant for custom variants
• Use bg-linear-to-* for gradients (not bg-gradient-to-*)

Anti-Patterns

• NEVER create a tailwind.config.js unless you need JavaScript-based dynamic config
• NEVER use @tailwind base/components/utilities - use @import "tailwindcss"
• NEVER use bg-opacity-*, text-opacity-* - use slash modifier syntax
• NEVER use @layer utilities for custom utilities - use @utility
• NEVER use bg-gradient-to-* - use bg-linear-to-*
• NEVER use postcss-import or autoprefixer with v4 - they're built in
• NEVER use shadow-sm when you mean the smallest shadow - it's now shadow-xs