Skip to content
Skills Library
Programming · Building & coding

tailwind-css

/tailwind-css

Tailwind CSS v4 patterns: CSS-first config, utility classes, component variants, v3 migration. Use when styling with Tailwind, configuring @theme tokens, using tailwind-variants/CVA, migrating v3 to v4, or fixing Tailwind styles and dark mode.

Repository
whetstone ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Tailwind CSS v4 patterns: CSS-first config, utility classes, component variants, v3 migration. Use when styling with Tailwind, configuring @theme tokens, using tailwind-variants/CVA, migrating v3 to v4, or fixing Tailwind styles and dark mode.

Original author description

Tailwind CSS v4 patterns: CSS-first config, utility classes, component variants, v3 migration. Use when styling with Tailwind, configuring @theme tokens, using tailwind-variants/CVA, migrating v3 to v4, or fixing Tailwind styles and dark mode.

How it works

  1. CSS-First Configuration
  2. v3 to v4 Breaking Changes
  3. Coding Rules
  4. Class Merging
  5. Component Variants
  6. Common Errors
  7. Dark Mode (v4 Pattern)
  8. References
Original SKILL.md headings · 120 lines, 683 words
SKILL.md preview
---
name: tailwind-css
description: >-
  Tailwind CSS v4 patterns: CSS-first config, utility classes, component
  variants, v3 migration. Use when styling with Tailwind, configuring
  @theme tokens, using tailwind-variants/CVA, migrating v3 to v4, or
  fixing Tailwind styles and dark mode.
---

# Tailwind CSS v4

## CSS-First Configuration

v4 eliminates `tailwind.config.ts`. All configuration lives in CSS.

| Directive | Purpose |
|-----------|---------|
| `@import "tailwindcss"` | Entry point (replaces `@tailwind base/components/utilities`) |
| `@theme { }` | Define/extend design tokens — auto-generates utility classes |
| `@theme inline { }` | Map CSS variables to Tailwind utilities without generating new vars |
| `@theme static { }` | Define tokens that don't generate utilities |
| `@utility name { }` | Create custom utilities (replaces `@layer components` + `@apply`) |
| `@custom-variant name (selector)` | Define custom variants |

```css
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.72 0.11 178);
  --font-display: "Inter", sans-serif;
  --animate-fade-in: fade-in 0.2s ease-out;
  @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
}

@custom-variant dark (&:where(.dark, .dark *));
```

Tokens defined with `@theme` become utilities automatically: `--color-brand` produces `bg-brand`, `text-brand`, `border-brand`.

## v3 to v4 Breaking Changes

| v3 | v4 | Notes |
|----|-----|-------|
| `tailwind.config.ts` | `@theme` in CSS | Delete config file |
| `@tailwind base/components/utilities` | `@import "tailwindcss"` | Single import |
| `darkMode: "class"` | `@custom-variant dark (...)` | CSS-only |
| `bg-gradient-to-r` | `bg-linear-to-r` | Also: `bg-radial`, `bg-conic` |
| `bg-opacity-60` | `bg-red-500/60` | All `*-opacity-*` removed |
| `rounded-md` (6px) | `rounded` (6px) | Radius scale shifted down |
| `min-h-screen` | `min-h-dvh` | `dvh` handles mobile browser chrome |
| `w-6 h-6` | `size-6` | Size shorthand for equal w/h |
| `space-x-4` | `gap-4` | Gap handles flex/grid wrapping correctly |
| `text-base leading-7` | `text-base/7` | Inline line-height modifier |
| `require("tailwindcss-animate")` | `tw-animate-css` | CSS-only animations |
| `forwardRef` | `ref` as prop | React 19 change (not Tailwind, but co-occurs) |

## Coding Rules

- **`gap` over `space-x`/`space-y`** — gap handles wrapping; space-* breaks on wrap
- **`size-*` over `w-* h-*`** — for equal dimensions
- **`min-h-dvh` over `min-h-screen`** — dvh accounts for mobile browser chrome
- **Opacity modifier** (`bg-black/50`) — `*-opacity-*` utilities are removed in v4
- **Design tokens over arbitrary values** — check `@theme` before using `[#hex]`
- **Never construct classes dynamically** — `text-${color}-500` won't be detected; use complete class names
- **`@utility` over `@apply` with `@layer`** — `@apply` on `@layer` classes fails in v4

## Class Merging

Use `cn()` combining `clsx` + `tailwind-merge` for conditional/dynamic classes. Use plain strings for static `className` attributes.

```typescript
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }
```

```typescript
// Static: plain string
<button className="rounded-lg px-4 py-2 font-medium bg-blue-600">

// Conditional: use cn()
<button className={cn("rounded-lg px-4 py-2", isActive ? "bg-blue-600" : "bg-gray-700")} />
```

## Component Variants

Use `tailwind-variants` (`tv()`) for type-safe variant components. Alternative: `class-variance-authority` (`cva()`).

```typescript
import { tv } from "tailwind-variants";
const button = tv({
  base: "rounded-lg px-4 py-2 font-medium transition-colors",
  variants: {
    color: { primary: "bg-blue-600 text-white", secondary: "bg-gray-200 text-gray-800" },
    size: { sm: "text-sm px-3 py-1", md: "text-base", lg: "text-lg px-6 py-3" },
  },
  defaultVariants: { color: "primary", size: "md" },
});
```

See [tailwind-variants patterns](references/component-patterns.md) for slots, composition, and responsive variants.

## Common Errors

| Symptom | Fix |
|---------|-----|
| `bg-primary` doesn't work | Add `@theme inline { --color-primary: var(--primary); }` |
| Colors all black/white | Double `hsl()` wrapping — use `var(--color)` not `hsl(var(--color))` |
| `@apply` fails on custom class | Use `@utility` instead of `@layer components` |
| Build fails after migration | Delete `tailwind.config.ts` |
| Animations broken | Replace `tailwindcss-animate` with `tw-animate-css` |
| `.dark { @theme { } }` fails | v4 does not support nested `@theme` — use `:root`/`.dark` CSS vars mapped via `@theme inline` |

## Dark Mode (v4 Pattern)

```css
:root { --background: hsl(0 0% 100%); --foreground: hsl(222 84% 4.9%); }
.dark { --background: hsl(222 84% 4.9%); --foreground: hsl(210 40% 98%); }
@theme inline { --color-background: var(--background); --color-foreground: var(--foreground); }
```

Semantic classes (`bg-background`, `text-foreground`) auto-switch — no `dark:` variants needed for themed colors.

## References

- [Component patterns](references/component-patterns.md) — tailwind-variants slots, CVA, compound components
- [Layout patterns](references/layout-patterns.md) — grid areas, container queries, z-index management, fluid typography
Files in this package (4)
  • SKILL.md 5 KB
  • manifest.json 1 KB
  • references/component-patterns.md 3 KB
  • references/layout-patterns.md 4 KB

Versions

RepositoryScoreLicence
This page · iliaal/whetstone100MIT
peterbamuhigire/chwezi-dev-engine100MIT
sablier-labs/plugin-marketplace100MIT
paulocoutinhox/skills95MIT
PaulRBerg/agent-skills90MIT

Database snapshot: 13.11.2026 · package version fc77a3f7ea9d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100styling-with-tailwind
    Provides utility-first CSS styling patterns using Tailwind CSS 3.x. Use when styling components with utility classes, configuring tailwind.config.js, implementing responsive designs, or creating dark mode themes.
  • 100tailwind-patterns
    Provides Tailwind CSS v4 patterns for CSS-first configuration, container queries, design tokens, and utility-first component architecture. Use when working with Tailwind CSS files or when the user mentions Tailwind, Tailwind v4, or utility-first CSS.
  • 100tailwind-best-practices
    Tailwind CSS patterns and conventions. Use when writing responsive designs, implementing dark mode, creating reusable component styles, configuring Tailwind, or migrating from v3 to v4. Triggers on tasks involving Tailwind classes, responsive design, dark mode, CSS styling, or…
  • 100tailwind-css-v4
    Reference for Tailwind CSS v4 syntax and the differences from v3.x. Use when configuring Tailwind (CSS-first @theme config, @import "tailwindcss"), using new v4 features (container queries, 3D transforms, gradients, composable variants, @utility/@custom-variant/@plugin), or…
  • 100tailwindcss
    Tailwind CSS v4 utility-first styling patterns including responsive design, dark mode, and custom configuration. Use when styling with Tailwind, adding utility classes, configuring Tailwind, setting up dark mode, or customizing the theme.
  • 100tailwind-patterns
    Tailwind CSS v4 patterns, component styling, dark mode, responsive design, and design system integration. Use when styling components or reviewing CSS.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.