@surea11y/core 1.4.0 → 1.4.1

package/src/checks/automatic/aria-deprecated-role.js

@@ -5,30 +5,36 @@
 /**
  * @check aria-deprecated-role
  * @atomic true
- * @summary An explicit role attribute must not use a deprecated or author-prohibited ARIA role
+ * @summary An explicit role attribute should not use a deprecated or author-discouraged ARIA role
  * @standard WCAG 2.2
  * @sc 4.1.2
  * @applicability
  *   Applies to any element whose role attribute's first (used) token is a
- *   valid, non-abstract ARIA role that authors must never explicitly
+ *   valid, non-abstract ARIA role that authors should not explicitly
  *   declare — either because WAI-ARIA has deprecated it (e.g. "directory",
- *   superseded by role="list") or because it's reserved for user-agent-
- *   internal use only, not a spec deprecation but the same "valid token,
- *   prohibited for authors" shape (role="generic" — per WAI-ARIA 1.2 and
- *   MDN's "It should not be used by web authors" guidance).
+ *   superseded by role="list") or because it is reserved for user-agent-
+ *   internal use (role="generic", which ARIA 1.2 §5.4 says authors SHOULD
+ *   NOT use in content).
  * @expectation
- *   The role in use is neither deprecated nor author-prohibited. This is a
- *   distinct, atomic decision from aria-roles-valid (existence/
- *   abstractness): a role can be perfectly valid and non-abstract while
- *   still being off-limits for explicit author use.
+ *   The role in use is neither deprecated nor reserved. Graded by the
+ *   strength of the rule ARIA states:
+ *   - CANTTELL at SHOULD NOT, which leaves the usage conforming, so the
+ *     author decides whether it matters: a deprecated role ("directory") or
+ *     one reserved for user agents ("generic").
+ *   - FAIL at MUST NOT. No ARIA 1.2 or 1.3 role carries an author MUST NOT
+ *     outside the abstract roles, so this outcome is reserved for a later
+ *     revision promoting a role to that strength.
+ *   Distinct, atomic decision from aria-roles-valid (existence/
+ *   abstractness): a role can be valid and non-abstract while still being
+ *   discouraged in explicit author use.
  */
 
 const id = 'aria-deprecated-role';
 
 const meta = {
-  title: 'role attribute must not use a deprecated or author-prohibited ARIA role',
+  title: 'role attribute should not use a deprecated or author-discouraged ARIA role',
   description:
-    'Checks that an explicit role="" attribute does not use a role deprecated by the WAI-ARIA specification, or one reserved for user-agent-internal use only (e.g. role="generic").',
+    'Checks that an explicit role="" attribute does not use a role deprecated by the WAI-ARIA specification, or one reserved for user-agent-internal use (e.g. role="generic").',
   i18n: {
     titleKey: 'ariaDeprecatedRole_title',
     descriptionKey: 'ariaDeprecatedRole_description'
@@ -64,12 +70,31 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart('[role]')
     : helpers.queryAll('[role]');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
+  // A role on an element hidden from assistive technology has no effect, so
+  // ACT 674b10 does not apply to it.
+  function isHidden(el) {
+    try {
+      if (typeof helpers.isDomVisibleEligible === 'function') {
+        if (!helpers.isDomVisibleEligible(el, ctx)) return true;
+      }
+      for (let n = el; n && n.getAttribute; n = n.parentElement) {
+        if (String(n.getAttribute('aria-hidden') || '').toLowerCase() === 'true') return true;
+      }
+    } catch {
+      return false;
+    }
+    return false;
+  }
+
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
 
+    if (isHidden(el)) continue;
+
     const role = ariaHelpers.getExplicitRole(el);
     if (!role) continue;
 
@@ -79,7 +104,14 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    if (!ariaHelpers.isDeprecatedRole(role)) continue;
+    const deprecated = ariaHelpers.isDeprecatedRole(role);
+    const discouraged =
+      typeof ariaHelpers.isAuthorDiscouragedRole === 'function' &&
+      ariaHelpers.isAuthorDiscouragedRole(role);
+    const prohibited =
+      typeof ariaHelpers.isAuthorProhibitedRole === 'function' &&
+      ariaHelpers.isAuthorProhibitedRole(role);
+    if (!deprecated && !discouraged && !prohibited) continue;
 
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
     const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
@@ -87,34 +119,70 @@ function runInPage(ctx) {
       ? ariaHelpers.getDeprecatedRoleGuidance(role)
       : 'Replace the deprecated role with its recommended replacement.';
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: `This element uses role="${role}", which authors must not explicitly declare.`,
-      hint: guidance,
-      i18n: {
-        summaryKey: 'ariaDeprecatedRole_summary_fail',
-        hintKey: 'ariaDeprecatedRole_hint_fail',
-        params: { role, guidance }
-      },
-      data: {
-        details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance }
-      }
-    });
+    if (prohibited) {
+      // Author MUST NOT: the usage is non-conforming, not merely discouraged.
+      failOccurrences.push({
+        selector: stableSelector,
+        html,
+        summary: `This element uses role="${role}", which authors must not explicitly declare.`,
+        hint: guidance,
+        occurrenceOutcome: 'fail',
+        i18n: {
+          summaryKey: 'ariaDeprecatedRole_summary_fail',
+          hintKey: 'ariaDeprecatedRole_hint_fail',
+          params: { role, guidance }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ROLE_AUTHOR_PROHIBITED', role, guidance }
+        }
+      });
+    } else if (discouraged) {
+      // Reserved for user-agent-internal use, at SHOULD NOT strength.
+      cantTellOccurrences.push({
+        selector: stableSelector,
+        html,
+        summary: `This element uses role="${role}", which is reserved for user agents (still valid, but discouraged).`,
+        hint: guidance,
+        occurrenceOutcome: 'cantTell',
+        i18n: {
+          summaryKey: 'ariaDeprecatedRole_summary_cantTell_discouraged',
+          hintKey: 'ariaDeprecatedRole_hint_cantTell',
+          params: { role, guidance }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance }
+        }
+      });
+    } else {
+      // Deprecated but still valid: surfaced for the author to decide.
+      cantTellOccurrences.push({
+        selector: stableSelector,
+        html,
+        summary: `This element uses role="${role}", which is deprecated in WAI-ARIA.`,
+        hint: guidance,
+        occurrenceOutcome: 'cantTell',
+        i18n: {
+          summaryKey: 'ariaDeprecatedRole_summary_cantTell',
+          hintKey: 'ariaDeprecatedRole_hint_cantTell',
+          params: { role, guidance }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance }
+        }
+      });
+    }
   }
 
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-roles-valid.js

@@ -67,19 +67,44 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // Programmatically hidden per the ACT glossary: display:none, visibility not
+  // visible, or aria-hidden on the element or an ancestor.
+  function isHidden(el) {
+    try {
+      if (typeof helpers.isDomVisibleEligible === 'function') {
+        if (!helpers.isDomVisibleEligible(el, ctx)) return true;
+      }
+      for (let n = el; n && n.getAttribute; n = n.parentElement) {
+        if (String(n.getAttribute('aria-hidden') || '').toLowerCase() === 'true') return true;
+      }
+    } catch {
+      return false;
+    }
+    return false;
+  }
+
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
 
-    const role = ariaHelpers.getExplicitRole(el);
-    if (!role) continue; // role="" or whitespace-only: not this rule's concern
+    // ACT 674b10 is not applicable to a programmatically hidden element.
+    if (isHidden(el)) continue;
 
-    applicableCount += 1;
+    // role takes a fallback list and the first token the browser recognises
+    // wins, so role="searchfield searchbox" resolves to searchbox. The rule
+    // fails only when no token names a concrete role.
+    const tokens =
+      typeof ariaHelpers.getAllRoleTokens === 'function'
+        ? ariaHelpers.getAllRoleTokens(el)
+        : [ariaHelpers.getExplicitRole(el)].filter(Boolean);
+    if (!tokens.length) continue; // role="" or whitespace-only: not this rule's concern
 
-    const isAbstract = ariaHelpers.isAbstractRole(role);
-    const isKnown = ariaHelpers.isKnownRole(role);
+    applicableCount += 1;
 
-    if (isKnown && !isAbstract) continue;
+    const usable = tokens.find((t) => ariaHelpers.isKnownRole(t) && !ariaHelpers.isAbstractRole(t));
+    if (usable) continue;
 
+    const role = tokens[0];
+    const isKnown = tokens.some((t) => ariaHelpers.isKnownRole(t));
     const reasonCode = !isKnown ? 'ARIA_ROLE_INVALID' : 'ARIA_ROLE_ABSTRACT';
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
     const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';

package/src/checks/automatic/autocomplete-valid.js

@@ -130,7 +130,15 @@ function runInPage(ctx) {
     if (tokens[i] && tokens[i].startsWith('section-') && tokens[i].length > 'section-'.length)
       i += 1;
     if (tokens[i] === 'shipping' || tokens[i] === 'billing') i += 1;
-    if (CONTACT_MODALITY.has(tokens[i])) i += 1;
+    // A contact modality token is only allowed when the field that follows is
+    // a contact field, so "work photo" is invalid while "work email" is not.
+    if (CONTACT_MODALITY.has(tokens[i])) {
+      const next = tokens[i + 1];
+      const isContactField =
+        next === 'email' || next === 'impp' || next === 'tel' || (next || '').startsWith('tel-');
+      if (!isContactField) return false;
+      i += 1;
+    }
 
     let end = tokens.length;
     if (tokens[end - 1] === 'webauthn') end -= 1;
@@ -147,11 +155,39 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // ACT 73f2c2 exempts controls where the attribute cannot describe an input
+  // purpose: the on/off toggle, disabled controls, input types with a fixed
+  // value, and controls that take no input.
+  const FIXED_VALUE_TYPES = new Set([
+    'button',
+    'checkbox',
+    'file',
+    'image',
+    'radio',
+    'reset',
+    'submit'
+  ]);
+
+  function isExempt(el) {
+    const tag = String(el.tagName || '').toLowerCase();
+    if (tag === 'input') {
+      const type = String(el.getAttribute('type') || 'text').toLowerCase();
+      if (FIXED_VALUE_TYPES.has(type)) return true;
+    }
+    if (el.hasAttribute && el.hasAttribute('disabled')) return true;
+    if (String(el.getAttribute('aria-disabled') || '').toLowerCase() === 'true') return true;
+    return false;
+  }
+
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
     const raw = String(el.getAttribute('autocomplete') || '').trim();
     if (!raw) continue;
 
+    const tokens = raw.toLowerCase().split(/\s+/).filter(Boolean);
+    if (tokens.length === 1 && (tokens[0] === 'on' || tokens[0] === 'off')) continue;
+    if (isExempt(el)) continue;
+
     applicableCount += 1;
 
     if (isValidAutocomplete(raw)) continue;

package/src/checks/automatic/avoid-inline-spacing.js

@@ -5,31 +5,36 @@
 /**
  * @check avoid-inline-spacing
  * @atomic true
- * @summary Inline style must not force text-spacing properties with !important
+ * @summary Inline style must not force text spacing below the WCAG metric
  * @standard WCAG 2.2
  * @sc 1.4.12
  * @applicability
- *   Applies to elements with an inline style attribute that sets
- *   line-height, letter-spacing, or word-spacing.
+ *   Applies to a rendered element with visible text of its own whose style
+ *   attribute declares line-height, letter-spacing or word-spacing as
+ *   `!important` with a real value. A CSS-wide keyword (inherit, initial,
+ *   unset, revert) specifies no spacing of its own and is out of scope.
  * @expectation
- *   None of those three properties are declared with `!important` in the
- *   inline style. WCAG 1.4.12 (Text Spacing) requires that users be able
- *   to override these properties via a user stylesheet without losing
- *   content or functionality; `!important` on an inline declaration
- *   defeats that override (inline `!important` wins over nearly every
- *   other origin, including user stylesheets applied the normal way).
+ *   Each such declaration already meets WCAG 1.4.12's own metric for that
+ *   property, as a multiple of the font size: line-height at least 1.5,
+ *   letter-spacing at least 0.12, word-spacing at least 0.16. A forced value
+ *   that already satisfies the criterion leaves the user nothing to override.
  * @implementation-notes
- * - Static text-based parsing of the style attribute string (regex for
- *   the three property names followed by `!important`), not computed
- *   style.
+ * - Computed style resolves the cascade and the units; the declared value is
+ *   only a fallback for environments that do not lay the document out. Spacing
+ *   that resolves to neither is left unreported rather than failed.
+ * - Within one declaration block, importance outranks order, so the effective
+ *   declaration is the last `!important` one for that property.
+ * - ACT 78fd32/24afc2/9e45ec additionally require the text to contain a soft
+ *   wrap break, which cannot be determined without layout. Not implemented, so
+ *   a forced value on text that never wraps is still reported.
  */
 
 const id = 'avoid-inline-spacing';
 
 const meta = {
-  title: 'Inline style must not force text spacing with !important',
+  title: 'Inline style must not force text spacing below the WCAG metric',
   description:
-    'Checks that inline style does not set line-height, letter-spacing, or word-spacing with !important, which blocks user text-spacing overrides.',
+    'Checks that where inline style forces line-height, letter-spacing or word-spacing with !important, the value already meets WCAG 1.4.12, so the user has nothing left to override.',
   i18n: {
     titleKey: 'avoidInlineSpacing_title',
     descriptionKey: 'avoidInlineSpacing_description'
@@ -57,6 +62,20 @@ function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
   const SPACING_PROPS = ['line-height', 'letter-spacing', 'word-spacing'];
+  // WCAG 1.4.12's own metrics, as multiples of the font size.
+  const MIN_RATIO = { 'line-height': 1.5, 'letter-spacing': 0.12, 'word-spacing': 0.16 };
+  // Only these two take the value from the parent, leaving this declaration
+  // specifying no spacing of its own. `initial` and `revert` resolve to a
+  // concrete value (`normal` for all three properties), so they stay in scope.
+  const INHERITED_KEYWORDS = ['inherit', 'unset'];
+  // No user agent's `normal` line height reaches 1.5, so a forced `normal`
+  // always falls short of the metric.
+  const NORMAL_LINE_HEIGHT_RATIO = 1.2;
+  const CAMEL = {
+    'line-height': 'lineHeight',
+    'letter-spacing': 'letterSpacing',
+    'word-spacing': 'wordSpacing'
+  };
 
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('[style]')
@@ -65,6 +84,136 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // Within one declaration block, importance wins over order, so the last
+  // important declaration is the one that takes effect. Passed Example 5 of ACT
+  // 78fd32 turns on this and Passed Example 6 on the non-important half.
+  function effectiveDeclaration(raw, prop) {
+    const re = new RegExp('(?:^|;)\\s*' + prop + '\\s*:\\s*([^;]*)', 'gi');
+    let chosen = null;
+    let m;
+    while ((m = re.exec(raw))) {
+      const value = String(m[1] || '').trim();
+      const important = /!\s*important\s*$/i.test(value);
+      const clean = value.replace(/!\s*important\s*$/i, '').trim();
+      if (!clean) continue;
+      if (!chosen || important || !chosen.important) {
+        if (chosen && chosen.important && !important) continue;
+        chosen = { value: clean, important };
+      }
+    }
+    return chosen;
+  }
+
+  function hasVisibleTextChild(el) {
+    let kids;
+    try {
+      kids = el.childNodes ? Array.from(el.childNodes) : [];
+    } catch {
+      return false;
+    }
+    return kids.some((n) => n && n.nodeType === 3 && String(n.nodeValue || '').trim() !== '');
+  }
+
+  function isRendered(el) {
+    if (helpers.isDomVisibleEligible) {
+      try {
+        return !!helpers.isDomVisibleEligible(el, ctx, { targetSet: 'dom' }).eligible;
+      } catch {
+        return true;
+      }
+    }
+    return true;
+  }
+
+  const px = (v) => {
+    const n = parseFloat(v);
+    return Number.isFinite(n) && /px\s*$/.test(String(v)) ? n : null;
+  };
+
+  function computedStyleOf(el) {
+    if (helpers && typeof helpers.computedStyle === 'function') {
+      try {
+        const cs = helpers.computedStyle(el);
+        if (cs) return cs;
+      } catch {
+        // fall through to the realm's own view
+      }
+    }
+    try {
+      const view = el.ownerDocument && el.ownerDocument.defaultView;
+      if (view && typeof view.getComputedStyle === 'function') return view.getComputedStyle(el);
+    } catch {
+      // no computed style available
+    }
+    return null;
+  }
+
+  // ACT scopes these rules to text visible on screen, and text pushed far off
+  // canvas is the one hidden shape the shared eligibility check keeps eligible.
+  function isOffScreen(el) {
+    if (!helpers.getVisibilityHintsInfo) return false;
+    try {
+      const info = helpers.getVisibilityHintsInfo(el, ctx, {});
+      return !!(info && Array.isArray(info.hints) && info.hints.indexOf('offscreen') !== -1);
+    } catch {
+      return false;
+    }
+  }
+
+  // A realm that does not lay the document out reports font-size as the CSS
+  // absolute-size keyword rather than a length. Resolving those keeps px-valued
+  // spacing checkable there, and cannot manufacture a failure: a font size
+  // larger than assumed only makes a px ratio smaller.
+  const ABSOLUTE_FONT_SIZES = {
+    'xx-small': 9,
+    'x-small': 10,
+    small: 13,
+    medium: 16,
+    large: 18,
+    'x-large': 24,
+    'xx-large': 32
+  };
+
+  function fontSizeOf(cs) {
+    if (!cs) return null;
+    const direct = px(cs.fontSize);
+    if (direct !== null) return direct;
+    const keyword = String(cs.fontSize || '')
+      .trim()
+      .toLowerCase();
+    return ABSOLUTE_FONT_SIZES[keyword] || null;
+  }
+
+  /**
+   * The spacing as a multiple of the font size, or null when it cannot be
+   * resolved. Computed style is preferred because it already applies the
+   * cascade and unit resolution; the declared value is only a fallback for
+   * environments that do not lay the document out.
+   */
+  function spacingRatio(el, prop, declared) {
+    const cs = computedStyleOf(el);
+    const fontSize = fontSizeOf(cs);
+    if (cs && fontSize) {
+      const used = px(cs[CAMEL[prop]]);
+      if (used !== null) return used / fontSize;
+    }
+
+    const v = String(declared || '')
+      .trim()
+      .toLowerCase();
+    // `normal`, and the keywords that resolve to it, add nothing for the two
+    // spacing properties and stay under the metric for line height.
+    if (v === 'normal' || v === 'initial' || v === 'revert' || v === 'revert-layer') {
+      return prop === 'line-height' ? NORMAL_LINE_HEIGHT_RATIO : 0;
+    }
+    if (/^[0-9.]+$/.test(v)) return parseFloat(v);
+    if (/em$/.test(v)) return parseFloat(v);
+    if (/%$/.test(v)) return parseFloat(v) / 100;
+    const asPx = px(v);
+    if (asPx !== null && fontSize) return asPx / fontSize;
+    return null;
+  }
+
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
     const raw = String(el.getAttribute('style') || '');
@@ -74,14 +223,25 @@ function runInPage(ctx) {
     const hasAnySpacingProp = SPACING_PROPS.some((p) => lower.includes(p));
     if (!hasAnySpacingProp) continue;
 
-    applicableCount += 1;
+    // The rule is about text the user needs to re-space, so an element with no
+    // text of its own, or none that renders, is not a target.
+    if (!hasVisibleTextChild(el) || !isRendered(el) || isOffScreen(el)) continue;
 
     const flagged = [];
+    let inScope = false;
     for (const prop of SPACING_PROPS) {
-      const re = new RegExp(prop.replace('-', '\\-') + '\\s*:[^;]*!important', 'i');
-      if (re.test(raw)) flagged.push(prop);
+      const decl = effectiveDeclaration(raw, prop);
+      if (!decl || !decl.important) continue;
+      if (INHERITED_KEYWORDS.indexOf(decl.value.toLowerCase()) !== -1) continue;
+      inScope = true;
+      const ratio = spacingRatio(el, prop, decl.value);
+      // Unresolvable spacing is left alone: this engine reserves fail for
+      // high-confidence violations.
+      if (ratio === null) continue;
+      if (ratio < MIN_RATIO[prop]) flagged.push(prop);
     }
 
+    if (inScope) applicableCount += 1;
     if (!flagged.length) continue;
 
     const tag = el.tagName.toLowerCase();
@@ -91,8 +251,8 @@ function runInPage(ctx) {
     occurrences.push({
       selector: stableSelector,
       html,
-      summary: `This element's inline style forces ${flagged.join(', ')} with !important, blocking user text-spacing overrides.`,
-      hint: 'Remove !important from line-height/letter-spacing/word-spacing in inline styles so users can override text spacing.',
+      summary: `This element's inline style forces ${flagged.join(', ')} with !important below the WCAG text-spacing metric, so the user cannot raise it.`,
+      hint: 'Remove !important from line-height/letter-spacing/word-spacing in inline styles, or set a value that already meets the metric (line-height 1.5, letter-spacing 0.12em, word-spacing 0.16em).',
       i18n: {
         summaryKey: 'avoidInlineSpacing_summary_fail',
         hintKey: 'avoidInlineSpacing_hint_fail',

package/src/checks/automatic/binary-control-name-present.js

@@ -137,9 +137,16 @@ function runInPage(ctx) {
     return '';
   }
 
+  // Naming rules apply only to elements included in the accessibility tree
+  // (ACT c487ae and siblings), which excludes focusable aria-hidden content.
+  // aria-hidden-focus (ACT 6cfa84) covers that markup instead.
   function isEligibleAcc(helpers, el, ctx) {
     const fn =
-      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+      helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+        ? helpers.isIncludedInAccessibilityTree
+        : helpers && typeof helpers.isAccTreeEligible === 'function'
+          ? helpers.isAccTreeEligible
+          : null;
     if (!fn) return true;
     try {
       const r = fn(el, ctx);
@@ -153,8 +160,9 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
-  const selector =
-    'input[type="checkbox"], input[type="radio"], [role="checkbox"], [role="radio"], [role="switch"]';
+  // Native checkbox/radio without an explicit role belongs to
+  // form-control-programmatic-label-present.
+  const selector = '[role="checkbox"], [role="radio"], [role="switch"]';
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);

package/src/checks/automatic/button-name-present.js

@@ -78,7 +78,14 @@ function runInPage(ctx) {
 
   for (const el of nodes) {
     // isAccTreeEligible returns { eligible, reasons }, not a boolean.
-    const eligResult = helpers.isAccTreeEligible ? helpers.isAccTreeEligible(el, ctx) : true;
+    // Naming rules apply only to elements included in the accessibility tree
+    // (ACT c487ae), which excludes focusable aria-hidden content;
+    // aria-hidden-focus (ACT 6cfa84) covers that markup instead.
+    const eligResult = helpers.isIncludedInAccessibilityTree
+      ? helpers.isIncludedInAccessibilityTree(el, ctx)
+      : helpers.isAccTreeEligible
+        ? helpers.isAccTreeEligible(el, ctx)
+        : true;
     const eligible =
       typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
     if (!eligible) continue;
@@ -104,24 +111,50 @@ function runInPage(ctx) {
       inputValueName = getInputButtonValueName(el);
     }
 
-    // A native <button> (or [role="button"]) whose role has been overridden to
-    // one of these roles is no longer semantically a button — per the WAI-ARIA
-    // Accessible Name and Description Computation spec these roles are
-    // name-from-author-only, and their rendered content represents a VALUE,
-    // not a NAME. E.g. <button role="combobox">List</button> where "List" is
-    // the combobox's currently selected value, not a label — crediting it as
-    // the accessible name would mask a missing name.
-    const VALUE_ROLES = [
-      'textbox',
-      'progressbar',
-      'scrollbar',
-      'slider',
-      'spinbutton',
-      'combobox',
-      'listbox'
+    // ARIA 1.2 "Name From: author, contents". Every other known role is
+    // name-from-author-only: <button role="combobox">List</button> exposes a
+    // value, not a label. An unknown role falls back to the implicit role.
+    // <generated:aria-name-from-content>
+    const NAME_FROM_CONTENT_ROLES = [
+      'button',
+      'cell',
+      'checkbox',
+      'columnheader',
+      'doc-backlink',
+      'doc-biblioref',
+      'doc-glossref',
+      'doc-noteref',
+      'graphics-object',
+      'gridcell',
+      'heading',
+      'link',
+      'menuitem',
+      'menuitemcheckbox',
+      'menuitemradio',
+      'option',
+      'radio',
+      'row',
+      'rowgroup',
+      'rowheader',
+      'switch',
+      'tab',
+      'tooltip',
+      'treeitem'
     ];
+    // </generated:aria-name-from-content>
+    const isKnownRoleToken =
+      helpers && helpers.aria && typeof helpers.aria.isKnownRole === 'function'
+        ? (() => {
+            try {
+              return !!helpers.aria.isKnownRole(roleNorm);
+            } catch {
+              return false;
+            }
+          })()
+        : false;
     const isContentNameCandidate =
-      (tag === 'button' || role === 'button') && !VALUE_ROLES.includes(roleNorm);
+      (tag === 'button' || role === 'button') &&
+      (!roleNorm || !isKnownRoleToken || NAME_FROM_CONTENT_ROLES.includes(roleNorm));
     const contentName =
       !trustedProgrammaticName && !inputValueName && isContentNameCandidate
         ? getConservativeSubtreeText(el)