Skip to main content
skill CX Codex

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

tailwind-v4 teaches the agent Tailwind CSS v4 conventions and flags v3-era classes that still compile but don't belong in new code.

Apache-2.0 120 installs ★ 29,724 updated 2026-10-25

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

What tailwind-v4 does

This skill keeps the agent on Tailwind CSS v4 idioms. Setup happens in CSS: tokens go into @theme, custom utilities use @utility, and tailwind.config.ts is off the table for new work.

The core is a rename table. Bare names moved down one step, so shadow-sm became shadow-xs and shadow became shadow-sm. The v3 spelling throws no error. It just renders smaller. The same shift applies to rounded and blur. Other swaps are covered too: outline-none → outline-hidden, bg-gradient-to-r → bg-linear-to-r, !bg-red-500 → bg-red-500!. Arbitrary values give way to named ones, so h-[1.5rem] w-[1.5rem] becomes size-6.

Dynamic names such as bg-${tone}-500 are ruled out because Tailwind has to find complete class strings in the source. The skill was written for the Mastra repo and points to the playground packages' package.json for the pinned tailwindcss version (4.3.3 when written). In your own project, check the version you actually have installed.

What it helps with

  • move settings from tailwind.config.ts into @theme and @import 'tailwindcss'
  • spot v3 classes like shadow-sm and rounded that render smaller in v4
  • replace h-[1.5rem] w-[1.5rem] with size-6
  • fix dynamic class names Tailwind can't detect in source files
  • define a dark variant with @custom-variant instead of a JS plugin

Example prompts for the agent

  • Review this component for Tailwind v3 syntax and rewrite it for v4.
  • Use the tailwind-v4 skill to add a color token in @theme and tell me which utilities it generates.
  • Replace bracketed arbitrary values with named Tailwind v4 utilities wherever one exists.

How to install tailwind-v4

1Skills CLI (Vercel)

npx skills add mastra-ai/mastra --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 do I install tailwind-v4 in Claude Code?

Run npx skills add mastra-ai/mastra --skill tailwind-v4 -a claude-code. The skill file lands at ~/.claude/skills/tailwind-v4/SKILL.md.

What does tailwind-v4 do?

It guides the agent in writing Tailwind CSS v4 and replacing v3 syntax. It kicks in for tasks involving Tailwind classes, @theme blocks, CSS-first configuration, and cleanup of old syntax.

Why does v3 shadow-sm look different in v4?

v4 shifted bare names down one step: shadow-sm is now shadow-xs and shadow is now shadow-sm. The old spelling still compiles but gives a smaller shadow, so the skill rewrites it.

Source text

SKILL.md · Apache-2.0
---
name: tailwind-v4
description: Tailwind CSS v4 usage guide and v3-to-v4 differences. This skill should be used when writing, reviewing, or refactoring any Tailwind CSS code in this repo. Triggers on tasks involving Tailwind classes, @theme blocks, CSS-first configuration, or cleanup of v3-era syntax.
---

# Tailwind CSS v4

How to write idiomatic Tailwind v4 and spot v3-era syntax that still compiles but should not appear in new code.

## Version and sources

Check the pinned version before using recent utilities: the playground packages pin `tailwindcss` in their `package.json` (4.3.3 at the time of writing, including v4.3 utilities like `scrollbar-*`, `zoom-*`, and `tab-*`). When unsure whether a utility, variant, or directive exists in the pinned version, verify against the docs instead of guessing:

- Utility/variant reference: https://tailwindcss.com/docs
- v3 → v4 migration: https://tailwindcss.com/docs/upgrade-guide
- What each minor added: https://tailwindcss.com/blog/tailwindcss-v4 (and `/tailwindcss-v4-1`, `/tailwindcss-v4-3`, ...)

## CSS-first configuration

Tailwind v4 is configured in CSS, not JavaScript.

| Use                                                                        | Never use (v3-era)                    |
| -------------------------------------------------------------------------- | ------------------------------------- |
| `@import 'tailwindcss'`                                                    | `@tailwind base/components/utilities` |
| `@theme { --color-x: ...; }` for tokens that should generate utilities     | `tailwind.config.ts` for new work     |
| `@utility name { ... }` for custom utilities (works with variants)         | `@layer utilities { .name { ... } }`  |
| `@custom-variant dark (&:is(.dark *))`                                     | JS `plugins` / `addVariant`           |
| `@source "path"` / `@source inline("...")` for extra sources / safelisting | `content` array / `safelist` config   |
| `@variant dark { ... }` to apply a Tailwind variant inside custom CSS      | duplicating media queries / selectors |
| `@reference "app.css"` for `@apply` in scoped styles (Vue, CSS Modules)    | duplicating stylesheet imports        |
| `var(--color-x)` in CSS, `getComputedStyle` in JS                          | `theme()` function, `resolveConfig`   |
| `@config "…"` / `@plugin "…"` only for existing JS-config integrations     | adding new JS configs or plugins      |

`@theme` variables are API: each one emits a native CSS variable AND generates utilities (`--color-*` → `bg-*`/`text-*`/`border-*`/..., `--text-*` → `text-*`, `--shadow-*` → `shadow-*`, `--animate-*` → `animate-*`, `--breakpoint-*` → responsive variants). A plain `:root { --x: ...; }` variable generates nothing — use it for runtime-only values. When a token's value references another variable (`--color-x: var(--y)`), declare it in `@theme inline` so the utility resolves the reference at the declaration site. In custom CSS, `--alpha(var(--color-x) / 50%)` and `--spacing(4)` replace v3 `theme()` math.

## v3 → v4 renames

Bare names shifted one step down the scale, so the v3 spelling silently renders smaller or lighter:

| v3                                | v4                                                                |
| --------------------------------- | ----------------------------------------------------------------- |
| `shadow-sm` / `shadow`            | `shadow-xs` / `shadow-sm`                                         |
| `drop-shadow-sm` / `drop-shadow`  | `drop-shadow-xs` / `drop-shadow-sm`                               |
| `blur-sm` / `blur`                | `blur-xs` / `blur-sm`                                             |
| `rounded-sm` / `rounded`          | `rounded-xs` / `rounded-sm`                                       |
| `outline-none`                    | `outline-hidden` (a11y-safe); `outline-none` now truly removes it |
| `ring` (3px)                      | `ring-3`; the default ring is now 1px `currentColor`              |
| `bg-opacity-50`, `text-opacity-*` | opacity modifier: `bg-black/50`, `text-white/50`                  |
| `bg-gradient-to-r`                | `bg-linear-to-r` (plus new `bg-conic-*`, `bg-radial-*`)           |
| `!bg-red-500` (prefix)            | `bg-red-500!` (suffix)                                            |
| `flex-shrink-*` / `flex-grow-*`   | `shrink-*` / `grow-*`                                             |
| `bg-[--var]`                      | `bg-(--var)`; brackets now require `bg-[var(--var)]`              |
| `grid-cols-[a,b]` (commas)        | underscores: `grid-cols-[max-content_auto]`                       |

## Prefer generated utilities over arbitrary values

The spacing scale is infinite — every number compiles via `calc(var(--spacing) * n)` — so most v3-era arbitrary values have a named form:

| Don't                                  | Do                                                                                      |
| -------------------------------------- | --------------------------------------------------------------------------------------- |
| `min-w-[400px]`, `w-[600px]`           | `min-w-100`, `w-150`                                                                    |
| `h-[1.5rem] w-[1.5rem]`                | `size-6`                                                                                |
| `mt-[68px]`                            | `mt-17`                                                                                 |
| `grid-cols-[repeat(15,minmax(0,1fr))]` | `grid-cols-15`                                                                          |
| `h-[100dvh]`, `w-[100dvw]`, `h-[1lh]`  | `h-dvh`, `w-dvw`, `h-lh`                                                                |
| `max-w-[80rem]`                        | `max-w-7xl` (container scale)                                                           |
| `data-[current]:opacity-100`           | `data-current:opacity-100` (values keep brackets: `data-[state=open]:`)                 |
| `bg-[var(--row-bg)]`                   | `bg-(--row-bg)`; type hints when ambiguous: `text-(color:--fg)`, `text-(length:--size)` |

Square brackets remain correct for true one-offs: `max-h-[calc(100dvh-3rem)]`, `grid-cols-[200px_minmax(0,1fr)]`, and arbitrary properties like `[mask-type:luminance]`.

Class strings must stay complete and statically detectable: map props to full strings (`{ success: 'bg-positive1' }[tone]`), never build fragments like `` `bg-${tone}-500` ``.

## Don't hand-write CSS or JS for what a variant covers

Before writing a stylesheet rule, a `style` prop, or an event handler for styling, check for a variant:

| Hand-written                                   | Tailwind                                                                 |
| ---------------------------------------------- | ------------------------------------------------------------------------ |
| `.btn:active { ... }` in CSS                   | `active:bg-surface5`                                                     |
| `:focus-visible` rules                         | `focus-visible:outline-accent1`                                          |
| `[aria-expanded="true"]` selectors             | `aria-expanded:rotate-180` (any `aria-*` boolean or value)               |
| `[data-state="open"]` selectors                | `data-[state=open]:opacity-100`, boolean: `data-current:`                |
| JS hover/focus state to style a sibling/child  | `group`/`group-hover:`, `peer`/`peer-checked:`, `in-focus:`              |
| parent-state selectors / JS "has child" checks | `has-checked:bg-accent1`, `has-[>svg]:pl-8`                              |
| `mask-image` / fade-out gradients in CSS       | `mask-b-from-80%`, `mask-t-from-*`                                       |
| `@media (hover: none)` blocks                  | `pointer-coarse:`/`pointer-fine:`                                        |
| first/last/nth rules in CSS                    | `first:`, `last:`, `odd:`, `nth-3:`, `not-first:`                        |
| styling all children from CSS                  | `*:rounded-full` (children), `**:data-avatar:rounded-full` (descendants) |

## New capabilities — reach for these before hacks or JS

- `field-sizing-content` — auto-growing textarea without a JS resize listener.
- `wrap-anywhere` / `wrap-break-word` — long-word breaking inside flex without the `min-w-0` hack.
- `items-center-safe`, `justify-center-safe` — centering that falls back to `start` on overflow.
- `pointer-coarse:` / `pointer-fine:` — adapt touch targets without user-agent sniffing.
- `user-valid:` / `user-invalid:` — validation styling only after user interaction (unlike `:valid`).
- `starting:` (+ `transition-discrete` for `display`/popover) — enter transitions without JS mount tricks.
- `text-shadow-*`, `mask-t-from-*`/`mask-b-to-*` (fade-out edges), `scheme-dark` (native controls/scrollbars), 3D transforms (`rotate-x-*`, `perspective-*`).

## Behavior changes to remember

- Transforms use individual CSS properties: custom transition lists need `transition-[opacity,scale]`, not `transition-[opacity,transform]`; reset with `scale-none`/`rotate-none`/`translate-none`.
- `hover:` only applies on hover-capable devices (`@media (hover: hover)`) — never gate required touch functionality behind hover.
- Default `border-*`, `divide-*`, ring, and outline colors are `currentColor` — set an explicit color when the color matters.
- Variant stacking applies left to right: v3 `first:*:pt-0` is now `*:first:pt-0`.
- `space-x/y-*` changed selectors (`:not(:last-child)`); prefer flex/grid with `gap-*`.
- Container queries are built in: `@container` on the parent, `@sm:`/`@max-md:` on children.
- Useful v4 variants: `starting:` (enter transitions), `not-*`, `in-*` (like `group-*` without the `group` class), `nth-*`, `*:` (direct children), `**:` (descendants), `inert:`.

## Motion

- Gate decorative animation: `motion-safe:animate-spin motion-reduce:animate-none`.
- Reusable animations are `--animate-*` tokens with their `@keyframes` inside `@theme`; local one-offs use `animate-(--local-animation)` or `animate-[...]`.

© mastra-ai · Apache-2.0 · mastra-ai/mastra

Similar skills

All skills for Frontend and UI →

tailwind-v4 by other authors comes first.

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-v4 boraoztunc 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. CX Codex +1 125installs 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 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-css PaulRBerg Guides coding agents on Tailwind CSS styling, v4 migrations, and class updates while enforcing real build checks and DOM inspection. CX Codex +1 3,100installs tailwind-patterns coco-research The tailwind-patterns skill guides Tailwind CSS v4 setup, responsive layouts, and design tokens. Use it when starting a v4 project or moving one from v3. CX Codex +1 ★ 328repo stars tailwind-wasp-drone Legion Code Inc. A framework specialist for Tailwind CSS v4 configuration, migration, dark mode, and container queries. Use it when a problem concerns Tailwind mechanics rather than project-specific design rules. CX Codex ★ 96repo stars tailwindcss-advanced-design-systems JosiahSiegel tailwindcss-advanced-design-systems is a Claude Code skill for building Tailwind v4 design systems. It activates for @theme setup, token workflows, and brand-specific themes. CX Codex +1 659installs

From the same set6

Project sponsors

Companies that keep this analytics open