eslint-plugin-uxlint

eslint-plugin-uxlint is a customizable UX heuristic linter for web applications.

It allows teams to define UX rules as data using a JSON-based DSL and enforce them during development via ESLint.

Instead of writing custom lint rules in JavaScript, designers and developers can define heuristics such as:

• Inputs should not rely on placeholder-only labels
• Icon-only buttons must have an accessible label
• Buttons should explicitly define their type

These rules are evaluated statically against your codebase.

Installation

Install the plugin:

npm install eslint-plugin-uxlint --save-dev

or

yarn add eslint-plugin-uxlint -D

Usage

Add the plugin to your ESLint configuration.

The quickest start is the recommended preset, which turns every rule on at warn:

import uxlint from "eslint-plugin-uxlint";
import tsParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.{ts,tsx,js,jsx}"],
    languageOptions: {
      parser: tsParser,
      parserOptions: { ecmaFeatures: { jsx: true } },
    },
  },
  uxlint.configs.recommended,
];

uxlint.configs.strict enables the same rules at error.

HTML, Vue and Svelte

The structural rules read markup through a format adapter, so they also run on .html files, Vue single-file components and Svelte components. Bring the parser you need — UXLint depends on none of them, and installs nothing extra if you only lint JSX.

import uxlint from "eslint-plugin-uxlint";
import htmlParser from "@html-eslint/parser";
import vueParser from "vue-eslint-parser";
import svelteParser from "svelte-eslint-parser";
import tsParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.html"],
    languageOptions: { parser: htmlParser },
  },
  {
    files: ["**/*.vue"],
    languageOptions: {
      parser: vueParser,
      // Only needed for <script lang="ts"> / <script lang="tsx">.
      parserOptions: { parser: tsParser, ecmaFeatures: { jsx: true } },
    },
  },
  {
    files: ["**/*.svelte"],
    languageOptions: {
      parser: svelteParser,
      // Only needed for <script lang="ts">.
      parserOptions: { parser: tsParser },
    },
  },
  uxlint.configs.recommended,
];

Seven rules apply: FORM-MULTI-001, INPUT-MOBILE-001, INPUT-CHOICE-004, INPUT-CHOICE-005, INPUT-DATE-001, INPUT-DATE-002 and MEDIA-AUTOPLAY-001. Vue's :id / @submit directives are understood, as are Svelte's bind:, on:click and onclick, and a web component is legible once it is declared:

{
  "designSystem": {
    "components": { "ui-text-field": { "role": "text-input" } }
  }
}

Vue also gets the interaction rules

ref() / reactive() / computed() are the state, x.value = v is the write, and template bindings — {{ x }}, :disabled="x", v-if="x", v-model — are what puts it on screen. Composables are understood (const { loading, error, save } = useSaver()), and so is handing an outcome onward: emit('saved') and await someStore.action() both delegate to something UXLint cannot see, so neither is reported as missing feedback.

Declare your app's notification helper, or nearly every handler will look silent:

{ "designSystem": { "feedbackFunctions": ["showError", "showMessage"] } }

Svelte gets them too

$state and $derived are the state, a plain assignment is the write, and a mustache or bound attribute puts it on screen. Svelte 4 needs no runes: a top-level let is reactive, which is the language rather than a guess, so it counts as state and a const does not. emit-style prop callbacks — await onSubmit(...) — delegate to the parent.

Svelte interactions are judged only on host elements. Handing a handler to a component, <Confirm onSubmit={save} />, puts the button and its pending state in another file, and there is no cross-component tracing yet.

The data rules read templates too

DATA-LOADING-001, DATA-EMPTY-001 and DATA-ERROR-001 ask a component that fetches a collection for the other three screens. v-for and {#each} render it; v-if and {#if} carry the branches. Svelte's {#await} answers loading and error by construction, since it is that shape.

The collection is found either from a data hook — useFetch, useAsyncData, useQuery — or, far more commonly, from a reactive binding filled by an await:

const items = ref([]);           let items = $state([]);
items.value = await api.get()    items = await api.get()

Its loading and error companions are matched by name (pending, isLoading, error), so a differently-named one will not be seen.

State handed to a child component needs no tracing: it counts as possibly-visible in every format, whatever the prop is called, because the child may render it and UXLint cannot prove otherwise.

On plain HTML the interaction and data rules do not run at all, because a document has no dataflow to trace.

Choosing severities per rule

Every built-in finding is its own ESLint rule, named after the finding id in lower case — INPUT-DATE-002 is reported by uxlint/input-date-002. So severity, editor filtering, and suppression all work per rule:

export default [
  {
    files: ["**/*.{ts,tsx,js,jsx}"],
    languageOptions: {
      parser: tsParser,
      parserOptions: { ecmaFeatures: { jsx: true } },
    },
    plugins: { uxlint },
    rules: {
      // Block the build on missing error feedback...
      "uxlint/interaction-async-error-001": "error",
      // ...but only nudge about date formats.
      "uxlint/input-date-002": "warn",
      "uxlint/input-choice-004": "off",
      // Rules you wrote in uxlint.rules.json.
      "uxlint/custom": "warn",
    },
  },
];

and a single finding can be suppressed where it is wrong:

{
  /* eslint-disable-next-line uxlint/input-mobile-001 -- label is rendered by the parent */
}
<input type="text" placeholder="Email" />;

The analysis runs once per file no matter how many of these rules are enabled.

Two rules exist alongside the built-in packs:

| Rule | Reports | | --------------------- | -------------------------------------------------- | | uxlint/custom | Rules you defined in uxlint.rules.json | | uxlint/config-error | uxlint.rules.json exists but could not be parsed |

uxlint/apply (all-in-one)

uxlint/apply reports every finding — built-in packs and your own rules — at one severity. It predates the split and still works:

rules: {
  "uxlint/apply": "warn",
}

Enable apply or the individual rules, not both: they report the same findings, so together every finding appears twice.

Built-in Rules

Besides the JSON DSL, uxlint/apply ships built-in rule packs that analyze interaction feedback and input controls:

• Interaction feedback (INTERACTION-SYNC-001, INTERACTION-ASYNC-START-001, INTERACTION-ASYNC-SETTLED-001, INTERACTION-ASYNC-ERROR-001, INTERACTION-ASYNC-SUCCESS-001) — traces user interactions (onClick, onSubmit, onPress) through handlers and state writes, across components and files, and reports when no visible UI feedback is detectable for the interaction or for an async phase (pending, settled, error, success). Common React Query, Redux, and Zustand status patterns are recognized.
• Form feedback (FORM-MULTI-001) — a form with a submit control should also expose a detectable error path.
• Input controls (INPUT-CHOICE-004, INPUT-CHOICE-005, INPUT-MOBILE-001, INPUT-DATE-001, INPUT-DATE-002, INPUT-TOGGLE-001, INPUT-TOGGLE-002, INPUT-SPLIT-001, INPUT-SPLIT-002) — structural checks on radio groups, checkbox/radio label association, placeholder-as-label (search fields are exempt: type="search" or a role="search" region, since what you type in one is self-evidently a query), split month/day/year date dropdowns, missing date-format guidance, non-binary or deferred toggle switches, and split buttons missing a default action or used for navigation.

Built-in rules can recognize your design-system components through config.designSystem in uxlint.rules.json:

{
  "version": 1,
  "config": {
    "designSystem": {
      "formComponents": ["AppForm"],
      "submitComponents": ["PrimaryButton"],
      "errorComponents": ["InlineError"],
      "components": {
        "TextField": { "role": "text-input", "labelProps": ["caption"] },
        "AppSelect": { "role": "select" },
        "UIButton": { "role": "button", "loadingProps": ["busy"] }
      }
    }
  },
  "rules": []
}

Each entry in components declares what a component is (role: "button", "text-input", "textarea", "select", "switch", or "split-button") and which props matter:

• labelProps — props that provide a visible label (in addition to the defaults label and labelText), used by the input-controls rules
• loadingProps / disabledProps — props the component visibly renders as loading or disabled state (in addition to the defaults loading, isLoading, and disabled); interaction rules trust these as visible feedback even when the component's implementation cannot be traced
• checkedProps — props carrying a "switch" component's bound value (in addition to the defaults checked, isChecked, value, on), used by INPUT-TOGGLE-001
• primaryActionProps / menuProps — props identifying a "split-button" component's default action and menu items (in addition to sensible defaults like onClick/label and items/actions), used by INPUT-SPLIT-001/INPUT-SPLIT-002

The older flat fieldComponents array keeps working and behaves like a text-input/select role declaration.

Interaction feedback is not limited to rendered state. Imperative feedback calls — toast(...), toast.error(...), alert(...) by default — and navigation (router.push, navigate(), window.location.href = ...) both count, classified into async phases by their position (before the first await, after it, in catch, in finally) and by member names like .error / .success. Add your own notifier names with designSystem.feedbackFunctions:

{
  "config": {
    "designSystem": {
      "feedbackFunctions": ["notify", "enqueueSnackbar"]
    }
  }
}

Individual built-in rules can be turned off or given a team-specific message through config.builtinRules:

{
  "version": 1,
  "config": {
    "builtinRules": {
      "INPUT-DATE-001": "off",
      "INTERACTION-ASYNC-SUCCESS-001": {
        "message": "Show a success toast or update the page after saving."
      }
    }
  },
  "rules": []
}

config.builtinRules is about the rule's content — whether it applies at all and what it says. The warn-versus-error level belongs in your ESLint config, per rule (see Choosing severities per rule). "off" works in either place.

Defining UX Rules

Rules are defined in a file named:

uxlint.rules.json

placed in your project root.

If the file cannot be parsed, uxlint/apply reports UXLINT-CONFIG-001 on each linted file instead of silently disabling your rules.

Example:

{
  "version": 1,
  "rules": [
    {
      "id": "FORM-001",
      "title": "Avoid placeholder-only labels",
      "severity": "warn",
      "appliesTo": ["JSXOpeningElement"],
      "when": {
        "all": [
          { "in": ["jsx.tag", ["input", "textarea", "select"]] },
          { "hasAttr": "placeholder" },
          { "not": { "hasAnyAttr": ["aria-label", "aria-labelledby"] } }
        ]
      },
      "report": {
        "message": "Avoid placeholder-only labels. Provide a visible <label> or an accessible name."
      }
    }
  ]
}

Rule DSL

Each rule has the following structure:

type Heuristic = {
  id: string;
  title: string;
  severity: "off" | "warn" | "error";
  appliesTo: string[];
  when: Expr;
  report: {
    message: string;
  };
};

Supported Signals

The DSL can reference signals extracted from the AST.

| Signal | Description | | ------------------- | ------------------------------ | | node.type | AST node type | | jsx.tag | HTML tag name (e.g. "input") | | jsx.componentName | JSX component name | | file.path | Current file path |

Fact Scopes

Besides raw AST node types, appliesTo can name a fact scope. Fact-scope rules run against the normalized facts the built-in analyzers collect, so a single rule covers native elements and declared design-system components alike.

InputControl

Evaluated once per collected input control (inputs, textareas, selects, checkboxes, radios, and design-system fields declared via designSystem.components or designSystem.fieldComponents).

| Signal | Type | Description | | ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | input.kind | string | "text-input", "textarea", "select", "checkbox", "radio", "design-system-field", "design-system-select" | | input.componentName | string | Component name for design-system controls | | input.inputType | string | The type attribute for native inputs | | input.name / input.id | string | name / id attributes | | input.placeholder | string | Placeholder text | | input.hasPlaceholder | boolean | Placeholder present and non-empty | | input.ariaLabel | string | aria-label text | | input.hasAriaLabel | boolean | aria-label present and non-empty | | input.hasVisibleLabel | boolean | Wrapping label, htmlFor/id pair, aria-labelledby, or a design-system label prop | | input.isWrappedByLabel | boolean | Control is nested inside a <label> | | input.isDefaultSelected | boolean | checked / defaultChecked present |

Missing facts read as "" / false, so comparisons stay decidable.

Example: replace the built-in placeholder rule with your team's own wording:

{
  "version": 1,
  "config": {
    "builtinRules": { "INPUT-MOBILE-001": "off" }
  },
  "rules": [
    {
      "id": "TEAM-LABEL-001",
      "title": "Placeholder is not a label",
      "severity": "warn",
      "appliesTo": ["InputControl"],
      "when": {
        "all": [
          {
            "in": [
              "input.kind",
              ["text-input", "textarea", "design-system-field"]
            ]
          },
          { "eq": ["input.hasPlaceholder", true] },
          { "eq": ["input.hasVisibleLabel", false] }
        ]
      },
      "report": {
        "message": "Fields need a visible label; placeholder text is not one."
      }
    }
  ]
}

Form

Evaluated once per collected form (native <form> or configured designSystem.formComponents).

| Signal | Type | Description | | ------------------------- | ------- | ----------------------------------------------- | | form.hasSubmitControl | boolean | A submit control was found inside the form | | form.hasErrorIndicator | boolean | An error indicator was found inside the form | | form.fieldCount | number | Number of collected fields | | form.submitControlCount | number | Number of collected submit controls | | form.source | string | "native", "framework", or "design-system" |

ToggleControl

Evaluated once per collected toggle: a native <input type="checkbox" role="switch"> (the WAI-ARIA switch pattern) or a component declared with role: "switch" in designSystem.components.

| Signal | Type | Description | | ---------------------------------- | ------- | --------------------------------------------------------------- | | toggle.componentName | string | JSX name of the toggle element | | toggle.boundValueShape | string | "boolean", "non-boolean", or "unknown" | | toggle.isBooleanBound | boolean | Bound value resolved to a boolean | | toggle.controlsConditionalRender | boolean | Bound state is the condition for other content in the same form | | toggle.isInsideForm | boolean | Toggle sits inside a collected form | | toggle.isInsideSubmitForm | boolean | That form also contains a submit control |

toggle.boundValueShape is the one signal where "unknown" is a value you can match on, rather than being normalized away: it means the bound value could not be classified statically, which is exactly what a fail-safe rule wants to test.

Example: replace the built-in deferred-toggle rule, keeping the exemption for progressive disclosure:

{
  "id": "TEAM-TOGGLE-001",
  "title": "Switches must apply immediately",
  "severity": "warn",
  "appliesTo": ["ToggleControl"],
  "when": {
    "all": [
      { "eq": ["toggle.isInsideSubmitForm", true] },
      { "eq": ["toggle.controlsConditionalRender", false] }
    ]
  },
  "report": {
    "message": "Use a checkbox when the change is deferred to Submit."
  }
}

SplitButton

Evaluated once per component declared with role: "split-button" in designSystem.components. There is no native split-button element, so this scope is only reachable with a component vocabulary.

| Signal | Type | Description | | ------------------------------ | ------- | ------------------------------------------------------------- | | splitButton.componentName | string | Declared component name | | splitButton.hasPrimaryAction | boolean | One of the configured primaryActionProps is present | | splitButton.navigatesToRoute | boolean | href / to, or a navigation call in an action or menu prop |

Interaction

Evaluated once per traced interaction (an onClick/onSubmit/onPress binding whose handler could be resolved), after handler expansion, multi-file tracing, and cross-component visibility analysis.

| Signal | Type | Description | | -------------------------------- | ------- | ------------------------------------------------------ | | interaction.eventName | string | "onClick", "onSubmit", "onPress", or "unknown" | | interaction.elementName | string | JSX element the handler is attached to | | interaction.componentName | string | React component containing the interaction | | interaction.label | string | aria-label of the interaction source, if any | | interaction.isAsync | boolean | Handler is async or writes non-sync phases | | interaction.writesState | boolean | Handler writes component or adapter state | | interaction.hasVisibleFeedback | boolean | Any written state is detectably visible | | interaction.hasStartFeedback | boolean | Visible feedback for the pending phase | | interaction.hasSettledFeedback | boolean | Visible feedback when pending clears | | interaction.hasErrorFeedback | boolean | Visible feedback for the error phase | | interaction.hasSuccessFeedback | boolean | Visible feedback for the success phase |

Example: an interaction lifecycle rule as data:

{
  "id": "TEAM-INT-001",
  "title": "Async interactions need error feedback",
  "severity": "warn",
  "appliesTo": ["Interaction"],
  "when": {
    "all": [
      { "eq": ["interaction.isAsync", true] },
      { "eq": ["interaction.writesState", true] },
      { "eq": ["interaction.hasErrorFeedback", false] }
    ]
  },
  "report": {
    "message": "Show the user when this async action fails."
  }
}

Reading Attribute Values

To read JSX attribute values use the call syntax:

{ "call": ["jsx.attrText", "type"] }

Example:

{
  "eq": [{ "call": ["jsx.attrText", "type"] }, "email"]
}

DSL Operators

all (AND)

{
  "all": [{ "eq": ["jsx.tag", "button"] }, { "hasAttr": "type" }]
}

any (OR)

{
  "any": [{ "eq": ["jsx.tag", "a"] }, { "eq": ["jsx.componentName", "Link"] }]
}

not

{ "not": { "hasAttr": "href" } }

eq

{ "eq": ["jsx.tag", "img"] }

in

{ "in": ["jsx.tag", ["input", "textarea"]] }

hasAttr

{ "hasAttr": "placeholder" }

hasAnyAttr

{ "hasAnyAttr": ["aria-label", "aria-labelledby"] }

Example Rules

Images must have alt text

{
  "id": "A11Y-IMG-001",
  "title": "Images must have alt text",
  "severity": "error",
  "appliesTo": ["JSXOpeningElement"],
  "when": {
    "all": [{ "eq": ["jsx.tag", "img"] }, { "not": { "hasAttr": "alt" } }]
  },
  "report": {
    "message": "<img> must have alt text."
  }
}

Buttons should explicitly set type

{
  "id": "BTN-001",
  "title": "Buttons should explicitly set type",
  "severity": "warn",
  "appliesTo": ["JSXOpeningElement"],
  "when": {
    "all": [{ "eq": ["jsx.tag", "button"] }, { "not": { "hasAttr": "type" } }]
  },
  "report": {
    "message": "<button> should explicitly set type=\"button\" or type=\"submit\"."
  }
}

Fail-safe behavior

When the engine cannot confidently evaluate a condition (for example due to dynamic expressions), the rule result becomes unknown.

The engine fails safely:

• true → report
• false → no report
• unknown → no report

This avoids noisy or misleading lint warnings.

License

MIT