Cursor rules file for Tailwind CSS v4.0

tailwind-css-v4.mdc

// Update globs depending on your framework
---
name: tailwind_v4
description: Guide for using Tailwind CSS v4 instead of v3.x
globs: ["**/*.{js,ts,jsx,tsx,mdx,css}"]
tags:
  - tailwind
  - css
---

# Tailwind CSS v4

## Core Changes

- **CSS-first configuration**: Configuration is now done in CSS instead of JavaScript
  - Use `@theme` directive in CSS instead of `tailwind.config.js`
  - Example:
    ```css
    @import "tailwindcss";

    @theme {
      --font-display: "Satoshi", "sans-serif";
      --breakpoint-3xl: 1920px;
      --color-avocado-500: oklch(0.84 0.18 117.33);
      --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
    }
    ```
- Legacy `tailwind.config.js` files can still be imported using the `@config` directive:
  ```css
  @import "tailwindcss";
  @config "../../tailwind.config.js";
  ```
- **CSS import syntax**: Use `@import "tailwindcss"` instead of `@tailwind` directives
  - Old: `@tailwind base; @tailwind components; @tailwind utilities;`
  - New: `@import "tailwindcss";`

- **Package changes**:
  - PostCSS plugin is now `@tailwindcss/postcss` (not `tailwindcss`)
  - CLI is now `@tailwindcss/cli`
  - Vite plugin is `@tailwindcss/vite`
  - No need for `postcss-import` or `autoprefixer` anymore

- **Native CSS cascade layers**: Uses real CSS `@layer` instead of Tailwind's custom implementation

## Theme Configuration

- **CSS theme variables**: All design tokens are available as CSS variables
  - Namespace format: `--category-name` (e.g., `--color-blue-500`, `--font-sans`)
  - Access in CSS: `var(--color-blue-500)`
  - Available namespaces:
    - `--color-*` : Color utilities like `bg-red-500` and `text-sky-300`
    - `--font-*` : Font family utilities like `font-sans`
    - `--text-*` : Font size utilities like `text-xl`
    - `--font-weight-*` : Font weight utilities like `font-bold`
    - `--tracking-*` : Letter spacing utilities like `tracking-wide`
    - `--leading-*` : Line height utilities like `leading-tight`
    - `--breakpoint-*` : Responsive breakpoint variants like `sm:*`
    - `--container-*` : Container query variants like `@sm:*` and size utilities like `max-w-md`
    - `--spacing-*` : Spacing and sizing utilities like `px-4` and `max-h-16`
    - `--radius-*` : Border radius utilities like `rounded-sm`
    - `--shadow-*` : Box shadow utilities like `shadow-md`
    - `--inset-shadow-*` : Inset box shadow utilities like `inset-shadow-xs`
    - `--drop-shadow-*` : Drop shadow filter utilities like `drop-shadow-md`
    - `--blur-*` : Blur filter utilities like `blur-md`
    - `--perspective-*` : Perspective utilities like `perspective-near`
    - `--aspect-*` : Aspect ratio utilities like `aspect-video`
    - `--ease-*` : Transition timing function utilities like `ease-out`
    - `--animate-*` : Animation utilities like `animate-spin`
  

- **Simplified theme configuration**: Many utilities no longer need theme configuration
  - Utilities like `grid-cols-12`, `z-40`, and `opacity-70` work without configuration
  - Data attributes like `data-selected:opacity-100` don't need configuration

- **Dynamic spacing scale**: Derived from a single spacing value
  - Default: `--spacing: 0.25rem`
  - Every multiple of the base value is available (e.g., `mt-21` works automatically)

- **Overriding theme namespaces**:
  - Override entire namespace: `--font-*: initial;`
  - Override entire theme: `--*: initial;`


## New Features

- **Container query support**: Built-in now, no plugin needed
  - `@container` for container context
  - `@sm:`, `@md:`, etc. for container-based breakpoints
  - `@max-md:` for max-width container queries
  - Combine with `@min-md:@max-xl:hidden` for ranges

- **3D transforms**:
  - `transform-3d` enables 3D transforms
  - `rotate-x-*`, `rotate-y-*`, `rotate-z-*` for 3D rotation
  - `scale-z-*` for z-axis scaling
  - `translate-z-*` for z-axis translation
  - `perspective-*` utilities (`perspective-near`, `perspective-distant`, etc.)
  - `perspective-origin-*` utilities
  - `backface-visible` and `backface-hidden`

- **Gradient enhancements**:
  - Linear gradient angles: `bg-linear-45` (renamed from `bg-gradient-*`)
  - Gradient interpolation: `bg-linear-to-r/oklch`, `bg-linear-to-r/srgb`
  - Conic and radial gradients: `bg-conic`, `bg-radial-[at_25%_25%]`

- **Shadow enhancements**:
  - `inset-shadow-*` and `inset-ring-*` utilities
  - Can be composed with regular `shadow-*` and `ring-*`

- **New CSS property utilities**:
  - `field-sizing-content` for auto-resizing textareas
  - `scheme-light`, `scheme-dark` for `color-scheme` property
  - `font-stretch-*` utilities for variable fonts

## New Variants

- **Composable variants**: Chain variants together
  - Example: `group-has-data-potato:opacity-100`

- **New variants**:
  - `starting` variant for `@starting-style` transitions
  - `not-*` variant for `:not()` pseudo-class
  - `inert` variant for `inert` attribute
  - `nth-*` variants (`nth-3:`, `nth-last-5:`, `nth-of-type-4:`, `nth-last-of-type-6:`)
  - `in-*` variant (like `group-*` but without adding `group` class)
  - `open` variant now supports `:popover-open`
  - `**` variant for targeting all descendants

## Custom Extensions

- **Custom utilities**: Use `@utility` directive
  ```css
  @utility tab-4 {
    tab-size: 4;
  }
  ```

- **Custom variants**: Use `@variant` directive
  ```css
  @variant pointer-coarse (@media (pointer: coarse));
  @variant theme-midnight (&:where([data-theme="midnight"] *));
  ```

- **Plugins**: Use `@plugin` directive
  ```css
  @plugin "@tailwindcss/typography";
  ```

## Breaking Changes

- **Removed deprecated utilities**:
  - `bg-opacity-*` → Use `bg-black/50` instead
  - `text-opacity-*` → Use `text-black/50` instead
  - And others: `border-opacity-*`, `divide-opacity-*`, etc.

- **Renamed utilities**:
  - `shadow-sm` → `shadow-xs` (and `shadow` → `shadow-sm`)
  - `drop-shadow-sm` → `drop-shadow-xs` (and `drop-shadow` → `drop-shadow-sm`)
  - `blur-sm` → `blur-xs` (and `blur` → `blur-sm`)
  - `rounded-sm` → `rounded-xs` (and `rounded` → `rounded-sm`)
  - `outline-none` → `outline-hidden` (for the old behavior)

- **Default style changes**:
  - Default border color is now `currentColor` (was `gray-200`)
  - Default `ring` width is now 1px (was 3px)
  - Placeholder text now uses current color at 50% opacity (was `gray-400`)
  - Hover styles only apply on devices that support hover (`@media (hover: hover)`)

- **Syntax changes**:
  - CSS variables in arbitrary values: `bg-(--brand-color)` instead of `bg-[--brand-color]`
  - Stacked variants now apply left-to-right (not right-to-left)
  - Use CSS variables instead of `theme()` function 

## Advanced Configuration

- **Using a prefix**:
  ```css
  @import "tailwindcss" prefix(tw);
  ```
  - Results in classes like `tw:flex`, `tw:bg-red-500`, `tw:hover:bg-red-600`

- **Source detection**:
  - Automatic by default (ignores `.gitignore` files and binary files)
  - Add sources: `@source "../node_modules/@my-company/ui-lib";`
  - Disable automatic detection: `@import "tailwindcss" source(none);`

- **Legacy config files**:
  ```css
  @import "tailwindcss";
  @config "../../tailwind.config.js";
  ```

- **Dark mode configuration**:
  ```css
  @import "tailwindcss";
  @variant dark (&:where(.dark, .dark *));
  ```

- **Container customization**: Extend with `@utility`
  ```css
  @utility container {
    margin-inline: auto;
    padding-inline: 2rem;
  }
  ```

- **Using `@apply` in Vue/Svelte**:
  ```html
  <style>
    @import "../../my-theme.css" theme(reference);
    /* or */
    @import "tailwindcss/theme" theme(reference);
    
    h1 {
      @apply font-bold text-2xl text-red-500;
    }
  </style>
  ```

@danhollick It might help to adjust the wording around "Configuration is now done in CSS instead of JavaScript" and "Use @theme directive in CSS instead of tailwind.config.js" to account for the fact that configurations can still be defined in JS and then imported into the CSS file. I do see the note about "Legacy config files", but it may be clearer to Cursor to call that out earlier.

Instead of this:

• CSS-first configuration: Configuration is now done in CSS instead of JavaScript
  • Use @theme directive in CSS instead of tailwind.config.js

Maybe this:

• CSS-first configuration: Configuration is now done in CSS by default instead of JavaScript/TypeScript. Legacy-style Tailwind configuration done in JS is still supported and can be imported into the CSS configuration.
  • Use the @theme directive in CSS instead of tailwind.config.js for any new features, unless specifically asked to make changes in the JS Tailwind config file (tailwind.config.js or tailwind.config.ts). For editing any existing configuration settings, edit them where they currently exist, whether in the CSS or JS/TS configuration file(s).

---

Just some initial thoughts. This is all looking really good.

It would also be worth testing Cursor with some of these slimmer rules.

For example, we could ensure that Cursor understands the Plugins rule— how to install plugins that way and set up new plugins using the updated syntax, falling back to v3 syntax for any more complicated plugins that can't be built in v4's CSS syntax.

Yeah, all good feedback. Will play around with this a bit more today and make some updates. Probably need to put some test projects together.

Okay, spun up a test project and it's performed pretty well. It got the wrong version of the typography plugin at first but aside from that, everything is working.

Don't forget Windsurf and other editors

hey @danhollick - also published your rules file here: https://ctxs.ai/gh/danhollick/tailwind-css-v4/

If you want to add it to a new project you can do

npx ctxs add "https://ctxs.ai/r/gh/danhollick/tailwind-css-v4.json"

ot download a plaintext version:

curl https://ctxs.ai/gh/danhollick/tailwind-css-v4.txt

@danfascia if you're up for it, feel free to contribute a Windsurf version!