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

// `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

// 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.