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):

css

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

Correct:

css

@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.exports = {
  theme: {
    extend: {
      colors: {
        brand: "#3b82f6",
      },
      spacing: {
        18: "4.5rem",
      },
    },
  },
};

Correct:

css

@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --spacing-18: 4.5rem;
}

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):

// postcss.config.mjs
export default {
  plugins: {
    "postcss-import": {},
    tailwindcss: {},
    autoprefixer: {},
  },
};

Correct:

// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

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):

html

<div class="bg-red-500 bg-opacity-50">
  <div class="text-blue-600 text-opacity-75"></div>
</div>

Correct:

html

<div class="bg-red-500/50">
  <div class="text-blue-600/75"></div>
</div>

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):

html

<div class="bg-[#3b82f6]"></div>

Correct:

css

@theme {
  --color-brand: #3b82f6;
}

html

<div class="bg-brand"></div>

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):

html

<div class="md:flex-row flex-col"></div>

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

html

<div class="@container">
  <div class="flex flex-col @md:flex-row">
    <!-- Responds to container width, not viewport -->
  </div>
</div>

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):

css

@layer utilities {
  .content-auto {
    content-visibility: auto;
  }
}

Correct:

css

@utility content-auto {
  content-visibility: auto;
}

Why: Tailwind v4 uses

@utility

directive instead of

@layer utilities

for custom utilities.

8. Use Correct Important Modifier

Wrong (agents do this):

// tailwind.config.js
module.exports = {
  important: true,
};

Correct:

css

@import "tailwindcss" important;

Why: The

important

option moved from config to the CSS import statement in v4.

9. Use Renamed Utilities

Wrong (agents do this):

html

<div class="shadow-sm ring-1 ring-gray-900/5">
  <div class="blur-sm">
    <div class="rounded-sm"></div>
  </div>
</div>

Correct:

html

<div class="shadow-xs ring-1 ring-gray-900/5">
  <div class="blur-xs">
    <div class="rounded-xs"></div>
  </div>
</div>

Why: In v4,

shadow-sm

was renamed to

shadow-xs

shadow

shadow-sm

blur-sm

blur-xs

rounded-sm

rounded-xs

, etc. The old

-sm

values now map to what was previously the default.

10. Use Modern Gradient Syntax

Wrong (agents do this):

html

<div class="bg-gradient-to-r from-blue-500 to-purple-500"></div>

Correct:

html

<div class="bg-linear-to-r from-blue-500 to-purple-500"></div>

Why: Tailwind v4 renamed

bg-gradient-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):

html

<div class="hover:bg-blue-500">
  <!-- No way to style non-hovered state specifically -->
</div>

Correct:

html

<div class="not-hover:opacity-75 hover:opacity-100"></div>

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):

css

.modal {
  opacity: 0;
  transition: opacity 0.3s;
}
.modal.open {
  opacity: 1;
}

Correct:

html

<div class="starting:opacity-0 opacity-100 transition-opacity duration-300"></div>

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
```

tailwind-best-practices

NPX Install

Tags

SKILL.md Content

When to use

Critical Rules

1. Use CSS @import Instead of @tailwind Directives

2. Use CSS-First Configuration with @theme

3. Use @tailwindcss/postcss Plugin

4. Use Modern Opacity Syntax

5. Use CSS Variables for Custom Colors

6. Use Container Queries with @container

7. Use @utility for Custom Utilities

8. Use Correct Important Modifier

9. Use Renamed Utilities

10. Use Modern Gradient Syntax

11. Use not-* Variant for Negation

12. Use @starting-style for Entry Animations

Patterns

Anti-Patterns