Interactive Elements Need Accessible Names

Interactive elements — buttons, links, and form controls — without accessible names are unusable for screen reader users.

frontendenforced by 1 rule

Context

Interactive elements — buttons, links, and form controls — without accessible names are unusable for screen reader users. A button with only an icon and no text content, aria-label, or aria-labelledby is announced as simply "button", giving no indication of its purpose. This violates WCAG 2.1 Level A (Success Criterion 4.1.2) and creates a poor experience for anyone using assistive technology.

Decision

All interactive elements must have an accessible name. This can come from text content, aria-label, or aria-labelledby. Icon-only buttons must have an aria-label describing their action. Empty or self-closing interactive elements without accessible names are not allowed.

Buttons must have visible text content or an aria-label.
Links must have descriptive text content or an aria-label.
Form inputs must have an associated <label> or aria-label.

Do's and Don'ts

Do

Give buttons visible text: <button>Save</button>.
Add aria-label to icon-only buttons: <button aria-label="Close dialog"><CloseIcon /></button>.
Associate labels with form inputs using htmlFor or wrapping.
Use aria-labelledby to reference visible labels when appropriate.

Don't

Create empty buttons: <button></button> or <button />.
Use icon-only buttons without aria-label.
Rely on title attributes as the sole accessible name.
Use non-descriptive text like "Click here" for links.

Consequences

Positive

All interactive elements are usable by screen reader users.
Meets WCAG 2.1 Level A accessibility requirements.
Improves usability for voice navigation users.

Negative

Icon-only buttons require maintaining aria-label alongside visual design.
Accessible names must be kept in sync with visual labels.

Enforcement rules

adrs/FE-002-interactive-elements-need-accessible-names.rules.ts

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "interactive-elements-need-accessible-names": {
      description:
        "Buttons and interactive elements must have accessible text or aria-label",
      async check(ctx) {
        const sourceGlob = "**/*.{tsx,jsx}";

        // Find self-closing buttons (no children, no aria-label)
        const selfClosingButtons = await ctx.grepFiles(
          /<button\s*\/>/u,
          sourceGlob
        );

        for (const m of selfClosingButtons) {
          if (
            m.file.includes(".test.") ||
            m.file.includes(".spec.") ||
            m.file.includes("__tests__")
          ) {
            continue;
          }
          ctx.report.warning({
            message:
              "Self-closing `<button />` has no accessible name — add text content or `aria-label`.",
            file: m.file,
            line: m.line,
            fix: 'Add text content: `<button>Label</button>` or an aria-label: `<button aria-label="Action"><Icon /></button>`.',
          });
        }

        // Find empty buttons: <button></button> without aria-label
        const emptyButtons = await ctx.grepFiles(
          /<button\s*>\s*<\/button>/u,
          sourceGlob
        );

        for (const m of emptyButtons) {
          if (
            m.file.includes(".test.") ||
            m.file.includes(".spec.") ||
            m.file.includes("__tests__")
          ) {
            continue;
          }
          ctx.report.warning({
            message:
              "Empty `<button></button>` has no accessible name — add text content or `aria-label`.",
            file: m.file,
            line: m.line,
            fix: 'Add text content: `<button>Label</button>` or an aria-label: `<button aria-label="Action"><Icon /></button>`.',
          });
        }

        // Find buttons with children that are non-text (e.g. icon-only) without aria-label
        const buttonsNoLabel = await ctx.grepFiles(
          /<button\s+(?!.*(?:aria-label|aria-labelledby))[^>]*>[^<]*<[^/]/u,
          sourceGlob
        );

        for (const m of buttonsNoLabel) {
          if (
            m.file.includes(".test.") ||
            m.file.includes(".spec.") ||
            m.file.includes("__tests__")
          ) {
            continue;
          }
          ctx.report.warning({
            message:
              "Button with non-text content (e.g. icon) may be missing an accessible name — add `aria-label` or `aria-labelledby`.",
            file: m.file,
            line: m.line,
            fix: 'Add an aria-label: `<button aria-label="Description"><Icon /></button>`.',
          });
        }
      },
    },
  },
} satisfies RuleSet;