@surea11y/core 1.5.0 → 1.7.0

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

@@ -7,7 +7,7 @@
  * @atomic true
  * @summary Container roles that require specific owned elements must contain at least one
  * @standard WCAG 2.2
- * @sc 4.1.2
+ * @sc 1.3.1
  * @applicability
  *   Applies to elements with an explicit, valid, non-abstract role that is
  *   also one of the container roles with a documented "required owned
@@ -15,9 +15,19 @@
  *   table, grid, treegrid, tablist, tree, row).
  * @expectation
  *   At least one descendant, or one aria-owns-referenced element, has one
- *   of the acceptable owned roles for that container role.
+ *   of the acceptable owned roles for that container role. Reported at
+ *   CANTTELL, never FAIL: this rule asks only whether the required content
+ *   is PRESENT, and a container that owns nothing conveys nothing false --
+ *   an empty role="list" is announced as a list with no items, which is what
+ *   it is. Whether the content a container does own is VALID is
+ *   aria-prohibited-children's decision, and that rule still fails, so a
+ *   genuinely misdescribed structure (a role="button" among list items, a
+ *   tablist of plain buttons) is caught with the same strength as before.
+ *   The native-HTML equivalents already work this way: nothing in this
+ *   ruleset fails an empty <ul>, and list-children-valid judges only the
+ *   children that exist.
  * @implementation-notes
- * - Deliberately scoped to REQUIRED_OWNED_ROLES in src/core/aria-helpers.js
+ * - Scoped to REQUIRED_OWNED_ROLES in src/core/aria-helpers.js
  *   (see that file's header for the conservative-scope rationale).
  * - Owned-role matching uses ariaHelpers.getContainmentRole, which combines
  *   explicit role="" attributes with a small, curated native-HTML-tag
@@ -28,12 +38,20 @@
  * - Only one qualifying descendant/owned element is required (per
  *   WAI-ARIA "required owned elements": any one acceptable role satisfies
  *   the requirement); the full subtree is scanned without excluding nested
- *   containers with their own differing role, favoring simplicity — this
+ *   containers with their own differing role, favoring simplicity, this
  *   can only under-report (recall), never over-report (fail integrity).
+ * - "At least one required child exists" is the whole of this rule's
+ *   decision. Whether every owned child is ALLOWED is
+ *   aria-prohibited-children's, and that rule does walk the owned graph
+ *   exclusively, with group/rowgroup transparency. ACT bc4a75 asks both
+ *   questions at once, which is why the mapping lists the two rules as a
+ *   family: read on its own, this rule looks like it under-reports a
+ *   container mixing valid and invalid children, and the sibling is what
+ *   catches it.
  * - Gated on isAccTreeEligible for the container itself: unlike this
  *   file's sibling attribute/role-validity checks (e.g. aria-roles-valid),
  *   "does this container currently have a required child" is not a fact
- *   that stays fixed once written — it is routinely filled in by the same
+ *   that stays fixed once written, it is routinely filled in by the same
  *   script/interaction that reveals the container (a closed flyout menu
  *   or <dialog> populated on open). Flagging it while the container isn't
  *   currently exposed to the accessibility tree is a false positive; such
@@ -44,16 +62,16 @@
  *   widget is missing required owned elements due to script execution or
  *   loading, authors MUST mark a containing element with aria-busy equal
  *   to true." A container carrying aria-busy="true" is skipped the same
- *   way — only the exact string "true" counts (absent/"false" do not).
+ *   way, only the exact string "true" counts (absent/"false" do not).
  * - Descendant search tries a fast native querySelectorAll(CANDIDATE_
  *   SELECTOR) first (covers the light-DOM-only common case with no added
  *   cost); only when that finds nothing AND the container has a <slot>
  *   anywhere in its subtree does it fall back to a composed-tree walk that
- *   expands <slot> elements via assignedElements({flatten:true}) — plain
+ *   expands <slot> elements via assignedElements({flatten:true}). Plain
  *   querySelectorAll only sees a <slot>'s unrendered fallback content, never
- *   what's actually distributed into it. Deliberately scoped to slot
+ *   what's actually distributed into it. Scoped to slot
  *   expansion only, not a general "also descend into any nested custom
- *   element's own shadow root" walk — no known case needs that yet.
+ *   element's own shadow root" walk, no known case needs that yet.
  */
 
 const id = 'aria-required-children';
@@ -67,14 +85,14 @@ const meta = {
     descriptionKey: 'ariaRequiredChildren_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
-  wcagSc: ['4.1.2'],
+  tags: ['wcag2a', 'wcag131', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['1.3.1'],
   normativeMappings: [
     {
       standard: 'WCAG',
       version: '2.2',
-      requirement: '4.1.2',
-      title: 'Name, Role, Value',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
       conformanceLevel: 'A'
     }
   ],
@@ -82,7 +100,7 @@ const meta = {
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'medium',
-  coverage: { facetsBySc: { '4.1.2': ['aria-role-required-owned-children'] } }
+  coverage: { facetsBySc: { '1.3.1': ['aria-role-required-owned-children'] } }
 };
 
 function runInPage(ctx) {
@@ -114,7 +132,7 @@ function runInPage(ctx) {
   // Candidate selector for descendant scanning: explicit role attributes,
   // plus every native tag ariaHelpers.getContainmentRole() recognizes
   // (kept in sync with aria-helpers.js NATIVE_CONTAINMENT_ROLE_BY_ELEMENT).
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const CANDIDATE_SELECTOR =
     '[role], li, option, tr, td, th, thead, tbody, tfoot, ul, ol, table, select, input[type="radio"]';
@@ -130,11 +148,11 @@ function runInPage(ctx) {
   // light-DOM subtree, so a container whose real owned children are
   // distributed via <slot> (e.g. a shadow-DOM role="list" wrapping
   // <slot></slot>, with the actual role="listitem" elements living in the
-  // light DOM and projected in) would never find them there — same class
+  // light DOM and projected in) would never find them there, same class
   // of bug as aria-required-parent's ancestor search, just in the opposite
   // (descendant) direction.
   //
-  // Deliberately scoped to slot expansion only — does NOT separately
+  // Scoped to slot expansion only, does NOT separately
   // descend into an unrelated nested custom element's own shadow root
   // (e.g. a <my-widget> child with no <slot> involvement at all). That's a
   // qualitatively different question (does an arbitrary component's own
@@ -192,9 +210,8 @@ function runInPage(ctx) {
     let found = false;
 
     // Fast path first: native querySelectorAll over the curated candidate
-    // selector, exactly as before this fix — covers the overwhelming
-    // majority of containers (no shadow DOM involved at all) with zero
-    // added cost.
+    // selector. Covers the overwhelming majority of containers (no shadow
+    // DOM involved at all) with zero added cost.
     let descendants;
     try {
       descendants = el.querySelectorAll(CANDIDATE_SELECTOR);
@@ -210,7 +227,7 @@ function runInPage(ctx) {
     }
 
     // Slow path only when the fast path found nothing AND there's an actual
-    // <slot> somewhere in the subtree to expand — bounds the extra cost to
+    // <slot> somewhere in the subtree to expand, bounds the extra cost to
     // exactly the containers that could possibly need it.
     if (!found) {
       let hasSlot;
@@ -262,6 +279,16 @@ function runInPage(ctx) {
           hintKey: 'ariaRequiredChildren_hint_fail',
           params: { role, requiredRoles: requiredOwned.join(', ') }
         },
+        uncertainty: {
+          code: 'spec-only',
+          needed:
+            'Whether this container is legitimately empty, or holds items that never got their role.',
+          evidence: {
+            role,
+            requiredOwnedRoles: requiredOwned,
+            childElementCount: el.children ? el.children.length : null
+          }
+        },
         data: {
           details: {
             reasonCode: 'ARIA_REQUIRED_CHILD_MISSING',
@@ -276,15 +303,12 @@ function runInPage(ctx) {
   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(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-required-parent.js

@@ -7,7 +7,7 @@
  * @atomic true
  * @summary Roles that require a specific ancestor/owner context role must have one
  * @standard WCAG 2.2
- * @sc 4.1.2
+ * @sc 1.3.1
  * @applicability
  *   Applies to elements with an explicit, valid, non-abstract role that is
  *   also one of the roles with a documented, non-empty "required context
@@ -19,7 +19,7 @@
  *   ancestor/owner's aria-owns) whose effective role is one of the
  *   acceptable context roles for this element's role.
  * @implementation-notes
- * - Deliberately scoped to REQUIRED_CONTEXT_ROLE in src/core/aria-helpers.js
+ * - Scoped to REQUIRED_CONTEXT_ROLE in src/core/aria-helpers.js
  *   (see that file's header for the conservative-scope rationale); roles
  *   with an explicitly empty entry (e.g. tabpanel) are left unconstrained.
  * - Context-role matching uses ariaHelpers.getContainmentRole, which
@@ -34,8 +34,8 @@
  *   independent path via a reverse lookup over the search root.
  * - Gated on isAccTreeEligible for the element itself. The ancestor-role
  *   walk itself doesn't care about visibility (a hidden ancestor's role is
- *   still found by plain DOM/composed-tree containment, so a genuinely
- *   correctly-nested-but-hidden widget was never at risk here) — the
+ *   still found by plain DOM/composed-tree containment, so a
+ *   correctly-nested-but-hidden widget was never at risk here), the
  *   remaining false-positive shape is an element whose required ancestor
  *   context doesn't exist YET because it (and its wrapping context) are
  *   assembled together at reveal time (e.g. a portal-rendered item staged
@@ -43,6 +43,16 @@
  *   aria-required-children/aria-prohibited-children, applied for
  *   consistency; an element that isn't currently exposed to the
  *   accessibility tree is skipped (notApplicable), not failed.
+ * - Also honors WAI-ARIA's escape hatch for a widget script has not
+ *   finished assembling: "When a widget is missing required owned elements due to
+ *   script execution or loading, authors MUST mark a containing element
+ *   with aria-busy equal to true." aria-required-children reads that from
+ *   the container it is checking; read from the item's side it is an
+ *   ancestor, so the walk looks up rather than at the element itself, and
+ *   only the exact string "true" counts. It also outranks the
+ *   roleless-generic-parent rule below, since aria-busy is itself a global
+ *   ARIA attribute and would otherwise block the context search and fail
+ *   the very markup the spec says to mark.
  */
 
 const id = 'aria-required-parent';
@@ -56,14 +66,14 @@ const meta = {
     descriptionKey: 'ariaRequiredParent_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
-  wcagSc: ['4.1.2'],
+  tags: ['wcag2a', 'wcag131', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['1.3.1'],
   normativeMappings: [
     {
       standard: 'WCAG',
       version: '2.2',
-      requirement: '4.1.2',
-      title: 'Name, Role, Value',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
       conformanceLevel: 'A'
     }
   ],
@@ -71,7 +81,7 @@ const meta = {
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'medium',
-  coverage: { facetsBySc: { '4.1.2': ['aria-role-required-context-parent'] } }
+  coverage: { facetsBySc: { '1.3.1': ['aria-role-required-context-parent'] } }
 };
 
 function runInPage(ctx) {
@@ -96,13 +106,57 @@ function runInPage(ctx) {
   }
 
   // Roles that may host a nested listitem/treeitem group without breaking
-  // the required-context chain — the group role is transparent for exactly
+  // the required-context chain, the group role is transparent for exactly
   // these two roles.
   const GROUP_TRANSPARENT_FOR_ROLES = new Set(['listitem', 'treeitem']);
 
-  // A real ancestor role — not "no role at all" and not the two roles that
+  // The WAI-ARIA "Global States and Properties" set (same list as
+  // aria-prohibited-children.js's GLOBAL_ARIA_ATTRS, duplicated, not
+  // imported, since runInPage must be self-contained per
+  // scripts/build-core.js). A roleless ancestor carrying any of these is
+  // still "included in the accessibility tree" and is therefore a real
+  // (generic) parent, not a transparent one: ACT's ff89c9 test corpus
+  // covers exactly this with role="listitem" whose actual DOM parent is a
+  // roleless <div aria-live="polite">, itself inside a role="list", the
+  // required-context chain is broken by that included-but-roleless div,
+  // even though a role="list" ancestor does exist further up.
+  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'
+  ];
+
+  function hasGlobalAriaAttr(el) {
+    for (const attr of GLOBAL_ARIA_ATTRS) {
+      if (el.getAttribute && el.getAttribute(attr) != null) return true;
+    }
+    return false;
+  }
+
+  // A real ancestor role, not "no role at all" and not the two roles that
   // strip an element from the accessibility tree's parent/child chain
-  // entirely (presentation/none) — stops the search. This is stricter than
+  // entirely (presentation/none), stops the search. This is stricter than
   // "any ancestor with the right role anywhere up the tree": the
   // required-context relationship is about the accessibility tree's actual
   // PARENT, so an intervening ancestor with its OWN distinct real role
@@ -110,19 +164,27 @@ function runInPage(ctx) {
   // a further-up ancestor has the correct role. E.g. a <button role="tab">
   // inside a plain <li> (native listitem) inside <ul role="tablist"> fails:
   // the tablist is never the tab's accessible-tree parent, the listitem is.
+  //
+  // A roleless ancestor is normally transparent (it isn't a node in the
+  // accessibility tree at all), UNLESS it carries a global ARIA attribute
+  // -- that alone includes it in the tree as a real, roleless (generic)
+  // parent, which still blocks the search the same way a distinct real
+  // role would.
   function getRealContextRole(el) {
     const role = ariaHelpers.getContainmentRole(el);
-    if (!role || role === 'presentation' || role === 'none') return '';
+    if (!role || role === 'presentation' || role === 'none') {
+      return hasGlobalAriaAttr(el) ? 'generic' : '';
+    }
     return role;
   }
 
-  // Flat-tree ancestor walk (ctx.helpers.composedParent — assignedSlot wins
+  // Flat-tree ancestor walk (ctx.helpers.composedParent, assignedSlot wins
   // over parentNode, then shadow host). A slotted light-DOM element's real
   // rendered ancestor is whatever the shadow tree wraps its <slot> in (e.g.
   // a role="list" container), not its own light-DOM parentElement.
   // composedParent can return a non-Element node (a ShadowRoot, nodeType
   // 11) when climbing out of a shadow tree that has no further light-DOM
-  // parent — skip those and keep climbing rather than treating them as a
+  // parent, skip those and keep climbing rather than treating them as a
   // (roleless) context.
   const getComposedParent =
     helpers && typeof helpers.composedParent === 'function'
@@ -131,6 +193,21 @@ function runInPage(ctx) {
           return n && n.parentElement ? n.parentElement : null;
         };
 
+  // The escape hatch marks the container being assembled, not the item inside
+  // it, so this walks up instead of reading the element's own attribute.
+  function hasBusyAncestor(el) {
+    let cur = getComposedParent(el);
+    let guard = 0;
+    while (cur && guard++ < 200) {
+      if (cur.nodeType === 1 && cur.getAttribute) {
+        const v = cur.getAttribute('aria-busy');
+        if (v != null && String(v).trim().toLowerCase() === 'true') return true;
+      }
+      cur = getComposedParent(cur);
+    }
+    return false;
+  }
+
   function hasAcceptableAncestorContext(el, acceptableRoles, ownRole) {
     const allowsGroup = acceptableRoles.has('group');
     let cur = getComposedParent(el);
@@ -200,6 +277,7 @@ function runInPage(ctx) {
     if (!requiredContext || !requiredContext.length) continue; // no entry, or explicitly unconstrained
 
     if (!isEligibleAcc(el)) continue; // not currently exposed to the accessibility tree
+    if (hasBusyAncestor(el)) continue; // author has signaled transient incompleteness per WAI-ARIA
 
     applicableCount += 1;
 

package/src/checks/automatic/aria-role-name-present.js

@@ -3,7 +3,8 @@
 'use strict';
 
 /**
- * Generic name-presence rule for selected ARIA composite/widget roles that should expose an accessible name.
+ * Generic name-presence rule for the ARIA roles WAI-ARIA *requires* an
+ * accessible name for.
  *
  * Notes:
  * - This rule intentionally focuses on author-provided naming mechanisms:
@@ -11,20 +12,40 @@
  * - It does NOT treat descendant text content as a valid name source for these roles
  *   (to avoid false passes from labelled children inside composite widgets).
  * - Eligibility is based on helpers.isAccTreeEligible(node, ctx) per engine checks.
+ * - The role set is generated from aria-query by
+ *   scripts/generate-aria-tables.js; see that script for why each role is in
+ *   or out, and for the name-required roles no rule covers yet.
+ *
+ * @applicability
+ *   Applies to elements whose role attribute is exactly one of grid, meter,
+ *   progressbar, radiogroup or tree, and that are included in the
+ *   accessibility tree. Membership is decided by WAI-ARIA's own "Accessible
+ *   Name Required: True" characteristic, not by whether a role merely permits
+ *   a name: tablist, toolbar, menu, menubar and scrollbar are name-from-author
+ *   roles the spec does not require a name for, and are out of
+ *   scope. meter and progressbar are also covered by meter-name-present and
+ *   progressbar-name-present, which map to SC 1.1.1; this rule is what gives
+ *   those two roles their 4.1.2 coverage.
+ * @expectation
+ *   The element has a non-empty aria-label, an aria-labelledby that resolves
+ *   to non-empty text, or a non-empty title. Every role in the set is
+ *   name-from-author-only, so descendant text is not accepted:
+ *   a labelled child inside a composite widget would otherwise pass the
+ *   container that has no name of its own.
  */
 
 const id = 'aria-role-name-present';
 
 const meta = {
-  title: 'ARIA widget/container roles have an accessible name',
+  title: 'ARIA roles that require an accessible name have one',
   description:
-    'Checks that selected ARIA widget/container roles expose a non-empty accessible name.',
+    'Checks that the ARIA roles WAI-ARIA requires an accessible name for expose a non-empty one.',
   i18n: {
     titleKey: 'ariaRoleNamePresent_title',
     descriptionKey: 'ariaRoleNamePresent_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'navigation', 'atomic', 'automatic', 'name'],
+  tags: ['wcag2a', 'wcag412', 'aria', 'navigation', 'atomic', 'automatic', 'name'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
     {
@@ -93,7 +114,7 @@ function runInPage(ctx) {
   // button-name-present et al.), which correctly includes hidden/aria-hidden
   // referenced nodes per the Accessible Name and Description Computation
   // spec (a hidden node directly referenced by aria-labelledby still
-  // supplies its text — this is a standard visually-hidden-label pattern).
+  // supplies its text, this is a standard visually-hidden-label pattern).
   const resolveLabelledby = (el, maxRefs) => {
     if (!getAriaLabelledByInfo) return '';
     try {
@@ -115,23 +136,16 @@ function runInPage(ctx) {
     }
   };
 
-  // Frozen allowlist of roles to check in this generic rule.
-  // (Keep this small, explicit, and standards-based for determinism.)
-  const roleSet = new Set([
-    'scrollbar',
-    'toolbar',
-    'tablist',
-    'radiogroup',
-    'tree',
-    'grid',
-    'menu',
-    'menubar',
-    'meter',
-    'progressbar'
-  ]);
-
-  const selector =
-    '[role="scrollbar"],[role="toolbar"],[role="tablist"],[role="radiogroup"],[role="tree"],[role="grid"],[role="menu"],[role="menubar"],[role="meter"],[role="progressbar"]';
+  // Roles WAI-ARIA marks "Accessible Name Required: True" and names from the
+  // author only. Generated from aria-query by scripts/generate-aria-tables.js:
+  // a role that merely *allows* an author name (tablist, toolbar, menu,
+  // menubar, scrollbar) is not a 4.1.2 failure when unnamed and is not listed.
+  // <generated:aria-name-required-roles>
+  const NAME_REQUIRED_ROLES = new Set(['grid', 'meter', 'progressbar', 'radiogroup', 'tree']);
+  // </generated:aria-name-required-roles>
+
+  // Derived from the set above so the two cannot drift apart.
+  const selector = [...NAME_REQUIRED_ROLES].map((r) => `[role="${r}"]`).join(',');
 
   const nodes = (() => {
     try {
@@ -161,7 +175,7 @@ function runInPage(ctx) {
         return '';
       }
     })();
-    if (!roleSet.has(role)) continue;
+    if (!NAME_REQUIRED_ROLES.has(role)) continue;
 
     if (!isEligible(el)) continue;
 

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

@@ -11,16 +11,15 @@
  * @applicability
  *   Applies to any element with a non-empty role="" attribute in the composed DOM.
  * @expectation
- *   The role attribute's first token (the role actually used by assistive technology;
- *   later space-separated tokens are author-supplied fallbacks and are not evaluated
- *   here) must be a real WAI-ARIA role name, and must not be an abstract role
- *   (abstract roles exist only for the specification's own role taxonomy and must
- *   never be used directly in markup).
- * @implementation-notes
- * - Unlike this engine's accessible-name rules, ARIA validity is a static markup
- *   property independent of current visibility/eligibility, so this rule does not
- *   gate on isAccTreeEligible: an invalid role is a defect whether or not the
- *   element happens to be hidden right now.
+ *   At least one role token names a concrete, non-abstract ARIA role.
+ *   Graded by what the element falls back to when none does:
+ *   - FAIL on a roleless host (div, span, custom element), which is left
+ *     exposed as generic, so the role the author meant reaches no one.
+ *   - CANTTELL where the element has a native role (a <button>, <nav>,
+ *     <a href>), which the accessibility tree keeps using. ACT 674b10 lists
+ *     4.1.2 as a secondary requirement only, "satisfied through the implicit
+ *     role," so the bad token is worth reporting but is not itself the
+ *     criterion failing.
  */
 
 const id = 'aria-roles-valid';
@@ -64,7 +63,8 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart('[role]')
     : helpers.queryAll('[role]');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   // Programmatically hidden per the ACT glossary: display:none, visibility not
@@ -121,8 +121,42 @@ function runInPage(ctx) {
     const isKnown = tokens.some((t) => ariaHelpers.isKnownRole(t));
     const reasonCode = !isKnown ? 'ARIA_ROLE_INVALID' : 'ARIA_ROLE_ABSTRACT';
 
-    occurrences.push(
+    // An unusable role token leaves the element on its native role, when it
+    // has one: ACT 674b10 lists 4.1.2 as only a secondary requirement for
+    // exactly that reason. A roleless host (div, span, custom element) has
+    // nothing to fall back to and is exposed as generic instead.
+    const nativeRole =
+      typeof ariaHelpers.getNativeRoleForElement === 'function'
+        ? ariaHelpers.getNativeRoleForElement(el) || ''
+        : '';
+
+    if (nativeRole) {
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          occurrenceOutcome: 'cantTell',
+          summary: `The role attribute value is not usable, so this element is still exposed as its native role="${nativeRole}".`,
+          hint: 'Fix or remove the role token; assistive technology is using the native role in the meantime.',
+          i18n: {
+            summaryKey: 'ariaRolesValid_summary_cantTell',
+            hintKey: 'ariaRolesValid_hint_cantTell',
+            params: { role, nativeRole }
+          },
+          uncertainty: {
+            code: 'spec-only',
+            needed: 'Whether the native role this element falls back to is the one intended.',
+            evidence: { role, nativeRole, fallbackExposed: true }
+          },
+          data: {
+            details: { reasonCode, role, nativeRole }
+          }
+        })
+      );
+      continue;
+    }
+
+    failOccurrences.push(
       helpers.reportOccurrence(el, {
+        occurrenceOutcome: 'fail',
         summary: !isKnown
           ? 'The role attribute value is not a recognized ARIA role.'
           : 'The role attribute value is an abstract ARIA role, which must not be used directly.',
@@ -146,15 +180,12 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'serious'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };