Tailwind CSS v4 Skill | Agent Skills

Tailwind CSS v4

Write modern, maintainable styles using Tailwind CSS v4's utility-first approach.

Quick Reference

Responsive: sm:, md:, lg:, xl:, 2xl: (mobile-first) States: hover:, focus:, active:, disabled:, group-hover:, peer-checked: Dark mode: dark: Arbitrary values: top-[117px], bg-[#bada55] CSS variables: bg-(--my-color) (v4 syntax)

Core Concepts

Utility-First: Compose styles from single-purpose classes directly in HTML
Mobile-First: Breakpoint prefixes apply at that width and above
State Variants: Prefix utilities to apply conditionally
Theme Variables: Define in @theme { } as CSS custom properties

v4 Architecture

CSS-First Configuration

Configuration moved from JS to CSS via @theme:

/* app.css */
@import "tailwindcss";

@theme {
  --font-sans: "Inter", system-ui, sans-serif;
  --color-brand-500: oklch(0.637 0.237 25.331);
  --breakpoint-lg: 64rem;
  --spacing: 0.25rem;
}

Theme values generate both utility classes (bg-brand-500) and CSS variables (var(--color-brand-500)).

Simplified Imports

Replace v3 directives with single import:

/* v3 (deprecated) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

Browser Requirements

Requires: Safari 16.4+, Chrome 111+, Firefox 128+

Uses native CSS features: @property, color-mix(), cascade layers. Use v3.4 for older browsers.

Build Tool Packages

CLI: @tailwindcss/cli
PostCSS: @tailwindcss/postcss
Vite (recommended): @tailwindcss/vite

No longer need postcss-import or autoprefixer as separate dependencies.

v3 to v4 Migration

Run npx @tailwindcss/upgrade for automated migration.

Renamed Utilities

| v3 | v4 | |----|----| | shadow-sm | shadow-xs | | shadow | shadow-sm | | blur-sm | blur-xs | | blur | blur-sm | | rounded-sm | rounded-xs | | rounded | rounded-sm | | drop-shadow-sm | drop-shadow-xs | | drop-shadow | drop-shadow-sm | | outline-none | outline-hidden | | ring | ring-3 |

Removed Utilities

Opacity utilities (bg-opacity-50) → slash syntax (bg-black/50)
flex-shrink-* → shrink-*
flex-grow-* → grow-*
overflow-ellipsis → text-ellipsis

Default Value Changes

Border color: currentColor (was gray-200)
Ring color: currentColor (was blue-500)
Ring width: 1px (was 3px, use ring-3 for old default)
Placeholder: 50% opacity text color (was gray-400)
Button cursor: default (was pointer)

Syntax Changes

CSS variable shorthand: bg-(--my-color) instead of bg-[--my-color]
Prefix syntax: tw:bg-red-500 (variant-like)
Variant stacking: Left-to-right order (was right-to-left)
Hover on mobile: Only applies when device supports hover (@media (hover: hover))

Custom Utilities

Use @utility instead of @layer utilities:

@utility btn-primary {
  background-color: var(--color-brand-500);
  padding: 0.5rem 1rem;
  border-radius: 0.25rem;
}

Scoped Styles (Vue/Svelte/CSS Modules)

Use @reference to access theme in isolated style blocks:

<style scoped>
@reference "../app.css";

.custom { @apply bg-brand-500; }
</style>

Or use CSS variables directly: var(--color-brand-500)

Functions & Directives

| Directive | Purpose | |-----------|---------| | @import "tailwindcss" | Import Tailwind | | @theme { } | Define design tokens | | @source "../path" | Include source paths for class detection | | @source not "../path" | Exclude paths | | @utility name { } | Custom utility classes | | @variant name { } | Apply variants in CSS | | @custom-variant | Define new variants | | @apply | Inline utilities (needs @reference in modules) | | @reference "path" | Import for context without output |

Functions:

--alpha(color / opacity) - adjust color opacity
--spacing(value) - generate spacing values
var(--theme-variable) - reference theme variables

Advanced Variants

ARIA: aria-checked:, aria-disabled: Data attributes: data-[size=large]:, data-active: Has selector: has-[:focus]: Child/descendant: *:p-2, **:rounded-full Named groups: group/item, peer-checked/opt1:

Container Queries

<div class="@container">
  <div class="@sm:grid-cols-2 @lg:grid-cols-4">
    <!-- Styles based on container width -->
  </div>
</div>

Named containers: @container/sidebar, @lg/sidebar:

Reference Documentation

Read these files only when you need detailed utility reference:

Layout - display, position, visibility, columns, overflow
Flexbox & Grid - flex, grid, alignment, gap
Spacing & Sizing - padding, margin, width, height
Typography - fonts, text styling, lists
Backgrounds & Borders - bg, border, radius, ring
Effects - shadows, opacity, filters, blend modes
Transforms & Transitions - scale, rotate, animate
Interactivity - cursor, scroll, form controls
SVG & Masks - fill, stroke, mask utilities
Tables - table layout and borders
Colors - palette, opacity, customization

Common Patterns

Centering

<!-- Flex -->
<div class="flex items-center justify-center">

<!-- Grid -->
<div class="grid place-items-center">

<!-- Absolute positioning -->
<div class="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2">

Responsive Grid

<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">

Card with Shadow

<div class="rounded-lg bg-white p-6 shadow-md dark:bg-gray-800">

Button

<button class="rounded-md bg-blue-600 px-4 py-2 text-white hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">

Form Input

<input class="w-full rounded-md border border-gray-300 px-3 py-2 focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500">

Truncate Text

<p class="truncate">Very long text...</p>
<!-- or multi-line -->
<p class="line-clamp-3">...</p>

Agent Skills: Tailwind CSS v4

Install this agent skill to your local

Skill Files