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.
Tailwind Best Practices teaches Tailwind CSS v4 syntax and configuration to replace outdated v3 patterns.
AI-generated summary based on this skill's SKILL.md
Install
ofershap/tailwind-best-practices/tailwind-best-practices · repository language: JavaScript
git clone https://github.com/ofershap/tailwind-best-practices
cp -r tailwind-best-practices/skills/tailwind-best-practices ~/.claude/skills/tailwind-best-practicesnpx skillfed install ofershap/tailwind-best-practices/tailwind-best-practicesFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What are the tailwind css v4 best practices?
tailwind-best-practices teaches 12 critical rules for v4 success. Key practices include using CSS @import statements instead of @tailwind directives, leveraging the @theme directive for CSS-first configuration, adopting modern opacity syntax (e.g., `text-red-500/50`), implementing container queries for responsive design, and avoiding v3 anti-patterns. The skill emphasizes proper PostCSS configuration and helps migrate from tailwind.config.js to CSS-first approaches while ensuring AI-generated code stays current.
How do I fix tailwind v3 code to work with v4?
tailwind-best-practices guides you through converting v3 code for v4 compatibility. Replace deprecated utilities with their v4 equivalents, update opacity syntax from `opacity-50` modifiers to slash notation (`text-red-500/50`), switch @tailwind directives to @import statements, and adopt the @theme directive for configuration. The skill identifies renamed utilities and explains modern patterns like container queries that v3 didn't support, helping you modernize AI-generated or legacy code efficiently.
What is the tailwind v4 @theme directive and how do I use it?
tailwind-best-practices explains that the @theme directive is central to v4's CSS-first configuration approach. Instead of configuring everything in tailwind.config.js, you define design tokens directly in CSS using @theme blocks. This replaces the traditional JavaScript configuration pattern and gives you more control over your design system within stylesheets. The skill covers syntax, best practices for organizing themes, and how this approach integrates with modern PostCSS setups.
What utilities were renamed or deprecated in tailwind v4?
tailwind-best-practices documents v4's utility changes to help you migrate legacy code. The skill identifies which v3 utilities were renamed, removed, or replaced with modern equivalents. It covers opacity syntax updates, gradient changes, and other shifted utility names. Understanding these deprecations prevents broken styles when upgrading and ensures your codebase—especially AI-generated code that may default to v3 patterns—uses current, supported utilities.
How do I implement container queries in tailwind v4?
tailwind-best-practices covers container queries as a modern v4 feature for responsive design beyond viewport breakpoints. The skill explains the @container directive syntax, how to define container query sizes, and applying responsive utilities within container contexts. Container queries let you style elements based on their parent container's size rather than the viewport, enabling more modular and reusable component designs that v3 didn't natively support.
What anti-patterns should I avoid when using tailwind v4?
tailwind-best-practices identifies common v4 anti-patterns to keep your code clean and maintainable. Avoid mixing old @tailwind directives with new @import syntax, don't rely on v3 configuration patterns when @theme is available, and steer clear of deprecated utilities. The skill warns against improper PostCSS setup, incorrect opacity syntax, and misusing container queries. Learning what NOT to do—especially for AI-generated code that may default to outdated patterns—ensures your stylesheets remain performant and future-proof.
SKILL.md
rendered from the published skill — quoted content, verbatim
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.exports = {
theme: {
extend: {
colors: {
brand: "#3b82f6",
},
spacing: {
18: "4.5rem",
},
},
},
};
Correct:
```css @import "tailwindcss";
@theme {
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
skills/tailwind-best-practices/SKILL.md