enforce-canonical

Enforce canonical Tailwind CSS class names using canonicalizeCandidates()

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), bg-gradient-to-r → bg-linear-to-r, break-words → wrap-break-word, start-2 → inset-s-2, flex-grow-1 → grow, 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.

Named classes resolve through a precomputed in-memory canonicalMap (sub-microsecond). Arbitrary values (p-[2px], bg-(--c)) 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

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

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

// v3 spellings the official canonicalize step rewrites
<div className="bg-gradient-to-r break-words" />

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

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

// Variants and important are preserved
<div className="hover:!break-words" />

✓ Correct

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

<div className="bg-linear-to-r wrap-break-word" />

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

<div className="grow-2" />

<div className="hover:!wrap-break-word" />

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.