@surea11y/core 1.4.1 → 1.6.0

package/src/checks/manual/presentation-role-conflict-manual.js

@@ -6,28 +6,29 @@
  * @check presentation-role-conflict
  * @atomic true
  * @summary role="presentation"/"none" must not be combined with a global ARIA naming attribute or focusability
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with an explicit role="presentation" or
- *   role="none", OR an <img alt=""> (empty alt gives an <img> an implicit
- *   presentation role per HTML-AAM, even with no explicit role attribute
- *   at all — `img[alt=''], [role="none"], [role="presentation"]`).
+ *   role="none", OR an <img alt=""> carrying no explicit role of its own
+ *   (empty alt gives an <img> an implicit presentation role per HTML-AAM,
+ *   even with no explicit role attribute at all: `img[alt=''],
+ *   [role="none"], [role="presentation"]`).
  * @expectation
  *   The element does not also carry a WAI-ARIA *global* state/property
  *   (aria-label, aria-hidden, aria-describedby, aria-live, aria-current,
- *   ... — the full global-attribute set, not just the naming ones), AND
+ *   ...; the full global-attribute set, not just the naming ones), AND
  *   is not focusable. Per the WAI-ARIA spec's Presentational Roles
  *   Conflict Resolution section, a presentational role is "restored" to
- *   the element's implicit semantic role when either condition holds —
+ *   the element's implicit semantic role when either condition holds:
  *   the presentation/none role silently stops working, contradicting the
  *   author's evident intent to hide the element from the accessibility
  *   tree.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - `aria-hidden="true"` (the exact valid truthy value) on the
- *   presentational element itself is deliberately EXCLUDED as a trigger,
+ *   presentational element itself is EXCLUDED as a trigger on purpose,
  *   even though it's a global ARIA attribute: it removes the element from
  *   the accessibility tree unconditionally, so the "role restoration"
  *   this rule warns about never actually reaches assistive tech, making a
@@ -38,18 +39,23 @@
  *   exemption (see the code comment at the check site).
  * - The conflicting-attribute set is the full list of ARIA attributes
  *   marked `global: true`, not a narrower naming-only list.
- * - Deliberately NOT applying an implicit-role applicability gate that
+ * - Not applying an implicit-role applicability gate on purpose, one that
  *   would make the check inapplicable to role="presentation" on elements
  *   with no native implicit role to suppress (e.g. `<div
- *   role="presentation" aria-hidden="true">` — a <div> has no native role,
+ *   role="presentation" aria-hidden="true">`: a <div> has no native role,
  *   so there's nothing for the presentational role to "conflict" with).
  *   surea11y stays broader/more cautious here rather than narrower, which
- *   is the safer direction to diverge in. The native-implicit-role table
- *   needed to add that gate, if this scope decision is ever revisited, is
- *   in ROADMAP.md §7 item 9.
+ *   is the safer direction to diverge in. Adding that gate later would
+ *   need a native-implicit-role table, which doesn't exist yet.
  * - Focusability is computed via helpers.getFocusableInfo (native +
- *   tabindex), same helper aria-hidden-focus already relies on — a
+ *   tabindex), same helper aria-hidden-focus already relies on. A
  *   `:disabled` or otherwise non-focusable element is not flagged.
+ * - An `<img alt="">` carrying an explicit role of its own (e.g. `<img
+ *   alt="" role="img" aria-label="Logo">`) is out of scope: the explicit
+ *   role wins over the presentation role empty alt would otherwise confer,
+ *   so nothing presentational is left to conflict with. An explicit role
+ *   whose tokens are all unknown confers nothing either, and the empty alt
+ *   still applies.
  */
 
 const id = 'presentation-role-conflict';
@@ -77,7 +83,7 @@ function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
   // The full set of ARIA attributes marked `global: true` per the WAI-ARIA
-  // spec — any of these present on a presentational element restores its
+  // spec. Any of these present on a presentational element restores its
   // implicit role, not just the naming ones.
   const CONFLICTING_ATTRS = [
     'aria-atomic',
@@ -109,6 +115,26 @@ function runInPage(ctx) {
   const getFocusableInfo =
     helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+
+  // The role attribute holds a fallback list; the first token naming a real
+  // role wins, and unknown tokens are skipped over. Returns '' when the
+  // element has no role attribute or none of its tokens name a role: the
+  // cases where an <img alt=""> keeps the presentation role empty alt gives
+  // it.
+  function getEffectiveRoleToken(el) {
+    const raw = el.getAttribute ? el.getAttribute('role') : null;
+    if (!raw) return '';
+    const tokens = String(raw).trim().toLowerCase().split(/\s+/);
+    for (const token of tokens) {
+      if (!token) continue;
+      if (token === 'presentation' || token === 'none') return token;
+      const known = ariaHelpers ? ariaHelpers.isValidConcreteRole(token) : true;
+      if (known) return token;
+    }
+    return '';
+  }
+
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('[role="presentation"], [role="none"], img[alt=""]')
     : helpers.queryAll('[role="presentation"], [role="none"], img[alt=""]');
@@ -119,30 +145,37 @@ function runInPage(ctx) {
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
 
+    // Only reachable via the img[alt=""] branch of the selector: an explicit
+    // role other than presentation/none overrides the presentation role that
+    // empty alt would confer, leaving no presentational intent to conflict
+    // with.
+    const roleToken = getEffectiveRoleToken(el);
+    if (roleToken && roleToken !== 'presentation' && roleToken !== 'none') continue;
+
     applicableCount += 1;
 
     // Presence, not value truthiness: the WAI-ARIA role-conflict-resolution
     // rule triggers on a global ARIA attribute being SPECIFIED at all, even
-    // with an empty value — e.g. <img alt="" aria-hidden="">, where
+    // with an empty value, e.g. <img alt="" aria-hidden="">, where
     // aria-hidden="" (empty string) is still a specified attribute. A
     // truthy-value check would miss this.
     let present = CONFLICTING_ATTRS.filter((attr) =>
       el.hasAttribute ? el.hasAttribute(attr) : el.getAttribute(attr) != null
     );
 
-    // aria-hidden="true" (the exact, valid truthy value — not the
+    // aria-hidden="true" (the exact, valid truthy value, not the
     // empty-string case above, which never actually hides anything) is a
     // special case: it removes the element and its subtree from the
     // accessibility tree unconditionally, independent of role. That makes
     // the "role restoration" this rule warns about ("...which restores its
     // implicit role and cancels the presentational intent") factually
-    // inert — no AT will ever expose the restored role OR any of the other
+    // inert. No AT will ever expose the restored role OR any of the other
     // conflicting attributes (aria-label, aria-describedby, ...) present
     // alongside it, since the whole element stays out of the tree
     // regardless. This pattern is extremely common (e.g. <svg
-    // role="presentation" aria-hidden="true"> decorative icons — a
+    // role="presentation" aria-hidden="true"> decorative icons, a
     // defensive belt-and-suspenders double-hide, not an authoring mistake).
-    // Focusability is NOT covered by this exemption — a keyboard user can
+    // Focusability is NOT covered by this exemption: a keyboard user can
     // still tab onto an aria-hidden="true" focusable element (the
     // aria-hidden-focus anti-pattern), a real, independent hazard
     // aria-hidden does nothing to prevent.
@@ -165,34 +198,29 @@ function runInPage(ctx) {
     const parts = present.slice();
     if (isFocusable) parts.push('focusable');
 
-    // No explicit role attribute means this matched via the img[alt=""]
+    // No role token means this matched via the img[alt=""]
     // implicit-presentation case.
-    const role =
-      String(el.getAttribute('role') || '')
-        .trim()
-        .toLowerCase() || 'presentation';
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: `This role="${role}" element also has a conflicting condition (${parts.join(', ')}), which restores its implicit role and cancels the presentational intent.`,
-      hint: 'Remove the conflicting naming attribute(s) and/or focusability (tabindex/native) if the element should stay presentational, or remove role="presentation"/"none" if it should be exposed to assistive technology.',
-      i18n: {
-        summaryKey: 'presentationRoleConflict_summary_cantTell',
-        hintKey: 'presentationRoleConflict_hint_cantTell',
-        params: { role, attrs: parts.join(', ') }
-      },
-      data: {
-        details: {
-          reasonCode: 'PRESENTATION_ROLE_CONFLICT',
-          role,
-          conflictingAttrs: present,
-          focusable: isFocusable
+    const role = roleToken || 'presentation';
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This role="${role}" element also has a conflicting condition (${parts.join(', ')}), which restores its implicit role and cancels the presentational intent.`,
+        hint: 'Remove the conflicting naming attribute(s) and/or focusability (tabindex/native) if the element should stay presentational, or remove role="presentation"/"none" if it should be exposed to assistive technology.',
+        i18n: {
+          summaryKey: 'presentationRoleConflict_summary_cantTell',
+          hintKey: 'presentationRoleConflict_hint_cantTell',
+          params: { role, attrs: parts.join(', ') }
+        },
+        data: {
+          details: {
+            reasonCode: 'PRESENTATION_ROLE_CONFLICT',
+            role,
+            conflictingAttrs: present,
+            focusable: isFocusable
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/region-manual.js

@@ -6,10 +6,10 @@
  * @check region
  * @atomic true
  * @summary Page content should be contained within a landmark region
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to any element under <body> that directly carries visible text
- *   (or other own content — see @implementation-notes) and is not itself a
+ *   (or other own content, see @implementation-notes) and is not itself a
  *   landmark, live region, dialog, button, <svg>, <iframe>/<frame>, or a
  *   resolvable skip-link.
  * @expectation
@@ -18,14 +18,14 @@
  *   search), so assistive technology users navigating by landmark do not
  *   miss content that was never placed inside one.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent and the landmark-
  *   detection model.
  * - Recursive tree walk, not a direct-<body>-children-only scan: a
  *   direct-children-only scope is nearly inert on the single most common
  *   real-world page shape, a modern framework's single root mount div
- *   (`<body><div id="root">...everything...</div></body>`) — that shape
+ *   (`<body><div id="root">...everything...</div></body>`). That shape
  *   gives at most one candidate for the entire page and either misses
  *   every real gap inside it or collapses the whole page into one
  *   undifferentiated report.
@@ -37,30 +37,30 @@
  *        live region, dialog, button, <svg>, <iframe>/<frame>, or a
  *        resolvable skip-link), mark it and every ancestor up to <body> as
  *        "has a stopper" and don't recurse further into it (an <iframe>/
- *        <frame> is additionally reported as its own occurrence — its
+ *        <frame> is additionally reported as its own occurrence, since its
  *        content is opaque to this engine, so from the outer page's
  *        perspective it IS unplaced content).
  *     3. Otherwise, if the node has OWN content (a direct child text node,
- *        being an inherently visual element, or an aria-label) — checked
- *        non-recursively, so a plain wrapper <div> with only nested
- *        children never short-circuits the walk into its descendants —
+ *        being an inherently visual element, or an aria-label), checked
+ *        non-recursively so a plain wrapper <div> with only nested
+ *        children never short-circuits the walk into its descendants,
  *        collect it as a candidate and stop recursing into it.
  *     4. Otherwise recurse into its element children.
  *   Each collected candidate is then walked back UP through parents while
  *   the parent has no "stopper" marker and isn't <body> itself, collapsing
  *   contiguous unplaced content into one occurrence per real gap instead
- *   of reporting every individual text-bearing leaf — this is what keeps
+ *   of reporting every individual text-bearing leaf. This is what keeps
  *   the walk from being noisy on ordinary pages that mix landmarked and
  *   stray content.
  * - "Stopper" exemptions (button, dialog, <svg>, resolvable skip-links)
- *   are a deliberate scope choice, not an oversight: these
+ *   are a scope choice, not an oversight: these
  *   are extremely common real-world patterns (floating action buttons,
  *   modal dialogs, decorative/icon SVGs, "skip to content" links) that
  *   aren't the kind of "content organization" gap this rule exists to
  *   catch, and flagging them would reintroduce the false-positive noise
  *   the original narrow scope was trying to avoid.
- * - The "own content" check for aria-label deliberately does NOT resolve
- *   aria-labelledby — a known, narrow scope gap (an element named only via aria-labelledby, with no
+ * - The "own content" check for aria-label does NOT resolve
+ *   aria-labelledby, a known, narrow scope gap (an element named only via aria-labelledby, with no
  *   own text/aria-label, and no other content anywhere in its subtree,
  *   could be silently skipped) accepted to avoid a full accessible-name
  *   computation (recursive itself) inside an already-recursive structural
@@ -137,11 +137,11 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
   // question "does this element sit inside a sectioning-content/<main>
-  // ancestor that suppresses its conditional implicit role" — role-aware
+  // ancestor that suppresses its conditional implicit role": role-aware
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
-  // in src/core/aria-helpers.js for the full algorithm — e.g. an
+  // in src/core/aria-helpers.js for the full algorithm, e.g. an
   // <aside role="dialog"> containing its own <header>, where the <header>
   // keeps its banner role.
   function hasSectioningAncestor(el, includeMain) {
@@ -189,7 +189,7 @@ function runInPage(ctx) {
   const SKIP_TAGS = new Set(['script', 'style', 'template', 'noscript', 'link', 'meta', 'title']);
 
   // Roles/attributes that make an element its own self-contained
-  // announced area — not literally a WAI-ARIA landmark, but not "content
+  // announced area: not literally a WAI-ARIA landmark, but not "content
   // that needs a landmark" either.
   const LIVE_REGION_ROLES = new Set(['alert', 'status', 'log', 'marquee', 'timer']);
 
@@ -217,8 +217,8 @@ function runInPage(ctx) {
     return false;
   }
 
-  // A "skip to content" link is deliberately placed outside the main
-  // content flow at the very top of the page — exempting it (when its
+  // A "skip to content" link is placed outside the main content flow
+  // on purpose, at the very top of the page. Exempting it (when its
   // fragment actually resolves to a real target, not a dead "#"
   // placeholder) avoids flagging a helpful, common accessibility pattern
   // as the very thing this rule is meant to catch.
@@ -249,8 +249,8 @@ function runInPage(ctx) {
 
   const VISUAL_CONTENT_TAGS = new Set(['img', 'video', 'audio', 'canvas', 'object', 'embed']);
 
-  // Non-recursive "does THIS element, on its own, carry content" check —
-  // deliberately mirrors only the direct-content half of getContentNameInfo,
+  // Non-recursive "does THIS element, on its own, carry content" check.
+  // Mirrors only the direct-content half of getContentNameInfo on purpose,
   // not a full name-from-content recursion: the whole point is to keep
   // recursing through plain wrapper elements (a framework's root mount
   // <div> included) until reaching the actual content-bearing node, rather
@@ -352,14 +352,11 @@ function runInPage(ctx) {
     }
   }
 
+  // Report the element itself: without a node reference the engine re-finds
+  // each one with document.querySelector to build its structuralPath.
   const occurrences = collapsed.map((el) => {
     const tag = el.tagName ? lower(el.tagName) : '';
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    const partial = {
       summary: 'This content is not contained within a landmark region.',
       hint: 'Move this content inside a landmark region (main, nav, aside, a labeled section, etc.).',
       i18n: {
@@ -371,6 +368,16 @@ function runInPage(ctx) {
         details: { reasonCode: 'CONTENT_OUTSIDE_LANDMARK', element: tag }
       }
     };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      return helpers.reportOccurrence(el, partial);
+    }
+
+    return {
+      selector: helpers.buildSelector ? helpers.buildSelector(el) : 'html',
+      html: helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '',
+      ...partial
+    };
   });
 
   if (occurrences.length === 0) {

package/src/checks/manual/scope-attr-valid-manual.js

@@ -6,7 +6,7 @@
  * @check scope-attr-valid
  * @atomic true
  * @summary The scope attribute must have a valid value
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with a non-empty scope attribute.
  * @expectation
@@ -15,7 +15,7 @@
  *   assistive technology, silently losing the row/column header
  *   association it was meant to declare.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  */
@@ -61,23 +61,20 @@ function runInPage(ctx) {
 
     if (VALID_SCOPES.has(raw.toLowerCase())) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This scope attribute value is not recognized.',
-      hint: 'Use one of row, col, rowgroup, or colgroup for the scope attribute.',
-      i18n: {
-        summaryKey: 'scopeAttrValid_summary_cantTell',
-        hintKey: 'scopeAttrValid_hint_cantTell',
-        params: { value: raw }
-      },
-      data: {
-        details: { reasonCode: 'SCOPE_ATTR_INVALID', value: raw }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This scope attribute value is not recognized.',
+        hint: 'Use one of row, col, rowgroup, or colgroup for the scope attribute.',
+        i18n: {
+          summaryKey: 'scopeAttrValid_summary_cantTell',
+          hintKey: 'scopeAttrValid_hint_cantTell',
+          params: { value: raw }
+        },
+        data: {
+          details: { reasonCode: 'SCOPE_ATTR_INVALID', value: raw }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/scrollable-region-focusable-manual.js

@@ -9,10 +9,10 @@
  * @standard WCAG 2.2
  * @sc 2.1.1, 2.1.3
  * @applicability
- *   Deliberately scoped to a fixed set of likely-to-scroll container tags
+ *   Scoped on purpose to a fixed set of likely-to-scroll container tags
  *   (div, section, article, aside, main, nav, pre, table, blockquote, ul,
  *   ol, textarea) with computed `overflow-x`/`overflow-y` of `auto` or
- *   `scroll` — not every element on the page, to keep this deterministic
+ *   `scroll`, not every element on the page, to keep this deterministic
  *   and performant (same style of scope-down as `region`).
  * @expectation
  *   A region whose CSS declares it may scroll (`auto`/`scroll`) should be
@@ -22,18 +22,18 @@
  *   scroll from), or the region itself carries a non-negative `tabindex`.
  * @implementation-notes
  * - jsdom does not perform layout, so `scrollHeight`/`clientHeight` are
- *   not available to confirm the region's content actually overflows —
+ *   not available to confirm the region's content actually overflows,
  *   only that the CSS declares it *may*. Many elements declare
  *   `overflow: auto` defensively without their content ever actually
  *   overflowing, which would be a false positive if treated as a hard
  *   `fail`. For that reason this is authored as `type: 'manual'`
- *   (cantTell-capped, never fail) rather than `automatic` — same class of
- *   layout-dependent gap as `iframe-focusable-content`'s
+ *   (cantTell-capped, never fail) rather than `automatic`, the same class
+ *   of layout-dependent gap as `iframe-focusable-content`'s
  *   `contentDocument` limitation.
  * - "Has a focusable descendant" is a presence check (link/button/form
  *   control/`[tabindex]`/`iframe`/`[contenteditable]`), not a full
- *   focusability computation (disabled state, visibility, etc.) — a
- *   deliberate simplification to keep this rule self-contained and fast.
+ *   focusability computation (disabled state, visibility, etc.). Kept
+ *   simple on purpose, to keep this rule self-contained and fast.
  */
 
 const id = 'scrollable-region-focusable';

package/src/checks/manual/skip-link-manual.js

@@ -6,17 +6,17 @@
  * @check skip-link
  * @atomic true
  * @summary A "skip" link must resolve to a real, usable target
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to <a href="#fragment"> elements whose accessible name
  *   matches a common "skip to ..." / "jump to ..." authoring convention
- *   (case-insensitive "skip" or "jump to" in the name) — the recognizable
+ *   (case-insensitive "skip" or "jump to" in the name), the recognizable
  *   pattern for a skip-navigation link, not every same-page anchor link
  *   on the page. "jump to" is included alongside "skip" since real skip
  *   links use both conventions (e.g. a "Jump to section" link, which a
  *   purely positional match would catch but a "skip"-only text pattern
- *   would miss). Text-pattern matching itself stays deliberate (see
- *   implementation-notes) — this only widens the known-convention list.
+ *   would miss). Text-pattern matching itself stays intentional (see
+ *   implementation-notes); this only widens the known-convention list.
  * @expectation
  *   The link's fragment resolves to a real element in the document
  *   (via a matching id, or a legacy <a name="...">), and that target is
@@ -25,7 +25,7 @@
  *   whose target is missing or effectively unusable does not provide a
  *   reliable bypass destination.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - Keyed on the "skip" text-pattern convention rather than positional
@@ -184,59 +184,51 @@ function runInPage(ctx) {
       const unusableByGeometry = !!geometryReasonCode;
       if (!unusableByAcc && !unusableByGeometry) continue;
 
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This skip link points to a target that exists but is not currently usable.',
+          hint: 'Point this skip link to a target that is exposed and usable as a navigation destination.',
+          i18n: {
+            summaryKey: 'skipLink_summary_unusableTarget_cantTell',
+            hintKey: 'skipLink_hint_unusableTarget_cantTell',
+            params: { href }
+          },
+          data: {
+            details: {
+              reasonCode: 'SKIP_LINK_TARGET_UNUSABLE',
+              href,
+              unusableReasonCode: unusableByAcc ? 'ACC_TREE_INELIGIBLE' : geometryReasonCode,
+              targetSelector: helpers.buildSelector ? helpers.buildSelector(target) : null,
+              geometryCheckEnabled: geometrySupported
+            },
+            visibilityFilter: {
+              targetSet: 'acc',
+              accEligible: accEligibility.eligible,
+              reasons: accEligibility.reasons
+            },
+            targetGeometry: geometryEligibility
+              ? { eligible: geometryEligibility.eligible, reasons: geometryEligibility.reasons }
+              : { eligible: null, reasons: [] }
+          }
+        })
+      );
+      continue;
+    }
 
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This skip link points to a target that exists but is not currently usable.',
-        hint: 'Point this skip link to a target that is exposed and usable as a navigation destination.',
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: "This skip link's target does not exist.",
+        hint: "Point the skip link's href at an id that exists in the document, or add the missing target element.",
         i18n: {
-          summaryKey: 'skipLink_summary_unusableTarget_cantTell',
-          hintKey: 'skipLink_hint_unusableTarget_cantTell',
+          summaryKey: 'skipLink_summary_cantTell',
+          hintKey: 'skipLink_hint_cantTell',
           params: { href }
         },
         data: {
-          details: {
-            reasonCode: 'SKIP_LINK_TARGET_UNUSABLE',
-            href,
-            unusableReasonCode: unusableByAcc ? 'ACC_TREE_INELIGIBLE' : geometryReasonCode,
-            targetSelector: helpers.buildSelector ? helpers.buildSelector(target) : null,
-            geometryCheckEnabled: geometrySupported
-          },
-          visibilityFilter: {
-            targetSet: 'acc',
-            accEligible: accEligibility.eligible,
-            reasons: accEligibility.reasons
-          },
-          targetGeometry: geometryEligibility
-            ? { eligible: geometryEligibility.eligible, reasons: geometryEligibility.reasons }
-            : { eligible: null, reasons: [] }
+          details: { reasonCode: 'SKIP_LINK_TARGET_MISSING', href }
         }
-      });
-      continue;
-    }
-
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: "This skip link's target does not exist.",
-      hint: "Point the skip link's href at an id that exists in the document, or add the missing target element.",
-      i18n: {
-        summaryKey: 'skipLink_summary_cantTell',
-        hintKey: 'skipLink_hint_cantTell',
-        params: { href }
-      },
-      data: {
-        details: { reasonCode: 'SKIP_LINK_TARGET_MISSING', href }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/svg-text-alternative-quality-manual.js

@@ -9,6 +9,15 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to inline <svg> elements that already carry a text alternative:
+ *   non-empty <title> or <desc> text, a non-empty aria-label, or an
+ *   aria-labelledby that resolves to non-empty text. <desc> counts here as
+ *   something to review even though it never contributes to the accessible
+ *   name: that distinction is svg-text-alternative-present's. The element
+ *   must be included in the accessibility tree, and
+ *   role="presentation"/"none" takes it out of scope unless it is focusable,
+ *   which restores its role.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */

package/src/checks/manual/tabindex-manual.js

@@ -6,7 +6,7 @@
  * @check tabindex
  * @atomic true
  * @summary tabindex should not be greater than 0
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with a tabindex attribute whose value parses as
  *   a valid integer.
@@ -16,7 +16,7 @@
  *   page changes and usually indicates the natural DOM order should be
  *   fixed instead.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  */
@@ -62,23 +62,20 @@ function runInPage(ctx) {
 
     if (n <= 0) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This element has a positive tabindex, overriding the natural tab order.',
-      hint: 'Use tabindex="0" (or a negative value to remove from tab order) instead of a positive number; fix the DOM order if a different tab order is needed.',
-      i18n: {
-        summaryKey: 'tabindex_summary_cantTell',
-        hintKey: 'tabindex_hint_cantTell',
-        params: { value: String(n) }
-      },
-      data: {
-        details: { reasonCode: 'TABINDEX_POSITIVE', value: n }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This element has a positive tabindex, overriding the natural tab order.',
+        hint: 'Use tabindex="0" (or a negative value to remove from tab order) instead of a positive number; fix the DOM order if a different tab order is needed.',
+        i18n: {
+          summaryKey: 'tabindex_summary_cantTell',
+          hintKey: 'tabindex_hint_cantTell',
+          params: { value: String(n) }
+        },
+        data: {
+          details: { reasonCode: 'TABINDEX_POSITIVE', value: n }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {