feat: enforces-shorthand (#447)

* test: auto generated vars

* refactor: joiner ❤️

* test: padding config

* WIP

* fix(#448): false positives on tailwind-variants

* add failing rounded strategies

* fix: allow multiple combos for the same shorthand

* fix: padding, margin & border

* feat: border, scale, skew, translate, scroll m/p

* docs

* refactor

Author: francoismassart

README.md

@@ -15,6 +15,7 @@
 | Name                                                                   | Description                                                                         | 💼  | ⚠️  | 🔧  | 💡  |
 | :--------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :-- | :-- | :-- | :-- |
 | [classnames-order](docs/rules/classnames-order.md)                     | Enforces a consistent order for the Tailwind CSS classnames, based on the compiler. |     | ✅  | 🔧  |     |
+| [enforces-shorthand](docs/rules/enforces-shorthand.md)                 | Avoid using multiple Tailwind CSS classnames when not required.                     |     | ✅  | 🔧  |     |
 | [no-contradicting-classname](docs/rules/no-contradicting-classname.md) | Avoid contradicting Tailwind CSS classnames.                                        | ✅  |     |     | 💡  |
 | [no-custom-classname](docs/rules/no-custom-classname.md)               | Detects classnames which do not belong to Tailwind CSS.                             |     | ✅  |     | 💡  |
 

ROADMAP.md

@@ -1,5 +1,15 @@
 # eslint-plugin-tailwindcss roadmap
 
+- [enforces-negative-arbitrary-values](https://github.com/francoismassart/eslint-plugin-tailwindcss/blob/HEAD/docs/rules/enforces-negative-arbitrary-values.md)
+- [no-arbitrary-value](https://github.com/francoismassart/eslint-plugin-tailwindcss/blob/HEAD/docs/rules/no-arbitrary-value.md)
+- [no-unnecessary-arbitrary-value](https://github.com/francoismassart/eslint-plugin-tailwindcss/blob/HEAD/docs/rules/no-unnecessary-arbitrary-value.md)
+- support for ESLint v10
+- performances improvements
+
+## May 2026
+
+- `enforces-shorthand`
+
 ## April 2026
 
 - `no-contradicting-classname`

docs/rules/enforces-shorthand.md

@@ -0,0 +1,37 @@
+# Avoid using multiple Tailwind CSS classnames when not required
+
+⚠️ This rule _warns_ in the ✅ `recommended` config.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+```html
+<section class="mt-10 mb-10 mx-10 pt-5 pb-5 pr-15 pl-15">
+  <h1 class="overflow-hidden text-ellipsis whitespace-nowrap">
+    This title can be very long, it could get truncated on smaller screens!
+  </h1>
+</section>
+```
+
+Examples of **correct** code for this rule:
+
+```html
+<section class="m-10 py-5 px-15">
+  <h1 class="truncate">
+    This title can be very long, it could get truncated on smaller screens!
+  </h1>
+</section>
+```
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+<!-- end auto-generated rule options list -->
+
+There are no specific options for this rule, yet it uses the general [settings](../../README.md#settings).

src/index.ts

@@ -5,6 +5,10 @@ import {
   classnamesOrder,
   RULE_NAME as CLASSNAMES_ORDER,
 } from "./rules/classnames-order";
+import {
+  enforcesShorthand,
+  RULE_NAME as ENFORCES_SHORTHAND,
+} from "./rules/enforces-shorthand";
 import {
   noContradictingClassname,
   RULE_NAME as NO_CONTRADICTING_CLASSNAME,
@@ -37,13 +41,15 @@ const plugin = {
   },
   rules: {
     [CLASSNAMES_ORDER]: classnamesOrder,
+    [ENFORCES_SHORTHAND]: enforcesShorthand,
     [NO_CUSTOM_CLASSNAME]: noCustomClassname,
     [NO_CONTRADICTING_CLASSNAME]: noContradictingClassname,
   },
 } satisfies FlatConfig.Plugin;
 
 const recommended = {
   [CLASSNAMES_ORDER]: "warn",
+  [ENFORCES_SHORTHAND]: "warn",
   [NO_CUSTOM_CLASSNAME]: "warn",
   [NO_CONTRADICTING_CLASSNAME]: "error",
 } as const;

src/rules/classnames-order.ts

@@ -8,6 +8,7 @@ import { RuleCreator } from "@typescript-eslint/utils/eslint-utils";
 import { RuleContext as TSESLintRuleContext } from "@typescript-eslint/utils/ts-eslint";
 
 import urlCreator from "../url-creator";
+import { joiner } from "../utils/joiner";
 import {
   parsePluginSettings,
   PluginSettings,
@@ -42,30 +43,6 @@ type RuleContext = TSESLintRuleContext<MessageIds, Options>;
 // The parameter passed into RuleCreator is a URL generator function.
 export const createRule = RuleCreator(urlCreator);
 
-const joinSortedClassnames = (
-  classNames: Array<string>,
-  whitespaces: Array<string>,
-  headSpace: boolean,
-  tailSpace: boolean,
-) => {
-  // Make a copy of whitespaces because we don't want to mutate the original array
-  // (Remember that ESLint runs several times and we don't want to mess up the whitespaces for the next runs)
-  const spaces = [...whitespaces];
-
-  const head = headSpace ? spaces.shift() : "";
-  const tail = tailSpace ? spaces.pop() : "";
-
-  const validatedClasses: Array<string> = [];
-  for (const [index, className] of classNames.entries()) {
-    const spacer =
-      validatedClasses.length === 0 ? "" : (spaces[index - 1] ?? " ");
-    validatedClasses.push(spacer + className);
-  }
-
-  if (validatedClasses.length === 0) return "";
-  return head + validatedClasses.join("") + tail;
-};
-
 const sortClassnames = (
   context: RuleContext,
   settings: PluginSettings,
@@ -87,12 +64,12 @@ const sortClassnames = (
     );
 
     // Generates the validated/sorted attribute value
-    let validatedClassNamesValue = joinSortedClassnames(
-      orderedClassNames,
+    let validatedClassNamesValue = joiner({
+      classNames: orderedClassNames,
       whitespaces,
       headSpace,
       tailSpace,
-    );
+    });
 
     if (originalClassNamesValue !== validatedClassNamesValue) {
       validatedClassNamesValue = prefix + validatedClassNamesValue + suffix;

src/rules/enforces-shorthand.spec.ts

@@ -0,0 +1,195 @@
+import * as Parser from "@typescript-eslint/parser";
+import { RuleTester, TestCaseError } from "@typescript-eslint/rule-tester";
+
+import {
+  generalSettings,
+  withAngularParser,
+} from "../utils/parser/test-helpers";
+import { enforcesShorthand, MessageIds, RULE_NAME } from "./enforces-shorthand";
+
+const generateError = (
+  obsoleteClassnames: Array<string>,
+  shorthand: string,
+): TestCaseError<MessageIds> => {
+  return {
+    messageId: "fix:use-shorthand",
+    data: {
+      classnames: obsoleteClassnames.map((cls) => `'${cls}'`).join(", "),
+      shorthand: shorthand,
+    },
+  };
+};
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: Parser,
+    parserOptions: {
+      ecmaFeatures: {
+        jsx: true,
+      },
+    },
+  },
+  settings: {
+    tailwindcss: {
+      ...generalSettings,
+    },
+  },
+});
+
+ruleTester.run(RULE_NAME, enforcesShorthand, {
+  valid: [
+    // Angular / Native HTML + static text
+    `<h1 class="-mt- h-100 md:h-full">valid</h1>`,
+    `<h1 class="w-full md:h-full">modifiers</h1>`,
+  ].map((testedNgCode) => ({
+    code: testedNgCode,
+    languageOptions: withAngularParser,
+  })),
+  invalid: [
+    {
+      code: `ctl("overflow-x-hidden overflow-y-hidden")`,
+      errors: [
+        generateError(
+          ["overflow-x-hidden", "overflow-y-hidden"],
+          "overflow-hidden",
+        ),
+      ],
+      output: `ctl("overflow-hidden")`,
+    },
+    {
+      code: `ctl("overscroll-x-none overscroll-y-none")`,
+      errors: [
+        generateError(
+          ["overscroll-x-none", "overscroll-y-none"],
+          "overscroll-none",
+        ),
+      ],
+      output: `ctl("overscroll-none")`,
+    },
+    {
+      code: `ctl("top-0 right-0 bottom-0")`,
+      errors: [generateError(["top-0", "bottom-0"], "inset-y-0")],
+      output: `ctl("right-0 inset-y-0")`,
+    },
+    {
+      code: `ctl("top-0 right-0 bottom-0 left-0")`,
+      errors: [
+        generateError(["right-0", "left-0"], "inset-x-0"),
+        generateError(["top-0", "bottom-0"], "inset-y-0"),
+      ],
+      output: [
+        `ctl("top-0 bottom-0 inset-x-0")`,
+        `ctl("inset-x-0 inset-y-0")`,
+        `ctl("inset-0")`,
+      ],
+    },
+    {
+      code: `ctl("inset-y-0 right-0 left-0")`,
+      errors: [generateError(["right-0", "left-0"], "inset-x-0")],
+      output: [`ctl("inset-y-0 inset-x-0")`, `ctl("inset-0")`],
+    },
+    {
+      code: `ctl("-inset-y-10 -inset-x-10")`,
+      errors: [generateError(["-inset-x-10", "-inset-y-10"], "-inset-10")],
+      output: [`ctl("-inset-10")`],
+    },
+    {
+      code: `ctl("-my-10 -mx-10")`,
+      errors: [generateError(["-mx-10", "-my-10"], "-m-10")],
+      output: [`ctl("-m-10")`],
+    },
+    {
+      code: `ctl("dark:-my-10 dark:-mx-10")`,
+      errors: [generateError(["dark:-mx-10", "dark:-my-10"], "dark:-m-10")],
+      output: [`ctl("dark:-m-10")`],
+    },
+    {
+      code: `ctl("gap-x-10 gap-y-10")`,
+      errors: [generateError(["gap-x-10", "gap-y-10"], "gap-10")],
+      output: [`ctl("gap-10")`],
+    },
+    {
+      code: `<h1 class="block md:-mx-10 md:-my-10">margin</h1>`,
+      errors: [generateError(["md:-mx-10", "md:-my-10"], "md:-m-10")],
+      output: `<h1 class="block md:-m-10">margin</h1>`,
+      languageOptions: withAngularParser,
+    },
+    {
+      code: `<h1 class="md:pl-10 md:pr-10">padding</h1>`,
+      errors: [generateError(["md:pl-10", "md:pr-10"], "md:px-10")],
+      output: `<h1 class="md:px-10">padding</h1>`,
+      languageOptions: withAngularParser,
+    },
+    {
+      code: `ctl("w-1/2 h-1/2")`,
+      errors: [generateError(["w-1/2", "h-1/2"], "size-1/2")],
+      output: [`ctl("size-1/2")`],
+    },
+    {
+      code: `ctl("debug overflow-hidden text-ellipsis whitespace-nowrap")`,
+      errors: [
+        generateError(
+          ["overflow-hidden", "text-ellipsis", "whitespace-nowrap"],
+          "truncate",
+        ),
+      ],
+      output: [`ctl("debug truncate")`],
+    },
+    {
+      code: `ctl("rounded-bl-2xl rounded-br-2xl")`,
+      errors: [
+        generateError(["rounded-bl-2xl", "rounded-br-2xl"], "rounded-b-2xl"),
+      ],
+      output: [`ctl("rounded-b-2xl")`],
+    },
+    {
+      code: `ctl("rounded-ee-2xl rounded-es-2xl")`,
+      errors: [
+        generateError(["rounded-ee-2xl", "rounded-es-2xl"], "rounded-b-2xl"),
+      ],
+      output: [`ctl("rounded-b-2xl")`],
+    },
+    {
+      code: `ctl("border-t-1 border-b-1")`,
+      errors: [generateError(["border-t-1", "border-b-1"], "border-y-1")],
+      output: [`ctl("border-y-1")`],
+    },
+    {
+      code: `ctl("border-t border-b")`,
+      errors: [generateError(["border-t", "border-b"], "border-y")],
+      output: [`ctl("border-y")`],
+    },
+    {
+      code: `ctl("border-t border-b border-x")`,
+      errors: [generateError(["border-t", "border-b"], "border-y")],
+      output: [`ctl("border-x border-y")`, `ctl("border")`],
+    },
+    {
+      code: `ctl("border-spacing-x-20 border-spacing-y-20")`,
+      errors: [
+        generateError(
+          ["border-spacing-x-20", "border-spacing-y-20"],
+          "border-spacing-20",
+        ),
+      ],
+      output: [`ctl("border-spacing-20")`],
+    },
+    {
+      code: `ctl("scale-x-150 scale-y-150")`,
+      errors: [generateError(["scale-x-150", "scale-y-150"], "scale-150")],
+      output: [`ctl("scale-150")`],
+    },
+    {
+      code: `ctl("skew-x-150 dark:-skew-x-100 dark:skew-y-100 skew-y-150")`,
+      errors: [generateError(["skew-x-150", "skew-y-150"], "skew-150")],
+      output: [`ctl("dark:-skew-x-100 dark:skew-y-100 skew-150")`],
+    },
+    {
+      code: `ctl("-translate-y-10 -translate-x-10")`,
+      errors: [
+        generateError(["-translate-x-10", "-translate-y-10"], "-translate-10"),
+      ],
+      output: [`ctl("-translate-10")`],
+    },
+  ],
+});