tlq5l/tailwindcss-v4-skill

Overview

This skill teaches Tailwind CSS v4 patterns and migration steps from v3, focusing on the new CSS-first configuration and directives. It guides you through @theme, @utility, @custom-variant, @source, and @reference usage, plus CLI validation for agent workflows. Use it when developing or migrating projects to Tailwind v4 to ensure correct setup and modern patterns.

How this skill works

The skill inspects project CSS and PostCSS/Vite configs to validate v4-specific entry points and directives. It checks for deprecated v3 patterns (like @tailwind base/components/utilities and tailwind.config.js theme.extend) and recommends v4 replacements such as @import "tailwindcss" and @theme tokens. It also verifies safelisting sources, custom utilities/variants, and PostCSS/Vite plugin configuration.

When to use it

• Starting a new Tailwind v4 project or conversion from v3
• Auditing code for deprecated v3 patterns before builds
• Creating design tokens and CSS-first theme variables
• Adding custom utilities or functional utilities in v4
• Configuring safelists and external content sources for class detection

Best practices

• Use @import "tailwindcss" as the v4 entry point; avoid @tailwind base/components/utilities.
• Define design tokens in @theme blocks using CSS custom properties rather than tailwind.config.js.
• Create custom utilities with @utility; functional utilities must end with -* to accept values.
• Use @custom-variant to declare variants and @reference when importing values for @apply without emitting CSS.
• Configure PostCSS with '@tailwindcss/postcss' and Vite with '@tailwindcss/vite' plugins to match v4 tooling.
• Safelist dynamic classes via @source inline() or external glob patterns to ensure class detection.

Example use cases

• Migrate an app from Tailwind v3 by replacing tailwind.config.js theme tokens with @theme CSS variables.
• Add a project-specific utility like @utility content-auto to centralize behavior across components.
• Implement a custom state variant (hocus) using @custom-variant to unify hover/focus styles.
• Safelist classes used in markdown-driven content via @source "../content/**/*.md" to prevent runtime missing styles.
• Switch gradient utilities to the new bg-linear-to-* syntax for color-space-aware gradients.