@surea11y/core 1.3.0 → 1.4.1

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

package/src/checks/automatic/aria-braille-equivalent.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -16,13 +18,12 @@
  *   `"false"` silently drops the error message from the accessibility
  *   tree — authors almost always intend it to be exposed.
  * @implementation-notes
- * - This is deliberately narrow: a widely-used reference engine's own
- *   `aria-conditional-attr` rule covers a broader table of attribute/condition
- *   pairs. This rule implements only the one pairing (`aria-errormessage` /
- *   `aria-invalid`) that is unambiguous and explicitly stated in the
- *   ARIA spec, to keep `fail` high-confidence — matches this repo's
- *   established pattern (see `aria-required-attr`/`aria-prohibited-attr`
- *   for the same "narrower than that reference engine, but zero false positives"
+ * - This is deliberately narrow: the broader space is a table of many
+ *   attribute/condition pairs. This rule implements only the one pairing
+ *   (`aria-errormessage` / `aria-invalid`) that is unambiguous and
+ *   explicitly stated in the ARIA spec, to keep `fail` high-confidence —
+ *   matches this repo's established pattern (see `aria-required-attr`/
+ *   `aria-prohibited-attr` for the same "narrow but zero false positives"
  *   trade-off).
  * - Does not check whether the `aria-errormessage` ID reference itself
  *   resolves to an existing element — that is `aria-valid-attr-value`'s

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

@@ -1,33 +1,40 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @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" — verified 2026-07-20
- *   against both the WAI-ARIA 1.2 spec text and MDN's explicit "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'
@@ -63,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;
 
@@ -78,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 || '';
@@ -86,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-hidden-body.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -14,10 +16,10 @@
  * @expectation
  *   <body> does not have aria-hidden="true". Hiding the document body
  *   removes the entire page's content and structure from the
- *   accessibility tree at once — a widely-used reference engine tags this under both 1.3.1
- *   (Info and Relationships: the page's structure becomes entirely
- *   non-determinable) and 4.1.2 (Name, Role, Value: nothing in the
- *   document exposes a role/name/value any longer).
+ *   accessibility tree at once — both 1.3.1 (Info and Relationships: the
+ *   page's structure becomes entirely non-determinable) and 4.1.2 (Name,
+ *   Role, Value: nothing in the document exposes a role/name/value any
+ *   longer) apply.
  */
 
 const id = 'aria-hidden-body';

package/src/checks/automatic/aria-hidden-focus.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -12,7 +14,7 @@
  *   No element with aria-hidden="true" may itself be focusable, and no focusable element
  *   may exist within an aria-hidden="true" subtree.
  *
- * Notes on parity with a widely-used reference engine's aria-hidden-focus check:
+ * Notes:
  * - Focusability is computed via ctx.helpers.getFocusableInfo (native + tabindex + contenteditable).
  * - Elements that are not rendered (e.g., display:none, visibility:hidden, [hidden]) are excluded.
  * - Elements hidden via CSS in ways that still allow keyboard focus (e.g., opacity:0, off-screen, clip)
@@ -485,14 +487,11 @@ function runInPage(ctx) {
     // An explicit negative tabindex removes the element from the keyboard
     // tab sequence entirely, regardless of tag — the standard, WAI-
     // recommended technique for safely hiding focusable content behind
-    // aria-hidden (verified against a widely-used reference engine's own aria-hidden-focus check,
-    // which requires tabbability — not raw focusability — via its
-    // `focusable-not-tabbable` sub-check; confirmed via a real page:
-    // Wikipedia's sticky header uses <button tabindex="-1">/<a tabindex="-1">
-    // inside aria-hidden divs, a correct pattern this rule was previously
-    // flagging as a false positive). Such an element is still
-    // programmatically focusable (script could call .focus()), but that's
-    // not what "no focusable content behind aria-hidden" cares about.
+    // aria-hidden (e.g. <button tabindex="-1"> / <a tabindex="-1"> inside
+    // an aria-hidden container). This cares about tabbability, not raw
+    // focusability. Such an element is still programmatically focusable
+    // (script could call .focus()), but that's not what "no focusable
+    // content behind aria-hidden" cares about.
     const explicitTabindex = trim(el.getAttribute('tabindex'));
     if (
       explicitTabindex !== '' &&
@@ -640,10 +639,9 @@ function runInPage(ctx) {
     // cheaper first cannot change which elements end up in the bucket —
     // it only skips the expensive check for the (typically vast) majority
     // of focusable candidates that were never inside an aria-hidden root
-    // in the first place. On a real page with a large focusable-candidate
-    // count and a complex stylesheet (Daily Mail: ~1400 links, ~3600 CSS
-    // rules), this cut this check's runtime from ~30s to well under 1s —
-    // a pure ordering change, not a behavior change.
+    // in the first place. On pages with many focusable candidates and a
+    // large stylesheet this is a big speedup, and a pure ordering change,
+    // not a behavior change.
     const rootEl = closestAriaHiddenTrue(el);
     if (!rootEl) continue;
 
@@ -777,6 +775,7 @@ function runInPage(ctx) {
       hint: downgradedToCantTell
         ? 'Verify this is an intentional focus sentinel/focus-trap handoff and that keyboard users never remain on hidden focus targets.'
         : 'Remove focusability from descendants or remove aria-hidden; ensure focus and accessibility trees stay aligned.',
+      occurrenceOutcome: downgradedToCantTell ? 'cantTell' : 'fail',
       i18n: {
         summaryKey: downgradedToCantTell
           ? 'ariaHidden_focus_summary_cantTell_redirect'

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -7,15 +9,17 @@
  * @standard WCAG 2.2
  * @sc 4.1.2
  * @applicability
- *   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 (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.
+ *   Applies to (a) elements whose explicit, valid role is one of the ARIA
+ *   1.2 roles with a documented "Prohibited ARIA States and Properties"
+ *   list for naming attributes (pure text-semantics / non-naming
+ *   structural roles: caption, code, deletion, emphasis, generic,
+ *   insertion, mark, none, paragraph, presentation, strong, subscript,
+ *   suggestion, superscript, time), and (b) elements with no role at all —
+ *   a curated set of native HTML tags verified to carry no implicit role
+ *   (see ROLELESS_NATIVE_TAGS below), or any autonomous custom element (a
+ *   hyphenated, author-defined tag per the Custom Elements spec; see
+ *   isRolelessCustomElementTag below) — in both cases, only elements that
+ *   also carry aria-label or aria-labelledby.
  * @expectation
  *   Prohibited attributes must not be present on (a); for (b), the naming
  *   attribute is at best unreliable (nothing accessible-name-aware to hang
@@ -24,97 +28,55 @@
  *   this produces.
  * @implementation-notes
  * - Deliberately scoped to the single, well-established prohibition class
- *   (naming attributes on pure text-semantics roles) rather than
- *   attempting an exhaustive per-role prohibited-attribute table; see
+ *   (naming attributes on pure text-semantics roles) rather than an
+ *   exhaustive per-role prohibited-attribute table; see
  *   src/core/aria-helpers.js file header for this engine's confidence-
- *   scoping rationale.
- * - Role list widened 2026-07-19 (Tier 4) from 10 to 13 roles, adding
- *   `mark`, `suggestion`, and `time` — the other ARIA 1.2 "HTML-alignment"
- *   text-level roles that share the same documented prohibition as the
- *   original 10. Still deliberately not claiming full parity with a widely-used
- *   reference engine:
- *   only roles/attrs this engine has high confidence in from the spec
- *   text are included, per the file's own "wrong entries cause false-
- *   positive fails" caution.
- * - Widened again 2026-07-21 to add `presentation`/`none`, verified
- *   directly against a widely-used reference engine's own role data table
- *   (both have `prohibitedAttrs: ['aria-label', 'aria-labelledby']`), and
- *   corroborated by the W3C
- *   WAI-ARIA 1.2 spec's own §5.2.8.6 "Roles which cannot be named"
- *   listing `presentation` explicitly (`none` is `presentation`'s
- *   documented 1.2-introduced alias, identical semantics). The
- *   pre-existing `presentation-role-conflict` rule already treats
- *   aria-label/aria-labelledby as conflicting on these two roles, but at
- *   `manual`/cantTell confidence across a ~24-attribute general list —
- *   this addition lets the specific, unambiguous naming-prohibition case
- *   also fire as a hard, WCAG-normative `fail` via this rule, matching
- *   this engine's "one rule = one normative decision" pattern rather than
- *   only ever surfacing it as advisory.
- * - Investigated, but deliberately did NOT add, `definition`/`term`
- *   despite both appearing on MDN's aria-label reference page's
- *   "not supported" list: that MDN list is demonstrably wrong for these
- *   two — a widely-used reference engine's own role data explicitly declares
- *   `nameFrom: ['author']` (`definition`) / `nameFrom: ['author',
- *   'contents']` (`term`), and the W3C spec's own §5.2.8.4 "Roles
- *   Supporting Name From Author" index lists both by name; MDN's
- *   `definition_role` page even demonstrates `aria-labelledby` usage on
- *   it directly. A real, confirmed documentation bug on MDN's side, not
- *   a gap here.
+ *   scoping rationale. The 14-role list comes from the W3C WAI-ARIA 1.2
+ *   spec's §5.2.8.6 "Roles which cannot be named"; only roles/attrs with
+ *   high confidence from the spec text are included, since a wrong entry
+ *   here causes a false-positive fail.
+ * - The pre-existing presentation-role-conflict rule already treats
+ *   aria-label/aria-labelledby as conflicting on presentation/none, but at
+ *   manual/cantTell confidence across a broad attribute list; this rule's
+ *   narrower, unambiguous naming-prohibition case fires as a hard,
+ *   WCAG-normative fail instead, matching this engine's "one rule = one
+ *   normative decision" pattern.
+ * - Deliberately excludes `definition`/`term` despite both appearing on
+ *   MDN's aria-label "not supported" list: both support name from author
+ *   (`nameFrom: ['author']` for definition, `['author', 'contents']` for
+ *   term), and the W3C spec's §5.2.8.4 "Roles Supporting Name From Author"
+ *   index lists both by name.
  * - 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.
+ * - Second, independent branch: naming attributes on ROLELESS elements (no
+ *   explicit role="", no implicit/native role either) — e.g. icon-only
+ *   `<span aria-label="...">` tiles with no other accessible-name source.
+ *   ROLELESS_NATIVE_TAGS below is a curated, deliberately conservative
+ *   list of native tags confirmed to carry no implicit role (common
+ *   text-level tags like `<p>`/`<strong>`/`<em>`/`<code>`/`<mark>`/`<time>`
+ *   resolve to role `null`, same as a bare `<div>`/`<span>`);
+ *   `<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 handling in
+ *   `getElementRoleKey`'s `section`/`section[named]`/`header`/
+ *   `header[toplevel]` branches that this rule doesn't 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.
+ *   already produces a non-empty accessible name from its content (via
+ *   `helpers.getContentNameInfo`, same as
+ *   link-name-present/button-name-present), 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 is a confident, deterministic `fail`. 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.
+ * - The Tier-2 "already has a role, not this branch's concern" guard
+ *   validates the explicit role via `isValidConcreteRole` before treating
+ *   it as real (matching `getNearestAncestorRole`'s own pattern): an
+ *   unrecognized role token (e.g. `role="totally-bogus"`) is ignored by
+ *   the accessibility tree, not honored, so the element is still
+ *   effectively roleless and must still be checked by this branch.
  */
 
 const id = 'aria-prohibited-attr';
@@ -212,6 +174,7 @@ function runInPage(ctx) {
       failOccurrences.push({
         selector: stableSelector,
         html,
+        occurrenceOutcome: 'fail',
         summary: 'This attribute is prohibited on this element’s role.',
         hint: 'Remove this attribute; this role must not carry an accessible name.',
         i18n: {
@@ -229,11 +192,10 @@ 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).
+  // Small, curated set of native tags verified 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',
@@ -268,10 +230,8 @@ function runInPage(ctx) {
     '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).
+  // WAI-ARIA roles typed as "widget" (the role set the roleless-branch
+  // exemption below branches on, not the six-category WAI-ARIA taxonomy).
   const WIDGET_TYPE_ROLES = new Set([
     'alert',
     'alertdialog',
@@ -337,6 +297,37 @@ function runInPage(ctx) {
     return '';
   }
 
+  // A small, spec-reserved set of hyphenated tag names that are NOT
+  // autonomous custom elements despite containing a hyphen (legacy SVG/
+  // MathML tags predating the Custom Elements spec) — see
+  // https://html.spec.whatwg.org/#valid-custom-element-name's own
+  // exclusion list. Excluded so this doesn't misclassify them as
+  // always-roleless the same way a real custom element is.
+  const RESERVED_HYPHENATED_TAGS = new Set([
+    'annotation-xml',
+    'color-profile',
+    'font-face',
+    'font-face-src',
+    'font-face-uri',
+    'font-face-format',
+    'font-face-name',
+    'missing-glyph'
+  ]);
+
+  // An autonomous custom element (author-defined tag, always containing a
+  // hyphen per the Custom Elements spec's naming grammar) has no implicit
+  // ARIA role at all -- unlike native tags, there is no conditional-role
+  // nuance to worry about here (a native <a>/<section>/<form> can gain an
+  // implicit role depending on other attributes, which is exactly why
+  // ROLELESS_NATIVE_TAGS is a hand-verified allowlist rather than a
+  // blanket rule; a custom element has no such spec-defined conditional
+  // role logic whatsoever). Covers e.g. a `<play-button aria-label="...">`
+  // or `<app-carousel aria-label="...">` with no other name source, which
+  // the fixed native-tag allowlist below would otherwise skip.
+  function isRolelessCustomElementTag(tag) {
+    return tag.includes('-') && !RESERVED_HYPHENATED_TAGS.has(tag);
+  }
+
   const namingSelector = '[aria-label],[aria-labelledby]';
   const namingNodes = helpers.queryAllSmart
     ? helpers.queryAllSmart(namingSelector)
@@ -346,7 +337,7 @@ function runInPage(ctx) {
     if (!el || !el.getAttribute) continue;
 
     const tag = String(el.tagName || '').toLowerCase();
-    if (!ROLELESS_NATIVE_TAGS.has(tag)) continue;
+    if (!ROLELESS_NATIVE_TAGS.has(tag) && !isRolelessCustomElementTag(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
@@ -378,6 +369,7 @@ function runInPage(ctx) {
         cantTellOccurrences.push({
           selector: stableSelector,
           html,
+          occurrenceOutcome: 'cantTell',
           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: {
@@ -398,6 +390,7 @@ function runInPage(ctx) {
         failOccurrences.push({
           selector: stableSelector,
           html,
+          occurrenceOutcome: 'fail',
           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: {