Skip to main content
skill CX Codex

tailwind-v4 · boraoztunc — Claude Code skill: what it does, how to install

tailwind-v4 — a skill for Claude Code and other AI platforms that automates Tailwind CSS v4 migration, configuration, and debugging. Runs during styling tasks or framework upgrades.

Apache-2.0 125 installs ★ 484 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add boraoztunc/skills --skill tailwind-v4 -a claude-code
Open on GitHub

What tailwind-v4 does

This skill guides projects through the Tailwind CSS v4 transition by setting up CSS-first configurations via @theme blocks and fixing utility generation issues. It identifies the installed framework version, suggests migration paths from v3, and validates dynamic class name usage.

Avoid creating tailwind-v4 projects with manual tailwind.config.js files, as the framework now relies on CSS-driven configuration. The skill detects file sources automatically, advises on removing redundant autoprefixer or postcss-import dependencies, and ensures design tokens are properly integrated into the CSS layer.

What it helps with

  • detect the Tailwind CSS version
  • migrate project config from v3 to v4
  • configure design tokens in @theme
  • debug non-generating utility classes
  • verify @source file paths

Example prompts for the agent

  • Check the Tailwind CSS version for this project
  • Help migrate this project to Tailwind v4
  • Add a new design token to the @theme block

How to install tailwind-v4

1Skills CLI (Vercel)

npx skills add boraoztunc/skills --skill tailwind-v4 -a claude-code

2Manually: put the files in place

~/.claude/skills/tailwind-v4/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tailwind-v4/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tailwind-v4

How to install tailwind-v4 in Claude Code?

Run npx skills add boraoztunc/skills --skill tailwind-v4 -a claude-code. The configuration file is located at ~/.claude/skills/tailwind-v4/SKILL.md.

What does tailwind-v4 do?

It streamlines Tailwind v4 adoption by providing automated migration steps, CSS-based configuration support, and troubleshooting for utility class generation.

What is required for tailwind-v4?

You need Node.js installed and tailwindcss declared in your package.json to allow the skill to detect and analyze your project version.

Source text

SKILL.md · Apache-2.0
---
name: tailwind-v4
description: Tailwind CSS v4 conventions for real projects — CSS-first configuration with @theme, automatic content detection, the v3-to-v4 migration diffs, and dynamic class-name safety. Use when writing Tailwind utilities, setting up or upgrading Tailwind, defining design tokens as Tailwind theme values, debugging classes that do not generate, or when unsure whether a project is on v3 or v4.
---

# Tailwind CSS v4

## Detect the version first

This is the highest-value step. v3 and v4 configure completely differently, and
guidance for one is actively wrong for the other.

```bash
# Check the installed major version
npm ls tailwindcss --depth=0 2>/dev/null || grep '"tailwindcss"' package.json
```

| Signal | Version |
|---|---|
| `@import "tailwindcss";` in CSS | v4 |
| `@tailwind base; @tailwind components; @tailwind utilities;` | v3 |
| `@theme { }` block in CSS | v4 |
| `tailwind.config.js` with a `content: [...]` array | v3 (or a v4 project using the compat layer) |
| `@config "./tailwind.config.js";` | v4 loading a legacy config |
| `@tailwindcss/postcss` or `@tailwindcss/vite` dependency | v4 |
| `autoprefixer` + `postcss-import` required in postcss config | v3 |

**Never write a `tailwind.config.js` for a v4 project by default.** v4 reads
configuration from CSS. A hand-added config file is silently ignored unless
explicitly loaded with `@config`.

## v4 setup

```css
/* app.css — the single entry point */
@import "tailwindcss";
```

That one line replaces the three `@tailwind` directives, and it also handles
`postcss-import` and `autoprefixer` internally — remove both from the PostCSS config.

Vite:
```js
// vite.config.js
import tailwindcss from "@tailwindcss/vite";
export default { plugins: [tailwindcss()] };
```

PostCSS:
```js
// postcss.config.mjs
export default { plugins: { "@tailwindcss/postcss": {} } };
```

## Configuration is CSS-first

Design tokens go in `@theme`. Every entry generates the matching utilities *and*
exposes a real CSS custom property.

```css
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 250);
  --color-brand-muted: oklch(0.72 0.08 250);
  --font-display: "IBM Plex Sans", sans-serif;
  --radius-card: 14px;
  --spacing-gutter: 2.75rem;
  --ease-out-soft: cubic-bezier(0.22, 0.61, 0.36, 1);
}
```

`--color-brand` yields `bg-brand`, `text-brand`, `border-brand`, … and is readable
anywhere as `var(--color-brand)`. That dual nature is the main v4 win: tokens are no
longer trapped inside a JS config.

Namespaces map to utility families — `--color-*`, `--font-*`, `--text-*`,
`--spacing-*`, `--radius-*`, `--shadow-*`, `--ease-*`, `--animate-*`, `--breakpoint-*`.

Override a whole namespace, or everything:
```css
@theme {
  --color-*: initial;          /* drop the default palette */
  --color-ink: #18181b;
}
```

**No `content` array.** v4 detects source files automatically, honoring
`.gitignore` and skipping binaries. Point it at extra sources only when needed:

```css
@source "../packages/ui/src";           /* add a path outside the project root */
@source not "../legacy";                 /* exclude */
@source inline("bg-red-500 bg-red-600"); /* the v4 replacement for safelist */
```

## Migrating v3 → v4

Run the codemod first, then review the diff:
```bash
npx @tailwindcss/upgrade
```

The renames that break silently:

| v3 | v4 |
|---|---|
| `shadow-sm` | `shadow-xs` |
| `shadow` | `shadow-sm` |
| `rounded-sm` | `rounded-xs` |
| `rounded` | `rounded-sm` |
| `blur-sm` | `blur-xs` |
| `outline-none` | `outline-hidden` |
| `bg-opacity-50` | `bg-black/50` (slash opacity only) |
| `flex-shrink-0` | `shrink-0` |

The bare `shadow` → `shadow-sm` and `rounded` → `rounded-sm` shifts are the dangerous
pair: the old class names still exist but now mean *one step smaller*, so a v3
codebase silently loses a step of elevation and radius everywhere rather than erroring.

Other behavior changes to expect:
- Default border color is now `currentColor`, not `gray-200`. `border` alone inherits
  text color — set the color explicitly.
- Default ring is `1px currentColor`, was `3px` blue. `ring` → `ring-3` to keep v3 sizing.
- Space-between uses a different selector; sibling-margin edge cases can shift.
- Hover only applies where the device actually supports hover.
- Variant stacking now reads left-to-right.

## Dynamic class names

The rule survives from v3, because the scanner still reads source text statically:

```jsx
// BROKEN — never generated
<div className={`text-${color}-500`} />

// CORRECT — complete class names, statically visible
const TONE = {
  danger: "text-red-500",
  success: "text-emerald-500",
};
<div className={TONE[tone]} />
```

v4 does support dynamic *values* on many utilities without config —
`grid-cols-15`, `w-17`, `mt-23` work arbitrarily. What cannot be assembled is the
class *name* string. For genuinely runtime-only values, use an inline style or a CSS
variable, not string concatenation:

```jsx
<div className="w-(--w)" style={{ "--w": `${pct}%` }} />
```

## Practical patterns

**Dark mode.** v4 defaults to `prefers-color-scheme`. For class-based toggling:
```css
@custom-variant dark (&:where(.dark, .dark *));
```

**Component extraction order.** Prefer a real component over `@apply`. When you do
need shared CSS, v4 wants `@utility`:
```css
@utility card {
  border-radius: var(--radius-card);
  background: var(--color-surface);
}
```
Heavy `@apply` use forfeits the point of utilities and inflates CSS — reach for it
last, not first.

**Arbitrary values** stay available for one-offs: `top-[117px]`,
`bg-[oklch(0.7_0.1_200)]`, `grid-cols-[1fr_auto]`.

## Common failures

- Classes not generating → a dynamically-built class name, or a source file outside
  auto-detection (add `@source`).
- A `tailwind.config.js` having no effect → v4 project without `@config`.
- Build errors after upgrade → `postcss-import`/`autoprefixer` still in the PostCSS
  chain; v4 includes both.
- Borders/rings looking wrong post-migration → the `currentColor` and `ring-1`
  default changes above.
- Elevation subtly flattened post-migration → the `shadow`/`rounded` rename shift.

## Related skills

- `visual-style-presets` — pick a direction, then encode its tokens in `@theme`
- `beautiful-shadows` — exact layered shadows as arbitrary utilities

© boraoztunc · Apache-2.0 · boraoztunc/skills

Similar skills

All skills for Frontend and UI →

tailwind-v4 by other authors comes first.

tailwind-v4 mastra-ai tailwind-v4 teaches the agent Tailwind CSS v4 conventions and flags v3-era classes that still compile but don't belong in new code. CX Codex +1 120installs tailwind-v4 existential-birds tailwind-v4 — a skill that tells your coding agent how to set up Tailwind CSS v4: theme in CSS, design tokens, OKLCH colors and dark mode. CX Codex +1 827installs tailwind-4-docs Lombiq The tailwind-4-docs skill syncs a local snapshot of the Tailwind CSS v4 docs so your agent answers utility, config and v3-to-v4 migration questions from official text. CX Codex +1 19,300installs tailwind-refactor pproenca tailwind-refactor — a skill for refactoring Tailwind CSS classes: migrating from v3 to v4, replacing deprecated utilities and cleaning up code without changing the visual output. CX Codex +1 321installs hyva-compile-tailwind-css hyva-themes hyva-compile-tailwind-css builds Tailwind CSS stylesheets for Hyvä themes in Magento 2. It triggers production builds or watch mode when updated utility classes fail to render on the storefront. CX Codex +1 1,300installs tailwind-css-patterns giuseppe-trisciuoglio tailwind-css-patterns is a Claude Code skill with Tailwind CSS patterns for responsive interfaces and components. It activates for styling React, Vue, or Svelte components, building design systems, and adding dark mode. CX Codex +1 18,100installs tailwind-v4-shadcn secondsky tailwind-v4-shadcn sets up Tailwind CSS v4 with shadcn/ui, Vite, and React. Solves broken CSS variables, theme switching errors, and v4 migration pitfalls. CX Codex +1 8,300installs tailwind-theme-builder jezweb tailwind-theme-builder is a Claude Code skill that configures Tailwind v4 and shadcn/ui themes with dark mode. It activates for theme setup, v3-to-v4 migrations, and colour or CSS configuration errors. CX Codex +1 3,300installs

From the same set22

The whole set →
three Keeps a Three.js scene in HyperFrames tied to composition time: the adapter fires hf-seek and the scene draws the frame requested. CX Codex +1 209installs typegpu Skill for building GPU compositions with TypeGPU and WebGPU in HyperFrames: WGSL fragment shaders, compute pipelines, liquid glass effects, and particles on canvas. CX Codex +1 207installs linear-local-first-architecture linear-local-first-architecture tells the agent how to build a web app that answers instantly: workspace in IndexedDB, edits applied locally, sync queued in the background. CX Codex +1 201installs conductor-rewrite-performance conductor-rewrite-performance optimizes React performance in local-first Tauri desktop apps. Stops cascading re-renders on route changes and cleans up sluggish streaming lists. CX Codex +1 186installs minimal-zine-poster minimal-zine-poster turns a theme, phrase, object, or photo into a prompt for a sparse zine-style poster, then generates the image. Use it for essay or newsletter cover art. CX Codex +1 126installs visual-style-presets The visual-style-presets Claude Code skill selects and applies a visual direction to a website, landing page, dashboard, or app shell. It activates when a request names a look or asks for a coherent design direction. CX Codex +1 123installs better-typography The better-typography skill automates web typography verification and configuration. It assists in font selection, spacing setup, and heading hierarchy management during coding or code reviews. CX Codex +1 109installs better-ui better-ui — a skill for Claude Code and Codex that enforces UI polish and frontend engineering rules. Activates during visual tuning, transitions, borders, and hover states. CX Codex +1 106installs

Project sponsors

Companies that keep this analytics open