eslint-plugin-tailwind-a11y 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chamroro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# 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 .`.
+
+## Install
+
+```bash
+npm install --save-dev eslint-plugin-tailwind-a11y
+```
+
+Requires ESLint 9 or 10 (flat config).
+
+## Usage
+
+```js
+// eslint.config.js
+import tailwindA11y from "eslint-plugin-tailwind-a11y";
+
+export default [
+  ...tailwindA11y.configs.recommended,
+];
+```
+
+`configs.recommended` scopes itself to `**/*.jsx`/`**/*.tsx` and enables all three rules
+as errors. To register rules manually instead:
+
+```js
+import tailwindA11y from "eslint-plugin-tailwind-a11y";
+
+export default [
+  {
+    files: ["**/*.jsx", "**/*.tsx"],
+    plugins: { "tailwind-a11y": tailwindA11y },
+    rules: {
+      "tailwind-a11y/contrast": "error",
+      "tailwind-a11y/touch-target": "warn",
+      "tailwind-a11y/focus-indicator": "error",
+    },
+  },
+];
+```
+
+## Rules
+
+| Rule | WCAG | Catches |
+|---|---|---|
+| `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
+
+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.
+
+## 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
+```
+
+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/`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { ESLint } from "eslint";
+declare const plugin: ESLint.Plugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,45 @@
+import { createRequire } from "node:module";
+import contrast from "./rules/contrast.js";
+import touchTarget from "./rules/touch-target.js";
+import focusIndicator from "./rules/focus-indicator.js";
+// `../package.json` resolves correctly from both `src/` (dev) and `dist/`
+// (published), so the plugin version can't drift from the package version.
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const plugin = {
+    meta: {
+        name: "eslint-plugin-tailwind-a11y",
+        version,
+        namespace: "tailwind-a11y",
+    },
+    rules: {
+        contrast,
+        "touch-target": touchTarget,
+        "focus-indicator": focusIndicator,
+    },
+    configs: {},
+};
+// Assigned after `plugin` exists so the config can reference the plugin
+// itself. Scoped to jsx/tsx to match cli.ts's default glob, and to avoid
+// the engine's unparsable-file console warning firing as confusing noise
+// inside an unrelated linter run.
+Object.assign(plugin.configs, {
+    recommended: [
+        {
+            name: "tailwind-a11y/recommended",
+            files: ["**/*.jsx", "**/*.tsx"],
+            // Espree (ESLint's default parser) doesn't parse JSX unless told to —
+            // without this, ESLint fails to parse .jsx files at all before any
+            // rule here runs. Doesn't cover TypeScript syntax in .tsx files; see
+            // README for the TS-parser caveat.
+            languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },
+            plugins: { "tailwind-a11y": plugin },
+            rules: {
+                "tailwind-a11y/contrast": "error",
+                "tailwind-a11y/touch-target": "error",
+                "tailwind-a11y/focus-indicator": "error",
+            },
+        },
+    ],
+});
+export default plugin;

package/dist/rules/contrast.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/rules/contrast.js

@@ -0,0 +1,39 @@
+import { extractChecks, checkContrast } from "tailwind-a11y";
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Enforce WCAG 1.4.3 AA color contrast between Tailwind text-* and bg-* classes",
+            recommended: true,
+            url: "https://github.com/chamroro/tailwind-a11y/tree/main/packages/eslint-plugin-tailwind-a11y#contrast",
+        },
+        schema: [],
+        messages: {
+            contrast: "{{textClass}} on {{bgClass}} — ratio {{ratio}}, needs {{required}} ({{level}})",
+        },
+    },
+    create(context) {
+        return {
+            // Runs once per file — the engine does its own independent Babel
+            // parse of the raw source, so this never participates in ESLint's
+            // own AST traversal.
+            Program() {
+                const violations = checkContrast(extractChecks(context.sourceCode.getText(), context.filename));
+                for (const v of violations) {
+                    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,
+                        },
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/focus-indicator.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/rules/focus-indicator.js

@@ -0,0 +1,30 @@
+import { extractFocusIndicatorChecks, checkFocusIndicators } from "tailwind-a11y";
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Enforce WCAG 2.4.7 AA visible focus indicators — flag focus:outline-none with no visible replacement",
+            recommended: true,
+            url: "https://github.com/chamroro/tailwind-a11y/tree/main/packages/eslint-plugin-tailwind-a11y#focus-indicator",
+        },
+        schema: [],
+        messages: {
+            focusIndicator: "<{{tagName}}> removes the focus outline ({{removalClass}}) with no visible replacement (focus:ring-*/border-*/shadow-*/bg-*/outline-*)",
+        },
+    },
+    create(context) {
+        return {
+            Program() {
+                const violations = checkFocusIndicators(extractFocusIndicatorChecks(context.sourceCode.getText(), context.filename));
+                for (const v of violations) {
+                    context.report({
+                        loc: { line: v.line, column: 0 },
+                        messageId: "focusIndicator",
+                        data: { tagName: v.tagName, removalClass: v.removalClass },
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/touch-target.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/rules/touch-target.js

@@ -0,0 +1,36 @@
+import { extractTouchTargetChecks, checkTouchTargets } from "tailwind-a11y";
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Enforce WCAG 2.5.8 AA minimum 24x24px touch targets on interactive elements sized with Tailwind w-*/h-* classes",
+            recommended: true,
+            url: "https://github.com/chamroro/tailwind-a11y/tree/main/packages/eslint-plugin-tailwind-a11y#touch-target",
+        },
+        schema: [],
+        messages: {
+            touchTarget: "<{{tagName}}> is {{widthPx}}×{{heightPx}}px ({{widthClass}} {{heightClass}}) — WCAG 2.5.8 requires >= 24×24px",
+        },
+    },
+    create(context) {
+        return {
+            Program() {
+                const violations = checkTouchTargets(extractTouchTargetChecks(context.sourceCode.getText(), context.filename));
+                for (const v of violations) {
+                    context.report({
+                        loc: { line: v.line, column: 0 },
+                        messageId: "touchTarget",
+                        data: {
+                            tagName: v.tagName,
+                            widthPx: v.widthPx,
+                            heightPx: v.heightPx,
+                            widthClass: v.widthClass,
+                            heightClass: v.heightClass,
+                        },
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "eslint-plugin-tailwind-a11y",
+  "version": "0.1.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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "tailwindcss",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "wcag22",
+    "contrast",
+    "touch-target",
+    "focus-visible"
+  ],
+  "author": "chamroro",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chamroro/tailwind-a11y.git",
+    "directory": "packages/eslint-plugin-tailwind-a11y"
+  },
+  "bugs": {
+    "url": "https://github.com/chamroro/tailwind-a11y/issues"
+  },
+  "homepage": "https://github.com/chamroro/tailwind-a11y/tree/main/packages/eslint-plugin-tailwind-a11y#readme",
+  "dependencies": {
+    "tailwind-a11y": "^0.1.0"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0 || ^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^10.8.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  }
+}