eslint-plugin-tailwind-a11y 0.1.0 → 0.2.0

package/README.md

@@ -1,15 +1,8 @@
 # eslint-plugin-tailwind-a11y
 
-ESLint rules that catch [WCAG](https://www.w3.org/WAI/WCAG21/quickref/) accessibility
-violations in Tailwind CSS class combinations — color contrast, touch target size, and
-focus indicator removal — as part of your normal `eslint` run, instead of a separate CLI
-you have to remember to invoke.
-
-This plugin is a thin ESLint adapter over the [`tailwind-a11y`](https://github.com/chamroro/tailwind-a11y/tree/main/packages/tailwind-a11y)
-engine, which does the actual work: resolving Tailwind utility classes back into real
-computed values (colors, sizes) via AST analysis. Every rule here calls straight into
-that engine and reports its violations — there's no separate implementation to drift out
-of sync, and no wording that differs between `npx tailwind-a11y` and `eslint .`.
+ESLint rules for [`tailwind-a11y`](https://github.com/chamroro/tailwind-a11y/tree/main/packages/tailwind-a11y) —
+inline WCAG diagnostics during normal linting, powered by the same engine as the CLI
+and VS Code extension. No detection logic is duplicated, so results never disagree.
 
 ## Install
 
@@ -25,17 +18,12 @@ Requires ESLint 9 or 10 (flat config).
 // eslint.config.js
 import tailwindA11y from "eslint-plugin-tailwind-a11y";
 
-export default [
-  ...tailwindA11y.configs.recommended,
-];
+export default [...tailwindA11y.configs.recommended];
 ```
 
-`configs.recommended` scopes itself to `**/*.jsx`/`**/*.tsx` and enables all three rules
-as errors. To register rules manually instead:
+Or register rules individually:
 
 ```js
-import tailwindA11y from "eslint-plugin-tailwind-a11y";
-
 export default [
   {
     files: ["**/*.jsx", "**/*.tsx"],
@@ -51,46 +39,20 @@ export default [
 
 ## Rules
 
-| Rule | WCAG | Catches |
+| Rule | WCAG | Detects |
 |---|---|---|
-| `tailwind-a11y/contrast` | 1.4.3 (AA) | `text-*`/`bg-*` pairs below the 4.5:1 contrast ratio, same-element or direct-parent |
-| `tailwind-a11y/touch-target` | 2.5.8 (AA) | Interactive elements sized under 24×24px via `w-*`/`h-*` |
-| `tailwind-a11y/focus-indicator` | 2.4.7 (AA) | `focus:outline-none` with no visible replacement style |
-
-Each rule's exact scope and known limitations are documented in the
-[engine's README](https://github.com/chamroro/tailwind-a11y/tree/main/packages/tailwind-a11y#what-it-deliberately-doesnt-catch-v1-scope) —
-this plugin doesn't change what's checked, only how it's surfaced.
-
-## `.tsx` files and parsers
+| `contrast` | 1.4.3 (AA) | Low-contrast `text-*`/`bg-*` pairs — suggests the nearest passing shade |
+| `touch-target` | 2.5.8 (AA) | Interactive elements under 24×24px |
+| `focus-indicator` | 2.4.7 (AA) | `focus:outline-none` with no visible replacement |
 
-The underlying engine parses each file's source independently with Babel (`jsx` +
-`typescript` plugins), so `.tsx` syntax is understood regardless of what parser your
-ESLint config uses. But ESLint itself still needs to parse the file *first* to run any
-rule at all — if your config doesn't already set a TypeScript-aware
-`languageOptions.parser` (e.g. `typescript-eslint`) for `.tsx` files, ESLint will fail to
-parse them before this plugin ever runs. If you already lint `.tsx` files today, you have
-this covered; nothing extra to add for this plugin specifically.
+Exact scope and known limitations: [engine README](https://github.com/chamroro/tailwind-a11y/tree/main/packages/tailwind-a11y#scope).
 
-## Relationship to the `tailwind-a11y` CLI
-
-Same checks, same engine, two ways to run them: `eslint-plugin-tailwind-a11y` for
-inline, per-file feedback during normal linting; [`tailwind-a11y`](https://github.com/chamroro/tailwind-a11y/tree/main/packages/tailwind-a11y)
-(the CLI) for a one-shot scan, e.g. in a CI step that doesn't otherwise run ESLint. Use
-either, or both — they'll never disagree, since the plugin doesn't reimplement anything.
-
-## Development
-
-This package lives in the [`tailwind-a11y` monorepo](https://github.com/chamroro/tailwind-a11y)
-(npm workspaces) alongside the engine it depends on:
-
-```bash
-npm install                              # from the monorepo root
-npm run build --workspaces               # or: npm run build -w tailwind-a11y -w eslint-plugin-tailwind-a11y
-npm test --workspaces --if-present
-```
+## Notes
 
-After changing the engine (`packages/tailwind-a11y`), rebuild it before running this
-package's tests — the workspace dependency resolves through its `dist/`, not its `src/`.
+`.tsx` files need a TypeScript-aware `languageOptions.parser` (e.g. `typescript-eslint`)
+in your own config for ESLint to parse them at all. This plugin's own analysis
+understands TypeScript syntax regardless — but ESLint has to parse the file successfully
+before any rule, including this one, ever runs.
 
 ## License
 

package/dist/rules/contrast.js

@@ -10,6 +10,11 @@ const rule = {
         schema: [],
         messages: {
             contrast: "{{textClass}} on {{bgClass}} — ratio {{ratio}}, needs {{required}} ({{level}})",
+            // Separate messageId rather than an optional {{suggestion}} placeholder
+            // in the base template — ESLint's interpolate() renders literal
+            // "undefined" if the data key is present-but-undefined, and RuleTester
+            // hard-fails on an unsubstituted {{placeholder}} if the key is omitted.
+            contrastWithSuggestion: "{{textClass}} on {{bgClass}} — ratio {{ratio}}, needs {{required}} ({{level}}); try {{suggestion}} ({{suggestedRatio}})",
         },
     },
     create(context) {
@@ -20,16 +25,21 @@ const rule = {
             Program() {
                 const violations = checkContrast(extractChecks(context.sourceCode.getText(), context.filename));
                 for (const v of violations) {
+                    const data = {
+                        textClass: v.textClass,
+                        bgClass: v.bgClass,
+                        ratio: v.ratio.toFixed(2),
+                        required: v.required,
+                        level: v.level,
+                    };
+                    if (v.suggestion) {
+                        data.suggestion = v.suggestion;
+                        data.suggestedRatio = v.suggestedRatio.toFixed(2);
+                    }
                     context.report({
                         loc: { line: v.line, column: 0 },
-                        messageId: "contrast",
-                        data: {
-                            textClass: v.textClass,
-                            bgClass: v.bgClass,
-                            ratio: v.ratio.toFixed(2),
-                            required: v.required,
-                            level: v.level,
-                        },
+                        messageId: v.suggestion ? "contrastWithSuggestion" : "contrast",
+                        data,
                     });
                 }
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-tailwind-a11y",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "ESLint rules that catch WCAG accessibility violations — color contrast, touch target size, and focus indicator removal — in Tailwind CSS class combinations.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,9 @@
     },
     "./package.json": "./package.json"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24"
   },
@@ -47,7 +49,7 @@
   },
   "homepage": "https://github.com/chamroro/tailwind-a11y/tree/main/packages/eslint-plugin-tailwind-a11y#readme",
   "dependencies": {
-    "tailwind-a11y": "^0.1.0"
+    "tailwind-a11y": "^0.2.0"
   },
   "peerDependencies": {
     "eslint": "^9.0.0 || ^10.0.0"