tailwindcss-v4_skill

Overview

This skill documents Tailwind CSS v4.1 core features, the new @theme system, directives, and a focused migration guide from v3 to v4. It concentrates on the CSS-first configuration, updated utility/variant syntax, and the new naming and variable behaviors you need to adopt. The content highlights installation, browser support, and key API functions for day-to-day development.

How this skill works

The skill inspects and explains v4’s CSS-first approach where design tokens live in @theme CSS variables that generate utilities automatically. It describes directive changes (@import "tailwindcss" replacing @tailwind layers), new directives like @utility, @variant, and @custom-variant, and how arbitrary values and important modifiers are now parsed. It also covers migration steps, renamed utilities, removed deprecated utilities, and the upgrade CLI tool requirements.

When to use it

• When migrating a project from Tailwind v3 to v4 and you need a clear change list and examples.
• When adopting CSS-first theming with centralized design tokens expressed as @theme variables.
• When creating custom utilities, custom variants, or new conditional styles using @utility and @variant.
• When configuring content detection and custom style layers in a v4 workflow.
• When you need quick reference for renamed utilities, removed features, and browser support.

Best practices

• Define global design tokens in a single @theme block to generate consistent utilities.
• Replace v3 @tailwind layers with @import "tailwindcss" and move custom utilities to @utility blocks.
• Prefer new variable syntax bg-(--brand-color) for arbitrary values and move important modifiers to the end (e.g., bg-red-500!).
• Use @custom-variant to create theme-aware selectors that scope styles to data-theme attributes.
• Run the upgrade tool (Node.js 20+) and manually verify renamed utilities and removed features in your UI.

Example use cases

• Convert an existing v3 project: run the upgrade tool, replace @tailwind directives, and map renamed utilities.
• Create a design system: store colors, spacing, radii, and shadows in @theme to auto-generate utility classes.
• Add a custom utility: define tab-size via @utility tab-4 and use it directly as class="tab-4".
• Implement dark mode variants: register a @custom-variant that targets [data-theme="dark"] and use dark:bg-* classes.
• Compose component styles: use @apply with generated utilities to keep component rules concise.