use-tailwind-v4_skill

Overview

This skill provides a focused Tailwind CSS v4 reference and migration guide for developers upgrading from v3 or starting new v4 projects. It highlights syntax changes, renamed utilities, new defaults, and practical migration commands. Use it to resolve v4-specific configuration and utility differences quickly.

How this skill works

The skill inspects common v3 → v4 changes and explains the updated syntax, variable usage, and variant stacking rules. It summarizes renamed and deprecated utilities, new defaults, and the preferred patterns (CSS variables, new arbitrary value syntax, prefix placement). It also points to the automated upgrade tool and upgrade workflow recommendations.

When to use it

• Migrating an existing Tailwind v3 project to v4 and auditing breaking changes.
• Starting a new project built on Tailwind CSS v4 and needing current syntax guidance.
• Troubleshooting utility or configuration behavior that changed between v3 and v4.
• Updating build/config tools (PostCSS, Vite, CLI) to align with v4 requirements.
• Refactoring custom utilities or theme values to the v4 CSS-variable model.

Best practices

• Prefer the v4-exposed CSS variables (e.g., var(--color-red-500)) over theme() calls for runtime theming.
• Run the automated upgrade tool (npx @tailwindcss/upgrade) in a feature branch and review diffs carefully.
• Replace deprecated opacity utilities with slash modifiers (bg-black/50) and rename shifted utilities per the quick reference.
• Use the new parentheses syntax for arbitrary values (bg-(--brand-color)) and place any project prefix at the start of class lists (tw:).
• Re-check variant stacking in places that used right-to-left stacking; update to left-to-right order where needed.

Example use cases

• Convert project-wide shadows and blur utilities after v4 renames (e.g., shadow → shadow-sm, shadow-sm → shadow-xs).
• Migrate theme tokens to CSS variables to enable runtime color and font swapping.
• Fix UI differences after default changes such as ring width/color or border-color fallbacks.
• Adjust complex variant expressions to the new left-to-right stacking order.
• Audit and update custom utilities to the v4 @utility and @config setup when replacing legacy @tailwind/@layer usage.