@surea11y/core 1.1.2 → 1.3.0

package/src/checks/automatic/aria-prohibited-attr.js

@@ -7,16 +7,21 @@
  * @standard WCAG 2.2
  * @sc 4.1.2
  * @applicability
- *   Applies to elements whose explicit, valid role is one of the small set
- *   of WAI-ARIA 1.2 roles with a documented "Prohibited ARIA States and
+ *   Applies to (a) elements whose explicit, valid role is one of the small
+ *   set of WAI-ARIA 1.2 roles with a documented "Prohibited ARIA States and
  *   Properties" list (pure text-semantics / non-naming structural roles:
  *   caption, code, deletion, emphasis, generic, insertion, mark, none,
  *   paragraph, presentation, strong, subscript, suggestion, superscript,
- *   time), and that also carry aria-label or aria-labelledby.
+ *   time), and (b) a small, curated set of native HTML tags verified to
+ *   carry no explicit or implicit ARIA role at all (see ROLELESS_NATIVE_TAGS
+ *   below) — in both cases, only elements that also carry aria-label or
+ *   aria-labelledby.
  * @expectation
- *   Prohibited attributes must not be present, since these roles are
- *   defined to never carry an accessible name — a naming attribute on them
- *   is a real, deterministic spec violation, not a style preference.
+ *   Prohibited attributes must not be present on (a); for (b), the naming
+ *   attribute is at best unreliable (nothing accessible-name-aware to hang
+ *   it off) and at worst silently ignored by assistive technology — see the
+ *   roleless-branch implementation note below for the confidence split
+ *   this produces.
  * @implementation-notes
  * - Deliberately scoped to the single, well-established prohibition class
  *   (naming attributes on pure text-semantics roles) rather than
@@ -58,13 +63,66 @@
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
+ * - Widened 2026-07-31 to add a second, independent branch covering
+ *   naming attributes on ROLELESS elements (no explicit role="", no
+ *   implicit/native role either) — found on the emoji-mart demo page
+ *   (missive.github.io/emoji-mart): hundreds of
+ *   `<span aria-label="party_parrot" class="emoji-mart-emoji...">` tiles,
+ *   plain roleless spans with no other accessible-name source, which this
+ *   rule previously ignored entirely, since its own Tier-1 branch only ever
+ *   looked at the EXPLICIT role="" attribute, never at "no role at all."
+ *   Empirically determined (not guessed) which native tags genuinely carry
+ *   no role at all, by resolving each candidate tag's role against a live
+ *   Chromium page — several surprises: common text-level tags like `<p>`,
+ *   `<strong>`, `<em>`, `<code>`, `<mark>`, `<time>` have no implicit role
+ *   at all (their prohibited-attrs entries only ever matter for an
+ *   EXPLICIT `role="paragraph"`/`role="strong"`/etc. restatement, a rare
+ *   case — the native tag itself resolves to role `null`, same as a bare
+ *   `<div>`/`<span>`, and falls into this same roleless branch). See
+ *   ROLELESS_NATIVE_TAGS below for the resulting curated list —
+ *   deliberately conservative: `<section>`/`<form>`/`<a>` are excluded
+ *   even though they can also resolve to no role, because their native
+ *   role is conditional (name-dependent/href-dependent) and already has
+ *   dedicated, more nuanced handling elsewhere in this engine
+ *   (`getElementRoleKey`'s `section`/`section[named]`/`header`/
+ *   `header[toplevel]` branches) that this rule doesn't attempt to
+ *   duplicate.
+ *   Two confidence tiers instead of a flat fail: if the element's subtree
+ *   ALREADY produces a non-empty accessible name from its content
+ *   (computed the same way link-name-present/button-name-present do, via
+ *   `helpers.getContentNameInfo`), the naming attribute might just be a
+ *   redundant/intentional override — reported as `cantTell`, not a hard
+ *   fail. Only a roleless element with NO other accessible-name source at
+ *   all (the emoji-mart case: an icon-only span, background-image styled,
+ *   no text anywhere in its subtree) is a confident, deterministic `fail`
+ *   — nothing else could ever expose this element's name, and no role
+ *   exists to make it a Name/Role/Value candidate in the first place.
+ *   The widget-ancestor exemption (skip when the closest real ancestor role
+ *   is a "widget"-type role) avoids over-flagging roleless helper
+ *   spans/divs used as internal decoration inside a custom composite
+ *   widget.
+ * - Fixed 2026-07-31 (same day as introduced): the Tier-2 "already has a
+ *   role, not this branch's concern" guard checked only whether `role=""`
+ *   was present (`getExplicitRole`), not whether the value was a real,
+ *   recognized ARIA role. An invalid/typo'd role token (e.g.
+ *   `role="totally-bogus"`) therefore silently suppressed detection of an
+ *   otherwise-flaggable roleless naming attribute — identical markup with
+ *   the bogus role attribute removed entirely correctly failed, but with
+ *   it present the element was skipped as if it had a real role. Per spec
+ *   (and per this same file's own `getNearestAncestorRole` helper a few
+ *   lines below, which already gets this right), an unrecognized role
+ *   token is ignored by the accessibility tree, not honored — the element
+ *   is still effectively roleless. Now validates via the existing
+ *   `isValidConcreteRole` before treating an explicit role as real,
+ *   matching `getNearestAncestorRole`'s own pattern.
  */
 
 const id = 'aria-prohibited-attr';
 
 const meta = {
   title: 'ARIA naming attributes must not be used on roles that prohibit them',
-  description: 'Checks that aria-label/aria-labelledby are not present on WAI-ARIA roles whose specification explicitly prohibits ARIA naming (e.g. generic, emphasis, strong, paragraph).',
+  description:
+    'Checks that aria-label/aria-labelledby are not present on WAI-ARIA roles whose specification explicitly prohibits ARIA naming (e.g. generic, emphasis, strong, paragraph).',
   i18n: {
     titleKey: 'ariaProhibitedAttr_title',
     descriptionKey: 'ariaProhibitedAttr_description'
@@ -73,7 +131,13 @@ const meta = {
   tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'moderate',
   category: 'robust',
@@ -83,7 +147,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
@@ -96,19 +160,36 @@ function runInPage(ctx) {
   // scope) because the build inlines only this function's own source text
   // — see scripts/build-core.js header ("runInPage MUST be self-contained").
   const ROLES_PROHIBITING_NAME = new Set([
-    'caption', 'code', 'deletion', 'emphasis', 'generic', 'insertion',
-    'mark', 'none', 'paragraph', 'presentation', 'strong', 'subscript',
-    'suggestion', 'superscript', 'time'
+    'caption',
+    'code',
+    'deletion',
+    'emphasis',
+    'generic',
+    'insertion',
+    'mark',
+    'none',
+    'paragraph',
+    'presentation',
+    'strong',
+    'subscript',
+    'suggestion',
+    'superscript',
+    'time'
   ]);
 
   const PROHIBITED_NAMING_ATTRS = ['aria-label', 'aria-labelledby'];
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
-
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
-  for (const el of nodes) {
+  // --- Tier 1: explicit, valid role from the naming-prohibited set ---
+
+  const roleNodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('[role]')
+    : helpers.queryAll('[role]');
+
+  for (const el of roleNodes) {
     if (!el || !el.getAttribute) continue;
 
     const role = ariaHelpers.getExplicitRole(el);
@@ -125,10 +206,10 @@ function runInPage(ctx) {
     if (!present.length) continue;
 
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     for (const attr of present) {
-      occurrences.push({
+      failOccurrences.push({
         selector: stableSelector,
         html,
         summary: 'This attribute is prohibited on this element’s role.',
@@ -145,13 +226,206 @@ function runInPage(ctx) {
     }
   }
 
+  // --- Tier 2: no role at all (see header comment for the full rationale
+  // and how ROLELESS_NATIVE_TAGS/WIDGET_TYPE_ROLES were derived) ---
+
+  // Small, curated set of native tags empirically verified (against a
+  // widely-used reference engine's own getRole() at runtime, not guessed)
+  // to carry no explicit or implicit ARIA role. Deliberately excludes
+  // <section>/<form>/<a> — all conditionally roleless too, but already
+  // handled with more nuance elsewhere in this engine (see header comment).
+  const ROLELESS_NATIVE_TAGS = new Set([
+    'p',
+    'b',
+    'i',
+    'em',
+    'strong',
+    'span',
+    'div',
+    'code',
+    'mark',
+    'time',
+    'ins',
+    'del',
+    'small',
+    'sub',
+    'sup',
+    'abbr',
+    'cite',
+    'q',
+    'kbd',
+    'samp',
+    'var',
+    'address',
+    'blockquote',
+    'pre',
+    'figcaption',
+    'picture',
+    'template',
+    'hgroup',
+    'wbr',
+    'br',
+    'legend'
+  ]);
+
+  // WAI-ARIA roles a widely-used reference engine's own role table types as
+  // "widget" (verified directly against its source, not the six-category
+  // WAI-ARIA taxonomy — this engine's algorithm branches on its own `type`
+  // field, so parity means matching that field exactly).
+  const WIDGET_TYPE_ROLES = new Set([
+    'alert',
+    'alertdialog',
+    'button',
+    'checkbox',
+    'combobox',
+    'dialog',
+    'gridcell',
+    'link',
+    'listbox',
+    'log',
+    'marquee',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'progressbar',
+    'radio',
+    'scrollbar',
+    'searchbox',
+    'slider',
+    'spinbutton',
+    'status',
+    'switch',
+    'tab',
+    'tabpanel',
+    'textbox',
+    'timer',
+    'treeitem'
+  ]);
+
+  const getComposedParent =
+    helpers && typeof helpers.composedParent === 'function'
+      ? helpers.composedParent
+      : function (n) {
+          return n && n.parentElement ? n.parentElement : null;
+        };
+
+  // Nearest ancestor's real role (explicit-if-valid, else native/implicit),
+  // skipping roleless/presentation/none ancestors — used only to check
+  // whether that role is a "widget"-type one (the roleless-branch
+  // exemption). Not the same helper as aria-required-parent's containment
+  // walk: this one also accepts non-required-context roles.
+  function getNearestAncestorRole(el) {
+    let cur = getComposedParent(el);
+    let guard = 0;
+    while (cur && guard++ < 200) {
+      if (cur.nodeType !== 1) {
+        cur = getComposedParent(cur);
+        continue;
+      }
+      const explicit = ariaHelpers.getExplicitRole(cur);
+      const role =
+        explicit && ariaHelpers.isValidConcreteRole(explicit)
+          ? explicit
+          : ariaHelpers.getNativeRoleForElement(cur);
+      if (!role || role === 'presentation' || role === 'none') {
+        cur = getComposedParent(cur);
+        continue;
+      }
+      return role;
+    }
+    return '';
+  }
+
+  const namingSelector = '[aria-label],[aria-labelledby]';
+  const namingNodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(namingSelector)
+    : helpers.queryAll(namingSelector);
+
+  for (const el of namingNodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const tag = String(el.tagName || '').toLowerCase();
+    if (!ROLELESS_NATIVE_TAGS.has(tag)) continue;
+    const explicitRole = ariaHelpers.getExplicitRole(el);
+    if (explicitRole && ariaHelpers.isValidConcreteRole(explicitRole)) continue; // has a real, recognized role — Tier 1's concern (if in ROLES_PROHIBITING_NAME) or a role this rule has no opinion on. An INVALID role token (e.g. a typo) is ignored per spec, same as no role attribute at all, and must still fall through to this branch.
+    if (ariaHelpers.getNativeRoleForElement(el)) continue; // has a real implicit role after all — not this branch's concern
+
+    const present = [];
+    for (const attr of PROHIBITED_NAMING_ATTRS) {
+      const v = el.getAttribute(attr);
+      if (v != null && String(v).trim() !== '') present.push(attr);
+    }
+    if (!present.length) continue;
+
+    applicableCount += 1;
+
+    const ancestorRole = getNearestAncestorRole(el);
+    if (ancestorRole && WIDGET_TYPE_ROLES.has(ancestorRole)) continue; // roleless helper node inside a real widget — not flagged
+
+    const nameInfo = helpers.getContentNameInfo ? helpers.getContentNameInfo(el, ctx) : null;
+    const hasContentFallback = !!(
+      nameInfo &&
+      nameInfo.present &&
+      String(nameInfo.value || '').trim() !== ''
+    );
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
+
+    for (const attr of present) {
+      if (hasContentFallback) {
+        cantTellOccurrences.push({
+          selector: stableSelector,
+          html,
+          summary: `This ${tag} has no role, so ${attr} may not be exposed as its accessible name by assistive technology — but the element's own content already provides one.`,
+          hint: 'Verify whether the existing text content already serves as this element’s label; if so the naming attribute is redundant, otherwise give the element a role that supports naming (e.g. role="img").',
+          i18n: {
+            summaryKey: 'ariaProhibitedAttr_summary_cantTell_roleless',
+            hintKey: 'ariaProhibitedAttr_hint_cantTell_roleless',
+            params: { attr, element: tag }
+          },
+          data: {
+            details: {
+              reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS_NEEDS_REVIEW',
+              attr,
+              role: null,
+              element: tag
+            }
+          }
+        });
+      } else {
+        failOccurrences.push({
+          selector: stableSelector,
+          html,
+          summary: `This ${tag} has no role and no other accessible-name source, so ${attr} is not reliably exposed to assistive technology.`,
+          hint: 'Give this element a role that supports an accessible name (e.g. role="img"/"button"), or remove this attribute if it serves no purpose without one.',
+          i18n: {
+            summaryKey: 'ariaProhibitedAttr_summary_fail_roleless',
+            hintKey: 'ariaProhibitedAttr_hint_fail_roleless',
+            params: { attr, element: tag }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS', attr, role: null, element: tag }
+          }
+        });
+      }
+    }
+  }
+
   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: [] };
+
+  // See helpers.resolveTieredOutcome's own header comment (src/core/dom-helpers.js):
+  // a fail-tier finding never silently discards cantTell-tier findings from
+  // the same run — both are returned together when the outcome is 'fail'.
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-prohibited-children.js

@@ -52,12 +52,42 @@
  *   focusability) are static, declarative markup facts with no live-DOM/
  *   hydration risk, unlike e.g. `aria-checked-state-mismatch`'s DOM-
  *   property comparison.
+ * - Fixed 2026-07-30: a roleless-but-focusable descendant's message and
+ *   `data.details.attr` used to always claim "carries tabindex" even when
+ *   the element had no tabindex attribute at all and was only focusable
+ *   natively (e.g. an <a href> link). `helpers.getFocusableInfo`'s
+ *   `mechanism` field ('tabindex' | 'native' | ...) is now used to tell
+ *   the two apart, with a distinct `nativeFocusable` attr/message for the
+ *   native case. Found via a real Angular app: a routerLink <a> inside a
+ *   role="list" was reported as "carries tabindex" though the rendered
+ *   markup had no such attribute.
  * - Recursion stops at the first non-transparent role boundary, same as
  *   that reference engine: a nested container with its own real role (e.g. a
  *   <div role="listbox"> inside a menubar) is evaluated as ITS OWN
  *   owned-role entry against the outer container (and, separately, gets
  *   its own applicability pass as a container in the same rule run) —
  *   its descendants are never misattributed to the outer container.
+ * - Fixed 2026-07-31: child-role resolution used `ariaHelpers.getExplicitRole`
+ *   (explicit role="" attribute only), unlike aria-required-children's
+ *   descendant matching which uses `ariaHelpers.getContainmentRole` (explicit
+ *   role, falling back to the native-tag map — li/tr/td/th/tbody/ul/ol/
+ *   table/select/input[type=radio] — see that helper's own header comment).
+ *   A bare `<li>` with no role="" attribute — the common CSS-reset
+ *   workaround `<ul role="list"><li>...</li></ul>` that getContainmentRole
+ *   exists specifically to handle — was therefore read as roleless here,
+ *   making it structurally transparent: the walk recursed straight through
+ *   the listitem boundary into its subtree and could report a focusable
+ *   descendant several levels down as a disallowed owned child of the list,
+ *   instead of stopping at the (implicit) listitem the way
+ *   aria-required-children already does. Switched to getContainmentRole so
+ *   both rules resolve an owned child's role identically. This is a general
+ *   fix, not list/listitem-specific: it applies to every container role in
+ *   REQUIRED_OWNED_ROLES whose native-tag counterpart the child map covers
+ *   (e.g. a bare `<tr>`/`<td>` under a role="table"/"grid"/"row" container
+ *   with no explicit role="" was subject to the same flattening bug). Found
+ *   via a real Angular Material-style component library: an `<a routerlink>`
+ *   several DOM levels inside a bare `<li>` under `<ul role="list">` was
+ *   reported as an unallowed owned child of the list.
  * - Gated on isAccTreeEligible for the container itself, matching the fix
  *   applied to aria-required-children (see that rule's header): the
  *   original "not gated" note here just cited that rule's reasoning
@@ -81,7 +111,8 @@ const id = 'aria-prohibited-children';
 
 const meta = {
   title: 'Container roles must not own a child with a disallowed role',
-  description: 'Checks that every accessible-tree-owned child of a container role (list, listbox, menu, menubar, radiogroup, rowgroup, table, grid, treegrid, tablist, tree, row) has one of that role\'s allowed owned roles — the same set as its required owned roles.',
+  description:
+    "Checks that every accessible-tree-owned child of a container role (list, listbox, menu, menubar, radiogroup, rowgroup, table, grid, treegrid, tablist, tree, row) has one of that role's allowed owned roles — the same set as its required owned roles.",
   i18n: {
     titleKey: 'ariaProhibitedChildren_title',
     descriptionKey: 'ariaProhibitedChildren_description'
@@ -90,7 +121,13 @@ const meta = {
   tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'moderate',
   category: 'robust',
@@ -100,7 +137,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
@@ -108,7 +145,8 @@ function runInPage(ctx) {
   }
 
   function isEligibleAcc(el) {
-    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    const fn =
+      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
     if (!fn) return true;
     try {
       const r = fn(el, ctx);
@@ -125,12 +163,30 @@ function runInPage(ctx) {
   // roleless descendant carrying any of these is a real accessible-tree
   // node a widely-used reference engine's getOwnedRoles also flags, not a transparent wrapper.
   const GLOBAL_ARIA_ATTRS = [
-    'aria-atomic', 'aria-braillelabel', 'aria-brailleroledescription', 'aria-busy',
-    'aria-controls', 'aria-current', 'aria-describedby', 'aria-description',
-    'aria-details', 'aria-disabled', 'aria-dropeffect', 'aria-errormessage',
-    'aria-flowto', 'aria-grabbed', 'aria-haspopup', 'aria-hidden', 'aria-invalid',
-    'aria-keyshortcuts', 'aria-label', 'aria-labelledby', 'aria-live', 'aria-owns',
-    'aria-relevant', 'aria-roledescription'
+    'aria-atomic',
+    'aria-braillelabel',
+    'aria-brailleroledescription',
+    'aria-busy',
+    'aria-controls',
+    'aria-current',
+    'aria-describedby',
+    'aria-description',
+    'aria-details',
+    'aria-disabled',
+    'aria-dropeffect',
+    'aria-errormessage',
+    'aria-flowto',
+    'aria-grabbed',
+    'aria-haspopup',
+    'aria-hidden',
+    'aria-invalid',
+    'aria-keyshortcuts',
+    'aria-label',
+    'aria-labelledby',
+    'aria-live',
+    'aria-owns',
+    'aria-relevant',
+    'aria-roledescription'
   ];
 
   function getGlobalAriaAttr(el) {
@@ -151,6 +207,11 @@ function runInPage(ctx) {
   // entry with role: null, which can never satisfy a required-role set)
   // when it carries a global aria-* attribute or is focusable — matches
   // a widely-used reference engine's own getOwnedRoles exactly (see header comment).
+  // kidRole comes from getContainmentRole, not getExplicitRole (see header
+  // comment's 2026-07-31 fix): "roleless" here means neither an explicit
+  // role="" NOR one of the native containment tags (li, tr, td, ...), so a
+  // bare <li>/<tr>/... is a real listitem/row boundary, not a transparent
+  // wrapper the walk should pass through.
   function collectOwnedRoles(el, requiredSet, out, depth) {
     if (depth > MAX_DEPTH) return;
     const kids = el.children ? Array.prototype.slice.call(el.children) : [];
@@ -158,21 +219,31 @@ function runInPage(ctx) {
       if (!kid || kid.nodeType !== 1) continue;
       if (!isEligibleAcc(kid)) continue;
 
-      const kidRole = ariaHelpers.getExplicitRole(kid);
+      const kidRole = ariaHelpers.getContainmentRole(kid);
       const isPresentational = kidRole === 'presentation' || kidRole === 'none';
-      const isTransparentGroup = (kidRole === 'group' || kidRole === 'rowgroup') && requiredSet.has(kidRole);
+      const isTransparentGroup =
+        (kidRole === 'group' || kidRole === 'rowgroup') && requiredSet.has(kidRole);
 
       if (!kidRole && !isPresentational) {
         const globalAttr = getGlobalAriaAttr(kid);
-        let focusable = false;
+        let mechanism;
         try {
-          const fi = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo(kid, ctx) : null;
-          focusable = !!(fi && fi.focusable);
+          const fi =
+            helpers && typeof helpers.getFocusableInfo === 'function'
+              ? helpers.getFocusableInfo(kid, ctx)
+              : null;
+          mechanism = (fi && fi.focusable && fi.mechanism) || 'none';
         } catch {
-          focusable = false;
+          mechanism = 'none';
         }
-        if (globalAttr || focusable) {
-          out.push({ el: kid, role: null, attr: globalAttr || 'tabindex' });
+        if (globalAttr || mechanism !== 'none') {
+          // `mechanism` distinguishes an actual tabindex="" attribute from
+          // native focusability (e.g. <a href>, <button>, <input>) — these
+          // are different facts and must not be reported as the same
+          // "carries tabindex" claim (a native anchor with no tabindex
+          // attribute at all is not "carrying tabindex").
+          const attr = globalAttr || (mechanism === 'tabindex' ? 'tabindex' : 'nativeFocusable');
+          out.push({ el: kid, role: null, attr });
           continue; // real accessible-tree node: stop here, do not recurse further
         }
       }
@@ -189,7 +260,9 @@ function runInPage(ctx) {
     }
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('[role]')
+    : helpers.queryAll('[role]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -215,16 +288,34 @@ function runInPage(ctx) {
       if (entry.role && requiredSet.has(entry.role)) continue;
 
       const stableSelector = helpers.buildSelector ? helpers.buildSelector(entry.el) : 'html';
-      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(entry.el) : (entry.el.outerHTML || '');
+      const html = helpers.getOuterHtmlSnippet
+        ? helpers.getOuterHtmlSnippet(entry.el)
+        : entry.el.outerHTML || '';
       const containerSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
 
       const isRoleless = !entry.role;
-      const summary = isRoleless
-        ? `This element has no explicit role but carries ${entry.attr}, making it a real accessible-tree node that is not an allowed owned child of the enclosing role="${role}" container.`
-        : `This element has role="${entry.role}", which is not an allowed owned child of the enclosing role="${role}" container.`;
-      const hint = isRoleless
-        ? `Remove ${entry.attr} (or the role="${role}" container ownership), or give this element role="presentation"/"none" if it isn't meant to be its own accessible-tree node.`
-        : `Remove or change this role so it matches one of the container's allowed owned roles (${requiredOwned.join(', ')}), or move this element outside the ${role} container.`;
+      const isNativeFocusable = entry.attr === 'nativeFocusable';
+
+      let summary;
+      let hint;
+      let summaryKey;
+      let hintKey;
+      if (isNativeFocusable) {
+        summary = `This element has no explicit role but is natively focusable, making it a real accessible-tree node that is not an allowed owned child of the enclosing role="${role}" container.`;
+        hint = `Give this element role="presentation"/"none", remove its native focusability (e.g. drop the href/tabindex-granting attribute), or move it outside the ${role} container.`;
+        summaryKey = 'ariaProhibitedChildren_summary_fail_native_focusable';
+        hintKey = 'ariaProhibitedChildren_hint_fail_native_focusable';
+      } else if (isRoleless) {
+        summary = `This element has no explicit role but carries ${entry.attr}, making it a real accessible-tree node that is not an allowed owned child of the enclosing role="${role}" container.`;
+        hint = `Remove ${entry.attr} (or the role="${role}" container ownership), or give this element role="presentation"/"none" if it isn't meant to be its own accessible-tree node.`;
+        summaryKey = 'ariaProhibitedChildren_summary_fail_roleless';
+        hintKey = 'ariaProhibitedChildren_hint_fail_roleless';
+      } else {
+        summary = `This element has role="${entry.role}", which is not an allowed owned child of the enclosing role="${role}" container.`;
+        hint = `Remove or change this role so it matches one of the container's allowed owned roles (${requiredOwned.join(', ')}), or move this element outside the ${role} container.`;
+        summaryKey = 'ariaProhibitedChildren_summary_fail';
+        hintKey = 'ariaProhibitedChildren_hint_fail';
+      }
 
       occurrences.push({
         selector: stableSelector,
@@ -232,8 +323,8 @@ function runInPage(ctx) {
         summary,
         hint,
         i18n: {
-          summaryKey: isRoleless ? 'ariaProhibitedChildren_summary_fail_roleless' : 'ariaProhibitedChildren_summary_fail',
-          hintKey: isRoleless ? 'ariaProhibitedChildren_hint_fail_roleless' : 'ariaProhibitedChildren_hint_fail',
+          summaryKey,
+          hintKey,
           params: isRoleless
             ? { attr: entry.attr, containerRole: role }
             : { childRole: entry.role, containerRole: role, allowedRoles: requiredOwned.join(', ') }
@@ -256,7 +347,12 @@ function runInPage(ctx) {
     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: 'fail',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }