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
Decision gist · record as of 2026-02-20
Tailwind Best Practices teaches Tailwind CSS v4 syntax and configuration to replace outdated v3 patterns. 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.
Use it when
- tailwind-best-practices guides you through converting v3 code for v4 compatibility.
- tailwind-best-practices explains that the @theme directive is central to v4's CSS-first configuration approach.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
ofershap/tailwind-best-practices/tailwind-best-practices · repository language: JavaScript
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
File tree — 1 file
skills/tailwind-best-practices/SKILL.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Learn Tailwind CSS v4 syntax and configuration patterns”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Automates the mechanical parts of upgrading from Tailwind v3 to v4, then handles the judgment calls the codemod can't: reconciling dependencies, porting config to CSS-first `@theme`, auditing v4's changed defaults (border, ring, placeholder, cursor, dialog, hover), and verifying the rendered output stays identical. Works across Next.js, Vite, Tailwind CLI, and plain PostCSS setups.
This skill covers Tailwind v4 browser-runtime styling for HyperFrames compositions scaffolded with `hyperframes init --tailwind`. It explains CSS-first theme tokens, utility classes, dynamic class safety, and when to compile to CSS instead of relying on the runtime. Use it to debug missing styles, migrate from v3 syntax, and ensure deterministic frame rendering.
skill-tailwind teaches Tailwind CSS v4 implementation across any stack using plain HTML and CSS/SCSS. It covers CSS-first configuration, design-token mapping via @theme, v3→v4 migration, and two equal organizational approaches: utility-first classes and BEM with @apply.
Master Tailwind CSS v4's CSS-first configuration model, Rust-powered engine, and modern setup across Vite and PostCSS. This skill covers installation methods, @theme-based theming, custom utilities and variants, plugin loading, and the shift from JavaScript config to pure CSS. Includes v3-to-v4 migration guidance and reference for new v4 utilities.
Master Tailwind CSS with 29 rules spanning responsive layouts, dark mode setup, reusable component patterns, and configuration across v3.4+ and v4. Learn mobile-first design, conditional styling with utilities, and how to migrate projects from v3 to v4 using the new CSS-first approach.
Master Tailwind CSS v4's utility-first approach with CSS-based theme configuration using @theme directives and design tokens. This skill covers class composition, responsive breakpoints, container queries, state variants, and custom utility creation—all without JavaScript config files.
More skills tailwindcss (MIT) · byted-util-vite-react-tailwind (Apache-2.0) · hebrew-tailwind-preset (MIT)