# oxlint-tailwindcss

> oxlint-tailwindcss is the oxlint plugin for Tailwind CSS v4: lint rules that check your classes against your own design system, with autofixes.

---

<!-- https://oxlint-tailwindcss.pages.dev/index.md -->

# Tailwind CSS linting for oxlint

## What is oxlint-tailwindcss?

oxlint-tailwindcss is a plugin for [oxlint](https://oxc.rs/docs/guide/usage/linter), the linter of
the Oxc project, that lints Tailwind CSS v4 class names. It loads your project's design system from
the CSS entry point you configure — its `@theme` tokens, `@utility` and `@custom-variant`
definitions and plugins — and checks every class string in JSX, TSX, JavaScript and TypeScript (and
the `<script>` of Vue, Svelte and Astro files) against it, with 27 rules, most with an autofix.

## What it catches

- **Classes Tailwind can't generate**: a typo like `itms-center`, with the class you meant —
  [`no-unknown-classes`](/rules/no-unknown-classes).
- **Classes that override each other**: `p-4 p-6`, or `line-clamp-1 flex`, where `flex` replaces the
  clamp's `display` — [`no-conflicting-classes`](/rules/no-conflicting-classes).
- **Classes built at runtime**, which get no CSS: `` `bg-${color}-500` `` —
  [`no-dynamic-classes`](/rules/no-dynamic-classes).
- **Classes Tailwind v4 renamed**: `flex-shrink-0` → `shrink-0` —
  [`no-deprecated-classes`](/rules/no-deprecated-classes).
- **A dark-mode color with no light-mode base** —
  [`no-dark-without-light`](/rules/no-dark-without-light).
- **Values your theme already names**: `p-[10px]` → `p-2.5`, `bg-(--primary)` → `bg-primary` —
  [`prefer-scale-token`](/rules/prefer-scale-token),
  [`prefer-theme-tokens`](/rules/prefer-theme-tokens).
- **Order and form**: class and variant order, canonical and shorthand forms, whitespace —
  [`enforce-sort-order`](/rules/enforce-sort-order),
  [`consistent-variant-order`](/rules/consistent-variant-order),
  [`enforce-canonical`](/rules/enforce-canonical), and [the rest](/rules/).

## Quick start

```bash
pnpm add -D oxlint oxlint-tailwindcss
```

```jsonc
// .oxlintrc.json
{
  "jsPlugins": ["oxlint-tailwindcss"],
  "settings": { "tailwindcss": { "entryPoint": "src/styles.css" } },
  "rules": {
    "tailwindcss/no-unknown-classes": "error",
    "tailwindcss/no-conflicting-classes": "error"
  }
}
```

```bash
npx oxlint
```

`entryPoint` is the CSS file where you `@import "tailwindcss"`. [Setup](/setup) has the recommended
rules and the editor, monorepo and formatter setup.

---

<!-- https://oxlint-tailwindcss.pages.dev/setup.md -->

# Setup

Everything you need to get `oxlint-tailwindcss` running on a project in one page. Pick the section
that matches your repo shape — single package or monorepo — and copy the snippet.

## 1. Install

```bash
pnpm add -D oxlint oxlint-tailwindcss
```

Requirements:

- **oxlint 1.43.0** or newer.
- **Tailwind CSS v4.1.15** or newer. The plugin loads your design system via `@tailwindcss/node` and
  only understands v4 syntax (`@import "tailwindcss";`, `@theme { ... }`). It resolves _your_
  project's Tailwind per entry point; releases before 4.1.15 are not supported (they predate a
  design-system API the plugin needs) and are reported with a clear diagnostic. Insiders builds
  (`tailwindcss@insiders`) run with a one-time "untested engine" notice.
- **Node.js `^20.19.0 || >=22.12.0`** for the linter process — the same range oxlint itself
  requires.

::: warning Avoid oxlint 1.77.0 with the editor extension

oxlint **1.77.0** shipped a regression that panics the **language server** on any diagnostic from a
JS plugin — `disable_fix.rs:52`, `range end index N out of range for slice of length 0`, then
SIGABRT and a restart loop. It's an oxlint bug, not a plugin one, and the CLI is unaffected (CI and
`oxlint --fix` are fine). It's **fixed in oxlint 1.78.0**
([oxc#25280](https://github.com/oxc-project/oxc/pull/25280)) — upgrade to `oxlint@1.78.0` or newer
(or stay on `1.76.0`) if you use the editor extension.

:::

## 2. Minimal config

Create or extend your `.oxlintrc.json` at the project root:

```jsonc
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["oxlint-tailwindcss"],
  "rules": {
    "tailwindcss/no-unknown-classes": "error",
    "tailwindcss/no-conflicting-classes": "error",
    "tailwindcss/no-duplicate-classes": "warn",
    "tailwindcss/enforce-sort-order": "warn",
    "tailwindcss/enforce-canonical": "warn"
  },
  "settings": {
    "tailwindcss": {
      "entryPoint": "src/styles.css"
    }
  }
}
```

`settings.tailwindcss.entryPoint` is **required** in v1.0.0 and must point at the CSS file where you
`@import "tailwindcss";` and (optionally) declare your `@theme { ... }` tokens. The plugin reads
that file to build the design system every rule queries against.

That's it. Run `oxlint` and the plugin checks every file oxlint lints — `.js`, `.jsx`, `.ts`, `.tsx`
(and `.mjs`, `.cjs`, `.mts`, `.cts`) — against the design system loaded from `src/styles.css`. In
`.vue`, `.svelte` and `.astro` files oxlint only hands plugins the `<script>` blocks (and Astro's
frontmatter), so classes written in the template or markup are **not** checked yet. See
[Vue, Svelte & Astro](/frameworks).

### With `oxlint.config.ts`, or in a shared config

oxlint also reads its config from an `oxlint.config.ts` — experimental in oxlint, which imports it
through Node's own type stripping, so it needs oxlint 1.45.0 or later on Node 22.18.0 or later.
There, `oxlint-tailwindcss/config` gives you the plugin and the recommended rules at their
severities, for `extends`:

```ts
// oxlint.config.ts
import { defineConfig } from 'oxlint'
import tailwindcss from 'oxlint-tailwindcss/config'

export default defineConfig({
  extends: [tailwindcss()],
  settings: {
    tailwindcss: { entryPoint: 'src/styles.css' },
  },
})
```

Your own `rules` override the recommended ones, and `tailwindcss({ recommended: false })` registers
the plugin alone. The `settings` stay in your config, as above: oxlint never reads them from an
extended config, so `tailwindcss()` takes none. A relative `entryPoint` resolves against the
directory of the config that declares it.

This is also how a **shared config** — a preset published as a package — brings the plugin along. It
can't rely on `"oxlint-tailwindcss"` in `jsPlugins`: oxlint resolves that name from where it runs,
not from the preset that lists it, so whether the preset's own dependency is found depends on the
package manager and on how oxlint is started (under pnpm, often it isn't), and oxlint rejects a
relative path in an extended config. `tailwindcss()` registers the plugin by its absolute path, so
the preset puts it in its own `extends`, and the project needs no dependency of its own — only its
`settings.tailwindcss`. Publish the preset as JavaScript: Node doesn't strip types in
`node_modules`.

## 3. Recommended starter rule set

If you want a "blessed" set that catches problems without being noisy, turn these on. It is
generated from each rule's `recommended` severity, so it always matches the rules:

<!-- generated:recommended-config -->

```jsonc
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["oxlint-tailwindcss"],
  "settings": {
    "tailwindcss": {
      "entryPoint": "src/styles.css"
    }
  },
  "rules": {
    // Correctness
    "tailwindcss/no-conflicting-classes": "error",
    "tailwindcss/no-contradicting-variants": "warn",
    "tailwindcss/no-dark-without-light": "warn",
    "tailwindcss/no-duplicate-classes": "warn",
    "tailwindcss/no-dynamic-classes": "error",
    "tailwindcss/no-unknown-classes": "error",
    // Modernization
    "tailwindcss/enforce-canonical": "warn",
    "tailwindcss/enforce-negative-arbitrary-values": "warn",
    "tailwindcss/no-deprecated-classes": "error",
    "tailwindcss/no-unnecessary-arbitrary-value": "warn",
    // Consistency
    "tailwindcss/consistent-variant-order": "warn",
    "tailwindcss/enforce-consistent-important-position": "warn",
    "tailwindcss/enforce-consistent-variable-syntax": "warn",
    "tailwindcss/enforce-shorthand": "warn",
    "tailwindcss/enforce-sort-order": "warn",
    "tailwindcss/no-unnecessary-whitespace": "warn",
    // Design-system guardrails
    "tailwindcss/no-hardcoded-colors": "warn"
  }
}
```

<!-- /generated:recommended-config -->

Layer in extra rules as you go:

- `enforce-logical` / `enforce-physical` if you have a direction preference.
- `no-arbitrary-value`, `no-restricted-classes` and `max-class-count` if you want stricter
  design-system guardrails.
- `prefer-theme-tokens` and `prefer-scale-token` to push named utilities over `var()` references and
  hardcoded values.

The full catalog is at [Rules](/rules/). Each rule page documents the exact behavior, the available
options, and ✓ / ✗ examples.

## 4. Validate the setup

The fastest sanity check is to misspell a class on purpose:

```tsx
<div className="flx items-cetner" />
```

oxlint should flag both classes with `no-unknown-classes`, and the `flex` / `items-center`
suggestions should appear in your editor.

If you see a `designSystemUnavailable` diagnostic instead, the `entryPoint` setting is missing or
points at a file the plugin can't read. The diagnostic message tells you exactly which path it tried
— copy that into your `entryPoint` setting. A relative `entryPoint` is resolved against the
directory of the nearest enclosing oxlint config (`.oxlintrc.json`, `.oxlintrc.jsonc`,
`oxlint.config.ts` or `oxlint.config.mts` — the config that declares it), falling back to the
directory where you run `oxlint`.

## 5. Monorepo setups

If you have one `.oxlintrc.json` at the root and multiple Tailwind CSS files across packages, use
the mapping shape — first matching glob wins:

```jsonc
{
  "settings": {
    "tailwindcss": {
      "entryPoint": [
        { "files": "packages/ui/**",    "use": "packages/ui/src/styles.css" },
        { "files": "packages/admin/**", "use": "packages/admin/src/admin.css" },
        { "files": "packages/web/**",   "use": "packages/web/src/app.css" },
        { "files": "**",                "use": "src/global.css" }
      ]
    }
  }
}
```

Add a `"**"` fallback at the end so any file outside the explicit globs resolves to a default.

If instead each package has its own `.oxlintrc.json` extending a shared base, just put
`entryPoint: "./src/styles.css"` (string) in each package's settings. See the
[monorepo guide](/monorepo) for both patterns side by side.

## 6. Coexisting with oxfmt or prettier-plugin-tailwindcss

`enforce-sort-order` sorts classes the way oxfmt and prettier-plugin-tailwindcss do **once they read
the same CSS and know your class helpers**. By default the formatters use the theme bundled in
`tailwindcss` — which doesn't know your `@theme` tokens — and sort only class attributes. Point them
at your CSS and list your helpers:

```jsonc
// .oxfmtrc.json
{ "sortTailwindcss": { "stylesheet": "./src/styles.css", "functions": ["cn", "clsx", "cva", "tv"] } }

// .prettierrc
{
  "plugins": ["prettier-plugin-tailwindcss"],
  "tailwindStylesheet": "./src/styles.css",
  "tailwindFunctions": ["cn", "clsx", "cva", "tv"]
}
```

Read the full [interop guide](/interop) for who formats what, the `--fix` note, and plugins like
`@tailwindcss/typography`.

## 7. Going further

- **Adjust extractors**: by default the plugin scans `className` / `class`, ~14 callees (`cn`,
  `clsx`, `cva`, `twMerge`, …), `tw` tagged templates, and variables matching `/^classNames?$/`,
  `/^classes$/`, `/^styles?$/`. Add `attributes`, `attributePatterns` (regex for `*ClassName`-style
  props), `callees`, `calleeExtractors` (route a custom wrapper through the `tv`/`cva`/`classed`
  extractor), `tags`, `variablePatterns`, or remove defaults via `exclude`. See
  [settings reference](/settings).
- **Tune timeouts**: `settings.tailwindcss.timeout` (ms, default 60000) bounds how long the plugin
  waits for the worker thread that precomputes the design system. Slow CI may need this raised.
- **Debug logging**: `settings.tailwindcss.debug: true` (or `DEBUG=oxlint-tailwindcss`) logs which
  CSS entry point resolved per linted file.
- **Which Tailwind gets used**: the plugin loads _your_ project's Tailwind engine, resolved per
  entry point, so the linter and your build agree. If the resolved engine is a major newer than the
  plugin (a future Tailwind 5) or drifts a major from your build, it fails loud;
  `settings.tailwindcss.allowUntestedEngine: true` opts into running anyway. See
  [settings reference](/settings#allowuntestedengine).
- **Upgrading from v0.x?** Read the [migration guide](/migration/v0-to-v1) — `entryPoint` is now
  required and the legacy `string[]` shape was removed.

---

<!-- https://oxlint-tailwindcss.pages.dev/frameworks.md -->

# Vue, Svelte & Astro

**Short answer:** oxlint-tailwindcss checks every class string oxlint lets a plugin see. In `.vue`,
`.svelte` and `.astro` files that is the **script**, not the template: oxlint passes JS plugins the
`<script>` blocks (and Astro's frontmatter) and never the markup. Classes written in a template are
not checked yet.

This is how oxlint 1.87 behaves, and the plugin's end-to-end suite locks it against the real binary.

## What gets linted

| File                                                  | Checked                                                                                   | Not checked                                         |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `.js` `.jsx` `.ts` `.tsx` `.mjs` `.cjs` `.mts` `.cts` | The whole file                                                                            | —                                                   |
| `.vue`                                                | Every `<script>` and `<script setup>` block, including JSX in `lang="tsx"` / `lang="jsx"` | `<template>` (`class="…"`, `:class="…"`), `<style>` |
| `.svelte`                                             | `<script module>` and the instance `<script>`                                             | Markup (`class="…"`, `class:…`), `<style>`          |
| `.astro`                                              | The frontmatter (`---`) and `<script>` tags                                               | Markup, `<style>`                                   |
| `.html`, `.md`, `.mdx`                                | Not linted by oxlint                                                                      | —                                                   |

## What it means in practice

- **Class lists defined in script are covered.** That includes `cva()` / `tv()` variants in
  `<script setup>` or in a `.ts` file next to the component (shadcn-vue, for instance, keeps
  `buttonVariants` in `index.ts`), `cn()` / `clsx()` calls, and variables named like `classes` or
  `className`. See [settings](/settings) for the full detection list.
- **Classes written directly in the template are not.** `class="flex flex"` in a `<template>` is
  left alone. If you want a class list checked, build it in the script with a helper the plugin
  reads — `const cardClasses = cn('…')`, or a `cva()` / `tv()` definition — and bind it
  (`:class="cardClasses"`). A plain string only counts when the variable is named like `classes`,
  `className(s)` or `style(s)`, or matches your own
  [`variablePatterns`](/settings#extractor-configuration).
- **Fixes land where they should.** Diagnostics and autofixes map back to the right lines of the
  file, templates are never touched, and non-ASCII text before a class string doesn't shift a fix.
- **Keep `<script …>` on one line.** oxlint currently skips a Vue `<script` opening tag that spans
  several lines ([oxc#26289](https://github.com/oxc-project/oxc/pull/26289)).

## Sorting template classes

[oxfmt](https://oxc.rs/docs/guide/usage/formatter)'s `sortTailwindcss` sorts class attributes in
**`.vue` templates** (not `.svelte` or `.astro`), using the same Tailwind order as
[`enforce-sort-order`](/rules/enforce-sort-order). If you format with oxfmt, Vue template classes
are kept sorted even though the linter can't see them. See [Interop](/interop) for the setup.

## When will templates be linted?

It depends on oxlint exposing SFC templates to JS plugins. That work is tracked upstream in the
Language Plugins RFC ([oxc#21936](https://github.com/oxc-project/oxc/discussions/21936)), its
umbrella issue ([oxc#23207](https://github.com/oxc-project/oxc/issues/23207)) and
[oxc#20501](https://github.com/oxc-project/oxc/pull/20501) (reporting at real file positions). None
of it has shipped as of oxlint 1.87.

The plugin's test suite includes canaries that fail the day oxlint changes what plugins can see.
Template support follows once oxlint makes it possible.

---

<!-- https://oxlint-tailwindcss.pages.dev/settings.md -->

# `settings.tailwindcss`

Every setting lives under `settings.tailwindcss` in your `.oxlintrc.json`. Settings are read for
each linted file, so a nested `.oxlintrc.json` can give one package its own values — see
[different options and settings per package](/monorepo#different-options-and-settings-per-package).

oxlint doesn't check `settings`, so the plugin does: a key it doesn't know, a value of the wrong
type, a pattern that isn't a regular expression or an unknown `calleeExtractors` kind is reported
once per file, on its first line, by the first rule that lints it (`invalidSetting`):

```text
Check settings.tailwindcss: "rootfontsize" is not a setting (did you mean "rootFontSize"?)
```

A bad `entryPoint` is reported by the rules that need the design system, with a hint on how to fix
it (`designSystemUnavailable`).

## `entryPoint` (required)

Path to the CSS file that `@import "tailwindcss";` and (optionally) your `@theme { ... }`
customizations. The plugin reads this file to build the design system every rule queries.

Required by the DS-dependent rules, which fail loudly without it. A second group is **DS-optional**:
those work with nothing configured and get more accurate when it is there — `enforce-shorthand`
verifies each merge against the emitted CSS, `no-dark-without-light` groups the base by declared
property, `no-deprecated-classes` derives its rename list, and the directional rules confirm the
class they suggest exists. See the [defaults reference](./rules/#defaults-reference) for which rule
is in which group.

Two shapes are supported:

```jsonc
// Single project
{ "settings": { "tailwindcss": { "entryPoint": "src/styles.css" } } }

// Monorepo: explicit glob → CSS mapping, first match wins
{
  "settings": {
    "tailwindcss": {
      "entryPoint": [
        { "files": "packages/ui/**",    "use": "packages/ui/src/styles.css" },
        { "files": "packages/admin/**", "use": "packages/admin/src/admin.css" },
        { "files": "**",                "use": "src/global.css" }
      ]
    }
  }
}
```

A **relative string** `entryPoint` (the single-project shape) is resolved against the directory of
the nearest enclosing oxlint config (`.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts` or
`oxlint.config.mts`), falling back to the oxlint working directory — so a per-package config
resolves to the same CSS whether oxlint runs from the package (CLI) or the workspace root (editor).
See [Monorepos](/monorepo).

Globs (the mapping shape) are evaluated against the linted file's path relative to the oxlint
working directory. Supported syntax: `*` (any chars except `/`), `**` (any depth), literal segments.
Order matters — the first matching entry wins. Add a `"**"` fallback to handle files outside the
explicit globs.

`files` also accepts an array of globs (`string[]`): the entry matches if the linted file matches
any of them.

**v0.x → v1.0.0**: the legacy `string[]` shape was removed. Passing it in v1 throws
`DeprecatedEntryPointShapeError` with the migration snippet inline. See the
[migration guide](/migration/v0-to-v1).

## `rootFontSize`

`number`, default `16`.

The font size in pixels used to convert between px and rem. `prefer-scale-token` uses it to compare
a px value against the rem-based scale (`p-[10px]` → `p-2.5`), and `enforce-canonical` passes it to
Tailwind's canonicalizer. Change this only if your project sets a non-16 root size on `<html>`.

## `timeout`

`number` in milliseconds, default `60000`.

How long the plugin waits for the worker thread that precomputes the design system. Slow CI machines
may need this raised; you should not need it lowered.

This governs the **precompute loader** only. The sort / canonicalize / declaration worker services
that the design-system-dependent rules use while linting have their own **30 s per-request** timeout
that this setting does not move. If a slow-but-functional machine or CI runner reports
`worker request timed out after 30000ms` on valid class lists, raise it with the
`OXLINT_TAILWINDCSS_WORKER_REQUEST_TIMEOUT` environment variable (milliseconds) so the request
completes instead of failing:

```bash
OXLINT_TAILWINDCSS_WORKER_REQUEST_TIMEOUT=60000 oxlint
```

A timeout no longer costs O(files): after a few consecutive timeouts for one entry point the rest of
the run fails fast, and the state self-heals once the machine recovers.

## `debug`

`boolean`, default `false`. Also activated by the `DEBUG=oxlint-tailwindcss` environment variable.

When on, the plugin logs to stderr:

- Which CSS entry point resolved for each linted file (`src/Button.tsx → src/styles.css`).
- Each design-system load, once per entry point per run, with where it came from and how long each
  step took: `Loaded design system from "…" — cache hit; hash 1 ms, read 16 ms, build 18 ms`, or for
  a fresh precompute `precomputed in 3850 ms (load 20 ms, validate 402 ms, canonical 1416 ms, …)`.
- The Tailwind engine check for each entry point (`engine E=4.3.3 B=4.3.3 → ok`).

Use this when you're debugging which CSS the plugin actually loaded.

## `allowUntestedEngine`

`boolean`, default `false`.

The plugin loads **your** Tailwind engine — the `@tailwindcss/node` resolved from the project around
each entry point, per entry point (so a monorepo's packages can be on different Tailwind versions).
It grades that engine against the version it was built for:

- **Older than Tailwind v4.1.15** → fatal (`designSystemUnavailable`). Not affected by this flag
  (older releases lack a design-system API the plugin needs).
- **A major newer than the plugin** (e.g. a future Tailwind 5), or a **major-version drift** between
  the engine and the `tailwindcss` your build uses → fatal by default.
- **A newer minor**, a Tailwind **insiders build** (`0.0.0-insiders.*`), or a **minor-level drift**
  from your build → a one-time stderr warning; the plugin lints best-effort.
- **In range and aligned** → silent.

Set this to `true` to downgrade the future-major / major-drift **fatals** to a warning and lint
anyway (results may be inaccurate against an untested engine). An engine older than v4.1.15 stays
fatal regardless.

```jsonc
{
  "settings": {
    "tailwindcss": {
      "allowUntestedEngine": true
    }
  }
}
```

## Extractor configuration

The plugin scans these locations by default:

| Kind              | Defaults                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| Attributes        | `className`, `class` (JSX)                                                                                         |
| Callees           | `cn`, `clsx`, `cva`, `twMerge`, `tv`, `cx`, `classnames`, `ctl`, `twJoin`, `cc`, `clb`, `cnb`, `objstr`, `classed` |
| Tags              | `` tw`...` `` (tagged template literals)                                                                           |
| Variable patterns | `/^classNames?$/`, `/^classes$/`, `/^styles?$/`                                                                    |

`attributes`, `callees`, and `tags` match **exact names**. Two axes match by **regex**, and their
scope differs — mind which one you want:

- **`attributePatterns`** matches **JSX attribute names**. Use it for `*ClassName` conventions so
  you don't list every prop — e.g. `["ClassName$"]` catches `contentContainerClassName` and
  `tintColorClassName` on React Native / Uniwind components. Additive to the exact `attributes`
  list; empty by default, so exact matching stays the default.
- **`variablePatterns`** matches **variable declaration names only** (`const fooClassName = "..."`),
  **not** JSX attributes. Its default `/^classNames?$/` overlaps in spelling with the `className`
  attribute, but the two are unrelated — a `variablePatterns` entry never affects JSX props.

In an object, the keys are read as classes (`cn({ "bg-red-500": isError })`), except a style
declaration: a custom property, a CSS property name, a `-webkit-` / `-moz-` / `-ms-` property, or a
key whose value is a string, number or template literal. So the `style` objects of React, Solid,
Vue, Qwik, Lit or Angular that `/^styles?$/` reaches report nothing.

Add more without losing the defaults:

```jsonc
{
  "settings": {
    "tailwindcss": {
      "attributes": ["xyzClassName"],
      "attributePatterns": ["ClassName$"],
      "callees": ["myHelper"],
      "tags": ["css"],
      "variablePatterns": ["^tw[A-Z]"]
    }
  }
}
```

Or remove from the defaults with `exclude`, which takes `attributes`, `callees`, `tags` and
`variablePatterns`:

```jsonc
{
  "settings": {
    "tailwindcss": {
      "exclude": {
        "callees": ["objstr"],
        "variablePatterns": ["^styles?$"]
      }
    }
  }
}
```

`variablePatterns` exclusions match against `RegExp.source` literally.

### Structured wrappers (`calleeExtractors`)

`cva`, `tv`, and `classed` are extracted with dedicated logic that understands each helper's config
shape (`base`, `slots`, `variants`, `compoundVariants`, …). If a shared package re-exports one of
them under your own name, map that name to the structure it follows so it gets the same deep
extraction — without renaming imports at every call site:

```jsonc
{
  "settings": {
    "tailwindcss": {
      "calleeExtractors": {
        "defineStyles": "tv",     // reads base / slots / variants / compoundVariants
        "makeVariants": "cva",    // reads base / variants / compoundVariants
        "styledEl": "classed",    // skips the first (element-type) argument
        "cnx": "flat"             // plain cn/clsx/twMerge-style extraction
      }
    }
  }
}
```

Mapped names are registered as callees automatically — no need to list them in `callees` as well. A
value must be one of `tv`, `cva`, `classed`, or `flat`; any other value is ignored rather than
throwing. The reserved names `tv`, `cva`, and `classed` always use their built-in extractor and
can't be remapped.

## Environment variables

For what doesn't belong in a shared config file — CI tuning and one-off debugging:

| Variable                                    | Effect                                                                                                                                                                                                                      |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DEBUG=oxlint-tailwindcss`                  | Same as [`debug: true`](#debug), for every file.                                                                                                                                                                            |
| `OXLINT_TAILWINDCSS_CACHE_DIR`              | Where the design-system disk cache lives. Default: a per-user directory in the system temp dir (`oxlint-tailwindcss-<uid>`, the user name on Windows). Set it to keep the cache between CI jobs — see [Running in CI](/ci). |
| `OXLINT_TAILWINDCSS_WORKER_REQUEST_TIMEOUT` | Per-request timeout of the worker services, in milliseconds (default `30000`). See [`timeout`](#timeout). A value that isn't a positive number is ignored.                                                                  |

A cache directory the plugin creates is private to its owner (`0700`). If you point the variable at
an existing directory, make sure no one else can write to it: what the cache holds feeds the
autofixes.

## Cheat sheet

```jsonc
{
  "settings": {
    "tailwindcss": {
      "entryPoint": "src/styles.css",    // required
      "rootFontSize": 16,                  // optional
      "timeout": 60000,                    // optional
      "debug": false,                      // optional
      "allowUntestedEngine": false,        // optional
      "attributes": [],                    // optional
      "attributePatterns": [],             // optional
      "callees": [],                       // optional
      "calleeExtractors": {},              // optional (name → tv|cva|classed|flat)
      "tags": [],                          // optional
      "variablePatterns": [],              // optional
      "exclude": {                         // optional
        "attributes": [],
        "callees": [],
        "tags": [],
        "variablePatterns": []
      }
    }
  }
}
```

---

<!-- https://oxlint-tailwindcss.pages.dev/monorepo.md -->

# Monorepos

`oxlint-tailwindcss` v1 supports two patterns for monorepos, both fully deterministic — no glob
heuristics, no auto-detect surprises. Pick whichever maps better to how your team already structures
its config.

## Pattern A — single root config with a glob mapping

One `.oxlintrc.json` at the root. `entryPoint` is an array of `{ files, use }` objects, evaluated in
declaration order; the first glob matching the linted file wins.

```jsonc
// /my-monorepo/.oxlintrc.json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["oxlint-tailwindcss"],
  "rules": {
    "tailwindcss/no-unknown-classes": "error"
  },
  "settings": {
    "tailwindcss": {
      "entryPoint": [
        { "files": "packages/ui/**",     "use": "packages/ui/src/styles.css" },
        { "files": "packages/admin/**",  "use": "packages/admin/src/admin.css" },
        { "files": "packages/web/**",    "use": "packages/web/src/app.css" },
        { "files": "**",                  "use": "src/global.css" }
      ]
    }
  }
}
```

When to use this:

- All your packages share the same rule set.
- You want one source of truth for what lints how.
- You're already using oxlint's `overrides` for rule-by-rule customization at the root.

A `"**"` fallback entry at the end is recommended — without it, any file outside the explicit globs
will fail with `MissingEntryPointError`.

## Pattern B — one `.oxlintrc.json` per package

Each package owns its own config and CSS entry. oxlint resolves the closest config to the file being
linted, so per-package overrides just work.

```
my-monorepo/
├── .oxlintrc.json                       # rules base (optional entryPoint for top-level files)
├── packages/
│   ├── ui/
│   │   ├── .oxlintrc.json               # extends ../../.oxlintrc.json, sets entryPoint
│   │   ├── src/styles.css
│   │   └── src/Button.tsx
│   ├── admin/
│   │   ├── .oxlintrc.json
│   │   ├── src/admin.css
│   │   └── src/Page.tsx
│   └── shared-utils/                    # no Tailwind, no config needed
│       └── index.ts
```

```jsonc
// packages/ui/.oxlintrc.json
{
  "extends": ["../../.oxlintrc.json"],
  "settings": {
    "tailwindcss": { "entryPoint": "./src/styles.css" }
  }
}
```

A **relative** string `entryPoint` is resolved against the directory of the nearest enclosing
`.oxlintrc.json` — i.e. the config that declares it — not the current working directory. So
`./src/styles.css` points at `packages/ui/src/styles.css` whether oxlint runs from the package
(`cd packages/ui && oxlint`, as on the CLI) or from the workspace root (as editor extensions like
the VS Code oxlint plugin do). If the file isn't found there, resolution falls back to the CWD. This
is what makes per-package configs behave the same in the terminal and the editor (issue #39).

::: tip Explicit `-c` configs

Anchoring uses the nearest oxlint config (`.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts` or
`oxlint.config.mts`) because that's the config oxlint applies under its default nested-config
discovery. If you instead pass `oxlint -c <config>` (or disable nested configs), oxlint uses only
that one file — and the plugin can't see which config that was (oxlint exposes the file path and CWD
to plugins, never the config path). The nearest-config + CWD fallback still resolves correctly for
the usual layout, but if you mix an explicit `-c` config with an unrelated nested `.oxlintrc.json`
below the linted file, prefer an **absolute** `entryPoint` (or the mapping shape) to remove all
ambiguity.

:::

When to use this:

- Packages diverge significantly in rules, plugins, or globals.
- Different teams own different packages and want self-contained config.
- You have packages without Tailwind that should not run the plugin at all.

## Different options and settings per package

Rule options and `settings.tailwindcss` are resolved for each file, so packages can differ in both —
within one run, in the terminal and in the editor. Where you can set them:

| Set in                                    | Rule options | `settings.tailwindcss` |
| ----------------------------------------- | ------------ | ---------------------- |
| An `overrides` block of the root config   | ✓            | ✗                      |
| A nested config (Pattern B)               | ✓            | ✓                      |
| The root `entryPoint` mapping (Pattern A) | —            | `entryPoint` only      |

oxlint rejects `settings` inside `overrides` (``unknown field `settings` ``), so a package that
needs its own `attributes`, `callees`, `rootFontSize` or `debug` gets a nested config. A nested
config stands alone unless it lists the root in `extends` — then it inherits `jsPlugins` and `rules`
(never `settings`, which every config sets for itself) and only adds what differs, as in the Pattern
B example. A config shared as a package brings the plugin through `oxlint-tailwindcss/config`
instead: see
[`oxlint.config.ts` and shared configs](/setup#with-oxlint-config-ts-or-in-a-shared-config).

::: warning Vite+ and editors

- **Vite+** (`vp lint`) doesn't discover nested `.oxlintrc.json` files (oxlint 1.85+,
  [oxc#26763](https://github.com/oxc-project/oxc/pull/26763)): only the root config applies. Use
  Pattern A's `entryPoint` mapping for per-package CSS; other settings can't vary by package there.
- **Editors** (the oxc VS Code extension and other LSP clients) discover nested configs when
  `oxc.configPath` is unset. Since oxlint 1.84 an empty `""` counts as unset too
  ([oxc#26762](https://github.com/oxc-project/oxc/pull/26762)); pointing it at one file disables
  nested configs, like `oxlint -c`.

:::

## What does **not** work in v1

- `entryPoint: ["a.css", "b.css"]` — the legacy `string[]` shape was removed because its "closest
  entry by path prefix" heuristic was non-deterministic in edge cases. v1 throws
  `DeprecatedEntryPointShapeError` and prints the migration snippet directly in the diagnostic.

## Files that should not need the plugin

If a file lives in a package without any Tailwind — e.g. a pure TypeScript utility — the plugin's
DS-dependent rules will simply not fire on it, because they only run when the extractors find class
strings. There is no need to disable the plugin per-file.

## Verifying which CSS resolved per file

Set `settings.tailwindcss.debug` (or the `DEBUG=oxlint-tailwindcss` env var) and oxlint will print
one line per file showing which CSS the plugin loaded for it. Useful when a glob is matching the
wrong mapping.

## Per-package Tailwind engines

For each resolved CSS entry point the plugin loads the Tailwind engine (`@tailwindcss/node`) from
that package's own `node_modules`, so packages pinned to different Tailwind versions are each linted
with the engine they actually build with. The version guard runs per package too — an engine older
than v4.1.15, a future major, or a major-version drift from that package's build fails loud (see
[`allowUntestedEngine`](/settings#allowuntestedengine)). You don't need to do anything for this; it
follows the same per-file entry-point resolution above.

---

<!-- https://oxlint-tailwindcss.pages.dev/ci.md -->

# Running in CI

Nothing is CI-specific: install, point [`entryPoint`](/settings#entrypoint-required) at your CSS,
run `oxlint`. The rest of this page makes it faster and easier to read.

## Annotations on the pull request

`oxlint -f github` prints each diagnostic as a GitHub Actions annotation, so it shows up inline in
the pull request's diff:

```text
::error file=src/Button.tsx,line=1,endLine=1,col=39,endColumn=62,title=tailwindcss(no-unknown-classes)::src/Button.tsx:1:39: "itms-center" is not a valid Tailwind class. Did you mean "items-center"?
```

## Cache the design system between jobs

The first time the plugin sees a CSS entry point it precomputes that design system — every class
Tailwind can generate for it, with its CSS — and writes the result to a disk cache. Later runs read
it back and skip that step. The precompute is most of a cold run: on shadcn/ui's `apps/v4`, with
every rule on, a cold run takes several times as long as a warm one.

A GitHub-hosted runner starts every job on a fresh machine, so every job pays the cold start. Put
the cache in a directory you persist between jobs, with the `OXLINT_TAILWINDCSS_CACHE_DIR`
environment variable:

```yaml
- uses: actions/cache@v6
  with:
    path: ~/.cache/oxlint-tailwindcss
    key: oxlint-tailwindcss-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'src/**/*.css') }}

- run: OXLINT_TAILWINDCSS_CACHE_DIR="$HOME/.cache/oxlint-tailwindcss" npx oxlint -f github
```

- The plugin creates the directory if it doesn't exist. The variable takes the path as is — `~` is
  not expanded, which is why the step uses `$HOME`.
- A run that finds its design system in the cache doesn't compute it again. The directory also keeps
  the canonical form of each arbitrary-value class the rules meet (`p-[2px]`), so it grows a little
  as your code does; that part only saves time. Files the plugin hasn't used for 30 days are removed
  whenever it computes a new design system, so a cache restored run after run doesn't pile up old
  ones.
- The key above changes with the lockfile (which pins the Tailwind version and any Tailwind plugins)
  and with your CSS. Adjust the CSS glob to where your stylesheets live.

## See which rules cost what

`--debug timings` prints a per-rule table after the lint. JS plugin rules, like these, are in it
from oxlint 1.84:

```bash
npx oxlint -f default --debug timings
```

```text
Rule timings:
Rule                               Time (ms)  Relative  Calls  Source
--------------------------------  ----------  --------  -----  ---------
tailwindcss/no-unknown-classes        87.440     99.5%      2  js-plugin
tailwindcss/no-duplicate-classes       0.467      0.5%      2  js-plugin
```

It prints nothing with `-f github`: run it as a separate step, or locally, with the default format.

## What to trust

The cache holds data the rules act on — including what the autofixes rewrite classes to. Treat it
like any other build artifact:

- Restore only caches your own workflows saved.
- Don't point `OXLINT_TAILWINDCSS_CACHE_DIR` at a directory other users or jobs can write to. A
  directory the plugin creates is private to its owner (`0700`).

The plugin checks the shape of every cache file it reads and recomputes one that is corrupt or
truncated, so a bad cache costs a cold start, not a crash.

See also the [environment variables](/settings#environment-variables) reference.

---

<!-- https://oxlint-tailwindcss.pages.dev/interop.md -->

# Interop with oxfmt and prettier-plugin-tailwindcss

`enforce-sort-order` produces the official Tailwind class order — the same order
[prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) produces,
and [oxfmt](https://oxc.rs/docs/guide/usage/formatter)'s `sortTailwindcss`, which implements the
same algorithm. The formatter and this plugin agree on every class string the formatter touches,
**once both read the same CSS and the formatter knows your class helpers**. Two settings do it.

## 1. The same stylesheet

By default the formatter reads the theme bundled in the installed `tailwindcss` package — **not your
project's CSS** — so it doesn't know your `@theme` tokens and orders them differently: `bg-brand`
and `text-brand` are sorted as unknown classes. Point it at the file this plugin reads.

## 2. Your class helpers

The formatter sorts class attributes (`className`, `class`) and **only the functions you list**.
`cn("p-4 flex")` stays unsorted unless `cn` is in `functions`, while this plugin sorts every class
string it extracts. List the helpers you use:

```jsonc
// .oxfmtrc.json
{
  "sortTailwindcss": {
    "stylesheet": "./src/styles.css",
    "functions": ["cn", "clsx", "cva", "tv"]
  }
}
```

The same two settings for prettier:

```jsonc
// .prettierrc
{
  "plugins": ["prettier-plugin-tailwindcss"],
  "tailwindStylesheet": "./src/styles.css",
  "tailwindFunctions": ["cn", "clsx", "cva", "tv"]
}
```

## Who does what

With both settings, running the formatter leaves `enforce-sort-order` nothing to report in class
attributes and listed helpers, and running `oxlint --fix` leaves the formatter nothing to change.
Class strings the formatter never formats — a `const classes = "…"` variable, for instance — stay
the linter's.

The formatter also drops duplicate classes and collapses whitespace in the strings it formats, so it
overlaps with `no-duplicate-classes` and `no-unnecessary-whitespace` there; the lint rules keep
covering everything else.

That includes the line breaks of a class string that `enforce-consistent-line-wrapping` wrapped into
a block, whether a class attribute (`wrapStrings: "jsx"`) or a template in a helper the formatter
sorts (`cn(…)` with `wrapStrings: "all"`): the formatter puts it back on one line, and each undoes
the other. Set `preserveWhitespace: true` in `sortTailwindcss` to keep the block.

::: tip `--fix` more than once

When several rules fix the same class string (a duplicate, extra whitespace and the order), oxlint
applies one of those fixes per run: it has no multi-pass fixing. Run `oxlint --fix` again, or let
the formatter do the sorting, de-duplication and whitespace in one go.

:::

## Why this isn't fixed upstream

The Tailwind team
[intentionally requires explicit config](https://github.com/tailwindlabs/prettier-plugin-tailwindcss/issues/389)
for the stylesheet in v4. There's no convention like `tailwind.config.js` to auto-detect in v4 — CSS
files can live anywhere and be named anything. The plugin defaults to the bundled `theme.css` rather
than guess.

`oxlint-tailwindcss` v1 follows the same philosophy (explicit `entryPoint`), so the only step needed
for consistency is to tell each tool the same path.

## What about `tailwindcss-animate` and `@tailwindcss/typography`?

If you use plugins that register classes (e.g. `prose-*`, `animate-in`), they're imported via your
`@import` in CSS — both tools will pick them up automatically as long as they're reading the same
stylesheet.

## Multiple stylesheets per project

If different parts of your monorepo use different CSS files, see the [monorepo guide](/monorepo).
The same patterns apply to oxfmt: its
[`overrides`](https://oxc.rs/docs/guide/usage/formatter#configuration) can point different file
globs at different stylesheets.

```jsonc
// .oxfmtrc.json
{
  "sortTailwindcss": { "functions": ["cn"] },
  "overrides": [
    {
      "files": ["packages/admin/**"],
      "options": {
        "sortTailwindcss": { "stylesheet": "./packages/admin/src/admin.css", "functions": ["cn"] }
      }
    }
  ]
}
```

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/index.md -->

# Rules

The 27 rules in `oxlint-tailwindcss`, grouped by what they enforce. Click into any rule for examples
and option reference.

## Correctness

These rules catch problems that would generate invalid or unexpected CSS.

- [no-unknown-classes](./no-unknown-classes) — disallow class names the design system doesn't know
  about.
- [no-conflicting-classes](./no-conflicting-classes) — flag classes that fight over the same CSS
  property.
- [no-contradicting-variants](./no-contradicting-variants) — `flex hover:flex` is redundant (only on
  literal class lists on native elements, not `cn`/`twMerge` fragments).
- [no-dark-without-light](./no-dark-without-light) — a `dark:` colour should have a light-mode pair
  (only on literal class lists on native elements, not `cn`/`twMerge` fragments).
- [no-duplicate-classes](./no-duplicate-classes) — same class twice is dead weight.
- [no-dynamic-classes](./no-dynamic-classes) — `bg-${color}-500` is built at runtime, so Tailwind
  generates no CSS for it.

## Modernization

- [no-deprecated-classes](./no-deprecated-classes) — `flex-grow` → `grow`, etc.
- [enforce-canonical](./enforce-canonical) — `-m-0` → `m-0`, `start-2` → `inset-s-2`, etc.
- [no-unnecessary-arbitrary-value](./no-unnecessary-arbitrary-value) — `w-[100%]` → `w-full` when
  the named class emits identical CSS.
- [prefer-theme-tokens](./prefer-theme-tokens) — `border-(--border)` → `border-border` when a named
  utility maps to the same theme variable.
- [prefer-scale-token](./prefer-scale-token) — `p-[10px]` → `p-2.5`, `w-[200px]` → `w-50` when the
  token is the same VALUE (report-only; the CSS differs textually).
- [enforce-negative-arbitrary-values](./enforce-negative-arbitrary-values) — `-top-[5px]` →
  `top-[-5px]`.

## Consistency

- [enforce-sort-order](./enforce-sort-order) — sort classes in the official Tailwind order.
- [consistent-variant-order](./consistent-variant-order) — `dark:hover:` vs `hover:dark:`.
- [enforce-consistent-important-position](./enforce-consistent-important-position) — prefix `!flex`
  vs suffix `flex!`.
- [enforce-consistent-line-wrapping](./enforce-consistent-line-wrapping) — one class per line vs all
  on one.
- [enforce-consistent-variable-syntax](./enforce-consistent-variable-syntax) — `bg-(--x)` vs
  `bg-[var(--x)]`.
- [enforce-logical](./enforce-logical) — `ml-4` → `ms-4` for RTL support.
- [enforce-physical](./enforce-physical) — `ms-4` → `ml-4` for LTR-only projects.
- [enforce-shorthand](./enforce-shorthand) — `mt-2 mr-2 mb-2 ml-2` → `m-2`.
- [no-unnecessary-whitespace](./no-unnecessary-whitespace) — collapse runs of spaces.

## Design-system guardrails

- [no-arbitrary-value](./no-arbitrary-value) — disallow `w-[3.14rem]` and friends.
- [no-borrowed-component-styles](./no-borrowed-component-styles) — a plain element that rebuilds one
  of your components from its classes (experimental).
- [no-default-palette](./no-default-palette) — disallow `bg-red-500` when your theme has colors of
  its own.
- [no-hardcoded-colors](./no-hardcoded-colors) — disallow `bg-[#fff]`, prefer theme tokens.
- [no-restricted-classes](./no-restricted-classes) — ban specific classes or regex patterns.
- [max-class-count](./max-class-count) — cap how many classes a single class string can stack.

## Per-rule pages

Each rule's page covers:

- **What it does**, in one paragraph.
- **Options** with their default values and a description per option.
- **Correct / incorrect examples**.
- **When to disable it** — the use cases where this rule is the wrong fit.
- For DS-dependent rules: whether `entryPoint` is required (always yes in v1) and what happens when
  it's missing.

## Defaults reference

A quick lookup table for what each rule does when you turn it on without overriding
`meta.defaultOptions`.

### DS-dependent rules

These rules require `settings.tailwindcss.entryPoint` to be set; they emit a fatal
`designSystemUnavailable` diagnostic when it isn't.

| Rule                             | Default options                         |
| -------------------------------- | --------------------------------------- |
| `enforce-canonical`              | `{ reportNonEquivalent: false }`        |
| `enforce-sort-order`             | `{ mode: 'default' }`                   |
| `no-borrowed-component-styles`   | `{ components: [] }`                    |
| `no-conflicting-classes`         | `{ reportRedundant: true }`             |
| `no-default-palette`             | `{ allow: [] }`                         |
| `no-unknown-classes`             | `{ allowlist: [], ignorePrefixes: [] }` |
| `no-unnecessary-arbitrary-value` | `{}`                                    |
| `prefer-scale-token`             | `{}`                                    |
| `prefer-theme-tokens`            | `{}`                                    |

### DS-optional rules

These work with nothing configured — their fallback is deterministic on its own — and get more
accurate when an `entryPoint` is available. None of them can emit `designSystemUnavailable`. Each
also accepts a rule-level `entryPoint` that overrides the shared setting.

| Rule                               | Default options                                              | What the design system adds                                                                                                                                               |
| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consistent-variant-order`         | `{}` (same order with or without a DS)                       | What the project's own variants are: pseudo-element, barrier or breakpoint                                                                                                |
| `enforce-consistent-line-wrapping` | `{ printWidth: 80, group: 'newLine', wrapStrings: 'never' }` | The project prefix, so `wrapLines: 'all'` grouping treats it as transparent                                                                                               |
| `enforce-logical`                  | `{ allowlist: [], direction: 'both', sizing: false }`        | Confirms the suggested class exists and that your Tailwind has the 4.2 utilities (block axis, sizes, `inset-s`); without a DS the block axis and sizes are only suggested |
| `enforce-physical`                 | `{ allowlist: [], direction: 'both', sizing: false }`        | Confirms the suggested class exists                                                                                                                                       |
| `enforce-shorthand`                | `{}`                                                         | Verifies each merge against the emitted CSS                                                                                                                               |
| `no-arbitrary-value`               | `{ allow: [], allowVariables: 'none' }`                      | With `allowVariables: 'runtime'`, which CSS variables your stylesheet defines                                                                                             |
| `no-contradicting-variants`        | `{}`                                                         | What each variant's selector does                                                                                                                                         |
| `no-dark-without-light`            | `{ variants: ['dark'] }`                                     | Tells colours from the rest, and groups the base by declared CSS property                                                                                                 |
| `no-deprecated-classes`            | `{}`                                                         | Derives the rename list instead of using the built-in table                                                                                                               |
| `no-dynamic-classes`               | `{}`                                                         | Your project's own utilities and variants count as Tailwind's                                                                                                             |
| `no-hardcoded-colors`              | `{ allow: [] }`                                              | Names your theme's colors in the message                                                                                                                                  |

### DS-independent rules

| Rule                                    | Default options                 |
| --------------------------------------- | ------------------------------- |
| `enforce-consistent-important-position` | `{ position: 'suffix' }`        |
| `enforce-consistent-variable-syntax`    | `{ syntax: 'shorthand' }`       |
| `enforce-negative-arbitrary-values`     | (no options)                    |
| `max-class-count`                       | `{ max: 20 }`                   |
| `no-duplicate-classes`                  | (no options)                    |
| `no-restricted-classes`                 | `{ classes: [], patterns: [] }` |
| `no-unnecessary-whitespace`             | (no options)                    |

---

<!-- https://oxlint-tailwindcss.pages.dev/migration/v0-to-v1.md -->

# Migrating from v0.x to v1.0.0

v1.0.0 aligns `oxlint-tailwindcss` with the deterministic-config philosophy that the rest of the
ecosystem (prettier-plugin-tailwindcss, oxfmt, better-tailwindcss) already follows. The trade-off is
one required setting in exchange for "configure once, never fails again."

This page lists every breaking change with a side-by-side before/after.

## Required: declare `entryPoint`

In v0.x, the plugin walked the filesystem looking for your CSS. In v1.0.0 it doesn't — you tell it
explicitly.

### Single project

```jsonc
// v0.x (still works in v1 if you happen to have one,
// but no longer auto-detected)
{ }

// v1.0.0
{
  "settings": {
    "tailwindcss": {
      "entryPoint": "src/styles.css"
    }
  }
}
```

### Monorepo with multiple CSS files

```jsonc
// v0.x — array of strings, plugin picked the closest by path prefix
{
  "settings": {
    "tailwindcss": {
      "entryPoint": [
        "packages/ui/src/styles.css",
        "packages/admin/src/admin.css"
      ]
    }
  }
}

// v1.0.0 — explicit glob → CSS mapping, first match wins
{
  "settings": {
    "tailwindcss": {
      "entryPoint": [
        { "files": "packages/ui/**",    "use": "packages/ui/src/styles.css" },
        { "files": "packages/admin/**", "use": "packages/admin/src/admin.css" }
      ]
    }
  }
}
```

The legacy `string[]` shape now throws `DeprecatedEntryPointShapeError` at lint time, with the
migration snippet embedded directly in the diagnostic.

If your monorepo uses per-package `.oxlintrc.json` files, each with a plain `entryPoint: "..."`
string, no migration is needed for the per-package approach — only the root-config + array form
changed. See the [monorepo guide](/monorepo) for both patterns.

## Removed: filesystem auto-detect

v0 walked up from each linted file looking for files named `app.css`, `globals.css`, `tailwind.css`,
etc. If found, the plugin loaded that CSS automatically.

v1.0.0 removes this entirely. Two reasons:

1. Renaming or moving a CSS file silently changed lint results between team members.
2. It clashed with oxfmt and prettier-plugin-tailwindcss, both of which require explicit config. The
   [interop guide](/interop) explains why.

**Action**: add the `entryPoint` setting documented above. If you weren't passing one in v0.x, the
plugin was auto-detecting and you need to declare what it found.

## Removed: silent fallbacks

v0.x silently skipped DS-dependent rules when the design system couldn't load (missing
`@tailwindcss/node`, invalid CSS, worker timeout, etc.).

v1.0.0 surfaces failures as a single `designSystemUnavailable` diagnostic per file. The message
embeds an actionable hint — usually exactly the path the plugin tried, or the timeout that was hit.

**Action**: if you see new `designSystemUnavailable` lints on the first run, read the message. The
fix is in the hint.

## Removed: heuristic-sort fallback

`enforce-sort-order` used to fall back to a prefix-based heuristic sort when its worker thread timed
out. Different machines could produce different output for the same input.

v1.0.0 removes the fallback. If the worker fails, the rule emits a fatal diagnostic instead of
guessing.

**Action**: bump `settings.tailwindcss.timeout` if you hit timeouts on slow CI. Default is now 60
seconds (up from 30 seconds).

## Changed: disk cache key

The disk cache (`os.tmpdir()/oxlint-tailwindcss/`) used to combine an mtime index with a content
cache. v1.0.0 keys by content hash only — mtime is an in-memory fast path inside the linter process.

**Action**: delete the v0.x cache directory, `os.tmpdir()/oxlint-tailwindcss/`, once after
upgrading. Its stale `.idx` files are harmless but waste disk. Since v1.3 the cache lives in a
per-user directory (`oxlint-tailwindcss-<uid>` in the same temp dir, or wherever
[`OXLINT_TAILWINDCSS_CACHE_DIR`](/settings#environment-variables) points), so the old one is never
read again.

## Changed: timeouts

Default values raised to reduce spurious failures on slower hardware / CI:

| Constant                               | v0.x | v1.0.0 |
| -------------------------------------- | ---- | ------ |
| `loadDesignSystemSync` timeout         | 30 s | 60 s   |
| `sort-service` init timeout            | 30 s | 60 s   |
| `sort-service` request timeout         | 10 s | 30 s   |
| `canonicalize-service` init timeout    | 30 s | 60 s   |
| `canonicalize-service` request timeout | 10 s | 30 s   |

`settings.tailwindcss.timeout` sets the `loadDesignSystemSync` (precompute) timeout. The service
init timeouts are fixed at 60 s. The per-request timeouts can be raised with the
[`OXLINT_TAILWINDCSS_WORKER_REQUEST_TIMEOUT`](/settings#environment-variables) environment variable
(since v1.11).

## Changed: `enforce-physical` accepts options

To bring it into shape parity with `enforce-logical`:

```jsonc
// v0.x — no options
{ "tailwindcss/enforce-physical": "warn" }

// v1.0.0
{
  "tailwindcss/enforce-physical": [
    "warn",
    {
      "allowlist": ["^ml-auto$"],     // regex patterns (as strings)
      "direction": "both"              // 'inline' | 'block' | 'both'
    }
  ]
}
```

`enforce-logical` gained the same two options.

## What did _not_ change

- Every rule name, `messageId`, and `data` field is unchanged. `enforce-sort-order` still emits
  `unsorted`, `no-unknown-classes` still emits `unknown`, etc.
- Default extractor patterns (attributes, callees, tags, variable patterns) are the same. Custom
  `attributes`, `callees`, `tags`, `variablePatterns` and `exclude` settings work as before.
- The disk-cache path (`os.tmpdir()/oxlint-tailwindcss/`) was the same in v1.0; v1.3 moved it to a
  per-user directory (see [above](#changed-disk-cache-key)).
- Performance: the runtime cost per file is unchanged or slightly faster (fewer fallback branches).

## Need help?

- Read the [settings reference](/settings) for every option.
- See the [monorepo guide](/monorepo) for multi-CSS setups.
- File an issue at
  [github.com/sergioazoc/oxlint-tailwindcss](https://github.com/sergioazoc/oxlint-tailwindcss/issues)
  with your config snippet if the migration leaves something unclear.

---

<!-- https://oxlint-tailwindcss.pages.dev/ai-agents.md -->

# AI coding agents

Agents write Tailwind classes fast, and get them wrong the way people do: a typo, a palette color
instead of a theme one, two classes that override each other, a component rebuilt by hand.
oxlint-tailwindcss reports those with the fix in the message, which an agent can act on without
help. Two things make that automatic.

## The skill

```bash
npx skills add sergioazoc/oxlint-tailwindcss --skill oxlint-tailwindcss
```

It installs
[`skills/oxlint-tailwindcss/SKILL.md`](https://github.com/sergioazoc/oxlint-tailwindcss/blob/main/skills/oxlint-tailwindcss/SKILL.md)
for the agents `npx skills` supports. It tells the agent how to set the plugin up — the
requirements, the entry point, the [recommended config](/setup#3-recommended-starter-rule-set) — and
what to do about each diagnostic.

## The Claude Code plugin

In Claude Code:

```text
/plugin marketplace add sergioazoc/oxlint-tailwindcss
/plugin install oxlint-tailwindcss@oxlint-tailwindcss
```

It adds three things:

- **Diagnostics as Claude works.** It starts your project's `oxlint --lsp` as a language server, so
  Claude sees oxlint-tailwindcss's reports — and oxlint's — on the files it opens and edits.
- **A check before Claude finishes.** It notes each file Claude edits; when Claude is about to
  finish, it lints those files and, if oxlint-tailwindcss reports errors in them, sends Claude back
  with the list. Warnings and files Claude didn't touch don't count, and it never sends Claude back
  twice in a row.
- **The skill** above.

It runs your project's own oxlint (`node_modules/.bin/oxlint`, found from the project root up) with
your `.oxlintrc.json`, so install `oxlint` and `oxlint-tailwindcss` in the project and
[set it up](/setup) first. Without them, the plugin does nothing.

## Any agent

- Every page of these docs is also plain markdown at the same path, with `.md`
  ([`/setup.md`](https://oxlint-tailwindcss.pages.dev/setup.md)), and
  [`/llms.txt`](https://oxlint-tailwindcss.pages.dev/llms.txt) lists them.
- oxlint switches to a terse output format of its own when it detects that an agent runs it, which
  keeps the diagnostics short in an agent's context.

---

<!-- https://oxlint-tailwindcss.pages.dev/benchmark.md -->

# Benchmark

Three oxlint plugins that lint Tailwind CSS classes, run over the same real project and the same
seeded mistakes, and judged by Tailwind itself. Every number on this page is generated from
[`bench/results/latest.json`](https://github.com/sergioazoc/oxlint-tailwindcss/blob/main/bench/results/latest.json),
which
[`bench/score.mjs`](https://github.com/sergioazoc/oxlint-tailwindcss/blob/main/bench/score.mjs)
writes; a weekly job checks that a fresh run still agrees with it.

<!-- generated:bench-setup -->

- **Corpus**:
  [shadcn-ui/ui `apps/v4`](https://github.com/shadcn-ui/ui/tree/98a1fe67b439324ddc857f47fbdce056600a4329/apps/v4)
  @ `98a1fe67`, 880 files
- **Versions**: oxlint-tailwindcss 1.16.0, @shadcn/lint 0.2.0, eslint-plugin-better-tailwindcss
  4.9.0; oxlint 1.87.0, tailwindcss 4.3.3
- **Machine**: Apple M4 Pro, 12 cores, darwin 25.5.0, Node 24.19.0; median of 5 runs

<!-- /generated:bench-setup -->

## Speed

Each tool with all its rules on — and with its recommended set, where it has one — under the same
oxlint. A warm run reuses oxlint-tailwindcss's design-system cache; a cold run starts without it, as
the first run on a machine or in CI does ([Running in CI](/ci) keeps it between jobs). The other two
have no cache to be cold. better-tailwindcss is an ESLint plugin, run through oxlint's support for
them, like the other two.

<!-- generated:bench-speed -->

| Tool                             | Rules       | Warm run | Cold run | Diagnostics |
| -------------------------------- | ----------- | -------- | -------- | ----------- |
| oxlint-tailwindcss               | all         | 1.5 s    | 9.1 s    | 3,264       |
| oxlint-tailwindcss               | recommended | 1.1 s    | 9.3 s    | 352         |
| @shadcn/lint                     | all         | 1.0 s    | —        | 2,578       |
| eslint-plugin-better-tailwindcss | all         | 26.8 s   | —        | 6,284       |
| eslint-plugin-better-tailwindcss | recommended | 25.8 s   | —        | 705         |

<!-- /generated:bench-speed -->

## Seeded mistakes

Files of the mistakes people and agents make with Tailwind, in
[`bench/synthetic`](https://github.com/sergioazoc/oxlint-tailwindcss/tree/main/bench/synthetic):
palette colors, arbitrary values, restyled and rebuilt components, conflicts, typos, `var()`
references, deprecated and runtime-built classes. Each mistake is labeled with what it is, each
clean line as clean, and the ambiguous ones not at all. A tool catches a mistake when it reports its
line with a rule for that kind of mistake, and raises a false alarm when it reports a clean line
with anything but a style rule. Which rule is for which mistake comes from the tables of
[shadcn/ui and @shadcn/lint](/shadcn) and the [migration guide](/migration/from-better-tailwindcss),
which a weekly job checks against the real tools.

<!-- generated:bench-seeded -->

| Mistake                                                                        | oxlint-tailwindcss | @shadcn/lint | eslint-plugin-better-tailwindcss |
| ------------------------------------------------------------------------------ | ------------------ | ------------ | -------------------------------- |
| A Tailwind palette color instead of a theme color                              | 8/8                | 6/8          | 0/8                              |
| Arbitrary values                                                               | 8/8                | 8/8          | 0/8                              |
| Classes with a canonical form                                                  | 3/3                | 3/3          | 2/3                              |
| Restyling a design-system component through `className`                        | 1/6                | 6/6          | 0/6                              |
| Component rebuilt from raw classes                                             | 4/4                | 0/4          | 0/4                              |
| Classes that override each other                                               | 6/6                | 0/6          | 3/6                              |
| Duplicate classes                                                              | 1/1                | 0/1          | 1/1                              |
| Redundant or contradicting variant                                             | 1/1                | 0/1          | 0/1                              |
| Extra whitespace                                                               | 1/1                | 0/1          | 1/1                              |
| Classes Tailwind can't generate: typos in utilities, variants and theme colors | 9/9                | 9/9          | 9/9                              |
| A CSS variable where the theme has a named class                               | 3/3                | 1/3          | 0/3                              |
| Classes deprecated in Tailwind v4                                              | 2/2                | 0/2          | 2/2                              |
| Longhands with a shorthand                                                     | 1/1                | 0/1          | 1/1                              |
| A dark-mode color with no light-mode base                                      | 1/1                | 0/1          | 0/1                              |
| Classes built at runtime                                                       | 1/1                | 0/1          | 1/1                              |
| Inline styles                                                                  | 0/1                | 1/1          | 0/1                              |
| **All mistakes**                                                               | **50/56**          | **34/56**    | **20/56**                        |
| False alarms on the clean lines                                                | 0/6                | 0/6          | 0/6                              |

<!-- /generated:bench-seeded -->

The files are this project's, and cover the mistakes it was built for: read the table by row — which
kinds of mistake each tool covers — more than by the total. Restyled components and inline styles
are @shadcn/lint's alone; [shadcn/ui and @shadcn/lint](/shadcn) has the config that runs both.

::: details Every labeled line

<!-- generated:bench-seeded-lines -->

| Code                                                                                       | Mistake                                                                        | oxlint-tailwindcss | @shadcn/lint | eslint-plugin-better-tailwindcss |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------ | ------------ | -------------------------------- |
| `<div className="flex bg-red-500 p-4">Sale</div>`                                          | A Tailwind palette color instead of a theme color                              | ✓                  | ✓            | ✗                                |
| `<p className="text-gray-600">Subtitle</p>`                                                | A Tailwind palette color instead of a theme color                              | ✓                  | ✓            | ✗                                |
| `<div className="border border-slate-200">Box</div>`                                       | A Tailwind palette color instead of a theme color                              | ✓                  | ✓            | ✗                                |
| `<div className="bg-white">White</div>`                                                    | A Tailwind palette color instead of a theme color                              | ✓                  | ✗            | ✗                                |
| `<div className="text-black">Black</div>`                                                  | A Tailwind palette color instead of a theme color                              | ✓                  | ✗            | ✗                                |
| `<div className="bg-[#1a73e8] p-2">Hex</div>`                                              | Arbitrary values                                                               | ✓                  | ✓            | ✗                                |
| `<div className="shadow-[0_1px_2px_rgba(0,0,0,0.1)]">Shadow</div>`                         | Arbitrary values                                                               | ✓                  | ✓            | ✗                                |
| `<div className="text-[oklch(0.6_0.2_250)]">Oklch</div>`                                   | Arbitrary values                                                               | ✓                  | ✓            | ✗                                |
| `<div className="hover:bg-blue-600/80">Hover raw</div>`                                    | A Tailwind palette color instead of a theme color                              | ✓                  | ✓            | ✗                                |
| `<div className="bg-primary text-primary-foreground">OK token</div>`                       | clean                                                                          | ✓                  | ✓            | ✓                                |
| `<div className="p-[13px]">odd padding</div>`                                              | Arbitrary values                                                               | ✓                  | ✓            | ✗                                |
| `<div className="w-[350px]">fixed width</div>`                                             | Arbitrary values                                                               | ✓                  | ✓            | ✗                                |
| `<div className="text-[15px]">odd text</div>`                                              | Arbitrary values                                                               | ✓                  | ✓            | ✗                                |
| `<div className="rounded-[10px]">odd radius</div>`                                         | Arbitrary values                                                               | ✓                  | ✓            | ✗                                |
| `<div className="mt-[16px]">same as mt-4</div>`                                            | Classes with a canonical form                                                  | ✓                  | ✓            | ✗                                |
| `<div className="top-[1px] relative">same as top-px</div>`                                 | Classes with a canonical form                                                  | ✓                  | ✓            | ✓                                |
| `<div className="min-h-[100vh]">same as min-h-screen</div>`                                | Classes with a canonical form                                                  | ✓                  | ✓            | ✓                                |
| `<div className="p-4">OK scale</div>`                                                      | clean                                                                          | ✓                  | ✓            | ✓                                |
| `<Card className="p-8 shadow-xl">`                                                         | Restyling a design-system component through `className`                        | ✗                  | ✓            | ✗                                |
| `<CardTitle className="text-2xl font-bold">Checkout</CardTitle>`                           | Restyling a design-system component through `className`                        | ✗                  | ✓            | ✗                                |
| `<CardContent className="mt-2">`                                                           | clean                                                                          | ✓                  | ✓            | ✓                                |
| `<Badge className="rounded-sm px-3 text-sm">New</Badge>`                                   | Restyling a design-system component through `className`                        | ✗                  | ✓            | ✗                                |
| `<Button className="p-4 rounded-full">Pay</Button>`                                        | Restyling a design-system component through `className`                        | ✗                  | ✓            | ✗                                |
| `<Button className="bg-blue-600 text-white hover:bg-blue-700">Buy</Button>`                | Restyling a design-system component through `className`                        | ✓                  | ✓            | ✗                                |
| `<Button className="mt-4 w-full">Allowed layout</Button>`                                  | clean                                                                          | ✓                  | ✓            | ✓                                |
| `<Button size="lg" variant="outline">Allowed props</Button>`                               | clean                                                                          | ✓                  | ✓            | ✓                                |
| `<button className="inline-flex shrink-0 items-center justify-center gap-2 rounded-md bg…` | Component rebuilt from raw classes                                             | ✓                  | ✗            | ✗                                |
| `<input className="h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-3…` | Component rebuilt from raw classes                                             | ✓                  | ✗            | ✗                                |
| `<div className="flex flex-col gap-6 rounded-xl border bg-card py-6 text-card-foreground…` | Component rebuilt from raw classes                                             | ✓                  | ✗            | ✗                                |
| `<span className="inline-flex items-center justify-center rounded-md border px-2 py-0.5 …` | Component rebuilt from raw classes                                             | ✓                  | ✗            | ✗                                |
| `<div className="line-clamp-1 flex">clamp broken</div>`                                    | Classes that override each other                                               | ✓                  | ✗            | ✗                                |
| `<div className="p-4 p-6">double padding</div>`                                            | Classes that override each other                                               | ✓                  | ✗            | ✓                                |
| `<div className="text-sm text-base">double size</div>`                                     | Classes that override each other                                               | ✓                  | ✗            | ✓                                |
| `<div className="block flex">double display</div>`                                         | Classes that override each other                                               | ✓                  | ✗            | ✓                                |
| `<div className="size-5 w-4">size vs width</div>`                                          | Classes that override each other                                               | ✓                  | ✗            | ✗                                |
| `<div className="flex flex items-center">duplicate</div>`                                  | Duplicate classes                                                              | ✓                  | ✗            | ✓                                |
| `<div className="pt-3 xl:pt-3">redundant variant</div>`                                    | Redundant or contradicting variant                                             | ✓                  | ✗            | ✗                                |
| `<div className="absolute sr-only">redundant position</div>`                               | Classes that override each other                                               | ✓                  | ✗            | ✗                                |
| `<div className="mt-2   mb-2">whitespace</div>`                                            | Extra whitespace                                                               | ✓                  | ✗            | ✓                                |
| `<div className="itms-center flex">typo items</div>`                                       | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="jusitfy-between flex">typo justify</div>`                                 | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="bg-primray">typo token</div>`                                             | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="text-muted-foregound">typo token 2</div>`                                 | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="rounded-huge">unknown radius</div>`                                       | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="flex-cols">unknown flex</div>`                                            | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="shadow-xxl">unknown shadow</div>`                                         | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="md:grids-col-2 grid">typo grid</div>`                                     | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="bg-chart-6">undeclared token</div>`                                       | Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| `<div className="bg-surface text-code-foreground">declared custom tokens OK</div>`         | clean                                                                          | ✓                  | ✓            | ✓                                |
| `<div className="bg-(--primary)">var ref to token</div>`                                   | A CSS variable where the theme has a named class                               | ✓                  | ✗            | ✗                                |
| `<div className="text-[var(--muted-foreground)]">bracket var to token</div>`               | A CSS variable where the theme has a named class                               | ✓                  | ✓            | ✗                                |
| `<div className="border-(--border) border">var to border token</div>`                      | A CSS variable where the theme has a named class                               | ✓                  | ✗            | ✗                                |
| `<div className="bg-gradient-to-r from-primary to-secondary">deprecated gradient</div>`    | Classes deprecated in Tailwind v4                                              | ✓                  | ✗            | ✓                                |
| `<div className="flex-shrink-0">deprecated shrink</div>`                                   | Classes deprecated in Tailwind v4                                              | ✓                  | ✗            | ✓                                |
| `<div className="h-4 w-4">shorthand size-4</div>`                                          | Longhands with a shorthand                                                     | ✓                  | ✗            | ✓                                |
| `<div className="dark:hover:bg-accent">variant order</div>`                                | A dark-mode color with no light-mode base                                      | ✓                  | ✗            | ✗                                |
| `danger: "bg-red-500 text-white",`                                                         | A Tailwind palette color instead of a theme color                              | ✓                  | ✓            | ✗                                |
| `info: "bg-[#0ea5e9] text-white",`                                                         | Arbitrary values                                                               | ✓                  | ✓            | ✗                                |
| `<div className={`bg-${color}-500 p-2`}>template</div>`                                    | Classes built at runtime                                                       | ✓                  | ✗            | ✓                                |
| `<div className={cn("p-2", active && "bg-emerald-500")}>cn cond</div>`                     | A Tailwind palette color instead of a theme color                              | ✓                  | ✓            | ✗                                |
| `<Button className={cn(active && "rounded-none")}>cn on component</Button>`                | Restyling a design-system component through `className`                        | ✗                  | ✓            | ✗                                |
| <span v-pre>`<div style={{ color: "#f00", padding: 12 }}>inline style</div>`</span>        | Inline styles                                                                  | ✗                  | ✓            | ✗                                |

<!-- /generated:bench-seeded-lines -->

:::

## Real code, judged by Tailwind

On the corpus, a report can be checked against Tailwind itself. An unknown-class report of a class
Tailwind compiles is wrong for sure. One of a class a project stylesheet defines is most likely
wrong too: the class styles something, only not through Tailwind. A conflict report of two classes
that set no property in the same variant context has no conflict to report.

<!-- generated:bench-oracles -->

| Tool                             | Unknown-class reports | …of classes Tailwind compiles | …of classes a project stylesheet defines | Conflict reports | …of classes that share no property |
| -------------------------------- | --------------------- | ----------------------------- | ---------------------------------------- | ---------------- | ---------------------------------- |
| oxlint-tailwindcss               | 77                    | 0                             | 18                                       | 20               | 0                                  |
| @shadcn/lint                     | 34                    | 0                             | 18                                       | —                | —                                  |
| eslint-plugin-better-tailwindcss | 97                    | 0                             | 38                                       | 0                | 0                                  |

<!-- /generated:bench-oracles -->

## What the fixes do

Each tool's `--fix`, then `--fix --fix-suggestions`, applied to the corpus. Every class string a fix
changed is compared by its effective style before and after — the value each property ends up with,
in each variant context. It is the same style; a typo fixed, where a class Tailwind didn't know is
replaced by one that adds only its own declarations; or a changed style, listed below with its
before and after. Logical and physical properties are read left to right, theme values are
substituted, and `@supports` blocks apply, as they do in the browsers Tailwind v4 supports.

<!-- generated:bench-fixes -->

| Tool                             | Run                       | Class strings changed | Same style | Typo fixed | Style changed |
| -------------------------------- | ------------------------- | --------------------- | ---------- | ---------- | ------------- |
| oxlint-tailwindcss               | `--fix`                   | 1,028                 | 1,028      | 0          | 0             |
| oxlint-tailwindcss               | `--fix --fix-suggestions` | 1,191                 | 1,187      | 4          | 0             |
| @shadcn/lint                     | `--fix`                   | no autofix            | —          | —          | —             |
| @shadcn/lint                     | `--fix --fix-suggestions` | 249                   | 212        | 3          | **34**        |
| eslint-plugin-better-tailwindcss | `--fix`                   | 2,865                 | 2,864      | 0          | **1**         |
| eslint-plugin-better-tailwindcss | `--fix --fix-suggestions` | 2,865                 | 2,864      | 0          | **1**         |

<!-- /generated:bench-fixes -->

<!-- generated:bench-fix-changes -->

::: details @shadcn/lint: 34 strings whose style `--fix --fix-suggestions` changed

- `app/(app)/(create)/components/picker.tsx`

  ```diff
  - cn-menu-target z-50 no-scrollbar max-h-(--available-height) w-[calc(var(--available-width)-(--spacing(6)))] min-w-32 origin-(--transform-origin) translate-y-2 overflow-x-hidden overflow-y-auto rounded-xl border-0 bg-neutral-950/80 p-1.5 text-neutral-100 ring-1 ring-neutral-950/80 backdrop-blur-xl outline-none md:w-52 dark:bg-neutral-800/90 dark:ring-neutral-700/50 data-closed:overflow-hidden
  + cn-menu-target z-50 no-scrollbar max-h-(--available-height) w-[calc(var(--available-width)-(--spacing(6)))] min-w-32 origin-(--transform-origin) translate-y-2 overflow-x-hidden overflow-y-auto rounded-xl border-0 bg-sidebar-primary/80 p-1.5 text-neutral-100 ring-1 ring-neutral-950/80 backdrop-blur-xl outline-none md:w-52 dark:bg-neutral-800/90 dark:ring-neutral-700/50 data-closed:overflow-hidden
  ```

  `& | background-color`: `color-mix(in oklab, oklch(14.5% 0 none) 80%, transparent)` →
  `color-mix(in oklab, var(--sidebar-primary) 80%, transparent)`

- `app/(app)/(create)/components/picker.tsx`

  ```diff
  - px-2 py-1.5 text-xs font-medium text-neutral-400 data-inset:pl-8
  + px-2 py-1.5 text-xs font-medium text-ring data-inset:pl-8
  ```

  `& | color`: `oklch(70.8% 0 none)` → `var(--ring)`

- `app/(app)/(create)/components/picker.tsx`

  ```diff
  - group/dropdown-menu-item relative flex cursor-default items-center gap-2 rounded-lg px-2 py-1.5 text-sm font-medium outline-hidden select-none **:text-neutral-100 focus:bg-neutral-600 focus:text-neutral-100 focus:**:text-neutral-100 data-inset:pl-8 dark:focus:bg-neutral-700/80 pointer-coarse:gap-3 pointer-coarse:py-2.5 pointer-coarse:pl-3 pointer-coarse:text-base data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4
  + group/dropdown-menu-item relative flex cursor-default items-center gap-2 rounded-lg px-2 py-1.5 text-sm font-medium outline-hidden select-none **:text-muted focus:bg-neutral-600 focus:text-neutral-100 focus:**:text-neutral-100 data-inset:pl-8 dark:focus:bg-neutral-700/80 pointer-coarse:gap-3 pointer-coarse:py-2.5 pointer-coarse:pl-3 pointer-coarse:text-base data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4
  ```

  `& * | color`: `oklch(97% 0 none)` → `var(--muted)`

- `app/(app)/(create)/components/picker.tsx`

  ```diff
  - relative flex cursor-default items-center gap-2 rounded-lg py-1.5 pr-8 pl-2 text-sm font-medium outline-hidden select-none **:text-neutral-100 focus:bg-neutral-600 focus:text-neutral-100 focus:**:text-neutral-100 data-inset:pl-8 dark:focus:bg-neutral-700/80 pointer-coarse:gap-3 pointer-coarse:py-2.5 pointer-coarse:pl-3 pointer-coarse:text-base data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4
  + relative flex cursor-default items-center gap-2 rounded-lg py-1.5 pr-8 pl-2 text-sm font-medium outline-hidden select-none **:text-muted focus:bg-neutral-600 focus:text-neutral-100 focus:**:text-neutral-100 data-inset:pl-8 dark:focus:bg-neutral-700/80 pointer-coarse:gap-3 pointer-coarse:py-2.5 pointer-coarse:pl-3 pointer-coarse:text-base data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4
  ```

  `& * | color`: `oklch(97% 0 none)` → `var(--muted)`

- `app/(app)/(create)/components/picker.tsx`

  ```diff
  - -mx-1.5 my-1.5 h-px bg-neutral-600 dark:bg-neutral-700
  + -mx-1.5 my-1.5 h-px bg-muted-foreground dark:bg-neutral-700
  ```

  `& | background-color`: `oklch(43.9% 0 none)` → `var(--muted-foreground)`

- `app/(app)/(create)/components/picker.tsx`

  ```diff
  - ml-auto text-xs tracking-widest text-neutral-400! group-focus/dropdown-menu-item:text-neutral-100
  + ml-auto text-xs tracking-widest text-ring! group-focus/dropdown-menu-item:text-neutral-100
  ```

  `& | color`: `oklch(70.8% 0 none) !important` → `var(--ring) !important`

- `app/(app)/(create)/components/project-form.tsx`

  ```diff
  - size-4 text-neutral-100 [&_svg]:size-4 [&_svg]:fill-current
  + size-4 text-muted [&_svg]:size-4 [&_svg]:fill-current
  ```

  `& | color`: `oklch(97% 0 none)` → `var(--muted)`

- `app/(app)/(create)/components/project-form.tsx`

  ```diff
  - size-4 text-neutral-100 [&_svg]:size-4 *:[svg]:text-neutral-100!
  + size-4 text-muted [&_svg]:size-4 *:[svg]:text-neutral-100!
  ```

  `& | color`: `oklch(97% 0 none)` → `var(--muted)`

- `app/(app)/(create)/components/project-form.tsx`

  ```diff
  - size-4 shrink-0 text-neutral-100 [&_svg]:size-4 *:[svg]:text-neutral-100!
  + size-4 shrink-0 text-muted [&_svg]:size-4 *:[svg]:text-neutral-100!
  ```

  `& | color`: `oklch(97% 0 none)` → `var(--muted)`

- `app/(app)/(create)/components/welcome-dialog.tsx`

  ```diff
  - dialog-ring max-w-92 min-w-0 gap-0 overflow-hidden rounded-xl p-0 sm:max-w-sm dark:bg-neutral-900
  + dialog-ring max-w-92 min-w-0 gap-0 overflow-hidden rounded-xl p-0 sm:max-w-sm dark:bg-sidebar-primary
  ```

  `&.dark * | background-color`: `oklch(20.5% 0 none)` → `var(--sidebar-primary)`

- `app/(app)/(create)/components/welcome-dialog.tsx`

  ```diff
  - flex aspect-[2/1.2] w-full items-center justify-center rounded-t-xl bg-neutral-950 text-center text-neutral-100 sm:aspect-2/1
  + flex aspect-[2/1.2] w-full items-center justify-center rounded-t-xl bg-sidebar-primary text-center text-neutral-100 sm:aspect-2/1
  ```

  `& | background-color`: `oklch(14.5% 0 none)` → `var(--sidebar-primary)`

- `app/(app)/(styles)/sera/components/theme-switcher.tsx`

  ```diff
  - w-full max-w-[60vw] rounded-full border-0 bg-neutral-950/50 p-1.5 shadow-xl backdrop-blur-xl sm:max-w-fit
  + w-full max-w-[60vw] rounded-full border-0 bg-sidebar-primary/50 p-1.5 shadow-xl backdrop-blur-xl sm:max-w-fit
  ```

  `& | background-color`: `color-mix(in oklab, oklch(14.5% 0 none) 50%, transparent)` →
  `color-mix(in oklab, var(--sidebar-primary) 50%, transparent)`

…and 22 more

:::

::: details eslint-plugin-better-tailwindcss: 1 string whose style `--fix` changed

- `app/(app)/examples/playground/page.tsx`

  ```diff
  - h-5 w-5
  + block-5
  ```

  `& | width`: `20px` → none

:::

<!-- /generated:bench-fix-changes -->

## Run it yourself

```bash
git clone https://github.com/sergioazoc/oxlint-tailwindcss
cd oxlint-tailwindcss
pnpm install && pnpm build
cd bench
npm ci && npm run corpus
node score.mjs   # writes results/latest.json
```

[`bench/README.md`](https://github.com/sergioazoc/oxlint-tailwindcss/blob/main/bench/README.md) has
the details: the configs each tool runs with, how the seeded files are labeled, and how each oracle
decides.

## What it doesn't measure

- **One project.** A React app on Tailwind v4 with shadcn/ui; another codebase has other mistakes.
- **The seeded files are this project's**, so they lean to what it checks. Their labels are in the
  files, for anyone to dispute.
- **Class strings, not pages.** The oracles see what a class string does to its element, not what a
  `group-*` parent or a script does with a class.
- **Speed on one machine.** Compare the tools with each other, not with your machine.

---

<!-- https://oxlint-tailwindcss.pages.dev/comparison.md -->

# Compared with other plugins

Three plugins lint Tailwind CSS classes under oxlint:
[@shadcn/lint](https://github.com/shadcn-ui/lint), shadcn/ui's design-system policy for its
components;
[eslint-plugin-better-tailwindcss](https://github.com/schoero/eslint-plugin-better-tailwindcss), an
ESLint plugin oxlint can run; and this one. They overlap less than their names suggest. The numbers
below are the [benchmark](/benchmark)'s, generated from the same results file.

## At a glance

<!-- generated:comparison-summary -->

| Summary                                 | oxlint-tailwindcss 1.16.0 | @shadcn/lint 0.2.0 | eslint-plugin-better-tailwindcss 4.9.0 |
| --------------------------------------- | ------------------------- | ------------------ | -------------------------------------- |
| Seeded mistakes caught                  | 50/56                     | 34/56              | 20/56                                  |
| False alarms on clean lines             | 0/6                       | 0/6                | 0/6                                    |
| Warm run, all rules                     | 1.5 s                     | 1.0 s              | 26.8 s                                 |
| Unknown-class reports Tailwind compiles | 0/77                      | 0/34               | 0/97                                   |
| `--fix`: strings whose style changed    | 0/1,028                   | no autofix         | 1/2,865                                |

<!-- /generated:comparison-summary -->

Seeded mistakes are the [benchmark's labeled files](/benchmark#seeded-mistakes), and they lean to
what this plugin checks. "Unknown-class reports Tailwind compiles" are reports Tailwind itself
proves wrong, and "strings whose style changed" are class strings an unattended `--fix` changed the
look of.

## What each one checks

A ✓ means the plugin has a rule for it; which rules is in the tables of
[shadcn/ui and @shadcn/lint](/shadcn) and the [migration guide](/migration/from-better-tailwindcss).

<!-- generated:comparison-coverage -->

| Mistake                                                                        | oxlint-tailwindcss | @shadcn/lint | eslint-plugin-better-tailwindcss |
| ------------------------------------------------------------------------------ | ------------------ | ------------ | -------------------------------- |
| Restyling a design-system component through `className`                        | —                  | ✓            | —                                |
| Inline styles                                                                  | —                  | ✓            | —                                |
| A Tailwind palette color instead of a theme color                              | ✓                  | ✓            | —                                |
| Arbitrary values                                                               | ✓                  | ✓            | —                                |
| A CSS variable where the theme has a named class                               | ✓                  | —            | —                                |
| Classes Tailwind can't generate: typos in utilities, variants and theme colors | ✓                  | ✓            | ✓                                |
| Classes built at runtime                                                       | ✓                  | ✓            | ✓                                |
| Classes that override each other                                               | ✓                  | —            | ✓                                |
| Duplicate classes                                                              | ✓                  | —            | ✓                                |
| Classes deprecated in Tailwind v4                                              | ✓                  | —            | ✓                                |
| A dark-mode color with no light-mode base                                      | ✓                  | —            | —                                |
| Component rebuilt from raw classes                                             | ✓                  | —            | —                                |
| Redundant or contradicting variant                                             | ✓                  | —            | —                                |
| Arbitrary value that is on the scale                                           | ✓                  | —            | —                                |
| Classes with a canonical form                                                  | ✓                  | —            | ✓                                |
| Class and variant order                                                        | ✓                  | —            | ✓                                |
| Extra whitespace                                                               | ✓                  | —            | ✓                                |
| Longhands with a shorthand                                                     | ✓                  | —            | ✓                                |
| Other style policy                                                             | ✓                  | —            | ✓                                |

<!-- /generated:comparison-coverage -->

## Which to use

- **oxlint-tailwindcss** checks classes against your design system: that they exist, don't override
  each other, aren't deprecated, and stay within your theme. It reads your Tailwind build, so its
  reports and its fixes match what Tailwind generates. It is an oxlint plugin only.
- **@shadcn/lint** enforces shadcn/ui's component policy — no restyling a component through
  `className`, no inline styles — which this plugin doesn't check. The two run together:
  [shadcn/ui and @shadcn/lint](/shadcn) has a combined config that reports each problem once.
- **eslint-plugin-better-tailwindcss** is the choice for a project that stays on ESLint. Under
  oxlint, oxlint-tailwindcss has a rule for each of its rules, and runs faster:
  [the migration guide](/migration/from-better-tailwindcss) maps the rules and their settings.

---

<!-- https://oxlint-tailwindcss.pages.dev/faq.md -->

# FAQ

## Does it work with ESLint?

No. oxlint-tailwindcss is an oxlint plugin, built on oxlint's JS plugin API and tested with oxlint
only. Install oxlint and add the plugin to `jsPlugins` in `.oxlintrc.json` — see [Setup](/setup).

## Which Tailwind versions does it support?

Tailwind CSS v4.1.15 and later. The plugin loads your project's own Tailwind engine, so the linter
and your build read the same design system; an older engine, a future major, or a major-version
drift from your build is reported with a message that says so. Tailwind v3 (`tailwind.config.js`)
isn't supported.

## Which rules run?

Only the ones you list under `rules`. oxlint's `categories` don't turn on a JS plugin's rules, so a
config with the plugin and no rules reports nothing. Start from the
[recommended config](/setup#3-recommended-starter-rule-set) and add rules from [the list](/rules/).

## Do I need an entry point?

The rules that read your design system — which classes exist, their order, their CSS — need
`settings.tailwindcss.entryPoint`, the CSS file where you `@import "tailwindcss"`. Without it they
report `designSystemUnavailable` once per file, with a hint. The other rules work without one, and
several get more precise with it. [The rule list](/rules/) says which is which.

## Does it lint Vue, Svelte and Astro files?

Their `<script>` blocks, and Astro's frontmatter — not the templates. oxlint hands JS plugins only
those parts of the file. [Vue, Svelte & Astro](/frameworks) shows what is and isn't linted.

## Why is a class that works reported as unknown?

`no-unknown-classes` knows Tailwind's classes and the ones your CSS defines — in the entry point and
the stylesheets of yours it imports, up to four `@import`s down, and a package's stylesheet it
imports. A class it reports that still works in the browser usually comes from CSS the entry point
doesn't import, one your app loads separately. Or it has no CSS at all and is a hook for JavaScript
or tests. Import that CSS from the entry point, or tell the rule about the class with
[`allowlist` or `ignorePrefixes`](/rules/no-unknown-classes#options).

## Does it support Tailwind plugins?

Any plugin your entry point loads — with `@plugin` or `@import` — is part of the design system the
rules read, so its classes are known like Tailwind's own. The test suite runs with
`@tailwindcss/typography`, `tailwindcss-animate` and `tw-animate-css`.

## How do I turn a rule off for one line?

With oxlint's comments, naming the rule:

```tsx
// oxlint-disable-next-line tailwindcss/no-unknown-classes
<div className="legacy-widget flex" />
```

## Why does `oxlint --fix` leave some problems?

oxlint applies one fix per class string per run. When several rules fix the same string — a
duplicate, extra whitespace and the order — each run applies one of them; run `oxlint --fix` again
until nothing changes.

## Does it replace prettier-plugin-tailwindcss or oxfmt's class sorting?

No, they work together. The formatter sorts classes, removes duplicates and collapses whitespace in
what it formats; this plugin checks correctness — unknown, conflicting, deprecated and runtime-built
classes, and more. Point both at the same CSS and they sort the same way: see [Interop](/interop).

## How does it compare with @shadcn/lint and better-tailwindcss?

They check different things: [Compared with other plugins](/comparison) shows what each one checks,
and the [benchmark](/benchmark) measures them on the same code — mistakes caught, false positives,
speed, and what their fixes do.

## Can I use it with @shadcn/lint?

Yes. [shadcn/ui and @shadcn/lint](/shadcn) shows who reports what and a combined config that reports
each problem once.

## I use eslint-plugin-better-tailwindcss. How do I switch?

Each of its rules has a counterpart here; the [migration guide](/migration/from-better-tailwindcss)
maps them and their settings, and walks through the switch.

## I use eslint-plugin-tailwindcss. How do I switch?

Each of its rules has a counterpart here too. The
[migration guide](/migration/from-eslint-plugin-tailwindcss) maps them and their settings, and takes
you from an ESLint config to an `.oxlintrc.json`.

## How do I make it fast in CI?

The design system is precomputed once per entry point and cached on disk. Keep that cache between
jobs — [Running in CI](/ci) has the `actions/cache` recipe.

## Does it work in a monorepo?

Yes: map each package's files to its CSS in the root config, or give each package its own
`.oxlintrc.json`. See [Monorepo](/monorepo).

---

<!-- https://oxlint-tailwindcss.pages.dev/migration/from-better-tailwindcss.md -->

# Migrating from eslint-plugin-better-tailwindcss

[eslint-plugin-better-tailwindcss](https://github.com/schoero/eslint-plugin-better-tailwindcss) runs
in ESLint and, as a JS plugin, in oxlint. oxlint-tailwindcss is built for oxlint and Tailwind v4.
Each of better-tailwindcss 4.9.0's 15 rules has a counterpart here, and each pair reports the same
example — the tables below are checked against it every week, with its latest release.

## Rules

<!-- generated:btw-rules -->

| better-tailwindcss                      | oxlint-tailwindcss                                                                      | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enforce-consistent-class-order`        | [`enforce-sort-order`](/rules/enforce-sort-order)                                       | Their default `order: "official"` is this rule's order. Unknown classes go first, in the order written, as with their `unknownClassOrder: "preserve"`. `order: "strict"` → `mode: "strict"`, which also groups classes by variant chain (the order within can differ). `asc`, `desc` and the `componentClass*` / `unknownClass*` options have no equivalent.                                                                                                                                                                                                                    |
| `enforce-consistent-important-position` | [`enforce-consistent-important-position`](/rules/enforce-consistent-important-position) | `position: "recommended"` → `"suffix"` (the default, `p-4!`); `"legacy"` → `"prefix"` (`!p-4`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `enforce-consistent-line-wrapping`      | [`enforce-consistent-line-wrapping`](/rules/enforce-consistent-line-wrapping)           | `printWidth`, `classesPerLine` and `group` mean the same. The autofix rewrites template literals; with `wrapStrings: "all"` it wraps strings the way theirs does, a JSX string attribute in place and a JS string turned into a template literal (`"jsx"` wraps only the former, and otherwise a string is reported, not rewritten). A line over `printWidth` is rewrapped only with `wrapLines`. `indent`, `tabWidth`, `lineBreakStyle`, `preferSingleLine`, `strictness` and `vueConvertToBinding` have no equivalent: the indentation and line endings come from the source. |
| `enforce-consistent-variant-order`      | [`consistent-variant-order`](/rules/consistent-variant-order)                           | Both write chains outermost first (`sm:hover:`). This rule also orders color scheme and attribute variants (`dark:hover:`, `data-[state=open]:hover:`), which theirs leaves alone; `order` sets your own.                                                                                                                                                                                                                                                                                                                                                                       |
| `enforce-consistent-variable-syntax`    | [`enforce-consistent-variable-syntax`](/rules/enforce-consistent-variable-syntax)       | `syntax: "shorthand"` is the default in both; `"variable"` → `"explicit"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `enforce-shorthand-classes`             | [`enforce-shorthand`](/rules/enforce-shorthand)                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `enforce-logical-properties`            | [`enforce-logical`](/rules/enforce-logical)                                             | `ignore` → `allowlist` (regular expressions, too). The block axis (`mt-*` → `mbs-*`, `top-*` → `inset-bs-*`) is on by default; widths and heights (`w-*` → `inline-*`, `size-*` → `inline-* block-*`) need `sizing: true`. `direction` limits it to inline or block utilities; `enforce-physical` is the reverse rule.                                                                                                                                                                                                                                                          |
| `enforce-canonical-classes`             | [`enforce-canonical`](/rules/enforce-canonical)                                         | Their `collapse` (merging `mt-2 mb-2` into `my-2`) is `enforce-shorthand` here. `ignore` and `logical` have no equivalent.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `no-duplicate-classes`                  | [`no-duplicate-classes`](/rules/no-duplicate-classes)                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `no-deprecated-classes`                 | [`no-deprecated-classes`](/rules/no-deprecated-classes)                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `no-unnecessary-whitespace`             | [`no-unnecessary-whitespace`](/rules/no-unnecessary-whitespace)                         | Line breaks are always kept, as with their `allowMultiline: true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `no-concatenated-classes`               | [`no-dynamic-classes`](/rules/no-dynamic-classes)                                       | Both report a class built with `${}` or `+`. This one reports it when the built class starts with a Tailwind utility or variant, so `"p-4 " + extra` and `` `icon-${name}` `` are fine.                                                                                                                                                                                                                                                                                                                                                                                         |
| `no-unknown-classes`                    | [`no-unknown-classes`](/rules/no-unknown-classes)                                       | `ignore` (regular expressions) → `allowlist` (exact names) and `ignorePrefixes`. The classes your CSS defines (`@layer components`, `@utility`) are always known, so their `detectComponentClasses` setting has no counterpart.                                                                                                                                                                                                                                                                                                                                                 |
| `no-conflicting-classes`                | [`no-conflicting-classes`](/rules/no-conflicting-classes)                               | It also reports a class another one makes redundant (`reportRedundant`), and `allow` exempts pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `no-restricted-classes`                 | [`no-restricted-classes`](/rules/no-restricted-classes)                                 | `restrict: [{ pattern, message }]` → `patterns: [{ pattern, message }]`, and `classes` for exact names. There is no `fix`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

<!-- /generated:btw-rules -->

## Settings

<!-- generated:btw-settings -->

| `settings["better-tailwindcss"]` | `settings.tailwindcss`                                                                       | Notes                                                                                                                                                                                               |
| -------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entryPoint`                     | `entryPoint`                                                                                 | Required here. A string, or a glob → CSS mapping for a monorepo.                                                                                                                                    |
| `cwd`                            | `entryPoint`                                                                                 | Map each package's files to its CSS with `entryPoint: [{ files, use }]`, or give the package its own `.oxlintrc.json`.                                                                              |
| `rootFontSize`                   | `rootFontSize`                                                                               |                                                                                                                                                                                                     |
| `selectors`                      | `attributes`, `attributePatterns`, `callees`, `calleeExtractors`, `tags`, `variablePatterns` | Both read `class` / `className`, the same variable names and most helpers by default. Add what yours lists that this one doesn't: the `dcnb` helper to `callees`, the `twc` / `twx` tags to `tags`. |
| `detectComponentClasses`         | —                                                                                            | Always on: the classes your CSS defines are known.                                                                                                                                                  |
| `tailwindConfig`                 | —                                                                                            | A Tailwind v3 JavaScript config; this plugin reads Tailwind v4 CSS.                                                                                                                                 |
| `tsconfig`                       | —                                                                                            |                                                                                                                                                                                                     |
| `messageStyle`                   | —                                                                                            |                                                                                                                                                                                                     |

<!-- /generated:btw-settings -->

## Switching, step by step

1. Install the plugin: `pnpm add -D oxlint-tailwindcss` (and `oxlint`, if better-tailwindcss ran in
   ESLint).
2. In `.oxlintrc.json`, add `"jsPlugins": ["oxlint-tailwindcss"]`, and move
   `settings["better-tailwindcss"]` to `settings.tailwindcss` with the settings table. `entryPoint`
   is required.
3. Rename each `better-tailwindcss/<rule>` to the `tailwindcss/<rule>` of the rules table, turning
   its options into the ones its notes name. Or start from the [recommended config](/setup) and add
   what you had on top.
4. Remove eslint-plugin-better-tailwindcss — from `jsPlugins`, or from the ESLint config — and
   uninstall it, so the two don't report the same class.
5. Run `oxlint`, then `oxlint --fix` for the autofixes.

A typical config, before and after:

```jsonc
// Before
{
  "jsPlugins": ["eslint-plugin-better-tailwindcss"],
  "settings": { "better-tailwindcss": { "entryPoint": "src/styles.css" } },
  "rules": {
    "better-tailwindcss/enforce-consistent-class-order": "warn",
    "better-tailwindcss/enforce-consistent-important-position": ["warn", { "position": "legacy" }],
    "better-tailwindcss/no-unknown-classes": ["error", { "ignore": ["^swiper-"] }],
    "better-tailwindcss/no-concatenated-classes": "error"
  }
}

// After
{
  "jsPlugins": ["oxlint-tailwindcss"],
  "settings": { "tailwindcss": { "entryPoint": "src/styles.css" } },
  "rules": {
    "tailwindcss/enforce-sort-order": "warn",
    "tailwindcss/enforce-consistent-important-position": ["warn", { "position": "prefix" }],
    "tailwindcss/no-unknown-classes": ["error", { "ignorePrefixes": ["swiper-"] }],
    "tailwindcss/no-dynamic-classes": "error"
  }
}
```

## What else changes

- **Vue, Svelte and Astro templates.** In oxlint, JS plugins see only the `<script>` blocks of those
  files — better-tailwindcss run in ESLint with a framework parser reads templates too. See
  [Vue, Svelte & Astro](/frameworks).
- **Tailwind v3.** This plugin reads Tailwind v4 CSS (v4.1.15 and later); a `tailwind.config.js`
  project needs to stay on better-tailwindcss.

## Rules better-tailwindcss doesn't have

Worth a look once you've switched:

<!-- generated:btw-extra -->

[`enforce-negative-arbitrary-values`](/rules/enforce-negative-arbitrary-values) ·
[`enforce-physical`](/rules/enforce-physical) · [`max-class-count`](/rules/max-class-count) ·
[`no-arbitrary-value`](/rules/no-arbitrary-value) ·
[`no-borrowed-component-styles`](/rules/no-borrowed-component-styles) ·
[`no-contradicting-variants`](/rules/no-contradicting-variants) ·
[`no-dark-without-light`](/rules/no-dark-without-light) ·
[`no-default-palette`](/rules/no-default-palette) ·
[`no-hardcoded-colors`](/rules/no-hardcoded-colors) ·
[`no-unnecessary-arbitrary-value`](/rules/no-unnecessary-arbitrary-value) ·
[`prefer-scale-token`](/rules/prefer-scale-token) ·
[`prefer-theme-tokens`](/rules/prefer-theme-tokens)
<!-- /generated:btw-extra -->

---

<!-- https://oxlint-tailwindcss.pages.dev/migration/from-eslint-plugin-tailwindcss.md -->

# Migrating from eslint-plugin-tailwindcss

[eslint-plugin-tailwindcss](https://github.com/francoismassart/eslint-plugin-tailwindcss) is the
ESLint plugin for Tailwind CSS; its 4.x releases read Tailwind v4. oxlint-tailwindcss is built for
oxlint and Tailwind v4. Each of eslint-plugin-tailwindcss 4.4.0's 9 rules has a counterpart here,
and each pair reports the same example — the tables below are checked against it every week, with
its latest release.

## Rules

<!-- generated:eptw-rules -->

| eslint-plugin-tailwindcss            | oxlint-tailwindcss                                                                      | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `classnames-order`                   | [`enforce-sort-order`](/rules/enforce-sort-order)                                       | Both sort by Tailwind's own class order, the one prettier-plugin-tailwindcss uses. `mode: "strict"` also groups classes by variant chain.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `enforces-canonical-classname`       | [`enforce-canonical`](/rules/enforce-canonical)                                         | Both ask Tailwind for the canonical form, but this rule rewrites a class only when the two print the same CSS: `[&>*]:flex-1` → `*:flex-1` (another selector) and `aspect-[16/9]` → `aspect-video` (a theme variable) stay as written. The rest of what theirs folds in has its own rule here: v3 renames (`bg-gradient-to-r`) are `no-deprecated-classes`, `bg-[var(--x)]` → `bg-(--x)` is `enforce-consistent-variable-syntax`, `!p-4` → `p-4!` is `enforce-consistent-important-position`, and `-m-[5px]` → `m-[-5px]` is `enforce-negative-arbitrary-values`. |
| `enforces-negative-arbitrary-values` | [`enforce-negative-arbitrary-values`](/rules/enforce-negative-arbitrary-values)         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `enforces-shorthand`                 | [`enforce-shorthand`](/rules/enforce-shorthand)                                         | Their `overflow-hidden text-ellipsis whitespace-nowrap` → `truncate` has no equivalent here. Four corners or sides become one class at once (`rounded-tl-md rounded-tr-md rounded-br-md rounded-bl-md` → `rounded-md`), where theirs merges them two by two.                                                                                                                                                                                                                                                                                                      |
| `important-modifier-suffix`          | [`enforce-consistent-important-position`](/rules/enforce-consistent-important-position) | The suffix (`p-4!`) is the default here too; `position: "prefix"` asks for `!p-4` instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `no-arbitrary-value`                 | [`no-arbitrary-value`](/rules/no-arbitrary-value)                                       | Off in both recommended configs. Here `allow` tolerates arbitrary values under the prefixes you list (`grid-cols-`), `allowVariables` a value that is only a CSS variable, and the message names the closest values in your theme.                                                                                                                                                                                                                                                                                                                                |
| `no-contradicting-classname`         | [`no-conflicting-classes`](/rules/no-conflicting-classes)                               | Decided from the CSS each class prints, and the message names the class that wins. It also reports a class another one makes redundant (`reportRedundant`), and `allow` exempts pairs. A variant that repeats its base class (`flex hover:flex`) is `no-contradicting-variants`.                                                                                                                                                                                                                                                                                  |
| `no-custom-classname`                | [`no-unknown-classes`](/rules/no-unknown-classes)                                       | `whitelist` → `allowlist` for exact names and `ignorePrefixes` for families (`custom-`); a regular expression that is neither has no counterpart. The classes your CSS defines (`@layer components`, `@utility`) are always known, and a typo gets the closest class as a suggestion.                                                                                                                                                                                                                                                                             |
| `no-unnecessary-arbitrary-value`     | [`no-unnecessary-arbitrary-value`](/rules/no-unnecessary-arbitrary-value)               | This rule rewrites only when the named class prints the same CSS. Theirs also turns a value equal to a scale step or a theme value into its token (`m-[8px]` → `m-2`, `w-[20rem]` → `w-xs`): here that is `prefer-scale-token`, as a suggestion, since the token reads a variable your theme can change. `z-[123]` → `z-123` is `enforce-canonical`.                                                                                                                                                                                                              |

<!-- /generated:eptw-rules -->

## Settings

Both plugins read `settings.tailwindcss`, with different keys:

<!-- generated:eptw-settings -->

| eslint-plugin-tailwindcss | oxlint-tailwindcss                | Notes                                                                                                                                                                                                                                                                                                         |
| ------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cssConfigPath`           | `entryPoint`                      | Required in both. A relative path resolves against the nearest oxlint config here, and against the nearest `eslint.config.*` or `package.json` in theirs. A glob → CSS mapping covers a monorepo.                                                                                                             |
| `attributes`              | `attributes`, `attributePatterns` | Setting theirs replaces its defaults (`class`, `className`, `ngClass`, `@apply`); here `attributes` adds to `class` and `className`, and `attributePatterns` matches names with regular expressions. `ngClass` and `@apply` have nothing to match: oxlint hands JS plugins neither Angular templates nor CSS. |
| `functions`               | `callees`, `tags`                 | Theirs is one list for calls and tagged templates, and setting it replaces the defaults; `callees` and `tags` add to this plugin's. Of their defaults, `classNames(…)` and `tw(…)` as a call aren't read here: add them to `callees` if you use them.                                                         |
| `parseKeyFunctions`       | —                                 | The keys of an object passed to any callee are read as classes (`cn({ "p-4": isOpen })`), and its values aren't. Theirs reads the keys only in these functions (by default `classnames`, `classNames`, `clsx`) and the values elsewhere.                                                                      |
| `ignoredKeys`             | —                                 | `cva` and `tv` configs are read by their structure: `defaultVariants` is skipped, `compoundVariants` and `compoundSlots` are read.                                                                                                                                                                            |
| `cacheMaxSize`            | —                                 | The design system is cached on disk, keyed by the content of your CSS, and rebuilt when it changes: there is nothing to tune.                                                                                                                                                                                 |
| `cacheMaxAge`             | —                                 | Same as `cacheMaxSize`.                                                                                                                                                                                                                                                                                       |

<!-- /generated:eptw-settings -->

## Switching, step by step

1. Install oxlint and the plugin: `pnpm add -D oxlint oxlint-tailwindcss`.
2. Create `.oxlintrc.json` with `"jsPlugins": ["oxlint-tailwindcss"]`, and turn
   `settings.tailwindcss` into this plugin's keys with the settings table: `cssConfigPath` becomes
   `entryPoint`, which is required.
3. Rename each `tailwindcss/<rule>` to the `tailwindcss/<rule>` of the rules table — both plugins
   use the `tailwindcss` prefix. Or start from the [recommended config](/setup) and add what you had
   on top.
4. Remove eslint-plugin-tailwindcss from your ESLint config and uninstall it. Both plugins are named
   `tailwindcss`, so oxlint won't load the two side by side: it stops with
   `Plugin name 'tailwindcss' is already registered`.
5. Run `oxlint`, then `oxlint --fix` for the autofixes.

A typical config, before:

```js
// eslint.config.mjs
import tailwindcss from "eslint-plugin-tailwindcss";
import { defineConfig } from "eslint/config";

export default defineConfig([
  tailwindcss.configs.recommended,
  {
    settings: {
      tailwindcss: {
        cssConfigPath: "./src/styles.css",
        functions: ["cn", "cva", "classNames"],
      },
    },
    rules: {
      "tailwindcss/no-custom-classname": ["warn", { whitelist: ["swiper-.*", "legacy-card"] }],
      "tailwindcss/no-arbitrary-value": "warn",
    },
  },
]);
```

And after, with the rules the recommended config turned on:

```jsonc
// .oxlintrc.json
{
  "jsPlugins": ["oxlint-tailwindcss"],
  "settings": {
    "tailwindcss": { "entryPoint": "src/styles.css", "callees": ["classNames"] }
  },
  "rules": {
    "tailwindcss/enforce-sort-order": "warn",
    "tailwindcss/enforce-canonical": "warn",
    "tailwindcss/enforce-negative-arbitrary-values": "warn",
    "tailwindcss/enforce-shorthand": "warn",
    "tailwindcss/enforce-consistent-important-position": "warn",
    "tailwindcss/no-unknown-classes": [
      "warn",
      { "ignorePrefixes": ["swiper-"], "allowlist": ["legacy-card"] }
    ],
    "tailwindcss/no-conflicting-classes": "error",
    "tailwindcss/no-unnecessary-arbitrary-value": "warn",
    "tailwindcss/no-arbitrary-value": "warn"
  }
}
```

## What else changes

- **Vue and Svelte templates.** Their recommended config lints `.vue` and `.svelte` files, templates
  included, through ESLint's parsers. In oxlint, JS plugins see only the `<script>` blocks of those
  files. See [Vue, Svelte & Astro](/frameworks).
- **Classes in variables.** This plugin also reads the strings assigned to `className`, `classes` or
  `styles` (`variablePatterns`), which theirs leaves alone, so expect reports there too.
- **Tailwind v3.** This plugin reads Tailwind v4 CSS (v4.1.15 and later); a `tailwind.config.js`
  project needs to stay on eslint-plugin-tailwindcss 3.x.

## Rules eslint-plugin-tailwindcss doesn't have

Worth a look once you've switched:

<!-- generated:eptw-extra -->

[`consistent-variant-order`](/rules/consistent-variant-order) ·
[`enforce-consistent-line-wrapping`](/rules/enforce-consistent-line-wrapping) ·
[`enforce-consistent-variable-syntax`](/rules/enforce-consistent-variable-syntax) ·
[`enforce-logical`](/rules/enforce-logical) · [`enforce-physical`](/rules/enforce-physical) ·
[`max-class-count`](/rules/max-class-count) ·
[`no-borrowed-component-styles`](/rules/no-borrowed-component-styles) ·
[`no-contradicting-variants`](/rules/no-contradicting-variants) ·
[`no-dark-without-light`](/rules/no-dark-without-light) ·
[`no-default-palette`](/rules/no-default-palette) ·
[`no-deprecated-classes`](/rules/no-deprecated-classes) ·
[`no-duplicate-classes`](/rules/no-duplicate-classes) ·
[`no-dynamic-classes`](/rules/no-dynamic-classes) ·
[`no-hardcoded-colors`](/rules/no-hardcoded-colors) ·
[`no-restricted-classes`](/rules/no-restricted-classes) ·
[`no-unnecessary-whitespace`](/rules/no-unnecessary-whitespace) ·
[`prefer-scale-token`](/rules/prefer-scale-token) ·
[`prefer-theme-tokens`](/rules/prefer-theme-tokens)
<!-- /generated:eptw-extra -->

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/consistent-variant-order.md -->

# consistent-variant-order

oxlint rule that writes Tailwind CSS variant chains outermost first — `dark:hover:`, not
`hover:dark:` — and rewrites the rest to match, with an autofix.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options               |
| ------- | ------------------ | ---------------------------------------- | --------------------- |
| Yes     | Yes                | Optional — used when `entryPoint` is set | `entryPoint`, `order` |

## What this rule does

Reorders the variant prefixes inside a single class so that the chain is always written the same
way. `hover:dark:bg-red` and `dark:hover:bg-red` produce the same CSS in Tailwind v4, but
inconsistent variant order makes grep, code review, and diffs noisy. This rule picks one canonical
order and rewrites everything to match, with autofix on the first offender and editor suggestions on
the rest.

The order goes from the outside in — the way Tailwind's docs and shadcn/ui write chains:

1. **Where the page is**: breakpoints (`sm` … `2xl`, `min-*`, `max-*`), `supports-*`, `motion-*`,
   `contrast-*`, `forced-colors`, `pointer-*`, `portrait` / `landscape`, `dark`, container queries
   (`@md`, `@min-*`), `print`, `starting`, `ltr` / `rtl`.
2. **Which ancestor or sibling the element sits in**: `group-*`, `peer-*`, `in-*`.
3. **What the element is**: `aria-*`, `data-*`, `has-*`, `not-*`.
4. **How it's being used**: `visited`, `target`, `hover`, `focus`, `focus-within`, `focus-visible`,
   `active`.
5. **Its form state**: `enabled`, `disabled`, `checked`, … `read-only`, `open`, `inert`.
6. **Where it sits among its siblings**: `first`, `last`, `only`, `odd`, `even`, `*-of-type`,
   `nth-*`, `empty`.

Breakpoints among themselves, container queries among themselves, and the variants within step 2 or
within step 3 keep the order you wrote them in, so `data-[a]:data-[b]:` and `data-[b]:data-[a]:` are
both left alone. `not-X` sorts as X (`not-sm:hover:`). A variant the rule has no place for — one
your project defines with `@custom-variant` — is never moved, and nothing is moved across it.

Pseudo-elements (`before`, `after`, `file`, `placeholder`, `selection`, `marker`, `backdrop`,
`first-line`, `first-letter`, `details-content`) are always pinned innermost — closest to the
utility — because in Tailwind v4 a pseudo-element placed before an element-selecting variant
produces broken CSS like `&::before { &>svg { … } }`. Variants that point the selector at another
element (`*`, `**`, `[&>svg]`) are barriers: nothing is reordered across them, because
`hover:[&>svg]:` (`&:hover > svg`) and `[&>svg]:hover:` (`& > svg:hover`) style different elements.

DS-optional — the order is the same with or without `settings.tailwindcss.entryPoint`. What the
design system adds is what your project's own variants are, from the selectors it generates:
`@custom-variant thumb (&::-webkit-slider-thumb)` is pinned innermost like `before:`,
`@custom-variant child (& > *)` becomes a barrier, and a breakpoint you add with `--breakpoint-3xl`
sorts with the others. Without one, the rule uses the fixed lists above, and a missing entry point
is tolerated silently (`no-contradicting-variants` is the other rule that does this).

## Options

### `order`

`string[]`, optional.

Custom priority list, replacing the built-in order. Variants appear in the order you list them;
anything not listed sorts after, in its original position. Use this when your team has a house style
that differs from the default (e.g. you want states before breakpoints). The pseudo-element pin and
the barriers still apply regardless of your list.

```jsonc
{
  "tailwindcss/consistent-variant-order": ["error", { "order": ["hover", "focus", "sm", "md"] }]
}
```

### `entryPoint`

`string`, optional.

Per-rule override of `settings.tailwindcss.entryPoint`. Same semantics as the project-level setting;
almost never needed.

## Examples

### ✗ Incorrect

```tsx
// state before breakpoint
<div className="hover:sm:flex" />
// → <div className="sm:hover:flex" />

// state before color scheme
<div className="hover:dark:text-white" />
// → <div className="dark:hover:text-white" />

// how it's used before what it is
<div className="focus:data-[state=open]:bg-accent" />
// → <div className="data-[state=open]:focus:bg-accent" />

// pseudo-element before an element-selecting variant — broken in Tailwind v4
<div className="before:[&>svg]:text-red-500" />
// → <div className="[&>svg]:before:text-red-500" />
```

### ✓ Correct

```tsx
<div className="sm:hover:flex" />
<div className="dark:hover:text-white" />
<div className="md:peer-data-[variant=inset]:m-2" />
<div className="data-[state=open]:focus:bg-accent" />

// Pseudo-element innermost
<div className="[&>svg]:before:text-red-500" />
<div className="dark:has-[.active]:before:text-red-500" />

// Barriers: both orders target different elements, so both stay
<div className="hover:[&>svg]:w-4" />
<div className="[&>svg]:hover:w-4" />
```

## Interactions with other rules

- **`enforce-sort-order`**: complementary. `enforce-sort-order` sorts whole classes against each
  other; `consistent-variant-order` sorts the prefixes inside one class. Run both.
- **oxfmt's `sortTailwindcss`**: it sorts whole classes and leaves the variant chain inside each
  class as written, so it doesn't replace this rule.
- **`enforce-canonical`**: orthogonal. Canonical normalizes the utility shape (`m-0`,
  `bg-red-500/50`), not the variant chain.
- **`no-unknown-classes`**: when a variant is reordered the resulting class is still semantically
  equivalent, so unknown-class detection doesn't see a difference.

## When to disable it

- **Custom variant order that's hard to express as a flat list** (e.g. order depends on the
  utility): disable and rely on review.
- **Generated code** where variant order encodes meaning you don't want rewritten.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-canonical.md -->

# enforce-canonical

oxlint rule that rewrites Tailwind CSS classes to the canonical form Tailwind itself computes, like
`-m-0` → `m-0`, with an autofix.

## At a glance

| Autofix | Editor suggestions | Design system           | Options                             |
| ------- | ------------------ | ----------------------- | ----------------------------------- |
| Yes     | Yes                | Required (`entryPoint`) | `entryPoint`, `reportNonEquivalent` |

## What this rule does

Asks the design system for the canonical form of every utility in your code and rewrites the ones
that aren't already canonical. "Canonical" is whatever `canonicalizeCandidates()` from
`@tailwindcss/node` returns — the same source of truth used by prettier-plugin-tailwindcss, oxfmt,
and the official Tailwind tooling. Examples: `-m-0` → `m-0` (no negative is needed for a zero),
`start-2` → `inset-s-2`, `flex-grow-[2]` → `grow-2` (an arbitrary value whose named form emits
identical CSS), `text-[var(--color-text)]/90` → `text-(--color-text)/90`. Auto-fix lands the first
hit, suggestions cover the rest in the same string. The v3 renames (`bg-gradient-to-r` →
`bg-linear-to-r`, `break-words` → `wrap-break-word`) are owned by `no-deprecated-classes`, not this
rule — see Interactions.

Named classes resolve through a precomputed in-memory `canonicalMap` (sub-microsecond). Arbitrary
values (`p-[2px]`, `bg-(--c)`) and arbitrary variants (`data-[open]:`, `min-[40rem]:`) go through
the `canonicalize-service` worker because they need a live DS lookup; results are cached
process-wide per `(entryPoint, rem, class)`. The worker preserves the position of `!` (important
prefix vs suffix vs none).

DS-dependent — requires `settings.tailwindcss.entryPoint`. If the design system can't load, the rule
emits a single fatal `designSystemUnavailable` diagnostic per file instead of silently passing.

## Options

### `reportNonEquivalent`

`boolean`, default `false`.

Some canonical forms are **not the same CSS in your project**, and the rule leaves those classes as
written. With this option on, it also tells you about two kinds of them, never with an autofix:

- **A variant your CSS defines differently from stock Tailwind.** shadcn/ui, for instance, ships
  `data-disabled:` as a custom variant built on `:where([data-disabled="true"]), …`, so
  `data-[disabled]:opacity-50` — which stock Tailwind rewrites to `data-disabled:opacity-50` —
  matches different elements here. The report names both variants, and switching is your call.
- **A canonical form that also sets a variable other utilities read.** Tailwind rewrites
  `[line-height:var(--x)]` to `leading-(--x)`, but `leading-(--x)` also sets `--tw-leading`, which
  every `text-*` size reads for its line height, so next to one the two can render differently. The
  same goes for `[border-style:dashed]` → `border-dashed` (`--tw-border-style`, read by `border-2`),
  `[transition-duration:300ms]` → `duration-300` (`--tw-duration`, read by `transition`), and the
  `font-*`, `tracking-*`, `ease-*`, `outline-*` and `content-none` forms. The report names the
  variable and carries a suggestion your editor can apply.

A difference stock Tailwind has too (`has-[[data-slot=x]]:` vs `has-data-[slot=x]:` emit different
selectors anywhere) isn't reported, and neither is a value that reads the theme (`p-[2px]` vs
`p-0.5`, see [`prefer-scale-token`](./prefer-scale-token)). On shadcn/ui's `apps/v4` the option adds
23 reports, all `data-[disabled]:`, and none of the second kind.

```jsonc
{ "tailwindcss/enforce-canonical": ["warn", { "reportNonEquivalent": true }] }
```

### `entryPoint`

`string`, optional. Per-rule override of `settings.tailwindcss.entryPoint`. Configure the entry
point in `settings.tailwindcss.entryPoint` for the whole project instead whenever possible.

## Examples

### ✗ Incorrect

```tsx
// Negative-of-zero is just zero
<div className="-m-0 -mt-0" />
// → <div className="m-0 mt-0" />

// Logical inset shorthand → canonical inset-s-* / inset-e-*
<div className="start-2 end-4" />
// → <div className="inset-s-2 inset-e-4" />

// An arbitrary value whose named form emits identical CSS
<div className="flex-grow-[2]" />
// → <div className="grow-2" />

// Variants and important are preserved
<div className="hover:!flex-grow-[2]" />
// → <div className="hover:!grow-2" />

// Opacity modifiers and arbitrary variants, with or without other variants
<div className="dark:bg-white/[.08] data-[open]:flex min-[40rem]:flex" />
// → <div className="dark:bg-white/8 data-open:flex sm:flex" />

// options: { "reportNonEquivalent": true }
// Not the same CSS: leading-(--x) also sets --tw-leading, which text-* sizes read.
// Reported with a suggestion, never fixed
<div className="[line-height:var(--x)]" />
// → <div className="leading-(--x)" />
```

### ✓ Correct

```tsx
<div className="m-0 mt-0" />

<div className="inset-s-2 inset-e-4" />

<div className="grow-2" />

<div className="hover:!grow-2" />

<div className="dark:bg-white/8 data-open:flex sm:flex" />

<div className="leading-(--x)" />
```

## Interactions with other rules

- **`no-unnecessary-arbitrary-value`**: complementary, no double-fire. Both rewrite an arbitrary
  value to a named utility only when the two emit **identical** CSS; they split on shape.
  `no-unnecessary-arbitrary-value` owns the cases where the arbitrary maps directly to a single
  named utility (e.g. `h-[auto]` → `h-auto`). A value that is only _numerically_ equal to a scale
  step (`p-[2px]` → `p-0.5`, whose CSS text differs) is neither rule's business — that is
  `prefer-scale-token`, report-only.
- **`prefer-theme-tokens`**: the third partner of the arbitrary→named trio. It catches CSS-var
  references like `border-(--border)` → `border-border` where neither `enforce-canonical` (the CSS
  differs) nor `no-unnecessary-arbitrary-value` (no shared bracket equivalent) would fire.
- **`no-deprecated-classes`**: **it owns the v3 renames, and this rule skips them.** Tailwind
  canonicalizes them too, so `bg-gradient-to-r` → `bg-linear-to-r` used to be reported twice with
  the same fix; the other rule's message ("deprecated in v4") is the more actionable of the two.
  What stays here is everything that is current-but-not-canonical: `-m-0` → `m-0`, `start-2` →
  `inset-s-2`, and arbitrary-valued forms like `flex-grow-[2]` → `grow-2` (the rename list holds
  spellings, not values). Keep both rules on — with only this one enabled the renames go unreported.
- **`prefer-scale-token`**: the report-only half of what this rule gave up in #78. A rewrite whose
  emitted CSS differs textually (`p-[10px]` → `p-2.5`, where the token resolves through
  `var(--spacing)`) is not autofixed here and never will be; that rule reports it with a suggestion
  instead. The two can never both fire: this one only rewrites byte-identical pairs, which is
  exactly what the other one skips.
- **`enforce-consistent-important-position`**: this rule preserves the `!` position you wrote
  (prefix vs suffix vs none). `enforce-consistent-important-position` is the single source of truth
  for enforcing a particular position.

## When to disable it

- **You don't want any class rewrites at all** — for example, in a legacy file you're keeping
  verbatim for diffing.
- **Performance-sensitive lint runs** where the worker initialization cost is unwelcome. The cache
  makes subsequent runs cheap, but the first hit pays for `@tailwindcss/node` startup. Most projects
  will not notice.
- **You haven't migrated to Tailwind v4 yet**: the canonical forms produced here assume v4
  semantics.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-consistent-important-position.md -->

# enforce-consistent-important-position

oxlint rule that puts the Tailwind CSS important modifier in one position — suffix `flex!` (the v4
form) or prefix `!flex` — and fixes the rest.

## At a glance

| Autofix | Editor suggestions | Design system | Options    |
| ------- | ------------------ | ------------- | ---------- |
| Yes     | Yes                | Not used      | `position` |

## What this rule does

Tailwind v4 supports two syntaxes for the `!important` modifier: prefix (`!flex`, the v3-era form)
and suffix (`flex!`, the v4 canonical form). Both produce the same CSS, but mixing them inside one
project makes the codebase look inconsistent and breaks copy-paste between files. This rule picks
one position and rewrites every offender to match. Autofix on the first hit per location, editor
suggestion on subsequent hits.

DS-independent — works without `settings.tailwindcss.entryPoint`. It's a pure string transform, so
it runs everywhere, including in projects that haven't wired up the design system yet.

## Options

### `position`

`'prefix' | 'suffix'`, default `'suffix'`.

`'suffix'` is the Tailwind v4 canonical form (`flex!`, `hover:text-red!`), so it's the recommended
choice for new projects. `'prefix'` keeps the v3 form (`!flex`, `hover:!text-red`) — pick it only if
your codebase is still on the v3 spelling and you don't want to migrate yet.

```jsonc
{ "tailwindcss/enforce-consistent-important-position": ["error", { "position": "suffix" }] }
```

Note: `enforce-canonical` preserves whichever `!` position you write (it does not normalize it), so
either `position` value composes with it cleanly. This rule is the single source of truth for `!`
placement.

## Examples

### ✗ Incorrect

```tsx
// Default suffix: prefix is reported
<div className="!font-bold" />
//              ~~~~~~~~~~  → font-bold!

// Same with a variant chain
<div className="hover:!text-red" />
//              ~~~~~~~~~~~~~~~  → hover:text-red!

// Multiple offenders in one string
<div className="!font-bold !text-red" />
//              ~~~~~~~~~~ ~~~~~~~~~  → font-bold! text-red!
```

### ✓ Correct

```tsx
// Default (suffix)
<div className="font-bold!" />
<div className="hover:text-red!" />
<div className="font-bold! text-red!" />

// No important — rule doesn't touch normal classes
<div className="flex items-center" />
```

## Interactions with other rules

- **`enforce-canonical`**: preserves the `!` position you write (prefix, suffix, or none) rather
  than normalizing it, so it never fights this rule no matter which `position` you pick. This rule
  is the single source of truth for `!` placement.
- **`enforce-sort-order`**: order-independent of important position. Both prefix and suffix forms
  sort identically.
- **`no-unknown-classes`**: looks up the bare utility, stripping `!` on either side, so neither form
  trips it.

## When to disable it

- **The codebase deliberately mixes both forms** (e.g. legacy v3 files alongside fresh v4 ones
  during a migration). Re-enable once the migration is done.
- **You don't care about `!` position consistency.** No other rule enforces it — `enforce-canonical`
  preserves whatever position you wrote — so disabling this one means `!` placement goes unchecked.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-consistent-line-wrapping.md -->

# enforce-consistent-line-wrapping

oxlint rule that reports Tailwind CSS class strings over a print width or a classes-per-line budget,
and can wrap them onto several lines.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options                                                                           |
| ------- | ------------------ | ---------------------------------------- | --------------------------------------------------------------------------------- |
| Yes     | No                 | Optional — used when `entryPoint` is set | `entryPoint`, `printWidth`, `classesPerLine`, `wrapLines`, `group`, `wrapStrings` |

## What this rule does

Flags long class strings so they don't sprawl past a sensible line length and, when you opt in,
wraps them into multiple lines. Two independent formatting modes: a width-based re-wrap (opt-in via
`wrapLines`) and a class-count budget per line (`classesPerLine`), both autofixing template literals
and, with `wrapStrings`, string literals too: a JSX attribute's own string in place (`"jsx"`), and a
JS string turned into a template (`"all"`). Otherwise string literals only report — a JS string
can't span lines.

DS-optional — works without `settings.tailwindcss.entryPoint`. The rule operates on the raw class
string and doesn't care what the classes mean, with one exception: when a design system **is**
available, the `wrapLines: "all"` grouping consults it for the Tailwind v4 project prefix
(`@import "tailwindcss" prefix(tw)`) so the prefix is transparent to grouping — `tw:flex` groups as
a base utility and `tw:hover:x` as `hover:`. Without an entry point the rule silently falls back to
treating the prefix as part of the variant chain (it never reports a missing design system).

Both fixers wrap template literals into the **block convention**: the content starts on its own
line, each wrapped line is indented one level below the statement's own indentation, and the closing
backtick (or quote, for a JSX attribute string) sits on its own line. The base indentation is read
from the source line (not the backtick column), so the block nests correctly even inside
deeply-indented JSX. The `classesPerLine` fix and the `"overWidth"` width fix are
**non-destructive** — a template that is already wrapped only has its over-budget lines re-wrapped;
conforming lines are left untouched. The `"all"` width fix is a **full re-layout**: it lays the
whole template out in the canonical variant-grouped form, replacing any hand layout (which is why
it's a separate, explicit mode). Other rules (`no-unnecessary-whitespace`, `enforce-sort-order`, …)
are aware of this multiline shape and won't collapse it back.

## Options

### `printWidth`

`number`, default `80`.

Maximum length of any **single line** of the class string. For a one-line string that is its whole
length; for a multiline template it is the longest individual line, so splitting a long string
across lines can actually satisfy the rule. A line whose single class alone exceeds the width is not
reported — it can't be wrapped any shorter.

On its own, `printWidth` is **warn-only**: it reports `tooLong` and never rewrites your code. The
autofix is opt-in via `wrapLines`.

```jsonc
{ "tailwindcss/enforce-consistent-line-wrapping": ["error", { "printWidth": 100 }] }
```

### `wrapLines`

`"overWidth" | "all"`, optional. No default — like `classesPerLine`, leaving it unset means the
fixer is off and `printWidth` only reports.

Turns on the **width-based autofix** for template literals. The two modes differ in both reach and
layout:

- `"overWidth"`: only the **lines** that actually exceed `printWidth` are re-wrapped — each is
  greedily packed into the fewest lines that fit the budget (no variant grouping), reusing the
  line's own indentation. Everything else is left verbatim: templates whose lines all fit, and the
  conforming lines of a template that does get touched, keep their hand-formatted layout. A
  single-line template has no layout to preserve, so it converts to the block convention.
- `"all"`: **every** multiline (or over-width) template is normalized to a canonical layout,
  mirroring `eslint-plugin-better-tailwindcss`'s fixer: classes are grouped into runs sharing a
  variant chain (`hover:`, `md:hover:`, or none), and within a run classes are packed onto a line
  until adding the next would exceed `printWidth` (indentation included). How the runs are separated
  is controlled by `group` (below). Within-budget templates that don't match that layout report
  `inconsistentWrapping`.

In a JS string literal (`cn("…")`, `className={"…"}`, a variable) the rule reports `tooLong` without
a fix by default: a JS string can't hold a raw newline, and turning it into a multiline template
changes the string's value, so that is opt-in — see `wrapStrings`, which can also wrap a JSX
attribute's own string as it is. A template fragment **glued** to a `${}` with no whitespace
(`` `${a}flex …` `` — one runtime class) is never autofixed: any whitespace introduced at the
boundary would split that class in two.

Around an interpolation, the `"all"` layout puts the class run bordering a `${}` on its **own fresh
line** (never hanging inline after the expression), so every rewritten line stays within
`printWidth`. One caveat: the width of the `${…}` expression itself is opaque to the rule, which
measures each static fragment on its own. So a single physical line you hand-write with a short
fragment beside a wide interpolation can still exceed `printWidth` without being reported.

`wrapLines` only applies when `classesPerLine` is **not** set — `classesPerLine` owns the layout
otherwise.

```jsonc
{
  "tailwindcss/enforce-consistent-line-wrapping": [
    "error",
    { "printWidth": 100, "wrapLines": "overWidth" },
  ],
}
```

### `group`

`"newLine" | "emptyLine" | "never"`, default `"newLine"`.

How the `wrapLines: "all"` layout separates variant groups. Matches
`eslint-plugin-better-tailwindcss`'s `group` option (same name, values, and default), so a migrated
config carries over unchanged.

- `"newLine"` (default): each variant run starts its own line.
- `"emptyLine"`: additionally, a **blank line** separates the runs (the blank lines carry no
  trailing whitespace, and `no-unnecessary-whitespace` preserves them).
- `"never"`: no grouping — classes are packed greedily across run boundaries into the fewest lines
  that fit `printWidth`.

`group` only shapes the `"all"` layout: `"overWidth"` deliberately never re-groups (it only splits
over-budget lines), and the `classesPerLine` fixer chunks by count, so both ignore it.

```jsonc
{
  "tailwindcss/enforce-consistent-line-wrapping": [
    "error",
    { "printWidth": 100, "wrapLines": "all", "group": "emptyLine" },
  ],
}
```

### `classesPerLine`

`number`, optional. No default.

Maximum number of classes on a single line. When exceeded inside a template literal (`` `…` ``), the
rule autofixes by wrapping the classes into the block convention, chunks of `classesPerLine` per
line. Inside a string literal the rule reports `tooManyPerLine` without a fix, unless `wrapStrings`
covers it.

Setting `classesPerLine` switches the template-literal fixer to this chunk-based mode and turns the
width-based (variant-grouped) fixer off — `printWidth` then only reports, and `wrapLines` is
ignored.

```jsonc
{ "tailwindcss/enforce-consistent-line-wrapping": ["error", { "classesPerLine": 5 }] }
```

### `wrapStrings`

`"never" | "jsx" | "all"`, default `"never"`.

Which string literals the fixers may wrap, besides template literals. Both `wrapLines` and
`classesPerLine` apply, and a file with CRLF line endings gets CRLF breaks.

With `"jsx"`, a JSX attribute's own string — `className="…"`, or any attribute the plugin reads — is
wrapped in place into the block convention, the closing quote at the attribute line's indentation:

```tsx
<div
  className="
    flex items-center justify-between rounded-md px-3 py-1
    text-sm shadow-md
  "
/>
```

That is valid JSX as written: in a class attribute the newlines are plain whitespace, so nothing is
converted — it's the layout `eslint-plugin-better-tailwindcss` writes. A JS string —
`className={"…"}`, `cn("…")`, a variable — can't hold a raw newline, so with `"jsx"` it keeps
reporting without a fix.

With `"all"`, the JSX string is wrapped the same way, and a JS string is turned into a template
literal with the block layout, as `eslint-plugin-better-tailwindcss` does: in a call (`cn("…")`), in
`className={"…"}`, in an array, as an object value (`cva`, `tv`), in a ternary or `&&` branch, and
as a variable's value.

```tsx
const card = cn(`
  flex items-center justify-between rounded-md px-3 py-1
  text-sm shadow-md
`)
```

An object key (`cn({ "…": isActive })`) and a `+` operand are never turned into a template, and
neither is a string holding an escape sequence, a backtick or `${`, which a template reads
differently: those keep reporting without a fix. The string's value gains the newlines and the
indentation. In a class list that is whitespace, but if your code uses a class string as something
else — splits or compares a variable that `variablePatterns` matches — stay on `"jsx"`.

If oxfmt formats your files with `sortTailwindcss`, set its `preserveWhitespace: true`: by default
it collapses the whitespace in class strings, a JSX attribute's and a helper's template alike, the
block's line breaks included, and the two undo each other (see [/interop](/interop)).

```jsonc
{
  "tailwindcss/enforce-consistent-line-wrapping": [
    "error",
    { "printWidth": 100, "wrapLines": "overWidth", "wrapStrings": "all" },
  ],
}
```

### `entryPoint`

`string`, optional.

Per-rule override of `settings.tailwindcss.entryPoint`. The rule consults the design system only for
the Tailwind v4 project prefix, and only under `wrapLines: "all"` with `group` `"newLine"` or
`"emptyLine"` (see above); everywhere else it has no effect. Almost never needed.

## Examples

### ✗ Incorrect

```tsx
// Exceeds default printWidth of 80 characters — reports; without `wrapLines` there is no autofix
<div className="flex items-center justify-between p-4 m-2 bg-white text-black rounded shadow-lg border w-full" />
//              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ tooLong

// 6 classes with classesPerLine: 3 — template literal autofixes into a block
// options: { "classesPerLine": 3 }
const className = `flex items-center justify-between p-4 m-2 bg-white`
// → const className = `
//     flex items-center justify-between
//     p-4 m-2 bg-white
//   `

// Same count in a JSX string — reports; without wrapStrings: "jsx" there is no autofix
// options: { "classesPerLine": 3 }
<div className="flex items-center justify-between p-4 m-2 bg-white" />

// The same JSX string with wrapStrings: "jsx" — wrapped in place, between the quotes
// options: { "classesPerLine": 3, "wrapStrings": "jsx" }
<div className="flex items-center justify-between p-4 m-2 bg-white" />
// → <div className="
//     flex items-center justify-between
//     p-4 m-2 bg-white
//   " />

// A JS string with wrapStrings: "all" — turned into a template literal
// options: { "classesPerLine": 3, "wrapStrings": "all" }
const card = cn("flex items-center justify-between p-4 m-2 bg-white")
// → const card = cn(`
//     flex items-center justify-between
//     p-4 m-2 bg-white
//   `)

// printWidth: 40 with wrapLines: "overWidth" — ONLY the over-budget
// line is re-wrapped; the conforming lines around it stay exactly as written
// options: { "printWidth": 40, "wrapLines": "overWidth" }
const className = `
  flex hover:underline
  items-center justify-between gap-4 rounded-lg p-6
  focus:outline-none
`
// → const className = `
//     flex hover:underline
//     items-center justify-between gap-4
//     rounded-lg p-6
//     focus:outline-none
//   `

// printWidth: 40 with wrapLines: "all" — full re-layout, grouped by variant
// options: { "printWidth": 40, "wrapLines": "all" }
const className = `flex items-center gap-2 hover:bg-red-500 hover:underline focus:outline-none`
// → const className = `
//     flex items-center gap-2
//     hover:bg-red-500 hover:underline
//     focus:outline-none
//   `
```

### ✓ Correct

```tsx
// Fits within printWidth
<div className="flex items-center p-4" />

// Already wrapped at classesPerLine (block convention)
const className = `
  flex items-center p-4
  bg-white text-black
`

// Hand-formatted multiline template, every line within printWidth — untouched
// when wrapLines is unset or "overWidth"; only "all" re-groups it
const className = `
  flex hover:underline
  items-center
`

// A JSX string already in the block convention
// options: { "classesPerLine": 3, "wrapStrings": "jsx" }
<div className="
  flex items-center p-4
  bg-white text-black
" />
```

## Interactions with other rules

- **`no-unnecessary-whitespace`**: deliberately preserves the `\n` + indent introduced by this rule.
  The two were designed to coexist; without that preservation, fixers would oscillate (issue #14).
- **`enforce-sort-order`**: rebuilds class strings from a token list via `rebuildClassString`, which
  keeps the multiline separators. The sort fixer and the wrap fixer run on the same string without
  fighting. The width fixer never reorders classes — it only chooses where the line breaks go — so
  sorting stays entirely `enforce-sort-order`'s job.
- **All extractor-driven rules**: `splitClassesWithSeparators` is multiline-aware, so every other
  rule (`enforce-canonical`, `enforce-shorthand`, …) reports against multiline class strings the
  same way it does against single-line ones.

## When to disable it

- **You let `prettier` handle JSX line wrapping**: prettier breaks at the JSX-attribute level, not
  inside the string. The two are complementary, but if you don't want any in-string wrapping at all,
  disable.
- **Working with code generators** that emit very long class strings intentionally (e.g. CMS-driven
  content classes).
- **You use a different convention** like "always one class per line": this rule's chunk-based
  wrapping doesn't model that.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-consistent-variable-syntax.md -->

# enforce-consistent-variable-syntax

oxlint rule that writes Tailwind CSS variable values one way — shorthand `bg-(--primary)` or
`bg-[var(--primary)]` — and rewrites the other form.

## At a glance

| Autofix | Editor suggestions | Design system | Options  |
| ------- | ------------------ | ------------- | -------- |
| Yes     | Yes                | Not used      | `syntax` |

## What this rule does

Tailwind v4 added a shorthand for arbitrary CSS variable values: `bg-(--primary)` is sugar for
`bg-[var(--primary)]`. Both produce the same CSS. This rule picks one of the two syntaxes and
rewrites every class that uses the other. Autofix on the first offender per location, editor
suggestion on subsequent ones.

The rule only touches the simple `something-[var(--name)]` ↔ `something-(--name)` pair. Complex
expressions like `bg-[color-mix(in_srgb,var(--primary),transparent)]` are left alone — they don't
have a shorthand form. Important modifier (`!flex` / `flex!`) and variant chains (`hover:`, `dark:`)
round-trip correctly.

DS-independent — works without `settings.tailwindcss.entryPoint`. Pure string transform on the
utility shape; no design-system lookup.

## Options

### `syntax`

`'shorthand' | 'explicit'`, default `'shorthand'`.

`'shorthand'` rewrites `bg-[var(--primary)]` → `bg-(--primary)`. This is the Tailwind v4 idiomatic
form and the recommended choice for new projects. `'explicit'` rewrites the other direction —
`bg-(--primary)` → `bg-[var(--primary)]` — useful if you still target older tooling or if your team
prefers the longer form for grepability.

```jsonc
{ "tailwindcss/enforce-consistent-variable-syntax": ["error", { "syntax": "shorthand" }] }
```

## Examples

### ✗ Incorrect

```tsx
// Default shorthand — explicit form is reported
<div className="bg-[var(--primary)]" />
//              ~~~~~~~~~~~~~~~~~~~  → bg-(--primary)

// With a variant chain
<div className="dark:hover:text-[var(--color)]" />
//              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  → dark:hover:text-(--color)

// With important modifier
<div className="!bg-[var(--primary)]" />
//              ~~~~~~~~~~~~~~~~~~~~  → !bg-(--primary)
```

### ✓ Correct

```tsx
// Shorthand (default)
<div className="bg-(--primary) text-(--text-color)" />

// Variants and important round-trip cleanly
<div className="hover:bg-(--primary) font-bold!" />

// Complex expressions are NOT rewritten
<div className="bg-[color-mix(in_srgb,var(--primary),transparent)]" />
```

## Interactions with other rules

- **`enforce-canonical`**: this rule is the single owner of variable syntax. Because `bg-(--x)` is
  Tailwind's canonical form, `enforce-canonical` would otherwise report the same `bg-[var(--x)]` →
  `bg-(--x)` swap; instead it **cedes** the plain bracket↔paren conversion to this rule (the same
  way it cedes v3 renames to `no-deprecated-classes`). That prevents a duplicate diagnostic and,
  when this rule is set to `explicit`, an autofix fight. `enforce-canonical` still handles variable
  canonicalizations that _aren't_ a plain swap — a value that maps to a named token
  (`rounded-[var(--radius-sm)]` → `rounded-sm`) or an opacity-modifier form
  (`text-[var(--color-text)]/90` → `text-(--color-text)/90`).
- **`no-unnecessary-arbitrary-value`**: mostly disjoint — it converts an arbitrary value to its
  named equivalent (`bg-[#ff0000]` → `bg-red-500`). They overlap only when a variable's value
  matches a named utility: on `bg-[var(--color-red-500)]` that rule fires (→ `bg-red-500`) and this
  one fires too (→ `bg-(--color-red-500)`). The two propose different targets, so enable the one
  whose policy you want — or run `no-unnecessary-arbitrary-value` first if you prefer the named
  utility.
- **`prefer-theme-tokens`**: when a CSS variable matches a `@theme` token, that rule swaps to the
  named utility (`bg-(--primary)` → `bg-primary` if `--primary` is declared in `@theme`). Run that
  one before this one if you want both transforms.

## When to disable it

- **You target tooling older than Tailwind v4**: the shorthand form isn't supported. Set
  `syntax: 'explicit'` instead of disabling, so you get the rewrite in the safe direction.
- **Mixed-syntax codebase mid-migration** where consistency isn't yet the goal.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-logical.md -->

# enforce-logical

oxlint rule that rewrites physical Tailwind CSS utilities into logical, RTL-friendly ones, like
`ml-4` → `ms-4` and `pr-2` → `pe-2`, with an autofix.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options                                          |
| ------- | ------------------ | ---------------------------------------- | ------------------------------------------------ |
| Yes     | Yes                | Optional — used when `entryPoint` is set | `allowlist`, `direction`, `sizing`, `entryPoint` |

## What this rule does

Rewrites physical-direction Tailwind utilities into their logical, writing-mode aware equivalents:
`ml-4` → `ms-4`, `pr-2` → `pe-2`, `left-0` → `inset-s-0`, `rounded-tl-md` → `rounded-ss-md`, and on
the block axis `mt-4` → `mbs-4`, `top-0` → `inset-bs-0`, `border-b` → `border-be`. Logical utilities
resolve to `margin-inline-start` / `padding-block-end` / … in CSS, so they follow the writing
direction without any extra code: required if your app ships in Arabic, Hebrew, Farsi, or any other
RTL language, and the block axis also follows a vertical writing mode. Autofix on the first offender
per location, editor suggestion on subsequent ones.

| Physical                                                        | Logical                                                         | Axis                  |
| --------------------------------------------------------------- | --------------------------------------------------------------- | --------------------- |
| `ml` / `mr`, `pl` / `pr`                                        | `ms` / `me`, `ps` / `pe`                                        | inline                |
| `scroll-ml` / `scroll-mr`, `scroll-pl` / `scroll-pr`            | `scroll-ms` / `scroll-me`, `scroll-ps` / `scroll-pe`            | inline                |
| `left` / `right`                                                | `inset-s` / `inset-e` (`start` / `end` before 4.2)              | inline                |
| `border-l` / `border-r`                                         | `border-s` / `border-e`                                         | inline                |
| `rounded-l` / `rounded-r`, `rounded-tl` / `-tr` / `-bl` / `-br` | `rounded-s` / `rounded-e`, `rounded-ss` / `-se` / `-es` / `-ee` | inline                |
| `float-`, `clear-`, `text-` `left` / `right`                    | `float-`, `clear-`, `text-` `start` / `end`                     | inline                |
| `mt` / `mb`, `pt` / `pb`                                        | `mbs` / `mbe`, `pbs` / `pbe`                                    | block                 |
| `scroll-mt` / `scroll-mb`, `scroll-pt` / `scroll-pb`            | `scroll-mbs` / `scroll-mbe`, `scroll-pbs` / `scroll-pbe`        | block                 |
| `top` / `bottom`                                                | `inset-bs` / `inset-be`                                         | block                 |
| `border-t` / `border-b`                                         | `border-bs` / `border-be`                                       | block                 |
| `w`, `min-w`, `max-w`                                           | `inline`, `min-inline`, `max-inline`                            | inline, with `sizing` |
| `h`, `min-h`, `max-h`                                           | `block`, `min-block`, `max-block`                               | block, with `sizing`  |
| `size`                                                          | `inline` + `block`                                              | both, with `sizing`   |

`rounded-t-*` / `rounded-b-*` have no block-axis counterpart (Tailwind has no `rounded-bs`), so they
are left alone.

The table also covers the three utilities where the direction is the VALUE rather than part of the
property: `float-left` → `float-start` (`float: inline-start`), `clear-left` → `clear-start`, and
`text-left` → `text-start` (`text-align: start`). Miss those and a codebase can be "fully converted"
and still float things to the left in RTL.

The block axis, logical sizing and `inset-s-*` / `inset-e-*` shipped in Tailwind 4.2. With a design
system the rule checks that your Tailwind has them: on 4.1 it leaves the block axis alone and writes
`start-0` for `left-0`. Without `settings.tailwindcss.entryPoint` there is nothing to check against,
so it writes `start-0` and only **suggests** the block-axis rewrites, never autofixes them.

DS-independent in the sense that matters: the mapping table is static and the rule works without an
entry point. When one IS configured, the rule also checks that the class it suggests exists — a
project with its own `@utility ml-huge` used to be autofixed to `ms-huge`, which emits no CSS at
all, so the fix applied and the margin silently disappeared.

`enforce-logical` and `enforce-physical` are sibling rules — they share a mapping table that one
inverts. Enable **only one at a time**.

## Options

### `direction`

`'inline' | 'block' | 'both'`, default `'both'`.

Restricts conversion to one axis. `'inline'` converts left and right (`ml-*`, `left-*`, `border-r`,
`float-left`, …), the part that matters for RTL. `'block'` converts top and bottom (`mt-*`, `top-*`,
`border-b`, …), which only differ from their logical forms in a vertical writing mode. A codebase
converted for RTL that never sets text vertically can keep `'inline'`.

```jsonc
{ "tailwindcss/enforce-logical": ["error", { "direction": "inline" }] }
```

### `sizing`

`boolean`, default `false`.

Also converts widths and heights: `w-*` → `inline-*`, `h-*` → `block-*`, their `min-` / `max-`
forms, and `size-*` → `inline-* block-*`. Off by default: sizes are in nearly every class string,
and a width equals an inline size in every horizontal writing mode, RTL included. It follows
`direction` — `w-*` is inline, `h-*` block, and `size-*` needs both.

Some sizes have no logical counterpart and are left alone: a width in viewport heights (`w-dvh`) or
a height in viewport widths (`h-dvw`), `max-w-prose`, and `max-w-screen-*`. With a design system a
named value is converted only when the two classes declare the same thing: `w-*` reads `--width-*`
first and `inline-*` only `--container-*`, so if your theme defines `--width-xs`, `w-xs` and
`inline-xs` differ and `w-xs` stays as written.

```jsonc
{ "tailwindcss/enforce-logical": ["error", { "sizing": true }] }
```

### `allowlist`

`string[]`, default `[]`.

Regex patterns (compiled lazily, invalid ones silently skipped). Classes whose full string matches
any pattern bypass the rewrite. Use this for one-off cases where you genuinely want a physical
direction — e.g. an icon that should always sit on the visual left regardless of writing direction.

```jsonc
{ "tailwindcss/enforce-logical": ["error", { "allowlist": ["^ml-icon$", "^rounded-tl-special$"] }] }
```

### `entryPoint`

`string`, optional. A CSS entry point for this rule alone, overriding
`settings.tailwindcss.entryPoint`. Only used to confirm that the class being suggested exists and
that your Tailwind has the 4.2 utilities; the rule works without it.

## Examples

### ✗ Incorrect

```tsx
// Physical margins/padding
<div className="ml-4 pr-2" />
//              ~~~~ ~~~~  → ms-4 pe-2

// The direction as a VALUE
<div className="float-left clear-right text-left" />
//              ~~~~~~~~~~ ~~~~~~~~~~~ ~~~~~~~~~ → float-start clear-end text-start

// Positioning
<div className="left-0 right-0" />
//              ~~~~~~ ~~~~~~~  → inset-s-0 inset-e-0

// Borders and radii
<div className="border-l rounded-tl-md" />
//              ~~~~~~~~ ~~~~~~~~~~~~~  → border-s rounded-ss-md

// The block axis
<div className="mt-4 top-0 border-b" />
//              ~~~~ ~~~~~ ~~~~~~~~  → mbs-4 inset-bs-0 border-be

// options: { "sizing": true }
// Sizes
<div className="w-full h-screen size-4" />
//              ~~~~~~ ~~~~~~~~ ~~~~~~  → inline-full block-screen inline-4 block-4
```

### ✓ Correct

```tsx
// Logical equivalents
<div className="ms-4 pe-2" />
<div className="inset-s-0 inset-e-0" />
<div className="border-s rounded-ss-md" />
<div className="mbs-4 inset-bs-0 border-be" />

// Already logical — variants and important round-trip cleanly
<div className="hover:ms-4 ps-(--gutter) me-4!" />

// options: { "direction": "inline" }
// Only the inline axis: the block axis is left as written
<div className="mt-4 top-0" />
```

## Interactions with other rules

- **`enforce-physical`**: the inverse. They share the mapping table; enabling both at the same time
  will autofix in a loop. Pick one based on whether your app supports RTL (use `enforce-logical`) or
  is LTR-only (use `enforce-physical`).
- **`enforce-canonical`**: it agrees on the logical insets. On Tailwind 4.2+ this rule writes
  `inset-s-2`, the spelling the design system reports as canonical; `start-2` (what it writes
  without a design system, or on 4.1) is rewritten to `inset-s-2` by `enforce-canonical`. Same CSS
  either way, and `enforce-physical` converts both spellings back.
- **`enforce-shorthand`**: both rewrite pairs of sides. `mt-2 mb-2` is a block-axis pair to this
  rule and `my-2` to that one; `enforce-shorthand` also folds the logical pairs this rule writes
  (`mbs-2 mbe-2` → `my-2`, `inset-s-0 inset-e-0` → `inset-x-0`), so whichever fix lands first the
  string ends as `my-2`, which is already logical (`margin-block`). With `sizing`, `w-4 h-4` ends as
  `inline-4 block-4` either way: `enforce-shorthand` never folds that pair into `size-4`. The one
  combination that can end two ways is `direction: 'inline'` with `sizing`: `w-4 h-4` becomes
  `size-4` or `inline-4 h-4` depending on which fix runs first.

## When to disable it

- **LTR-only applications** where you're sure RTL will never be needed. Use `enforce-physical`
  instead if you want consistency in the other direction.
- **Pixel-perfect layouts where physical direction is part of the design** (rare, but happens with
  icons or decoration). Reach for `allowlist` before disabling globally.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-negative-arbitrary-values.md -->

# enforce-negative-arbitrary-values

oxlint rule that moves the negative sign into Tailwind CSS arbitrary values, like `-top-[5px]` →
`top-[-5px]`, with an autofix.

## At a glance

| Autofix | Editor suggestions | Design system | Options |
| ------- | ------------------ | ------------- | ------- |
| Yes     | Yes                | Not used      | None    |

## What this rule does

Detects utilities written with a negative prefix outside an arbitrary value bracket — `-top-[5px]`,
`-translate-x-[10px]`, `-mt-[8px]` — and rewrites the negative sign into the bracket: `top-[-5px]`,
`translate-x-[-10px]`, `mt-[-8px]`. The outer `-` is redundant once you have an arbitrary value, and
moving it inside makes the intent explicit and matches how `@tailwindcss/node` canonicalizes the
same shape. Auto-fix lands the first hit, suggestions cover the rest in the same string. Variants
(`hover:-mt-[8px]`) and `!` (important, prefix or suffix) are preserved.

The rule only fires when both conditions hold: the utility starts with `-` (after stripping `!`) AND
there is an arbitrary value bracket whose inner content does **not** already start with `-`. So
`top-[-5px]` and `-translate-x-1` (no brackets) are both correct as written.

Pure string transform — no design system, no worker, no entry point. This is the only rule in the
Modernization bucket that does not load the DS. It will run identically whether or not
`settings.tailwindcss.entryPoint` is configured.

## Options

This rule has no options. It applies the same transformation everywhere.

## Examples

### ✗ Incorrect

```tsx
// Negative outside brackets — move it inside
<div className="-top-[5px] -left-[10px]" />
// → <div className="top-[-5px] left-[-10px]" />

// Transform with arbitrary value
<div className="-translate-x-[10px]" />
// → <div className="translate-x-[-10px]" />

// Variant prefix preserved
<div className="hover:-mt-[8px]" />
// → <div className="hover:mt-[-8px]" />

// Important modifier preserved
<div className="!-top-[5px]" />
// → <div className="!top-[-5px]" />
```

### ✓ Correct

```tsx
// Negative is inside the bracket
<div className="top-[-5px] left-[-10px]" />

<div className="translate-x-[-10px]" />

<div className="hover:mt-[-8px]" />

<div className="!top-[-5px]" />

// Negative without arbitrary value — fine
<div className="-translate-x-1 -mt-4" />
```

## Interactions with other rules

- **`enforce-canonical`**: complementary. `enforce-canonical` will also normalize the canonical form
  of negative arbitraries through the worker; this rule provides the same fix without paying the DS-
  load cost. If both are enabled the autofixes converge on the same output.
- **`no-unnecessary-arbitrary-value`**: orthogonal. That rule only fires when the arbitrary value
  has a named equivalent; this one fires whether or not it does.
- **`prefer-theme-tokens`**: orthogonal. Theme-token references (`bg-(--name)`) don't carry an outer
  negative, so the two never touch the same class.

## When to disable it

- **You prefer the outer-negative form for readability** at the call site (rare — most teams find
  the inner-negative form clearer once they see it).
- **You're auto-generating class strings** that always emit the outer- negative form and you don't
  want lint diagnostics in that generated layer. Prefer disabling the rule in the generated file
  rather than project-wide.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-physical.md -->

# enforce-physical

oxlint rule for LTR-only projects that rewrites logical Tailwind CSS utilities into physical ones,
like `ms-4` → `ml-4` — the mirror of `enforce-logical`.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options                                          |
| ------- | ------------------ | ---------------------------------------- | ------------------------------------------------ |
| Yes     | Yes                | Optional — used when `entryPoint` is set | `allowlist`, `direction`, `sizing`, `entryPoint` |

## What this rule does

The mirror of `enforce-logical`. Rewrites logical, writing-direction aware utilities (`ms-4`,
`pe-2`, `inset-s-0`, `rounded-ss-md`, and on the block axis `mbs-4`, `inset-bs-0`, `border-be`, …)
into their physical equivalents (`ml-4`, `pr-2`, `left-0`, `rounded-tl-md`, `mt-4`, `top-0`,
`border-b`, …). Use this in LTR-only codebases where logical utilities add cognitive overhead
without a payoff — `ml-4` is more direct than `ms-4` when there's no RTL story. Autofix on the first
offender per location, editor suggestion on subsequent ones. The mapping is `enforce-logical`'s
table, inverted.

It converts **both** spellings of the logical insets: `inset-s-2` (what `enforce-logical` and
`enforce-canonical` write on Tailwind 4.2+, the spelling the design system calls canonical) and
`start-2` (the older spelling, which Tailwind's docs used and `enforce-logical` still writes without
a design system).

It also mirrors the three utilities where the direction is the VALUE: `float-start` → `float-left`,
`clear-start` → `clear-left`, `text-start` → `text-left`.

DS-independent in the sense that matters: it shares the static mapping table with `enforce-logical`
and inverts it, so it works without `settings.tailwindcss.entryPoint` — every physical class it
writes exists in every Tailwind v4. When an entry point IS configured, the rule additionally checks
that the class it suggests exists, so a rewrite can never introduce a class that emits nothing.

`enforce-physical` and `enforce-logical` are sibling rules. Enable **only one at a time** — running
both produces an autofix loop.

## Options

### `direction`

`'inline' | 'block' | 'both'`, default `'both'`.

Restricts conversion to one axis: `'inline'` converts the start/end utilities (`ms-*`, `inset-s-*`,
`border-e`, …), `'block'` the block-start/end ones (`mbs-*`, `inset-bs-*`, `border-be`, …).

```jsonc
{ "tailwindcss/enforce-physical": ["error", { "direction": "inline" }] }
```

### `sizing`

`boolean`, default `false`.

Also converts logical sizes back: `inline-*` → `w-*`, `block-*` → `h-*`, and their `min-` / `max-`
forms, one axis at a time (`inline-4 block-4` → `w-4 h-4`). `inline`, `block` and
`inline-{block,flex,grid,table}` are display utilities and are never touched.

```jsonc
{ "tailwindcss/enforce-physical": ["error", { "sizing": true }] }
```

### `allowlist`

`string[]`, default `[]`.

Regex patterns (compiled lazily, invalid ones silently skipped). Classes whose full string matches
any pattern bypass the rewrite. Useful when a specific logical utility is intentional even in an
otherwise-LTR codebase (e.g. one component that has to support RTL).

```jsonc
{ "tailwindcss/enforce-physical": ["error", { "allowlist": ["^ms-", "^pe-"] }] }
```

### `entryPoint`

`string`, optional. A CSS entry point for this rule alone, overriding
`settings.tailwindcss.entryPoint`. Only used to confirm the class being suggested exists; the rule
works without it.

## Examples

### ✗ Incorrect

```tsx
// The direction as a VALUE
<div className="float-start clear-end text-start" />
//              ~~~~~~~~~~~ ~~~~~~~~~ ~~~~~~~~~~ → float-left clear-right text-left

// Both spellings of the logical insets
<div className="start-2 inset-s-4" />
//              ~~~~~~~ ~~~~~~~~~  → left-2 left-4

// Logical margins/padding in an LTR-only project
<div className="ms-4 pe-2" />
//              ~~~~ ~~~~  → ml-4 pr-2

// Logical positioning
<div className="inset-s-0 inset-e-0" />
//              ~~~~~~~~~ ~~~~~~~~~  → left-0 right-0

// Logical borders and radii
<div className="border-s rounded-ss-md" />
//              ~~~~~~~~ ~~~~~~~~~~~~~  → border-l rounded-tl-md

// The block axis
<div className="mbs-4 inset-bs-0 border-be" />
//              ~~~~~ ~~~~~~~~~~ ~~~~~~~~~  → mt-4 top-0 border-b

// options: { "sizing": true }
// Logical sizes
<div className="inline-full block-screen" />
//              ~~~~~~~~~~~ ~~~~~~~~~~~~  → w-full h-screen
```

### ✓ Correct

```tsx
// Physical equivalents
<div className="ml-4 pr-2" />
<div className="left-0 right-0" />
<div className="border-l rounded-tl-md" />
<div className="mt-4 top-0 border-b" />

// options: { "sizing": true }
// Display utilities are not sizes
<div className="inline-flex block" />

// Already physical — variants and important round-trip cleanly
<div className="hover:ml-4 pl-(--gutter) mr-4!" />
```

## Interactions with other rules

- **`enforce-logical`**: the inverse. Pick **one**. Running both simultaneously rewrites in a loop.
- **`enforce-canonical`**: it rewrites `start-2` → `inset-s-2`. Harmless here: this rule converts
  both spellings to `left-2`.
- **`enforce-shorthand`**: both rewrite pairs of sides. `mbs-2 mbe-2` is two block-axis classes to
  this rule and `my-2` to that one, and `enforce-shorthand` folds the physical pair this rule writes
  (`mt-2 mb-2`) the same way, so whichever fix lands first the string ends as `my-2`.

## When to disable it

- **The app supports RTL** (Arabic, Hebrew, Farsi, …): use `enforce-logical` instead, otherwise the
  rule's autofix breaks RTL layouts.
- **You don't have a strong preference**: leaving both disabled is fine. The two rules exist to
  express team conventions, not to enforce correctness.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-shorthand.md -->

# enforce-shorthand

oxlint rule that merges Tailwind CSS utilities with the same value on every side into their
shorthand, like `mt-2 mr-2 mb-2 ml-2` → `m-2` or `w-4 h-4` → `size-4`.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options      |
| ------- | ------------------ | ---------------------------------------- | ------------ |
| Yes     | No                 | Optional — used when `entryPoint` is set | `entryPoint` |

## What this rule does

Combines per-axis Tailwind utilities into their shorthand equivalents when every axis carries the
same value. The most common case: `mt-2 mr-2 mb-2 ml-2` collapses to `m-2`. Covered families:

| Family                  | Collapses                                                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| margin / padding        | four sides → `m-*`, axes → `my-*`/`mx-*`, `mx-*`+`my-*` → `m-*`, and the logical sides: `ms-*`+`me-*` → `mx-*`, `mbs-*`+`mbe-*` → `my-*`, all four → `m-*`                      |
| `scroll-m*`/`scroll-p*` | the same shapes                                                                                                                                                                 |
| sizing                  | `w-*`+`h-*` → `size-*`                                                                                                                                                          |
| radii                   | corners → edges → `rounded-*`, including the logical corners (`rounded-ss-*`+`rounded-es-*` → `rounded-s-*`)                                                                    |
| borders                 | sides → `border-*`, axes → `border-x-*`/`border-y-*` — widths **and** colours, logical sides (`border-bs-*`+`border-be-*` → `border-y-*`) included                              |
| inset                   | `top`/`right`/`bottom`/`left` → `inset-*`, axes → `inset-x-*`/`inset-y-*`, `start-*`+`end-*` and `inset-s-*`+`inset-e-*` → `inset-x-*`, `inset-bs-*`+`inset-be-*` → `inset-y-*` |
| single-property pairs   | `gap-x`+`gap-y`, `overflow-x`+`overflow-y`, `overscroll-x`+`overscroll-y`, `border-spacing-x`+`border-spacing-y`, `translate-x`+`translate-y`                                   |

One diagnostic per collapsible group: four sides report `m-2` once, not `m-2` plus the `my-2`/`mx-2`
halves.

`scale-x-*`+`scale-y-*` is deliberately **not** a family. `scale-110` also writes `--tw-scale-z`,
which `scale-3d` reads, so merging would change how `scale-x-110 scale-y-110 scale-3d` renders.

### With an `entryPoint`, the merge is checked against the CSS

Tailwind v4 has per-axis theme namespaces: `w-*` reads `--width-*` (and `--container-*`), `h-*`
reads `--height-*`, `size-*` reads `--size-*`. So this theme

```css
@theme {
  --width-brand: 10rem;
  --height-brand: 20rem;
}
```

makes `w-brand h-brand` → `size-brand` destructive: `size-brand` does not exist, and the element
loses its width and its height. Configure `settings.tailwindcss.entryPoint` (or the rule's own
`entryPoint`) and the rule compares the declarations Tailwind emits — the parts have to resolve to
the same value and the replacement has to reproduce it — so that merge is not offered.

Named theme tokens on the sizing family are only merged when the values are literally identical.
`w-card h-card` is left alone even when all three namespaces define `card` as `30rem`, because each
side reads a different variable and a `:root` override of one makes them diverge — the same
reasoning [`enforce-canonical`](./enforce-canonical) applies to `rounded-[0.5rem]` → `rounded-lg`.

Without an entry point the rule keeps the merges that are safe whatever the theme says: numbers and
fractions (the shared spacing scale), arbitrary values (the same literal on both sides), the core
keywords (`full`, `auto`, `min`, `max`, `fit`, `px`, and the viewport units), and every family other
than sizing — those all draw from a single namespace.

## Options

### `entryPoint`

`string`, optional. A CSS entry point for this rule alone, overriding
`settings.tailwindcss.entryPoint`. Only used to verify merges against the emitted CSS; the rule
works without it.

## Examples

### ✗ Incorrect

```tsx
// Four-side margin
<div className="mt-2 mr-2 mb-2 ml-2" />
//              ~~~~ ~~~~ ~~~~ ~~~~  → m-2

// Two-axis (vertical, horizontal)
<div className="mt-2 mb-2" />  →  my-2
<div className="ml-2 mr-2" />  →  mx-2

// Width + height with the same value
<div className="w-full h-full" />
//              ~~~~~~ ~~~~~~  → size-full

// Sides and axes of any covered family
<div className="border-t-2 border-r-2 border-b-2 border-l-2" />  →  border-2
<div className="top-0 right-0 bottom-0 left-0" />                →  inset-0
<div className="rounded-tl-lg rounded-tr-lg" />                  →  rounded-t-lg
<div className="gap-x-4 gap-y-4" />                              →  gap-4

// Logical inline pairs — `ms-*`+`me-*` IS `margin-inline`
<div className="ms-4 me-4" />  →  mx-4

// Same with important — both sides must share the modifier
<div className="!mt-2 !mr-2 !mb-2 !ml-2" />
//              ~~~~~ ~~~~~ ~~~~~ ~~~~~  → !m-2
```

### ✓ Correct

```tsx
// Already a shorthand
<div className="m-2 p-4" />

// Different values across axes — no collapse possible
<div className="mt-2 mb-4" />

// w-screen is 100vw and h-screen is 100vh; size-screen doesn't exist
<div className="w-screen h-screen" />

// Per-axis theme tokens: `size-brand` would drop both dimensions
// (needs an entryPoint to be detected — see above)
<div className="w-brand h-brand" />

// scale-110 also writes --tw-scale-z, which scale-3d reads
<div className="scale-x-110 scale-y-110" />

// Partial coverage — needs all four sides for m-*
<div className="mt-2 mr-2" />

// Adjacent sides are not an axis
<div className="top-0 right-0" />

// Different variants — rule doesn't merge across variant chains
<div className="hover:mt-2 focus:mb-2" />
```

## Interactions with other rules

- **`enforce-sort-order`**: run shorthand first so the shorthand participates in sort with its own
  priority. Otherwise sort places `mt-2 mr-2 mb-2 ml-2` in spaced positions and the shorthand fix
  collapses them later.
- **`enforce-logical` / `enforce-physical`**: they rewrite the same sides. `mt-2 mb-2` is `my-2`
  here and a block-axis pair (`mbs-2 mbe-2`) to `enforce-logical`; this rule folds the logical pairs
  too, and lands on axis utilities (`my-*`, `inset-x-*`, `border-y-*`) neither directional rule
  converts, so whichever fix lands first the string ends the same. It never folds `inline-*` +
  `block-*` into `size-*`: `size-*` is a width and a height, and `enforce-logical`'s `sizing` would
  split it right back.
- **`enforce-consistent-important-position`**: shorthand respects the `!` placement convention of
  the merged classes. If all four use prefix, the shorthand is prefix; same for suffix.

## When to disable it

- **You want explicit per-axis values for readability**, especially in design-system component
  libraries where reviewers find `mt-2 mr-2 mb-2 ml-2` clearer than `m-2`.
- **Code generation** where every utility is emitted on purpose and collapsing them would hide the
  intent.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/enforce-sort-order.md -->

# enforce-sort-order

oxlint rule that sorts Tailwind CSS classes in the official order — the one
`prettier-plugin-tailwindcss` and `oxfmt` use — with an autofix.

## At a glance

| Autofix | Editor suggestions | Design system           | Options              |
| ------- | ------------------ | ----------------------- | -------------------- |
| Yes     | No                 | Required (`entryPoint`) | `entryPoint`, `mode` |

## What this rule does

Sorts every Tailwind class string in your code to match the official Tailwind class order — the same
order Tailwind uses when generating CSS, and the same one `prettier-plugin-tailwindcss` and `oxfmt`
apply. The rule autofixes: running `oxlint --fix` rewrites the string in place.

DS-dependent — requires `settings.tailwindcss.entryPoint`. The exact sort is computed by
`@tailwindcss/node`'s class-order API against your stylesheet, so theme tokens, plugins, and
`@layer` additions all participate. When the design system can't load, the rule emits a single fatal
`designSystemUnavailable` diagnostic per file instead of falling back to a heuristic.

Output is byte-compatible with `prettier-plugin-tailwindcss` and `oxfmt` as long as the three tools
point at the same `entryPoint` CSS. See the interop guide in the docs for the recommended
combination.

## Options

### `mode`

`'default' | 'strict'`, default `'default'`.

`'default'` delegates to the Tailwind class-order worker (one shot, official order). `'strict'`
groups classes by their variant chain first (`hover:`, `dark:hover:`, …), then sorts within each
group — useful if you want responsive/state prefixes to cluster visually rather than interleave by
utility. Most projects should keep the default; it's what every other Tailwind tooling does.

`'strict'` sorts from the precomputed order, so a class Tailwind never enumerated borrows the
position of the first sibling sharing its prefix: `from-33%` and `w-45` land in the `from-*` and
`w-*` buckets rather than at their exact positions inside them. That's the approximation the mode is
built on — `'default'` asks the worker for the real answer.

```jsonc
{ "tailwindcss/enforce-sort-order": ["error", { "mode": "strict" }] }
```

### `entryPoint`

`string`, optional.

Per-rule override of `settings.tailwindcss.entryPoint`. Useful in the rare case where this rule
needs to read a different stylesheet than the rest of the plugin (e.g. you scope the sort to a
sub-app). Almost nobody needs this — set the entry point once in `settings` and forget.

## Examples

### ✗ Incorrect

```tsx
// Out of order
<div className="text-red-500 flex" />
//                            ~~~~ → flex text-red-500

// Padding before flex
<div className="p-4 flex items-center" />
//              ~~~                    → flex items-center p-4

// Important modifiers keep their position
<div className="!text-red-500 !flex" />
//                            ~~~~~  → !flex !text-red-500
```

### ✓ Correct

```tsx
// Layout → spacing → typography → color
<div className="flex items-center p-4 text-red-500" />

// Variants cluster by Tailwind's variant priority
<div className="flex sm:hidden md:flex lg:hidden" />

// Strict mode: groups by variant first
<div className="flex p-4 hover:bg-red-500 hover:text-white" />
```

## Interactions with other rules

- **`enforce-canonical`**: run canonicalization first, then sort. Canonical forms (e.g. `m-0`
  instead of `-m-0`) participate in the sort with their proper priority.
- **`enforce-shorthand`**: combine `mt-2 mr-2 mb-2 ml-2` into `m-2` first, then let sort-order place
  the shorthand where it belongs.
- **`no-unnecessary-whitespace`**: harmless in either direction. The fixer rebuilds the string from
  a deterministic token list, so any leftover double spaces collapse on the next pass.
- **`prettier-plugin-tailwindcss` / `oxfmt`**: pick one source of truth. Pointed at the same CSS,
  with your class helpers listed in the formatter's `functions`, they sort the same way, so
  formatter and linter don't fight — see [Interop](/interop).

## When to disable it

- **You delegate sort to `prettier-plugin-tailwindcss` or `oxfmt` exclusively** and want to keep the
  rule budget small — for the class attributes and helpers it formats, the formatter does the same
  job. Class strings it doesn't format (variables, for instance) then go unsorted. Leaving both on
  is fine (no conflicts), it's just redundant work where they overlap.
- **Working in a codebase that intentionally orders classes by authoring intent** (e.g. visual
  grouping that doesn't match Tailwind's priority). Disable locally rather than globally if it's a
  per-component preference.

> **`tailwind-merge` caveat.** `tailwind-merge` resolves a conflict group by keeping the _last_
> occurrence in the string. If a single class string contains two classes from the same group
> (`cn("pl-4 px-2", …)`), sorting them into canonical order (`px-2 pl-4`) flips which one is last
> and therefore which one `twMerge` keeps — a rendering change, not a cosmetic one. This is the same
> behavior as `prettier-plugin-tailwindcss`, so the fixer is left as-is; it only bites two
> conflicting classes co-located in one string, which is itself an anti-pattern
> [`no-conflicting-classes`](./no-conflicting-classes) already flags. Splitting the override into a
> separate `cn`/`twMerge` argument avoids it.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/max-class-count.md -->

# max-class-count

oxlint rule that reports a Tailwind CSS class string with more classes than a set maximum (20 by
default) — a sign it should be a component.

## At a glance

| Autofix | Editor suggestions | Design system | Options |
| ------- | ------------------ | ------------- | ------- |
| No      | No                 | Not used      | `max`   |

## What this rule does

Counts the Tailwind classes in each class string and reports when the count exceeds a configurable
maximum. The diagnostic suggests extracting a component or utility — the assumption being that once
an element needs more than ~20 classes, you're describing a _component_ inline and the right move is
to name it.

A class string is a string literal — `className="…"`, one argument of `cn()`/`clsx()`, one
`cva()`/`tv()` value — or a whole template literal, `` tw`…` `` included. In a template the parts
around `${}` are added together: a class glued to an expression (`bg-${tone}-500`) counts once, and
a bare `${expr}` counts as nothing, since its classes aren't known statically. Separate `cn()`
arguments and variant values are counted one by one: they are often conditional or alternatives, and
adding them up would report class lists that never apply together.

The counter is dumb on purpose: it counts whitespace-separated classes after the standard extractor
has resolved the location. No deduplication, no semantic grouping, no DS lookup. That keeps it
predictable: if your `className` reads as N classes, the rule sees N. Multiline strings rebuilt by
`enforce-consistent-line-wrapping` are counted as the underlying class set, not by visual lines.

DS-independent — no `entryPoint` needed. No autofix: extracting a component requires judgement the
rule can't make for you.

## Options

### `max`

`number`, default `20`.

The maximum number of classes allowed in a single class string. The rule reports when
`classes.length > max` (i.e. the limit is inclusive: `max: 20` allows _exactly_ 20). Adjust it to
your team's threshold for "this is now a component."

```jsonc
{ "tailwindcss/max-class-count": ["warn", { "max": 15 }] }
```

Suggested ballparks:

- **`max: 10-15`** — strict component-extraction culture, lots of small reusable building blocks.
- **`max: 20`** (default) — middle ground, fires on outliers without nagging on legitimately dense
  utility-first markup.
- **`max: 30+`** — large dashboard apps where dense one-off layouts are common and you only want a
  guard against truly egregious cases.

## Examples

### ✗ Incorrect

```tsx
// 21 classes — over the default max of 20
<div className="flex items-center p-4 m-2 bg-white text-black rounded shadow border w-full h-10 gap-2 justify-between font-bold text-sm overflow-hidden cursor-pointer transition duration-200 opacity-50 z-10" />
// reports: Too many Tailwind classes (21). Maximum allowed is 20.

// 6 classes with `max: 5`
// options: { "max": 5 }
<div className="flex items-center p-4 m-2 gap-2 w-full" />

// A template is one class string: 6 classes with `max: 5`
// options: { "max": 5 }
<div className={`flex items-center p-4 ${gap} m-2 bg-${tone}-500 w-full`} />
```

### ✓ Correct

```tsx
// Within the default limit
<div className="flex items-center p-4 m-2 gap-2" />

// Extracted into a component — count resets per element
function Card({ children }) {
  return (
    <div className="rounded-lg border bg-white p-4 shadow">
      <div className="flex items-center gap-2">{children}</div>
    </div>
  )
}

// Each `cn()` argument is its own class string: 2 + 3, not 5, so `max: 4` is fine
// options: { "max": 4 }
cn("flex items-center", "p-4 m-2 gap-2")
```

## Interactions with other rules

- **`no-duplicate-classes`**: if a class is repeated, both rules will see the bloated count. Fix the
  duplicate first — the count drops and this rule may stop firing on its own.
- **`enforce-sort-order`** / **`enforce-consistent-line-wrapping`**: cosmetic siblings. The counter
  is whitespace-insensitive so line-wrapping doesn't change the verdict.
- **`enforce-shorthand`**: merges pairs such as `w-4 h-4` → `size-4`. Once its fix is applied, a
  borderline class string can drop back under the limit.
- **`no-arbitrary-value`**: orthogonal, but related in spirit — both nudge toward extracting a
  component when a single element starts carrying too much markup-level logic.

## When to disable it

- **Files that are inherently dense** (top-level layouts, marketing hero sections, design-system
  primitive components that _are_ the abstraction). Prefer per-line disables or a higher `max` in
  the override block.
- **Generated markup** (codegen, MDX components) where the count reflects the generator, not author
  intent.
- **You disagree with the heuristic**: the rule is opinionated and won't suit every codebase.
  There's no shame in turning it off — it exists for teams that want the nudge.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-arbitrary-value.md -->

# no-arbitrary-value

oxlint rule that reports Tailwind CSS arbitrary values like `w-[200px]` or `bg-[#ff0000]`, so values
come from your theme; an allow list covers exceptions.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options                                 |
| ------- | ------------------ | ---------------------------------------- | --------------------------------------- |
| No      | No                 | Optional — used when `entryPoint` is set | `allow`, `allowVariables`, `entryPoint` |

## What this rule does

Flags any Tailwind utility that uses an arbitrary value — the escape hatch — so your team is forced
to either reach for a design token or extend the theme instead of one-off literals. Anything the
parser recognizes as an arbitrary value qualifies: dimensions (`w-[200px]`, `text-[14px]`), colors
(`bg-[#ff0000]`), arbitrary calc expressions (`p-[calc(1rem+2px)]`), gradients, and the same inside
variants (`hover:w-[200px]`) or with the `!` modifier (`!w-[200px]`, `w-[200px]!`).

**Both spellings count.** `bg-(--brand)` is Tailwind v4 sugar for `bg-[var(--brand)]` — the same
arbitrary value, written two ways — and only the bracket form used to be reported. That made
[`enforce-consistent-variable-syntax`](./enforce-consistent-variable-syntax) a laundry service: with
its default `shorthand` setting, its autofix rewrote the reported form into the unreported one and
the violation disappeared with the code unchanged in substance.

DS-optional — no `entryPoint` is needed: whether a class is an arbitrary value is a syntactic check,
cheap on large repos. With one configured, the report also names the fix — the closest steps and
tokens of your theme, with their values, and the file to add a token to:

```text
"w-[203px]" uses an arbitrary value. Closest in your theme: w-50.5 (202px) or w-51 (204px).
If none fits, add a token to src/styles.css.
```

An exact step or token is offered alone (`h-[26px]` → `h-6.5 (26px)`); otherwise the nearest one
below and above. A value that isn't a length (a colour, a `calc()`) gets just the file. The design
system is loaded on the first violation, never for a clean file; `allowVariables: 'runtime'` uses it
too, to know which CSS variables your stylesheet defines. There is no autofix: replacing an
arbitrary value with a token requires human judgement, so the rule only reports.

Arbitrary _variants_ (`[&>svg]:w-4`) are not arbitrary _values_ and are left alone. The rule looks
at the value side of the utility, not the selector prefix.

## Options

### `allow`

`string[]`, default `[]`.

A list of utility prefixes where arbitrary values are tolerated. The match is a literal
`String.prototype.startsWith` against the utility's bare form (after stripping `!` and any
variants), so entries like `"grid-cols-"` permit `grid-cols-[18rem_1fr]` without unlocking
`grid-rows-[...]`. Common candidates: container queries (`@container`), grid templates
(`grid-cols-`, `grid-rows-`), and truly bespoke transforms (`bg-[url(`).

```jsonc
{
  "tailwindcss/no-arbitrary-value": ["error", {
    "allow": ["grid-cols-", "grid-rows-", "bg-[url("]
  }]
}
```

Tip: start with `[]` to see where your codebase actually needs escapes, then promote the legitimate
ones into `allow` rather than disabling the rule wholesale.

### `allowVariables`

`'none' | 'runtime' | 'all'`, default `'none'`.

What to do with a value that is nothing but a CSS variable — `w-(--sidebar-width)`,
`h-[var(--radix-select-trigger-height)]`, `text-(length:--size)`, with or without a fallback or an
opacity modifier:

- `'none'` reports them, like any arbitrary value.
- `'runtime'` allows the variables **no CSS in your design system defines** — the ones JavaScript or
  an inline `style` sets at runtime, like Radix's `--radix-*` or a sidebar's `--sidebar-width`, for
  which no token exists. A variable your stylesheet defines (`--primary`) is still reported: a named
  utility exists for it (see [`prefer-theme-tokens`](./prefer-theme-tokens)). This mode reads the
  design system; without an `entryPoint` nothing can be proven undefined, so references are
  reported.
- `'all'` allows every pure variable reference.

A value that does more than read a variable — `w-[calc(var(--x)*2)]` — is an arbitrary value in
every mode.

```jsonc
{ "tailwindcss/no-arbitrary-value": ["warn", { "allowVariables": "runtime" }] }
```

### `entryPoint`

`string`, optional. Per-rule override of `settings.tailwindcss.entryPoint`, read only by
`allowVariables: 'runtime'`.

## Examples

### ✗ Incorrect

```tsx
// One-off dimension instead of a spacing token
<div className="w-[200px] p-[10px]" />

// Hex literal instead of a theme color
<div className="bg-[#ff0000] text-white" />

// Variant doesn't change the verdict
<div className="hover:w-[200px]" />

// `!` modifier doesn't either
<div className="!w-[200px]" />

// The v4 shorthand is the same arbitrary value
<div className="bg-(--brand) border-(length:--stroke)" />
```

### ✓ Correct

```tsx
// Use spacing tokens
<div className="w-64 p-2.5" />

// Use a theme color you declared in @theme
<div className="bg-brand text-white" />

// Arbitrary variants are fine — they target selectors, not values
<div className="[&>svg]:w-4" />

// Allowed via `allow: ["grid-cols-"]`
// options: { "allow": ["grid-cols-"] }
<div className="grid grid-cols-[18rem_1fr]" />
```

## Interactions with other rules

- **`no-hardcoded-colors`**: a strict subset focused on color utilities (`bg-[#ff0]`,
  `text-[rgb(...)]`). Enable that one if you want the granular color-only message; enable both for
  layered enforcement. They'll both fire on the same class, which is usually desired during
  migration.
- **`no-unnecessary-arbitrary-value`**: this rule prohibits arbitrary values outright;
  `no-unnecessary-arbitrary-value` is gentler — it only flags arbitraries that have an exact named
  equivalent (`w-[100%]` → `w-full`). Both can coexist: the gentler rule autofixes the trivial cases
  and this rule catches what's left.
- **`prefer-theme-tokens`**: similar intent, but DS-dependent. `prefer-theme-tokens` actually
  consults your `@theme` and suggests the matching token. Pair them: this rule is your stop-gap when
  no token exists yet.
- **`enforce-consistent-variable-syntax`**: converts between `bg-[var(--x)]` and `bg-(--x)`. Since
  both forms report here, running it — in either direction — cannot move a class out of this rule's
  reach.

## When to disable it

- **Prototyping / spike branches** where speed beats discipline. Re-enable before merging.
- **Files that genuinely need an arbitrary value** (one-off marketing pages, dynamic CSS-in-JS
  shims). Prefer `allow` with a tight prefix list, or disable per-line via
  `// oxlint-disable-next-line tailwindcss/no-arbitrary-value`.
- **Libraries that ship Tailwind utilities consumers re-skin**: the arbitrary form is sometimes the
  cleanest contract. Document the decision and disable the rule in that package.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-borrowed-component-styles.md -->

# no-borrowed-component-styles

oxlint rule that reports a plain element rebuilding one of your components from Tailwind CSS
classes: a hand-made Button, Card or Input.

::: warning Experimental

Its heuristics may still change in a minor release, adding or removing reports. It is off in the
recommended config.

:::

## At a glance

| Autofix | Editor suggestions | Design system           | Options                    |
| ------- | ------------------ | ----------------------- | -------------------------- |
| No      | No                 | Required (`entryPoint`) | `components`, `entryPoint` |

## What this rule does

Your components hold the design system's decisions: `<Button>` is the primary color, the radius, the
height and the focus ring, in one place. A `<button>` that copies Button's classes — or rewrites
them from memory — looks the same today and drifts tomorrow: when Button changes, it doesn't, and it
never had the focus ring, the disabled state or the variants. This rule reads the components you
point it at, and reports a plain element whose classes rebuild one of them:

```text
<button> rebuilds Button: 9 of its 9 style declarations match. Use Button from
components/ui/button.tsx instead, so it follows your design system.
```

It compares what the classes do, not how they're written:

- each class becomes its CSS declarations, so `px-4` and `pl-4 pr-4`, or `rounded-md` and
  `rounded-t-md rounded-b-md`, are the same style;
- layout is left out — `flex`, `w-full`, `mt-4`, `gap-2`: where an element sits is yours to change;
- so are the classes behind a variant (`hover:`, `md:`, `data-[state=open]:`), on both sides.

An element is reported when it shares at least 4 declarations with a component, those are at least
60% of all the declarations either of them sets (the element's extras count against it), one of them
styles the box — background, border, corners or shadow — and none of its colors differ from the
component's. A Button's shape in another color is another style, and `text-sm font-medium` alone is
any text.

Only native elements (`<button>`, `<div>`, `<span>`) are compared, from their `className` string or
the `cn()` call in it: a component's `className` is merged into its own styles, not a copy of them.
The component files themselves are never reported.

DS-dependent — needs `settings.tailwindcss.entryPoint` to turn classes into declarations. No
autofix: replacing an element with a component changes its props and its behavior.

## How it reads your components

The rule reads each file under `components` without running it, and takes:

- a `cva()` or `tv()` definition: its base classes plus each variant group's default, as the
  component (`Button`), and one style per value of its first variant group
  (`Button variant="outline"`);
- a capitalized function component's first `className` — its root element — when it is a string or a
  `cn()` / `clsx()` call: `Card`, `CardHeader`.

A style is compared only when it has at least 4 declarations, a color and a box. Components that
pass `className` through untouched, or build their classes at runtime, are skipped.

## Options

### `components`

`string[]`, default `[]`.

The files and directories that hold your design system's components. A directory is read
recursively, skipping `*.test.*`, `*.spec.*`, `*.stories.*` and `*.d.ts` files. Relative paths are
resolved like `entryPoint`: against the directory of the nearest oxlint config (`.oxlintrc.json`,
`oxlint.config.ts`, …), then oxlint's working directory. With no components, the rule reports
nothing.

```jsonc
{
  "tailwindcss/no-borrowed-component-styles": ["warn", { "components": ["src/components/ui"] }]
}
```

### `entryPoint`

`string`, optional. Per-rule override of `settings.tailwindcss.entryPoint`.

## Examples

With shadcn/ui's Button and Card in `components/ui`:

### ✗ Incorrect

```tsx
// options: { "components": ["components/ui"] }
// Copied from Button
<button className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground h-9 hover:bg-primary/90">
  Pay
</button>
// reports: rebuilds Button

// Rewritten from memory: another order, pl-4 pr-4 for px-4, on a link
<a className="bg-primary text-primary-foreground pl-4 pr-4 py-2 h-9 rounded-md text-sm font-medium">
  Pay
</a>

// A Card, its classes merged by cn()
<div className={cn("rounded-xl border bg-card py-6", "text-card-foreground shadow-sm")}>Plan</div>
// reports: rebuilds Card
```

### ✓ Correct

```tsx
// options: { "components": ["components/ui"] }
// The components themselves
<Button className="mt-4 w-full">Pay</Button>

// Layout only
<div className="flex items-center gap-2 p-4" />

// A Button's shape in a color none of its variants use is another style
<div className="rounded-md bg-muted px-4 py-2 text-sm font-medium h-9" />

// No box in common: text styles alone are any text
<span className="h-9 px-4 py-2 text-sm font-medium text-primary-foreground" />
```

## Interactions with other rules

- **`no-default-palette`** and **`no-hardcoded-colors`** keep an element's colors in your theme;
  this rule keeps the styles your components already own in the components.
- **`max-class-count`**: a long class string on a plain element is often a component waiting to be
  extracted — or one that already exists, which this rule names.
- **@shadcn/lint's `no-restyle`** reports the other direction: classes that restyle a component
  (`<Button className="bg-blue-600">`). This rule reports a plain element restyled into one. See
  [shadcn/ui and @shadcn/lint](/shadcn).

## When to disable it

- **An element that can't be the component.** shadcn/ui draws a checkbox inside a command-menu item
  with Checkbox's classes, because a real Checkbox — a button — can't sit inside an option. Disable
  the line there.
- **Code that shows the components' markup**, such as stories or docs pages outside `components`.
- **While migrating** to the components: the reports are the to-do list; keep the rule at `warn`.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-conflicting-classes.md -->

# no-conflicting-classes

oxlint rule that reports Tailwind CSS classes on one element whose CSS clashes, like `p-2 p-4`,
comparing the declarations your design system emits.

## At a glance

| Autofix | Editor suggestions | Design system           | Options                                  |
| ------- | ------------------ | ----------------------- | ---------------------------------------- |
| No      | No                 | Required (`entryPoint`) | `entryPoint`, `reportRedundant`, `allow` |

## What this rule does

Detects pairs of Tailwind classes on the same element, under the same variant, whose CSS
declarations clash — where one of the two is silently discarded. The comparison is made against the
CSS the design system actually emits, values included: property names alone cannot tell a conflict
from a composition.

A shared property is a conflict only when the declaration that LOSES the cascade carries something
the winner does not reproduce. Which means these are **not** conflicts, and none of them is
special-cased:

- **the same value on both sides** — `mask-b-from-50% mask-b-from-black` share four byte-identical
  declarations, so whoever wins, the result is the same;
- **a `var()` forwarder and the class supplying the variable** — `outline-2` declares
  `outline-style: var(--tw-outline-style)` and carries no value of its own; matching is by the real
  variable name, so a plugin's `--scrollbar-*` behaves exactly like Tailwind's `--tw-*`;
- **a winner that still pulls the loser in** — `drop-shadow-indigo-500` reads the
  `--tw-drop-shadow-size` that `drop-shadow-xl` writes, followed transitively (that is how the
  `from-*` / `via-*` / `to-*` chain composes);
- **a custom property reset to `initial`** — `animate-in` initializes every `--tw-enter-*` for its
  modifiers to override;
- **declarations on different boxes** — `placeholder-*` styles `::placeholder`, `space-x-*` styles
  the children, neither styles the element.

Two classes that declare the same property with the same value are reported as **`redundant`**
instead: not a conflict, but one of them is dead weight. `reportRedundant: false` opts out.

Which class wins is asked of the design system, not inferred from the order you wrote the classes in
— Tailwind's output does not depend on that order. When the position cannot be known (for a class
whose value you wrote, like `w-[10px]`), the diagnostic reports the clash without naming a winner.

Only two compositions cannot be derived from the CSS, and they stay declared in the source with the
reason why: `prose` size variants and `prose` + `max-w-*` (the plugin intends the override and the
emitted CSS is indistinguishable from an accident), and `mask-composite` modes. For a composition
your own plugins produce, use the **`allow`** option rather than waiting for a release.

DS-dependent — requires `settings.tailwindcss.entryPoint`. When the design system can't load, the
rule emits a single fatal `designSystemUnavailable` diagnostic per file instead of silently passing.

## Options

| Option            | Type                             | Default | Description                                                                                                                                                                                                                     |
| ----------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reportRedundant` | `boolean`                        | `true`  | Report two classes that declare the same property with the same value as `redundant`.                                                                                                                                           |
| `allow`           | `(string \| [string, string])[]` | `[]`    | Patterns to silence, matched against the class **as written** (variant prefix and `!` included). A bare pattern silences any pair involving a matching class; a two-element pattern silences that combination, in either order. |
| `entryPoint`      | `string`                         | —       | Per-rule override of `settings.tailwindcss.entryPoint`.                                                                                                                                                                         |

```jsonc
{
  "rules": {
    "tailwindcss/no-conflicting-classes": [
      "error",
      {
        // Your plugin composes in a way the emitted CSS cannot show.
        "allow": [["^gutter-thin$", "^gutter-(thumb|track)-"]],
      },
    ],
  },
}
```

## Examples

### ✗ Incorrect

```tsx
// Same property, different value: one of them is discarded
<div className="text-red-500 text-blue-500" />

// Conflict survives across variants when both classes share the same one
<div className="hover:bg-red-500 hover:bg-blue-500" />

// `!important` doesn't help — same property, still a conflict
<div className="!text-red-500 !text-blue-500" />

// Same gradient role conflicts (`from-` + `from-`); different roles compose
<div className="from-red-500 from-blue-500" />

// Asymmetric narrowing: wider class AFTER the narrower one clobbers it
<div className="h-6 size-4" />
```

### ✓ Correct

```tsx
// Different properties
<div className="flex items-center" />

// Different variants — applied under different conditions
<div className="hover:bg-red-500 focus:bg-blue-500" />

// Gradient stops are complementary
<div className="from-blue-500 via-purple-500 to-pink-500" />

// `shadow-*` + `ring-*` compose via disjoint --tw-* custom properties
<div className="shadow-lg ring-1 ring-offset-2" />

```

## Interactions with other rules

- **`no-duplicate-classes`**: complementary. Duplicates are the exact same class repeated; conflicts
  are different classes that hit the same property. Keep both rules on.
- **`enforce-sort-order`**: cosmetic for the **plain CSS cascade** — which class wins is decided by
  the generated stylesheet, not by attribute order, so sorting only makes the pair easier to read.
  The one exception is **`tailwind-merge`**: it resolves same-group classes by _last occurrence in
  the string_, so reordering a fragment can flip which one survives. That only bites two conflicting
  classes co-located in a single merge fragment — the anti-pattern this rule already flags — so
  fixing the conflict removes the sort hazard too. See that rule's own note.
- **`no-deprecated-classes`**: a deprecated alias and its modern equivalent (`flex-grow` + `grow`)
  will trip this rule on the property level. Fixing the deprecation usually resolves the conflict.
- **`enforce-canonical`**: rewriting to canonical forms collapses trivially-aliased pairs before
  they reach this rule.

## When to disable it

- **Generated class lists** where the order is meaningful and you rely on "last wins" semantics
  intentionally (e.g. a base + override pattern in a design system primitive). Prefer extracting the
  override into a `cn()`/`twMerge()` call so the conflict becomes explicit.
- **Codebases whose own plugins compose in a way the emitted CSS cannot show**: use the `allow`
  option rather than disabling the rule. Patterns are matched against the class as written, so
  include the variant prefix if you need to silence `hover:` forms too.
- **Tests / fixtures** that intentionally build conflicting class strings to exercise other tooling.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-contradicting-variants.md -->

# no-contradicting-variants

oxlint rule that reports Tailwind CSS variant classes made redundant by the same utility applied
unconditionally, like `hover:flex` next to `flex`.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options      |
| ------- | ------------------ | ---------------------------------------- | ------------ |
| No      | No                 | Optional — used when `entryPoint` is set | `entryPoint` |

## What this rule does

Flags variant-prefixed classes that are redundant because the same utility is already applied
unconditionally on the same element. The canonical case is `flex hover:flex`: `flex` always applies,
so the `hover:` variant adds nothing — under hover it's already there, and outside hover the base
still wins. The variant is pure noise (and a strong hint that someone meant to write a different
utility, like `hover:inline-flex`).

The rule does NOT report when the variant targets a different element than the base. Pseudo-elements
(`after`, `before`, `placeholder`, `marker`, `backdrop`, `selection`, `first-line`, `first-letter`,
`file`), child selectors (`*:`, `**:`), and arbitrary selectors (`[&>svg]`, `[&_div]`) all change
the selector target, so `absolute after:absolute` or `shrink-0 [&>svg]:shrink-0` is fine — the base
applies to the element while the variant applies to a descendant or pseudo-element.

With `settings.tailwindcss.entryPoint` configured, that judgement comes from the selector the design
system actually generates for each variant, so it covers variants the project defines itself:
`@custom-variant thumb (&::-webkit-slider-thumb)` makes `size-4 thumb:size-4` valid, which no list
of variant names could know. Without an entry point the rule falls back to the names above and
behaves exactly as before — it never reports a missing design system.

The match is by exact utility identity, so `bg-white hover:bg-blue-500` is left alone (different
values), as is `flex hover:items-center` (different utilities).

"The base applies unconditionally" only holds when nothing else overrides its property. A responsive
class that re-establishes a property an intermediate breakpoint took away is **load-bearing**, not
redundant: in `block md:hidden lg:block` the base is `block`, but `md:hidden` sets `display: none`
from `md` up, and `lg:block` restores `display: block` from `lg` up — removing it leaves the element
hidden on large screens. The rule detects this and stays quiet when a sibling with a _different_
utility writes an overlapping CSS property. Without an entry point this covers the closed `display`
and `visibility` groups; with one configured it uses the properties the design system actually
reports, so it extends to every property (`text-align`, `position`, project-defined utilities, …).

## Options

| Option       | Type     | Default | Description                                             |
| ------------ | -------- | ------- | ------------------------------------------------------- |
| `entryPoint` | `string` | —       | Per-rule override of `settings.tailwindcss.entryPoint`. |

The entry point is optional: with one configured the rule classifies variants from the selectors the
design system generates, and without one it falls back to the built-in list. It never reports a
missing design system.

## Examples

### ✗ Incorrect

```tsx
// `flex` already applies — `dark:flex` is dead weight
<div className="flex dark:flex" />

// Same pattern with `hover`
<div className="hidden hover:hidden" />

// Multiple redundant variants on the same base
<div className="flex hover:flex dark:flex" />
```

### ✓ Correct

```tsx
// Different values under different variants
<div className="bg-white hover:bg-blue-500" />

// Different utilities — no redundancy
<div className="text-white dark:text-black" />

// Only variant classes, no base — nothing is redundant
<div className="hover:flex dark:flex" />

// Pseudo-element targets a different element from the base
<div className="absolute after:absolute" />
<div className="shrink-0 [&>svg]:shrink-0" />
<div className="flex *:data-[slot=select-value]:flex" />

// Responsive reset — `lg:block` restores `display` after `md:hidden` removed it
<div className="block md:hidden lg:block" />
```

## Interactions with other rules

- **`no-duplicate-classes`**: complementary. Duplicates are the same string twice
  (`hover:flex hover:flex`); this rule catches the subtler case where the base unconditionally
  subsumes a variant.
- **`no-conflicting-classes`**: a base utility shadowing a variant isn't a CSS-property conflict
  (both compute to the same property value), so `no-conflicting-classes` won't flag it. That's the
  gap this rule fills.
- **`no-dark-without-light`**: opposite shape. This rule flags `base + variant:same-utility`; that
  one flags `dark:foo` with no light counterpart at all.

## Composition and merge helpers (`cn` / `twMerge` / `cva`)

"`hover:flex` is redundant because `flex` already applies" only holds when the string being checked
is the element's **final, self-contained class list**. In a `tailwind-merge` composition — the
`cn`/`twMerge` + `cva` pattern shadcn-style codebases use — a `className` is frequently an
**override fragment** that gets merged at runtime with classes contributed elsewhere, often in
another module. There the variant is usually **load-bearing**: it exists to beat a same-group class
the component merges in from its own `cva`.

Take `<Button className="bg-transparent hover:bg-transparent" />`, where `Button` does
`twMerge(buttonVariants(), className)` and `buttonVariants()` contributes `hover:bg-accent`.
`bg-transparent` (no modifier) and `hover:bg-accent` (a `hover` modifier) sit in different
`tailwind-merge` conflict groups, so the unconditional `bg-transparent` does **not** evict
`hover:bg-accent` — only `hover:bg-transparent` does. Removing the "redundant"
`hover:bg-transparent` therefore restores the accent hover. The class looks redundant in isolation
but is required in context (issue #117).

Because the base the variant defeats lives in another argument or module, redundancy is not
decidable from the fragment alone without emulating `tailwind-merge`. So the rule only evaluates a
string it can be sure is the final list: a literal (or template) used directly as
`class`/`className` on a **native host element** (`<div>`, `<button>`, …). It does **not** report
strings that are:

- arguments to a merge-aware call — `cn(...)`, `twMerge(...)`, `cva(...)`, `tv(...)`, etc.;
- the `className`/`class` of a **custom component** (`<Button …>`, `<Field.Root …>`), which is
  opaque — the component may re-merge it internally;
- assigned to a variable, or emitted from a tagged template.

The trade-off is deliberate: it accepts a few false negatives (a genuinely redundant pair hidden in
one of those positions is not caught) to eliminate the false positives, which read as obviously
correct and invite a rendering regression.

## When to disable it

- **Code generators / class-name builders** on a native element that intentionally emit both a base
  and a same-utility variant. (Override fragments passed through `cn`/`twMerge` or a custom
  component are already skipped — see the section above.)
- **Snapshot tests / fixtures** that need the redundant pair to exercise downstream tooling.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-dark-without-light.md -->

# no-dark-without-light

oxlint rule that reports a Tailwind CSS `dark:` colour, like `dark:bg-gray-900`, with no class
setting that colour for light mode on the element.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options                  |
| ------- | ------------------ | ---------------------------------------- | ------------------------ |
| No      | No                 | Optional — used when `entryPoint` is set | `variants`, `entryPoint` |

## What this rule does

Catches the case where you wrote `dark:bg-gray-900` but forgot the matching light-mode base
(`bg-white`, `bg-zinc-50`, whatever). The moment a theme switcher is active, that element renders
unstyled in light mode — usually as transparent or whatever the parent inherits, almost never what
you wanted.

**Only colour needs a base.** A dark-only filter, display, border width or opacity leaves light mode
with the element's normal rendering — that's the point of `dark:brightness-[0.2]` on an image, or
`dark:hidden` on a decoration. So only a variant class that sets a colour is checked: with an entry
point configured, "sets a colour" is read from the CSS the class emits (a colour property such as
`color`, `background-color` or `fill`, a `--color-*` theme variable, or a colour literal); without
one, every class is checked except the families that are never colour — filters and backdrop
filters, opacity, display, visibility, position, `sr-only`, and border / outline / ring widths.
`dark:text-white` on its own is still reported: text colour is colour.

The check is by group, not by exact value: for every class that uses a watched variant, is there at
least one class in the same group that does NOT use one? If not, the variant class has no light-mode
counterpart and gets reported.

A class counts as the base in either of two ways:

- **Same utility prefix** — `bg-white` is the base for `dark:bg-black`, `text-gray-900` for
  `dark:text-white`. This is the leading property family (`bg`, `text`, `border-t`, `from`,
  `rounded-tl`, …).
- **Same declared CSS property**, when `settings.tailwindcss.entryPoint` (or the rule's own
  `entryPoint`) is configured. `underline` and `no-underline` share no prefix at all, yet both write
  `text-decoration-line` — so `underline dark:no-underline` is a complete pair, not a missing base.
  The same goes for `italic dark:not-italic`, `visible dark:invisible`,
  `uppercase dark:normal-case`, `truncate dark:text-clip` and `sr-only dark:not-sr-only`, all of
  which used to be reported.

The property check is **additive**: anything that matched by prefix still matches, so configuring an
entry point can only make this rule report less, never more. Without one it falls back to the prefix
check plus a small built-in table for `display` and `position` (so `block dark:hidden` works), which
is why the pairs listed above still report when no CSS is configured.

The set of "watched variants" is configurable. By default it's just `dark`, but the same shape
applies to any other scheme-style variant (`contrast-more`, `motion-reduce`, `print`, custom
data-attribute variants you've registered, etc.) — see `variants` below.

## Options

### `variants`

`string[]`, default `["dark"]`.

The list of variants that require a non-variant base on the same utility prefix. Override this when
your app uses a different mechanism for theme switching (e.g. `contrast-more:` for a high- contrast
theme, or a custom `theme-foo:` variant defined in your CSS).

```jsonc
{ "tailwindcss/no-dark-without-light": ["error", { "variants": ["dark", "contrast-more"] }] }
```

If you set `variants` to an empty array the rule effectively becomes a no-op — prefer disabling the
rule outright in that case.

### `entryPoint`

`string`, optional. A CSS entry point for this rule alone, overriding
`settings.tailwindcss.entryPoint`. Enables the declared-property grouping described above; the rule
works without it.

## Examples

### ✗ Incorrect

```tsx
// No light-mode background — element is bare when the dark class doesn't apply
<div className="dark:bg-gray-900" />

// `bg-*` has a base, but `text-*` doesn't
<div className="bg-white dark:bg-gray-900 dark:text-white" />
```

### ✓ Correct

```tsx
// Both modes covered
<div className="bg-white text-black dark:bg-gray-900 dark:text-white" />

// Same property under a different name — needs an entryPoint to be recognized
<div className="underline dark:no-underline" />
<div className="italic dark:not-italic" />
<div className="visible dark:invisible" />

// Show in light, hide in dark: both write `display`
<div className="block dark:hidden" />

// Not a colour: light mode keeps the element's normal rendering on purpose
<img className="object-cover dark:brightness-[0.2] dark:grayscale" />
<div className="flex-col dark:border-r" />

// No watched variant → rule doesn't care about base coverage
<div className="hover:bg-blue-500" />

// Custom variant + matching base
// options: { "variants": ["contrast-more"] }
<div className="bg-white contrast-more:bg-black" />

// A dark-only string inside a merge helper or on a custom component is an
// override fragment — the light base lives elsewhere, so it is NOT reported.
// See "Composition and merge helpers" below.
cn("dark:bg-gray-900")
;<Field className="dark:bg-transparent" />
```

## Interactions with other rules

- **`no-contradicting-variants`**: opposite shape. This rule flags `dark:foo` without a base; that
  one flags `foo dark:foo` where the base makes the variant redundant. They never disagree on the
  same pair of classes.
- **`no-conflicting-classes`**: orthogonal. Conflicting classes collide on a property; missing-base
  is the absence of a property for a given mode. A dark-only element won't trip
  `no-conflicting-classes` because it doesn't conflict — it just doesn't render the way you wanted.
- **`enforce-sort-order`**: doesn't affect detection (the rule doesn't care about order), but
  sorting tends to put the base and the dark variant adjacent, which makes the missing one obvious
  in review.

## Composition and merge helpers (`cn` / `twMerge` / `cva`)

"There is no base for this `dark:` class" only holds when the string being checked is the element's
**final, self-contained class list**. In a `tailwind-merge` composition — the `cn`/`twMerge` + `cva`
pattern shadcn-style codebases use — a `className` is frequently an **override fragment** that gets
merged at runtime with classes contributed elsewhere, often in another module. A dark-only override
like `<Field className="dark:bg-transparent" />` is not missing anything: the light base
(`bg-white`) lives in the component's own `cva`, and `tailwind-merge` keeps both because they sit in
different modifier scopes. Reporting it — and "fixing" it by adding a light base to the override —
silently changes light-mode rendering (issue #117).

Because that base lives in another argument or module, redundancy is not decidable from the fragment
alone without emulating `tailwind-merge`. So the rule only evaluates a string it can be sure is the
final list: a literal (or template) used directly as `class`/`className` on a **native host
element** (`<div>`, `<input>`, …). It does **not** report strings that are:

- arguments to a merge-aware call — `cn(...)`, `twMerge(...)`, `cva(...)`, `tv(...)`, etc.;
- the `className`/`class` of a **custom component** (`<Field …>`, `<Card.Body …>`), which is opaque
  — the component may re-merge it internally;
- assigned to a variable, or emitted from a tagged template.

The trade-off is deliberate: it accepts a few false negatives (a genuinely dark-only class hidden in
one of those positions is not caught) to eliminate the false positives, which read as obviously
correct and invite a rendering regression.

## When to disable it

- **Apps with a single color scheme** that nevertheless ship a few `dark:` classes for one-off
  overrides on top of a known-correct base in a parent component. Prefer narrowing `variants` (e.g.
  drop `dark`) before disabling.
- **Server-driven class strings** on a native element where the base lives in CSS and only the dark
  override is emitted from JS. (Override fragments passed through `cn`/`twMerge` or a custom
  component are already skipped — see the section above.)

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-default-palette.md -->

# no-default-palette

oxlint rule that reports Tailwind CSS default palette colors, like `bg-red-500`, in a project whose
theme defines its own colors — and names the ones to use.

## At a glance

| Autofix | Editor suggestions | Design system           | Options               |
| ------- | ------------------ | ----------------------- | --------------------- |
| No      | No                 | Required (`entryPoint`) | `entryPoint`, `allow` |

## What this rule does

Tailwind ships a default palette — `red-500`, `gray-100`, `white`, 288 colors in all — and your
theme adds its own: `brand`, or shadcn/ui's `primary`, `muted`, `destructive`. Once a project has
colors of its own, a palette color is usually a design-system leak: it doesn't follow the theme, and
`bg-white` stays white in dark mode where `bg-background` wouldn't. This rule reports every class
that reads a palette color, and names your colors in the message:

```text
"bg-red-500" uses red-500 from Tailwind's default palette, not one of your theme colors: brand,
brand-light.
```

It reads what each class does, not its name: any utility that sets a color (`bg-`, `text-`,
`border-`, `ring-`, `from-`, `fill-`, …), with variants and opacity modifiers
(`hover:bg-red-500/50`), and an arbitrary value that reads a palette variable
(`bg-[var(--color-red-500)]`). A palette color your theme redefines (`--color-red-500: …` in your
`@theme`) is yours, and isn't reported. `transparent`, `current` and `inherit` aren't palette
colors.

With no colors of its own — stock Tailwind — the palette _is_ the project's design system, and the
rule reports nothing.

DS-dependent — needs `settings.tailwindcss.entryPoint` to tell the palette from your colors. No
autofix: which of your colors a palette color should become is a design decision.

## Options

### `allow`

`string[]`, default `[]`.

Palette colors to allow, by name, or by prefix with a trailing `*`. `white` and `black` are palette
colors too, and are reported unless you allow them.

```jsonc
{ "tailwindcss/no-default-palette": ["error", { "allow": ["white", "black", "gray-*"] }] }
```

### `entryPoint`

`string`, optional. Per-rule override of `settings.tailwindcss.entryPoint`.

## Examples

With a theme that declares `--color-brand` and `--color-brand-light`:

### ✗ Incorrect

```tsx
<div className="bg-red-500" />
// reports: "bg-red-500" uses red-500 from Tailwind's default palette

// Variants, opacity modifiers and every color utility read the same variable
<div className="hover:text-blue-600 bg-gray-900/50 from-emerald-400" />

// An arbitrary value that reads a palette variable
<div className="bg-[var(--color-red-500)]" />

// white and black are palette colors
<div className="bg-white" />
```

### ✓ Correct

```tsx
<div className="bg-brand text-brand-light hover:bg-brand/90" />

// Not palette colors
<div className="bg-transparent text-current" />

// Allowed by name or prefix
// options: { "allow": ["white", "gray-*"] }
<div className="bg-white text-gray-900" />
```

## Interactions with other rules

- **`no-hardcoded-colors`**: the other half. It reports color literals (`bg-[#f00]`); this rule
  reports palette colors (`bg-red-500`). Together they leave only your theme's colors.
- **`no-unknown-classes`**: a misspelt theme color (`bg-brnd`) isn't a palette color; that rule
  reports it, with the name you meant.
- **@shadcn/lint's `no-raw-colors`** reports the same palette colors in a shadcn/ui project; run one
  of the two. See [shadcn/ui and @shadcn/lint](/shadcn).

## When to disable it

- **The palette is your design system**, or part of it, on purpose: allow those colors with `allow`,
  or leave the rule off.
- **Code you don't own**, such as vendored components styled with the palette.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-deprecated-classes.md -->

# no-deprecated-classes

oxlint rule that rewrites Tailwind CSS classes renamed in v4, like `flex-grow` → `grow` and
`bg-gradient-to-r` → `bg-linear-to-r`, with an autofix.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options      |
| ------- | ------------------ | ---------------------------------------- | ------------ |
| Yes     | Yes                | Optional — used when `entryPoint` is set | `entryPoint` |

## What this rule does

Flags any class that was renamed when Tailwind moved from v3 to v4 and rewrites it in place with an
auto-fix. Examples: `flex-grow` → `grow`, `flex-shrink` → `shrink`, `overflow-ellipsis` →
`text-ellipsis`, `decoration-clone` → `box-decoration-clone`, `bg-gradient-to-r` → `bg-linear-to-r`
(and the rest of the gradient directions). Variants and `!` (important) modifiers are preserved on
both sides of the rewrite.

### Where the rename list comes from

With `settings.tailwindcss.entryPoint` (or the rule's own `entryPoint`) configured, the list is
**derived from your design system**: Tailwind's own `canonicalizeCandidates` is asked what each v3
spelling maps to, and only the ones it still compiles AND still renames are reported. That covers
renames a hardcoded table did not — `break-words` → `wrap-break-word`, `order-none` → `order-0`, the
reordered position spellings `bg-left-top` → `bg-top-left` and `object-left-top` → `object-top-left`
— and, more importantly, an entry disappears by itself when a future Tailwind stops compiling it,
instead of suggesting a replacement for a class that no longer exists.

Without an entry point the rule falls back to a hardcoded table of the 15 best-known renames, so it
still works with nothing configured and never emits a `designSystemUnavailable` diagnostic.

## Options

### `entryPoint`

`string`, optional. A CSS entry point for this rule alone, overriding
`settings.tailwindcss.entryPoint`. Used to derive the rename list; the rule works without it.

## Examples

### ✗ Incorrect

```tsx
// v3 flex aliases — v4 dropped the `flex-` prefix
<div className="flex-grow flex-shrink-0" />
// → <div className="grow shrink-0" />

// Gradient direction — renamed to bg-linear-to-*
<div className="bg-gradient-to-r from-blue-500 to-purple-500" />
// → <div className="bg-linear-to-r from-blue-500 to-purple-500" />

// Text overflow alias and box-decoration shorthand
<div className="overflow-ellipsis" />
// → <div className="text-ellipsis" />
<div className="decoration-clone" />
// → <div className="box-decoration-clone" />

// Variants and important are preserved on the way out
<div className="hover:!flex-grow" />
// → <div className="hover:!grow" />
```

### ✓ Correct

```tsx
// Post-migration spellings
<div className="grow shrink-0" />

<div className="bg-linear-to-r from-blue-500 to-purple-500" />

<div className="text-ellipsis" />
<div className="box-decoration-clone" />

<div className="hover:!grow" />
```

## Interactions with other rules

- **`no-unknown-classes`**: silently skips any renamed spelling, asking the design system rather
  than a list of its own, so the two rules cannot disagree. You won't get "unknown class" plus
  "deprecated class" for `flex-grow` — only the deprecation. Keep both rules on.
- **`enforce-canonical`**: **this rule owns the renames.** Tailwind canonicalizes them too
  (`bg-gradient-to-r` → `bg-linear-to-r` is both a deprecation and a canonicalization), so both
  rules used to report the same class with the same fix. `enforce-canonical` now stays quiet about
  anything in the rename list and keeps the rest: valid-but-non-canonical forms like `-m-0` → `m-0`
  and `start-2` → `inset-s-2` (`start-*` is current Tailwind, just not the canonical spelling). Keep
  both on — with only `enforce-canonical` enabled the renames go unreported.
- **`no-restricted-classes`**: orthogonal. Use that one to ban valid classes; this one only triggers
  on the fixed v3→v4 rename list.

## When to disable it

- **You're still on Tailwind v3** and want to keep the v3 spellings. Disable this rule until you
  migrate.
- **You intentionally ship a v3-compatible class layer** alongside v4 (for example, a shared library
  that targets both). In that case prefer a targeted `eslint-disable` on the file rather than a
  project-wide disable.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-duplicate-classes.md -->

# no-duplicate-classes

oxlint rule that reports a Tailwind CSS class repeated in the same class list, like `flex flex`, and
removes the extra copies with `--fix`.

## At a glance

| Autofix | Editor suggestions | Design system | Options |
| ------- | ------------------ | ------------- | ------- |
| Yes     | No                 | Not used      | None    |

## What this rule does

Reports the same class string appearing more than once in the same class list, then autofixes by
removing the second (and any further) occurrences. `flex flex` is always dead weight — there's no
disagreement about which one wins, no shadowing, no override; the second one is purely a typing
accident.

The comparison is by exact token, so `hover:flex hover:flex` is a duplicate but `flex hover:flex` is
NOT — the latter is a different class even though it shares a utility (and is the territory of
`no-contradicting-variants`). The fix preserves the surrounding whitespace introduced by
`enforce-consistent-line-wrapping`, so a multiline class string keeps its indentation.

The rule walks the same extraction surface as every other rule: `className` / `class` attributes,
all 14 default callees (`cn`, `clsx`, `cva`, `twMerge`, `tv`, `cx`, `classnames`, `ctl`, `twJoin`,
`cc`, `clb`, `cnb`, `objstr`, `classed`), tagged templates like `` tw`...` ``, JSX object values
(`classNames={ { root: "..." } }`), and variables matching the default name patterns (`className`,
`classNames`, `classes`, `style`, `styles`). Deep extraction for `cva` / `tv` / `classed` covers
`base`, `slots`, `variants`, `compoundVariants`, and `compoundSlots`.

## Options

(no options — extractor surface comes from `settings.tailwindcss`)

## Examples

### ✗ Incorrect

```tsx
// Trivial duplicate
<div className="flex flex items-center" />
// → <div className="flex items-center" />

// Duplicate with variant — same token, twice
<div className="hover:flex hover:flex items-center" />
// → <div className="hover:flex items-center" />

// Triple duplicate — two diagnostics, fix collapses to one
<div className="flex flex flex" />
// → <div className="flex" />

// Inside helpers
cn("flex flex items-center")
// → cn("flex items-center")
cva("flex flex", {})
// → cva("flex", {})
tv({ slots: { header: "p-2 p-2" } })
// → tv({ slots: { header: "p-2" } })

// Template literal — surrounding whitespace is preserved
<div className={`flex flex items-center ${x}`} />
// → <div className={`flex items-center ${x}`} />
```

### ✓ Correct

```tsx
// Same utility, different variants — NOT a duplicate
<div className="flex hover:flex dark:flex" />

// Different values
<div className="p-4 m-2 text-red-500" />

// Inside helpers
cn("flex", "items-center")
tv({ slots: { header: "p-2", body: "p-4" } })
```

## Interactions with other rules

- **`no-contradicting-variants`**: `flex flex` is this rule; `flex hover:flex` is
  `no-contradicting-variants`. Keep both on — they cover disjoint shapes.
- **`no-conflicting-classes`**: a duplicate is a degenerate conflict (same class hits the same
  property, trivially). The duplicate path here is faster and produces a clearer message, so this
  rule reports first; `no-conflicting-classes` adds nothing on top.
- **`enforce-sort-order`**: sorting after dedup is the natural pipeline. Both rules autofix, so they
  can run in the same lint pass.
- **`enforce-consistent-line-wrapping`**: the autofix preserves the newlines + indentation that the
  wrapping rule introduced, so the two rules compose cleanly on multiline class strings.

## When to disable it

- **Never, basically.** A literal duplicate is always wrong and the fix is mechanical. If the rule
  is flagging something that isn't a real duplicate, the bug is in extractor configuration — tighten
  `settings.tailwindcss` (e.g. `exclude.attributes`, `exclude.callees`, `exclude.variablePatterns`)
  so the lookalike string isn't treated as a class list.
- **Generated code** in tests or fixtures that intentionally builds a duplicate to exercise
  downstream tooling — disable per file.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-dynamic-classes.md -->

# no-dynamic-classes

oxlint rule that reports Tailwind CSS classes built at runtime, like `bg-${color}-500`, which
Tailwind never sees written out and so generates no CSS for.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options      |
| ------- | ------------------ | ---------------------------------------- | ------------ |
| No      | No                 | Optional — used when `entryPoint` is set | `entryPoint` |

## What this rule does

Tailwind generates CSS for the class names it finds **written out** in your source files. A class
put together at runtime — `` `bg-${color}-500` ``, `` `text-${size}` ``, `` `w-[${width}px]` `` —
never appears in full anywhere, so Tailwind emits nothing for it and the element silently goes
unstyled. It works in development only if the same class happens to be written out somewhere else.

The rule reports each such class once, when the text glued to a `${}` — or to a `+` operand,
`"bg-" + color` — starts with a Tailwind utility (`bg-`, `grid-cols-`, `-mt-`, `w-[`) or a variant
(`hover:`, `md:`, `data-`). A whole class or list coming from a variable (`` `${base} p-4` ``,
`"p-4 " + extra`) is fine, and so is text that isn't Tailwind's (`` `icon-${name}` ``,
`` `${a}-${b}` ``). A class split over two strings (`"bg-" + "red-500"`) is reported too: Tailwind
reads each string on its own. There is no autofix: the fix is to write out every class the value can
map to.

DS-optional. With an `entryPoint`, your project's own utilities and variants count too (a `@theme`
namespace such as `bar-*`); without one, Tailwind's built-in utility and variant roots are used.

What it doesn't see: a variant chosen at runtime after the static text (`` `${breakpoint}:flex` ``).

## Options

### `entryPoint`

`string`, optional. Per-rule override of `settings.tailwindcss.entryPoint`, used to read your
project's utilities and variants.

## Examples

### ✗ Incorrect

```tsx
<div className={`bg-${color}-500 p-2`} />
<div className={`text-${size} font-bold`} />
<div className={`w-[${width}px]`} />
<div className={`hover:${hoverClass}`} />
<div className={cn(`p-${padding}`)} />
<div className={"text-" + tone} />
```

### ✓ Correct

```tsx
// Write out every class the value can map to
const bgByColor = { red: 'bg-red-500', blue: 'bg-blue-500' } as const
<div className={`${bgByColor[color]} p-2`} />

// Pick between full class names
<div className={cn(active ? 'bg-blue-500' : 'bg-gray-500')} />

// A value that really is dynamic: a CSS variable, set inline
<div className="w-(--width)" style={{ '--width': `${width}px` }} />
```

## Interactions with other rules

- **`no-unknown-classes`** ignores the glued fragments (`bg-`, `-500`) — they aren't classes, and
  this rule is the one that reports them.
- **`no-arbitrary-value`**: the CSS-variable fix above is an arbitrary value; allow it with
  `allowVariables: 'runtime'`.

## When to disable it

- **Your classes are safelisted** (`@source inline(…)`), so Tailwind generates them whether or not
  they appear in the source. Disable the rule for those files, or for the project if everything is
  safelisted.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-hardcoded-colors.md -->

# no-hardcoded-colors

oxlint rule that reports hardcoded colors in Tailwind CSS arbitrary values — hex, `rgb()`, `hsl()`,
`oklch()` and more — so colors come from your theme.

## At a glance

| Autofix | Editor suggestions | Design system                            | Options               |
| ------- | ------------------ | ---------------------------------------- | --------------------- |
| No      | No                 | Optional — used when `entryPoint` is set | `entryPoint`, `allow` |

## What this rule does

Flags any class whose arbitrary value carries a hardcoded color literal — anything you'd write with
a paint chip in your hand: hex (`bg-[#ff5733]`, `text-[#000]`), `rgb()`/`rgba()`, `hsl()`/ `hsla()`,
plus the modern color spaces `oklch()`, `oklab()`, `lab()`, `lch()`, `hwb()`, and `color()`. The
goal is the same as `no-arbitrary-value` but scoped exclusively to color, which is where
design-system drift tends to start.

The value is **scanned**, not matched from its first character, and the utility it hangs off is
irrelevant. That matters more than it sounds:

- a color in the middle of a shorthand counts — `shadow-[0_1px_2px_#000]` is a hardcoded black;
- so do utilities no prefix list kept up with — `inset-ring-[#000]`, `inset-shadow-[#000]`;
- and so do arbitrary properties, which no prefix could ever match — `[color:#f00]`,
  `[--brand:#f00]`.

Two things are deliberately excluded, and they are why this is a scanner rather than a regex: a `#`
inside a **quoted string** is text (`content-['#fff']`), and a `#` inside **`url()`** is an SVG node
reference (`fill-[url(#gradient)]`) — the most common non-color `#` in a Tailwind class. Non-color
arbitraries like `w-[200px]` or `tracking-[0.5em]` carry no literal, so they pass as before and this
rule can be enabled even where you _do_ want to allow arbitrary dimensions.

Named colors (`bg-[red]`) are not covered: `currentColor`, `transparent` and `inherit` make that a
judgement call rather than a scan.

Values that reference a CSS variable are treated as design-system indirection and pass:
`bg-[var(--primary)]`, `text-[hsl(var(--fg))]`, `bg-[oklch(var(--bg))]`, even
`bg-[var(--primary,#fff)]` (a fallback inside `var()` still counts as referencing a variable). The
non-recursive `var()` check is shallow — `bg-[linear-gradient(hsl(var(--a)),#fff)]` is _not_ flagged
because at least one `var()` is present. This is documented behavior and tested.

DS-optional — it works with nothing configured. With `settings.tailwindcss.entryPoint`, the message
also names your theme's colors, so the replacement is in front of you:

```text
"bg-[#ff6600]" uses a hardcoded color value. Use one of your theme colors instead: brand,
brand-light.
```

The design system is loaded only once there is a color to report, and a project with no colors of
its own — stock Tailwind — keeps the plain message. No autofix: picking the right token is a human
decision.

## Options

### `allow`

`string[]`, default `[]`.

Exact class strings to whitelist. Matches are literal (no prefix match, no regex) so you can pin
specific allowed escapes without opening the door wider. Useful for the occasional brand-mandated
hex in a single brand-asset component.

```jsonc
{
  "tailwindcss/no-hardcoded-colors": ["error", {
    "allow": ["bg-[#000]", "text-[#fff]"]
  }]
}
```

### `entryPoint`

`string`, optional. Per-rule override of `settings.tailwindcss.entryPoint`, read only to name your
theme's colors in the message.

## Examples

### ✗ Incorrect

```tsx
// Hex literals on color utilities
<div className="bg-[#ff5733] text-[#000]" />
// reports: Use one of your theme colors instead

// rgb/rgba/hsl/oklch are all the same answer
<div className="border-[rgba(0,0,0,0.5)] text-[hsl(120,100%,50%)]" />
<div className="bg-[oklch(0.5_0.2_240)]" />

// Variants and `!` modifier don't help
<div className="hover:bg-[#ff5733] !bg-[#ff5733]" />

// The colour doesn't have to be the whole value
<div className="shadow-[0_1px_2px_#000]" />

// Utilities a prefix list wouldn't have covered
<div className="inset-ring-[#000] inset-shadow-[#111]" />

// Arbitrary properties, including a custom property
<div className="[color:#f00] [--brand:#f00]" />
```

### ✓ Correct

```tsx
// Theme colors
<div className="bg-brand text-brand-light" />

// CSS variable indirection passes
<div className="bg-[var(--primary)] border-[hsl(var(--border))]" />

// Non-color arbitraries are not this rule's business
<div className="w-[200px] tracking-[0.5em]" />

// A `#` inside a quoted string is text
<div className="content-['#fff']" />

// A `#` inside url() references an SVG node
<svg className="fill-[url(#gradient)]" />

// Allowlisted exact string
// options: { "allow": ["bg-[#000]"] }
<div className="bg-[#000]" />
```

## Interactions with other rules

- **`no-arbitrary-value`**: superset. If you enable that rule, every hardcoded color is already
  flagged. Use `no-hardcoded-colors` alone when you want the specific color message and tolerate
  other arbitrary values; use both for a clearer diagnostic on color drift.
- **`no-default-palette`**: the other half. It reports Tailwind's default palette colors
  (`bg-red-500`); this rule reports color literals (`bg-[#f00]`). Together they leave only your
  theme's colors.
- **`prefer-theme-tokens`**: complementary. `prefer-theme-tokens` asks the design system if a
  matching `@theme` color exists and suggests it; this rule fires regardless of whether a token
  exists, so it catches drift earlier (before you've defined the token).
- **`no-unknown-classes`**: orthogonal. Hardcoded arbitraries are _valid_ Tailwind syntax, so
  `no-unknown-classes` won't flag them. Both should be on.

## When to disable it

- **Marketing/brand pages** with handpicked hex that genuinely doesn't belong in the shared design
  system. Prefer `allow` with the specific class strings.
- **Generated content** (e.g. inline avatars colored from a hash) where the color is determined at
  runtime and rendered as inline style anyway — those won't show up here, but if they do, disable
  the line.
- **Component libraries shipping examples** that intentionally demonstrate arbitrary-color usage in
  docs.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-restricted-classes.md -->

# no-restricted-classes

oxlint rule that bans the Tailwind CSS classes you list, by exact name or regex, each with a message
saying what to use instead.

## At a glance

| Autofix | Editor suggestions | Design system | Options               |
| ------- | ------------------ | ------------- | --------------------- |
| No      | No                 | Not used      | `classes`, `patterns` |

## What this rule does

The manual veto. Lets you ban specific Tailwind classes — by exact name or by regex pattern — and
surface a configurable message explaining why. No design system, no heuristics: if the class
matches, the rule fires.

Typical uses: phasing out legacy utilities a refactor wants gone (`float-*` in flexbox-only
codebases), keeping a deprecated brand color out of new code, banning visibility hacks (`hidden`
everywhere but a specific component), or quarantining utilities until a migration is complete.

DS-independent — no `entryPoint` required. No autofix: the rule reports and lets the developer
choose the replacement (often context-specific).

Without options, the rule is a no-op. Configure at least one of `classes` or `patterns` to make it
active.

## Options

### `classes`

`string[]`, default `[]`.

Exact class names to ban. Matches are literal — `"hidden"` matches the bare class `hidden` and the
same class anywhere in a class string (`"flex hidden items-center"`), but does _not_ match
`"sr-hidden"` or `"hover:hidden"`. Use this for a small, explicit ban list.

```jsonc
{
  "tailwindcss/no-restricted-classes": ["error", {
    "classes": ["hidden", "block"]
  }]
}
```

### `patterns`

`Array<{ pattern: string; message?: string }>`, default `[]`.

A list of regex patterns (passed as strings, compiled with `new RegExp`) with an optional custom
message. Use this when you want to ban an entire family (`^float-`, `^text-(red|orange)-`) or when a
literal list would balloon. Patterns are tested against the full class including variants, so
`^hover:bg-red-` matches `hover:bg-red-500`. Custom messages render after the class name and make
the diagnostic actionable.

```jsonc
{
  "tailwindcss/no-restricted-classes": ["error", {
    "patterns": [
      { "pattern": "^float-", "message": "Use flexbox or grid" },
      { "pattern": "^text-(red|orange)-", "message": "Use semantic color tokens" }
    ]
  }]
}
```

If a class matches both `classes` and a pattern, the exact match wins and the rule reports it once.
Otherwise the first matching pattern wins.

## Examples

### ✗ Incorrect

```tsx
// Banned exact class
// options: { "classes": ["hidden"] }
<div className="hidden" />

// Banned somewhere in the middle of a class string
// options: { "classes": ["hidden"] }
<div className="flex hidden items-center" />

// Banned via pattern with custom message
// options: { "patterns": [{ "pattern": "^float-", "message": "Use flexbox" }] }
<div className="float-left" />
// reports: "float-left" is restricted: Use flexbox

// Inside a cn() call
// options: { "classes": ["float-right"] }
cn("float-right")
```

### ✓ Correct

```tsx
// No restrictions configured → rule is silent
<div className="hidden" />

// Class not in the ban list
// options: { "classes": ["hidden"] }
<div className="flex items-center" />

// Variant changes the class — `hover:hidden` doesn't match `hidden`
// options: { "classes": ["hidden"] }
<div className="hover:hidden" />
```

## Interactions with other rules

- **`no-unknown-classes`**: orthogonal. That rule catches invalid classes; this one bans _valid_
  classes you've decided to forbid. Both should be on.
- **`no-deprecated-classes`**: covers the well-known Tailwind v3 → v4 deprecations automatically.
  Use this rule for your project's _own_ deprecations.
- **`no-arbitrary-value` / `no-hardcoded-colors`**: ban categories this rule can't easily express in
  a list. If your ban list is growing into a pattern, those rules might do the job better.

## When to disable it

- **Repos with no ban list**: don't enable it at all — leaving it on with empty options is a no-op
  but adds noise to config review.
- **Per-file legacy exceptions**: prefer
  `// oxlint-disable-next-line tailwindcss/no-restricted-classes` over disabling the rule globally,
  so the rest of the codebase keeps the enforcement.
- **Migration windows** where the ban list flip-flops: drop the rule to `warn`, complete the
  cleanup, then return to `error` once the ban list is stable.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-unknown-classes.md -->

# no-unknown-classes

oxlint rule that reports Tailwind CSS classes your design system doesn't generate, checked against
your CSS, with typo fixes like `itms-center` → `items-center`.

## At a glance

| Autofix | Editor suggestions | Design system           | Options                                     |
| ------- | ------------------ | ----------------------- | ------------------------------------------- |
| No      | Yes                | Required (`entryPoint`) | `entryPoint`, `allowlist`, `ignorePrefixes` |

## What this rule does

Walks every Tailwind class extracted from your code and asks the design system — built from your
`entryPoint` CSS — whether the class is real. If it isn't, the rule reports it. When the class looks
like a typo of a known class, the diagnostic includes a suggestion and an editor quick-fix to
replace it. "Looks like a typo" scales with length: one edit per three characters, at least 1 and at
most 3, where swapping two adjacent letters counts as one edit. So `fex` → `flex`, `opne:` → `open:`
and `bg-primray` → `bg-primary` get a suggestion, but a short project marker such as `line` is
reported without offering `inline`, which would change the layout.

The design system here means **everything Tailwind would generate for your stylesheet**: the core
utilities (`flex`, `bg-red-500`, `hover:underline`), any `@theme` tokens you defined (`bg-card`,
`text-brand-foreground`), any classes registered by plugins (`prose`, `animate-in`, etc.), and any
custom CSS you wrote inline.

DS-dependent — requires `settings.tailwindcss.entryPoint`. When the design system can't load, the
rule emits a single fatal `designSystemUnavailable` diagnostic per file instead of silently passing.

### The variant chain is checked too

A typo in a variant produces no CSS at all, and it used to pass silently: the validity check
stripped the variants before looking at anything. `hoverr:flex`, `darkk:size-4`, `peer-cheked:flex`
and `@mdd:flex` are all reported now, with a suggestion that is **confirmed against the design
system before it is offered** — so `group-hoverr` is corrected to `group-hover` (root kept, tail
fixed) and a variant your own CSS defines (`@custom-variant thumb (&::-webkit-slider-thumb)`) is
spell-checked like a built-in one.

This can't be done from a list of variant names: Tailwind's functional variants (`group-*`,
`data-*`, `@md`, `supports-[…]`, `min-[…]`, `nth-*`, `has-[…]`, `not-*`, `in-[…]`) have an unbounded
value space, so a name list would report most real-world variants as unknown. Instead the chain
itself is compiled, once per distinct chain in the project.

### Off-scale values are checked against Tailwind, not guessed

Tailwind accepts numbers outside the theme scale (`w-45`, `gap-13`, `min-h-17.5`), so the rule used
to accept anything shaped like one — which meant `bg-red-5000`, `bg-red-500/foo` and `w-[]` passed
for exactly the reason `w-45` legitimately does. Classes the precompute cannot enumerate are now
resolved through the design system, batched and memoized, so the answer is Tailwind's rather than a
guess.

`w-[garbage]` stays valid on purpose: Tailwind takes an arbitrary value verbatim and emits
`width: garbage`. Whether that CSS is meaningful is not this rule's call.

Percentages work the same way and used to be the loudest case of this: Tailwind enumerates 21 of the
101 values it compiles (`from-0%`, `from-5%`, …), so `from-33%`, `via-51%`, `mask-b-from-70%` and
`font-stretch-57%` were reported as typos — and the quick-fix offered `from-35%`, which moves the
gradient stop and leaves the lint green. They are accepted now, on the same 22 prefixes Tailwind
takes a percentage for; `p-4%` and `ms-33%` still report, because no percentage compiles there.

### Custom utilities with an open value type

`@utility` covers three kinds of value space, and only two of them can be listed:

```css
@utility brand-* {
  --brand: --value(--brand-*);
} /* bounded by the theme  → enumerable */
@utility align-* {
  --align: --value("a", "b");
} /* a literal set         → enumerable */
@utility step-* {
  --step: --value(integer);
} /* OPEN                  → not enumerable */
```

For the open one Tailwind's class list returns nothing at all — not `step-1`, not even the root
`step` — because there is no finite set to return. The rule used to read `step-1` as a typo for that
reason. It now asks the design system, which compiles the class and says so, and the same answer
keeps refusing what the value type refuses: with `--value(integer)`, `step-abc`, `step-1.5` and
`step-[3]` all still report.

One consequence worth knowing: there is no spelling suggestion for this family. A suggestion is
drawn from the enumerated class list, and by definition your open utility isn't in it — so a real
typo in the root (`stepp-1`) reports as plainly unknown.

### Named group/peer markers are valid

`group/menu-item` and `peer/menu-button` are the v4 idiom for binding a variant to **one specific**
ancestor or sibling when several are in play — the pattern shadcn/ui's sidebar is built on. The
marker emits no CSS of its own, which is the whole point: the CSS lives in the consumer that reads
it. `group-hover/menu-item:underline` compiles to

```css
.group-hover\/menu-item\:underline:is(:where(.group\/menu-item):hover *) { text-decoration-line: underline; }
```

A CSS class selector matches whole tokens of the `class` attribute, so bare `group` does **not**
satisfy `:where(.group\/menu-item)`. The marker is required markup — remove it and every consumer
silently stops matching.

The name is yours and Tailwind never checks that it exists, so any non-empty name is accepted,
including shapes only an arbitrary modifier on the consumer can reach (`group/*`, `group/a/b`,
`peer//x`). The one spelling that is genuinely dead is the **empty** name: `peer/` compiles to
nothing and is reported.

A class named by a `@custom-variant` selector works the same way and stays valid:
`@custom-variant sidebar-open (&:where(.sidebar-open *))` makes `sidebar-open` load-bearing even
though nothing declares it.

## Project prefix (`prefix(...)`)

If your entry point declares a Tailwind v4 prefix — `@import "tailwindcss" prefix(tw)` — every
utility must be written with that prefix (`tw:flex`, `tw:hover:underline`). The rule is
prefix-aware:

- A correctly prefixed utility (`tw:flex`) is valid.
- A Tailwind utility written **without** the prefix (`flex`) produces no CSS, so it's reported as
  needing the prefix, with a quick-fix that adds it (`flex` → `tw:flex`).
- Component classes from `@layer components` (`btn`, `card`) carry no prefix and stay valid either
  way — only Tailwind-generated utilities require it.
- Named markers need the prefix too, because that is what Tailwind puts in the selector:
  `tw:group-hover/menu-item:underline` compiles to `:is(:where(.tw\:group\/menu-item):hover *)`, so
  `tw:group/menu-item` is valid and a bare `group/menu-item` is reported as needing the prefix.
- Your own `@utility` follows the same rule, including the open-value kind above: the design system
  is asked about the prefixed form, so `tw:step-1` is valid and a bare `step-1` gets the quick-fix.
- The prefix is only offered as the fix when the prefixed form actually compiles. `bg-red-5000` is
  shaped like a utility, but `tw:bg-red-5000` is as dead as the unprefixed spelling, so that one is
  reported as unknown with a spelling suggestion instead.

The prefix is detected automatically from your `entryPoint`; there is nothing extra to configure.

## Options

### `allowlist`

`string[]`, default `[]`.

Exact class names to whitelist. Use this when the class is generated at runtime (template strings
the plugin can't statically resolve) or when it's deliberately not part of your design system but
you want it to survive linting. Matches are literal — `"my-special"` does not match
`"hover:my-special"`.

```jsonc
{ "tailwindcss/no-unknown-classes": ["error", { "allowlist": ["my-runtime-class", "legacy-button"] }] }
```

### `ignorePrefixes`

`string[]`, default `[]`.

Skip any class whose name begins with one of these prefixes. Use this for whole families of classes
you intentionally manage outside the design system — e.g. a CSS module compiled namespace (`s-`), a
third-party UI kit (`ant-`, `chakra-`), or framework-injected classes (`vue-enter`).

```jsonc
{ "tailwindcss/no-unknown-classes": ["error", { "ignorePrefixes": ["ant-", "swiper-"] }] }
```

Prefer `ignorePrefixes` over `allowlist` when there are many classes sharing a stem — easier to
maintain.

### `entryPoint`

`string`, optional.

Per-rule override of `settings.tailwindcss.entryPoint`. Almost nobody needs it — set the entry point
once in `settings`.

## Examples

### ✗ Incorrect

```tsx
// Typos — each class is reported with a suggestion
<div className="flx items-cetner" />
//              ~~~ ~~~~~~~~~~~~ → flex items-center

// Class doesn't exist (no plugin / no @theme token)
<div className="text-brrrand" />
// → <div className="text-brand" />

// Variant on a bogus class
<div className="hover:foo-500" />

// Typo in the VARIANT — the utility is fine, the class emits nothing
<div className="hoverr:flex peer-cheked:underline" />
//              ~~~~~~      ~~~~~~~~~~~ → hover:flex peer-checked:underline

// Shaped like an off-scale value, but Tailwind compiles neither
<div className="bg-red-5000 bg-blue-500/foo" />
// → <div className="bg-red-500 bg-blue-500/foo" />
```

### ✓ Correct

```tsx
// Core utility
<div className="flex items-center" />

// Theme token (works after declaring it in @theme in your entryPoint CSS)
<div className="bg-card text-card-foreground" />

// Plugin-registered class
<article className="prose prose-invert" />

// Off-scale values Tailwind does compile
<div className="w-45 gap-13 min-h-17.5 from-33%" />

// Your own utility, whatever its value type
// @utility step-* { --step: --value(integer) }
<div className="step-1 step-42" />

// Every variant shape, functional and arbitrary alike
<div className="group-hover:flex data-[state=open]:grid @md:block [&>svg]:size-4" />

// Named group/peer markers, and the consumers that read them
<div className="group/menu-item peer/menu-button" />
<div className="group-hover/menu-item:underline peer-data-[size=sm]/menu-button:top-1" />

// A class your runtime adds, allowlisted
// options: { "allowlist": ["my-runtime-class"] }
<div className="flex my-runtime-class" />

// A library's own classes, by prefix
// options: { "ignorePrefixes": ["swiper-"] }
<div className="swiper-slide flex" />
```

## Interactions with other rules

- **`no-deprecated-classes`**: this rule silently skips the v3 renames that one owns (`flex-grow`,
  `bg-gradient-to-r`, `break-words`, …) so you don't get two diagnostics for the same class. The
  list comes from the design system, not from a copy inside this rule, so the two cannot drift
  apart. Keep both rules on.
- **`enforce-canonical`**: complements this rule. `no-unknown-classes` catches typos and missing
  tokens; `enforce-canonical` rewrites valid-but-outdated forms (`-m-0` → `m-0`).
- **`no-restricted-classes`**: orthogonal. Use that one to ban valid classes you don't want; use
  this one to catch invalid ones.

## When to disable it

- **Heavy use of dynamic class generation** that the extractor can't resolve (e.g. classes assembled
  from untyped server data). The rule reports everything it doesn't recognize as unknown. Prefer
  `allowlist` or `ignorePrefixes` over disabling entirely.
- **Migrating an existing codebase**: run as `warn` until cleanup is complete, then bump to `error`.
- **Inside CSS-in-JS where the class strings aren't Tailwind**: this is usually solved by tightening
  your extractor config (remove the conflicting callee or attribute via
  `settings.tailwindcss.exclude`) rather than disabling the rule.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-unnecessary-arbitrary-value.md -->

# no-unnecessary-arbitrary-value

oxlint rule that replaces a Tailwind CSS arbitrary value with the named class that emits the same
CSS in your theme, like `w-[100%]` → `w-full`.

## At a glance

| Autofix | Editor suggestions | Design system           | Options      |
| ------- | ------------------ | ----------------------- | ------------ |
| Yes     | Yes                | Required (`entryPoint`) | `entryPoint` |

## What this rule does

Detects utilities written with an arbitrary value (`w-[200px]`, `h-[auto]`,
`bg-[var(--color-red-500)]`) where the design system already exposes a named utility that produces
the exact same CSS, and rewrites the arbitrary form to the named one. The lookup goes through the
precomputed `arbitraryEquivalents` map (built once per `@theme` — for every named utility, the
precompute step enumerates every dash split point so multi-segment utilities like `bg-red-500`
register both `bg-[<value>]` and `bg-red-[<value>]`). Auto-fix lands on the first hit, suggestions
cover the rest in the same string. Variants and `!` (important) are preserved.

The check fires only when an arbitrary value is present in the utility (`hasArbitraryValue(cls)` is
true) AND the cache returns a `getNamedEquivalent` match. That keeps the rule cheap and focused — no
fuzzy resolution, no DS round-trip per class.

DS-dependent — requires `settings.tailwindcss.entryPoint`. If the design system can't load, the rule
emits a single fatal `designSystemUnavailable` diagnostic per file instead of silently passing.

## Options

This rule has no per-rule options beyond the standard `entryPoint` override (string, defaults to
`settings.tailwindcss.entryPoint`). Configure the entry point in `settings.tailwindcss.entryPoint`
for the whole project instead of per-rule whenever possible.

## Examples

### ✗ Incorrect

```tsx
// `h-[auto]` is just `h-auto`
<div className="h-[auto] w-[auto]" />
// → <div className="h-auto w-auto" />

// var() reference to a theme color that has a named utility
<div className="bg-[var(--color-red-500)] text-[var(--color-blue-700)]" />
// → <div className="bg-red-500 text-blue-700" />

// Variant prefix and important are preserved
<div className="hover:h-[auto] !w-[auto]" />
// → <div className="hover:h-auto !w-auto" />
```

### ✓ Correct

```tsx
// Named utilities produce the same CSS
<div className="h-auto w-auto" />

<div className="bg-red-500 text-blue-700" />

<div className="hover:h-auto !w-auto" />

// Arbitrary value with no named equivalent — leave it
<div className="w-[200px] bg-[#custom]" />
```

## Interactions with other rules

- **`enforce-canonical`**: complementary, no double-fire. Both act only when the arbitrary form and
  its named replacement emit **identical** CSS. This rule owns the direct arbitrary→named case
  (`h-[auto]` → `h-auto`, `bg-[var(--color-red-500)]` → `bg-red-500`); `enforce-canonical` owns the
  canonicalizations where the arbitrary maps to a differently-named utility
  (`rounded-[var(--radius-sm)]` → `rounded-sm`). The two carve up the arbitrary→named space cleanly
  — and the plain `[var(--x)]` ↔ `(--x)` syntax swap is `enforce-consistent-variable-syntax`'s, not
  either of theirs.
- **`prefer-scale-token`**: owns what neither of the above touches — a value that is only
  _numerically_ equal to a scale step or theme token (`p-[2px]` → `p-0.5`), whose CSS text differs
  (`calc(var(--spacing) * 0.5)` vs `2px`). Report-only, off by default.
- **`prefer-theme-tokens`**: also complementary. It fires for CSS-var references in the
  `prefix-(--name)` / `prefix-[var(--name)]` paren shorthand when no bracket-equivalent exists —
  that's the heuristic- only case this rule explicitly rejects (see the `getNamedEquivalent` guard).
- **`no-deprecated-classes`**: orthogonal. Deprecated names like `flex-grow` don't have arbitrary
  values, so the two rules never touch the same class.

## When to disable it

- **You intentionally keep arbitrary values for readability** — some teams prefer `w-[200px]` to a
  token alias when the value is one-off or pixel-precise. Disable the rule and rely on
  `prefer-theme-tokens` + `enforce-canonical` for the cases you do want flagged.
- **Migrating from a different tooling chain** that produced arbitrary values for everything — run
  as `warn` until cleanup is complete, then bump to `error`.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/no-unnecessary-whitespace.md -->

# no-unnecessary-whitespace

oxlint rule that collapses repeated spaces and trims leading and trailing whitespace in Tailwind CSS
class strings, with an autofix.

## At a glance

| Autofix | Editor suggestions | Design system | Options |
| ------- | ------------------ | ------------- | ------- |
| Yes     | No                 | Not used      | None    |

## What this rule does

Normalizes whitespace inside Tailwind class strings: runs of spaces or tabs collapse to one space,
leading and trailing whitespace gets trimmed (with one carve-out at template-expression boundaries —
see below), and the rule autofixes everything in a single pass.

DS-independent — works without `settings.tailwindcss.entryPoint`. Pure whitespace transform.

The rule is **multiline-aware**: it deliberately preserves `\n` + the indentation that follows each
newline. That's the format `enforce-consistent-line-wrapping` produces with `classesPerLine`, and
collapsing it back would set up an unfixable cycle between the two rules (issue #14). This includes
the indented closing backtick of the block convention (a `\n` + spaces before the closing `` ` ``) —
that trailing indentation is intentional formatting and is never trimmed (issue #109). Inside one
line, tabs and double spaces still collapse normally.

Template literals get one extra rule: a single trailing space before an expression
(`` `flex ${x}` ``) or a single leading space after one (`` `${x} flex` ``) is preserved — those are
intentional spaces that prevent classes from being smashed together at runtime.

## Options

This rule has no options. The behavior is "collapse runs to single spaces, preserve intentional
newlines and template-boundary spaces" — there's no useful axis to configure.

## Examples

### ✗ Incorrect

```tsx
// Leading + trailing + internal double spaces
<div className="  flex   items-center  " />
//              ~~~~~~~~~~~~~~~~~~~~~~~~  → "flex items-center"

// Internal double space
<div className="flex  items-center" />
//              ~~~~~~~~~~~~~~~~~~  → "flex items-center"

// Tab as separator inside a single line
const className = `flex	items-center`
//                 ~~~~~~~~~~~~~~~~~  → "flex items-center"
```

### ✓ Correct

```tsx
// Single spaces
<div className="flex items-center" />

// Template literal: boundary spaces preserved
<div className={`flex ${x}`} />
<div className={`${x} flex`} />

// Multiline (e.g. from enforce-consistent-line-wrapping): preserved
const className = `bg-red-500 text-white
                   hover:bg-red-600 focus:ring-2`

// Block convention: the indented closing backtick is preserved (#109)
const className = `
  bg-red-500 text-white
  hover:bg-red-600 focus:ring-2
`
```

## Interactions with other rules

- **`enforce-consistent-line-wrapping`**: designed to coexist. This rule preserves the `\n` + indent
  that wrapping inserts; without that, the two would fight on every autofix pass.
- **`enforce-sort-order`** and every other class-rewriting rule: those rebuild the string via
  `rebuildClassString`, which always emits canonical single-space separators — running them first
  makes `no-unnecessary-whitespace` a no-op.
- **All extractor-driven rules**: the cleaned-up string is what every other rule sees on the next
  pass, so running this rule early in a fix cycle keeps downstream errors readable.

## When to disable it

- **You rely on a formatter** like `prettier` or `oxfmt` to handle whitespace globally. They cover
  the same ground, and disabling the lint rule removes redundant work.
- **Class strings that intentionally use unusual whitespace** (very rare — almost always a bug in
  extractor configuration rather than intent).

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/prefer-scale-token.md -->

# prefer-scale-token

oxlint rule that suggests the Tailwind CSS scale step or theme token a hardcoded value equals, like
`p-[10px]` → `p-2.5` or `rounded-[0.5rem]` → `rounded-lg`.

## At a glance

| Autofix | Editor suggestions | Design system           | Options                       |
| ------- | ------------------ | ----------------------- | ----------------------------- |
| No      | Yes                | Required (`entryPoint`) | `entryPoint`, `step`, `allow` |

## What this rule does

Reports a hardcoded value that is **numerically equal** to something your design system already
names, and suggests the name — `p-[10px]` → `p-2.5`, `w-[140px]` → `w-35`, `rounded-[0.5rem]` →
`rounded-lg`.

### Parity with Tailwind CSS IntelliSense

This is the rule that reproduces Tailwind CSS IntelliSense's `suggestCanonicalClasses` diagnostic
for arbitrary lengths — the "`pl-[15px]` can be written as `pl-3.75`" hint. `enforce-canonical` and
`no-unnecessary-arbitrary-value` deliberately do **not** report it: both require byte-identical CSS,
and `pl-3.75` compiles to `calc(var(--spacing) * 3.75)`, not `15px`
([#78](https://github.com/sergioazoc/oxlint-tailwindcss/issues/78)).

The suggestions are applied by `oxlint --fix-suggestions` (never by plain `oxlint --fix`), which
matches the editor experience. To reproduce the IntelliSense example exactly — dynamic steps like
`pl-3.75` that fall between the enumerated `0.5` stops — set a finer `step` (see [`step`](#step)
below):

```jsonc
{ "tailwindcss/prefer-scale-token": ["warn", { "step": 0.25 }] }
```

It exists because the other three arbitrary→named rules each key on something this case does not
satisfy:

| Rule                             | Fires on                               | Keyed on               |
| -------------------------------- | -------------------------------------- | ---------------------- |
| `no-unnecessary-arbitrary-value` | `w-[100%]` → `w-full`                  | byte-identical CSS     |
| `enforce-canonical`              | what `canonicalizeCandidates` proposes | the same, since #78    |
| `prefer-theme-tokens`            | `bg-(--primary)` → `bg-primary`        | the NAME of a variable |
| **this rule**                    | `p-[10px]` → `p-2.5`                   | **numeric equality**   |

`p-2.5` compiles to `padding: calc(var(--spacing) * 2.5)` and `p-[10px]` to `padding: 10px`. Same
length, different text — so no rule that requires identical CSS can report it, which is exactly what
changed in [#78](https://github.com/sergioazoc/oxlint-tailwindcss/issues/78) when the autofixer was
made conservative.

### Report-only, on purpose

**There is no autofix.** The equivalence holds in _this_ theme: the token reaches its value through
a CSS variable, so a `:root` override or a different root font size makes the two diverge. Rewriting
that automatically is the bug #78 fixed. The rule reports, offers the replacement as an editor
suggestion, and says so in the message.

### What counts as "equal"

Two families, both derived from your design system — there is no name table in this rule:

- **The spacing scale.** `--spacing` is read from your theme, and the utility prefixes that use it
  are found by asking what `<prefix>-1` compiles to. `p-[10px]` ÷ `0.25rem` = 2.5 steps → `p-2.5`.
- **Named theme tokens, by value.** For every class that emits exactly one declaration whose whole
  value is one `var(--x)`, the theme says what `--x` is worth: `0.5rem` → `rounded-lg`. Two
  restrictions come out of that shape and matter:
  - a class that declares MORE than the literal is not an equivalent, so `text-[14px]` → `text-sm`
    is **not** reported (`text-sm` also sets `line-height`);
  - a colour token can never match a value a human typed, so the ~7 000 colour classes are simply
    not candidates.

### Why there is a granularity at all

Tailwind v4 compiles _any_ number: `w-8.425` is a valid class. So every length is N spacing units
for some N, and reporting all of them would make this rule fire on practically every arbitrary value
— which is what `no-arbitrary-value` is for.

The cut is not a number picked here. Every step Tailwind's own scale enumerates (`0`, `0.5`, `1`,
`1.5`, `2`, `2.5`, `3`, `3.5`, `4`, `5`…`96`) is a multiple of `0.5`, and the precompute derives
that from the enumerated steps themselves. `w-[140px]` → `w-35` is reported (35 is a whole number of
steps); `w-[33.7px]` → `w-8.425` is not. Use `step` to go finer.

## Options

### `entryPoint`

`string`, optional. A CSS entry point for this rule alone, overriding
`settings.tailwindcss.entryPoint`. This rule is DS-dependent — every equivalence comes from the
design system, so there is no static fallback and a missing entry point is a fatal
`designSystemUnavailable` diagnostic.

### `step`

`number`, optional. Defaults to the granularity derived from your theme's enumerated scale (`0.5`
with Tailwind's default `--spacing`). Lower it to report finer values:

```jsonc
// also report w-[33px] → w-8.25
{ "tailwindcss/prefer-scale-token": ["warn", { "step": 0.25 }] }
```

Raising it makes the rule quieter (`step: 1` stops reporting `p-[10px]` → `p-2.5`). It has no effect
on named theme tokens: those match by value, not by granularity.

### `allow`

`string[]`, default `[]`. Utility prefixes to skip, matched with `startsWith` against the bare
utility — the same shape as `no-arbitrary-value`'s option.

```jsonc
{ "tailwindcss/prefer-scale-token": ["warn", { "allow": ["grid-cols-", "bg-[url("] }] }
```

## Examples

### ✗ Incorrect

```tsx
// Values that are whole steps of the spacing scale
<div className="p-[10px] gap-[4px] mt-[6px]" />
//              ~~~~~~~~ ~~~~~~~~~ ~~~~~~~~  → p-2.5 gap-1 mt-1.5

// Off the enumerated scale but still a whole step — Tailwind compiles w-35
<div className="w-[140px]" />
//              ~~~~~~~~~  → w-35

// A named theme token, matched by its value
<div className="rounded-[0.5rem] basis-[28rem]" />
//              ~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~  → rounded-lg basis-md

// Variants and `!` travel with the class
<div className="hover:p-[10px] p-[10px]!" />
// → <div className="hover:p-2.5 p-2.5!" />
```

### ✓ Correct

```tsx
// The token itself
<div className="p-2.5 rounded-lg w-35" />

// Finer than the granularity Tailwind's own scale uses
<div className="w-[33px] w-[33.7px]" />

// Byte-identical to a named class — no-unnecessary-arbitrary-value's business
<div className="w-[100%] z-[10] p-[0px]" />

// text-sm also sets line-height, so it is not what text-[14px] says
<div className="text-[14px]" />

// A variable reference has no literal to compare — prefer-theme-tokens looks at these
<div className="p-(--gutter) p-[var(--gutter)]" />

// Not a length, or on a prefix that does not read the scale
<div className="w-[50%] grid-cols-[18rem_1fr] bg-[#ff0000]" />
```

## Interactions with other rules

- **`enforce-canonical`**: this rule is the report-only half of what that one gave up in #78. They
  cannot both fire on the same class: anything `enforce-canonical` rewrites is byte-identical, and
  this rule's `getNamedEquivalent` guard skips exactly those.
- **`no-unnecessary-arbitrary-value`**: owns the byte-identical cases (`w-[100%]` → `w-full`). Same
  guard, same reason.
- **`prefer-theme-tokens`**: owns the cases where the user wrote a variable reference
  (`bg-(--primary)`), matched by NAME. This rule only looks at literals.
- **`no-arbitrary-value`**: a superset in spirit — it bans arbitrary values outright. If you run
  that, this rule adds the specific "and there is a token for this exact value" message.

The four-way boundary is locked down in `tests/integration/prefer-theme-tokens-coexistence.test.ts`.

## When to disable it

- **You deliberately use pixel values** for a subsystem where the scale is the wrong unit (a chart,
  a canvas overlay, an embedded third-party widget). Prefer `allow` with those prefixes.
- **You don't want the nudge at all.** This rule is off unless you enable it: the equivalence is
  real but acting on it is a convention, not a correctness fix.

---

<!-- https://oxlint-tailwindcss.pages.dev/rules/prefer-theme-tokens.md -->

# prefer-theme-tokens

oxlint rule that rewrites raw CSS variable references into your theme's named Tailwind CSS
utilities, like `border-(--border)` → `border-border`.

## At a glance

| Autofix | Editor suggestions | Design system           | Options      |
| ------- | ------------------ | ----------------------- | ------------ |
| Yes     | Yes                | Required (`entryPoint`) | `entryPoint` |

## What this rule does

Detects utilities written as a raw CSS-variable reference — `border-(--border)`,
`bg-[var(--primary)]`, `text-(--background)/80` — and rewrites them to the named theme-token utility
when one exists in your design system. So `border-(--border)` becomes `border-border`,
`hover:bg-[var(--primary)]/50` becomes `hover:bg-primary/50`, and `bg-(--red-500)` (where the user
reached past the `--color-` prefix) becomes `bg-red-500`. Both the paren shorthand
(`prefix-(--name)`) and the bracket form (`prefix-[var(--name)]`) are recognized, and opacity
modifiers (`/80`), variants, and `!` (important) are all preserved.

The candidate `${prefix}-${varName}` has to be a real utility in your DS — the rule consults
`cache.isValid(candidate)`. Existing by name is not enough, though: the named token has to MEAN the
same thing. `@theme inline { --color-primary: var(--primary) }` makes `bg-primary` and
`bg-(--primary)` the same declaration, while a literal `--color-primary` alongside an unrelated
`--primary` makes them different colours — and this rule autofixes. So the rewrite is only proposed
when the token's declaration resolves back to the variable you wrote, or when that variable is
defined nowhere (in which case the current declaration is dead CSS and the token can only be an
improvement). Then it skips any candidate that `cache.getNamedEquivalent` would also resolve,
because that case is owned by `no-unnecessary-arbitrary-value` (same CSS, no double-fire).

DS-dependent — requires `settings.tailwindcss.entryPoint`. If the design system can't load, the rule
emits a single fatal `designSystemUnavailable` diagnostic per file instead of silently passing.

## Options

This rule has no per-rule options beyond the standard `entryPoint` override (string, defaults to
`settings.tailwindcss.entryPoint`). Configure the entry point in `settings.tailwindcss.entryPoint`
for the whole project instead of per-rule whenever possible.

## Examples

### ✗ Incorrect

Assuming a shadcn-style theme with tokens like `--border`, `--primary`, `--background`:

```tsx
// Paren shorthand — the canonical case
<div className="border-(--border) bg-(--primary)" />
// → <div className="border-border bg-primary" />

// Bracket form
<div className="bg-[var(--primary)]/50" />
// → <div className="bg-primary/50" />

// Variants, important, opacity modifiers all preserved
<div className="hover:!border-(--border) dark:bg-(--primary)/80" />
// → <div className="hover:!border-border dark:bg-primary/80" />

// Directional sub-utility
<div className="border-l-(--border)" />
// → <div className="border-l-border" />
```

### ✓ Correct

```tsx
<div className="border-border bg-primary" />

<div className="bg-primary/50" />

<div className="hover:!border-border dark:bg-primary/80" />

<div className="border-l-border" />

// Variable with no matching named utility — leave it
<div className="border-(--no-such-token)" />
```

## Interactions with other rules

- **`no-unnecessary-arbitrary-value`**: paired explicitly. When the bracket form is CSS-equivalent
  to a named utility, the other rule wins and this one stays silent (`getNamedEquivalent` guard). So
  `bg-[var(--color-red-500)]` → `bg-red-500` is owned there; `border-(--border)` → `border-border`
  lives here.
- **`enforce-canonical`**: also part of the arbitrary→named trio. It handles cases where
  canonicalization produces a different CSS shape via your tokens. The three rules carve up the
  space so each arbitrary form has exactly one owner.
- **`enforce-consistent-variable-syntax`**: orthogonal — that rule decides between paren and bracket
  forms when you're staying on the CSS-var representation. This one promotes you off CSS-vars onto a
  named token when possible.

## When to disable it

- **You deliberately want to reference variables by name in markup** to make the theme dependency
  explicit at the call site. In that case keep `no-unnecessary-arbitrary-value` on (CSS-equivalent
  cases) but disable this rule.
- **Your design system uses CSS variables that aren't registered as named utilities** in `@theme` —
  the rule won't fire on those, but if your codebase mixes the two patterns and you don't want
  gradual pressure to expose more tokens, disable it.

---

<!-- https://oxlint-tailwindcss.pages.dev/shadcn.md -->

# shadcn/ui and @shadcn/lint

oxlint-tailwindcss reads a shadcn/ui project's theme — `app/globals.css`, with its CSS variables and
`@theme inline` colors — like any other Tailwind v4 stylesheet, so it needs nothing shadcn-specific.
[@shadcn/lint](https://github.com/shadcn-ui/lint) is a separate oxlint plugin with a different job:
it enforces your design-system policy — which classes a component accepts, theme colors instead of
the palette, no arbitrary values, no inline styles. They run together. Where both have a rule for
the same problem, turn one off, so each problem is reported once.

## Who reports what

<!-- generated:shadcn-table -->

| What                                                                           | Example                                                        | @shadcn/lint                          | oxlint-tailwindcss                               | Combined config    |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------ | ------------------ |
| Restyling a design-system component through `className`                        | `<Button className="rounded-full p-4">Pay</Button>`            | `no-restyle`                          | —                                                | @shadcn/lint       |
| Inline styles                                                                  | <span v-pre>`<div style={{ color: "#f00" }}>Sale</div>`</span> | `no-inline-styles`                    | —                                                | @shadcn/lint       |
| A Tailwind palette color instead of a theme color                              | `<div className="bg-red-500">Sale</div>`                       | `no-raw-colors`                       | `no-default-palette`                             | @shadcn/lint       |
| Arbitrary values                                                               | `<div className="p-[13px]">Card</div>`                         | `no-arbitrary-values`                 | `no-arbitrary-value`, `no-hardcoded-colors`      | @shadcn/lint       |
| A CSS variable where the theme has a named class                               | `<div className="bg-(--primary)">Card</div>`                   | —                                     | `no-arbitrary-value`, `prefer-theme-tokens`      | oxlint-tailwindcss |
| Classes Tailwind can't generate: typos in utilities, variants and theme colors | `<div className="itms-center">Card</div>`                      | `no-unknown-classes`, `no-raw-colors` | `no-unknown-classes`                             | oxlint-tailwindcss |
| Classes built at runtime                                                       | `<div className={`bg-${tone}-500`}>Card</div>`                 | `require-static-classes`              | `no-dynamic-classes`                             | both               |
| Classes that override each other                                               | `<div className="line-clamp-1 flex">Card</div>`                | —                                     | `no-conflicting-classes`                         | oxlint-tailwindcss |
| Duplicate classes                                                              | `<div className="flex flex">Card</div>`                        | —                                     | `no-duplicate-classes`                           | oxlint-tailwindcss |
| Classes deprecated in Tailwind v4                                              | `<div className="flex-shrink-0">Card</div>`                    | —                                     | `no-deprecated-classes`                          | oxlint-tailwindcss |
| Classes with a canonical form                                                  | `<div className="-m-0">Card</div>`                             | —                                     | `enforce-canonical`                              | oxlint-tailwindcss |
| A dark-mode color with no light-mode base                                      | `<div className="dark:bg-accent">Card</div>`                   | —                                     | `no-dark-without-light`                          | oxlint-tailwindcss |
| Class and variant order                                                        | `<div className="p-4 flex">Card</div>`                         | —                                     | `enforce-sort-order`, `consistent-variant-order` | oxlint-tailwindcss |

<!-- /generated:shadcn-table -->

Every example above is linted by both plugins in a minimal shadcn/ui project, and the table is
checked against what they report: this plugin's column on every build, @shadcn/lint's every week
against its latest release. Where the combined config below gives a problem to one of them:

- **Unknown classes → oxlint-tailwindcss.** Both report a misspelt utility or variant with a
  suggestion. This plugin also reports a class name Tailwind can't generate at all (`line`), and a
  misspelt theme color under the same rule, with the color you meant (`bg-primray` → `bg-primary`).
  @shadcn/lint's `no-raw-colors` reports that misspelt color as well, as an undeclared theme color —
  the one problem both still report.
- **Arbitrary values → @shadcn/lint.** Both report them with a fix; `no-arbitrary-values` suggests
  the exact value on the scale (`p-[13px]` → `p-3.25`). This plugin's `no-arbitrary-value` is off in
  its recommended config, and the combined config also turns off `no-hardcoded-colors`, whose
  arbitrary colors `no-arbitrary-values` already reports.
- **Classes built at runtime → both.** @shadcn/lint's `require-static-classes` reports a `className`
  it can't read on a component, which it needs to check the component's policy; this plugin's
  `no-dynamic-classes` reports a class built at runtime on any element, because Tailwind generates
  no CSS for it.
- **`prefer-theme-tokens` is on** (it's off in the recommended config): shadcn/ui's colors are CSS
  variables, and `bg-(--primary)` has a named class, `bg-primary`.

## The combined config

```bash
pnpm add -D oxlint oxlint-tailwindcss @shadcn/lint
```

<!-- generated:shadcn-config -->

```jsonc
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "jsPlugins": ["oxlint-tailwindcss", "@shadcn/lint"],
  "settings": {
    "tailwindcss": {
      "entryPoint": "app/globals.css"
    }
  },
  "rules": {
    // oxlint-tailwindcss: the recommended rules, adjusted for shadcn/ui
    "tailwindcss/no-conflicting-classes": "error",
    "tailwindcss/no-contradicting-variants": "warn",
    "tailwindcss/no-dark-without-light": "warn",
    "tailwindcss/no-duplicate-classes": "warn",
    "tailwindcss/no-dynamic-classes": "error",
    "tailwindcss/no-unknown-classes": "error",
    "tailwindcss/enforce-canonical": "warn",
    "tailwindcss/enforce-negative-arbitrary-values": "warn",
    "tailwindcss/no-deprecated-classes": "error",
    "tailwindcss/no-unnecessary-arbitrary-value": "warn",
    "tailwindcss/prefer-theme-tokens": "warn",
    "tailwindcss/consistent-variant-order": "warn",
    "tailwindcss/enforce-consistent-important-position": "warn",
    "tailwindcss/enforce-consistent-variable-syntax": "warn",
    "tailwindcss/enforce-shorthand": "warn",
    "tailwindcss/enforce-sort-order": "warn",
    "tailwindcss/no-unnecessary-whitespace": "warn",
    // @shadcn/lint
    "shadcn/no-restyle": ["error", { "allow": ["layout"] }],
    "shadcn/no-raw-colors": "error",
    "shadcn/no-arbitrary-values": "error",
    "shadcn/no-inline-styles": "error",
    "shadcn/require-static-classes": "error"
  },
  "overrides": [
    {
      "files": ["components/ui/**"],
      "rules": { "shadcn/no-restyle": "off" }
    }
  ]
}
```

<!-- /generated:shadcn-config -->

- `entryPoint` is the stylesheet `components.json` names under `tailwind.css`: `app/globals.css` in
  a Next.js app, `src/index.css` in a Vite one.
- The override turns `no-restyle` off inside the components directory, as @shadcn/lint's docs ask,
  so components can style their own internals. Point it at yours if `components.json` puts them
  elsewhere (`aliases.ui`).
- What each component accepts (`contracts`), custom messages and the rest of @shadcn/lint's
  configuration are its own: see [its rules](https://github.com/shadcn-ui/lint#rules).

## What it finds in shadcn/ui

Run on shadcn/ui's own components (`apps/v4` at `98a1fe67`), `no-conflicting-classes` reports the
select trigger in `registry/new-york-v4/ui/select.tsx`:

```text
"*:data-[slot=select-value]:flex" overrides "*:data-[slot=select-value]:line-clamp-1" on "display".
"*:data-[slot=select-value]:flex" comes later in the generated stylesheet, so it wins no matter how
the class attribute is ordered. Remove one.
```

`line-clamp-1` truncates with `display: -webkit-box`, and the later `display: flex` replaces it, so
the clamp never applies: a long selected value gets no ellipsis and pushes past the trigger's width.
[shadcn-ui/ui#11832](https://github.com/shadcn-ui/ui/pull/11832), an open pull request that fixes
that overflow, describes the same cause.

## Setting it up, step by step

For a person or an agent, in a shadcn/ui project:

1. Read `components.json`: `tailwind.css` is the entry point, and `aliases.ui` is the components
   directory (`@/components/ui` → `components/ui/**`).
2. Install `oxlint`, `oxlint-tailwindcss` and `@shadcn/lint` as dev dependencies, with the project's
   package manager.
3. Write the combined config to `.oxlintrc.json`, with `entryPoint` set to the entry point and the
   override's `files` to the components directory. If there's a config already, merge: keep its
   rules and add the plugins, the setting and the rules above.
4. Run `oxlint`. `oxlint --fix` applies the autofixes; the editor offers the suggestions.
5. Leave @shadcn/lint's policy — what each component accepts — to the design system's owner.