---
id: ofershap/tailwind-best-practices/tailwind-best-practices
version: "fb0187dd"
license: MIT
install: manual
updated: 2026-02-20
---
# tailwind-best-practices — This skill corrects AI agents that generate outdated Tailwind v3 code by teaching v4 syntax and configuration patterns. It covers 12 critical rules including CSS @import statements, @theme directives, modern opacity syntax, container queries, and renamed utilities, plus anti-patterns to avoid.
Publisher: ofershap · Stars: 13 · Updated: 2026-02-20
Install (manual): `git clone https://github.com/ofershap/tailwind-best-practices`
## SKILL.md
## 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):**
```js
// 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):**
```js
// postcss.config.mjs
export default {
plugins: {
"postcss-import": {},
tailwindcss: {},
autoprefixer: {},
},
};
```
**Correct:**
```js
// 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
```
**Correct:**
```html
```
**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
```
**Correct:**
```css
@theme {
--color-brand: #3b82f6;
}
```
```html
```
**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
```
**Correct (when sizing should be based on parent, not viewport):**
```html
```
**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):**
```js
// 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
```
**Correct:**
```html
```
**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):**
```html
```
**Correct:**
```html
```
**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):**
```html
```
**Correct:**
```html
```
**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
```
**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`
[View on SkillFed](https://skillfed.io/ofershap/tailwind-best-practices/tailwind-best-practices) · [View on GitHub](https://github.com/ofershap/tailwind-best-practices)