@surea11y/core 1.5.0 → 1.7.0

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

@@ -2,6 +2,25 @@
 
 'use strict';
 
+/**
+ * @check progressbar-name-present
+ * @atomic true
+ * @summary Elements with role="progressbar" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to elements carrying role="progressbar" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title.
+ *   role="progressbar" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom progressbar widget is not
+ *   reliably exposed as its name.
+ */
+
 const id = 'progressbar-name-present';
 
 const meta = {
@@ -54,7 +73,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -106,10 +125,10 @@ function runInPage(ctx) {
     if (title) return { ok: true, method: 'title' };
 
     // role="progressbar" is name-from-author-only per WAI-ARIA: aria-label,
-    // aria-labelledby, or title — no content-based naming method at all. It
+    // aria-labelledby, or title, no content-based naming method at all. It
     // must NOT fall back to subtree content: e.g. a <ul role="progressbar">
     // loading skeleton with no name of its own, whose nested descendants
-    // carry their own aria-label for a different purpose — falling back to
+    // carry their own aria-label for a different purpose, falling back to
     // subtree content would wrongly treat that as the progressbar's name.
     return { ok: false, method: 'none' };
   }
@@ -139,7 +158,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This progress bar has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this progress bar's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this progress bar's accessible name.",
         i18n: {
           summaryKey: 'progressbarNamePresent_summary_fail',
           hintKey: 'progressbarNamePresent_hint_fail',

package/src/checks/automatic/{role-img-alt-present.js → role-img-text-alternative-present.js}

@@ -5,26 +5,36 @@
 /**
  * @check role-img-text-alternative-present
  * @atomic true
- * @summary Accessible elements with role="img" must have an alternative text via aria-label or aria-labelledby
+ * @summary Accessible elements with role="img"/"graphics-symbol"/"graphics-document" must have a text alternative
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to elements with role="img" that are exposed to assistive technologies.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to elements with role="img", role="graphics-symbol" or
+ *   role="graphics-document" that are included in the accessibility tree
+ *   (ACT 23a2a8's "programmatically hidden" exemption:
+ *   display:none/visibility:hidden/aria-hidden="true" on the element or an
+ *   ancestor, with no carve-out for focusable or IDREF-referenced elements,
+ *   aria-hidden-focus and duplicate-id-aria own those separately). Per ACT
+ *   7d6734, this reaches any element carrying one of these roles, not only
+ *   the <svg> root, e.g. a <circle role="graphics-symbol"> nested inside a
+ *   plain <svg>. The <svg> root itself is left to svg-text-alternative-present's
+ *   own (already ACT-clean) title/aria-name handling; the <img> tag is
+ *   excluded here since it has its own dedicated rule.
  * @expectation
- *   Each applicable element with role="img" has an accessible text alternative:
+ *   Each applicable element has an accessible text alternative:
  *    - aria-label with a non-empty value; OR
  *    - aria-labelledby referencing at least one existing element that contributes non-empty text; OR
- *    - a non-empty title attribute (last-resort accessible-name source per HTML-AAM).
+ *    - a non-empty title attribute (last-resort accessible-name source per HTML-AAM); OR
+ *    - for an SVG-namespace element, a non-empty first-child <title> (SVG-AAM's own naming mechanism, not only for the <svg> root).
  */
 
 const id = 'role-img-text-alternative-present';
 
 const meta = {
-  title: '[role="img"] must have an accessible text alternative',
+  title:
+    '[role="img"/"graphics-symbol"/"graphics-document"] must have an accessible text alternative',
   description:
-    'Checks that elements with role="img" provide an accessible text alternative via aria-label, aria-labelledby, or a title attribute.',
+    'Checks that elements with role="img", "graphics-symbol" or "graphics-document" provide an accessible text alternative using aria-label, aria-labelledby, a title attribute, or (for SVG elements) a first-child <title>.',
   i18n: {
     titleKey: 'roleImg_textAlternativePresent_title',
     descriptionKey: 'roleImg_textAlternativePresent_description'
@@ -86,7 +96,7 @@ function runInPage(ctx) {
 
   const imgElements = (() => {
     // do not consider element "img" because it has its own rule
-    const sel = '[role="img" i]:not(img)';
+    const sel = '[role="img" i]:not(img), [role="graphics-symbol" i], [role="graphics-document" i]';
     try {
       return Array.from((queryAllSmart ? queryAllSmart(sel) : queryAll(sel)) || []);
     } catch {
@@ -101,8 +111,16 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // ACT 23a2a8 (same rule as native img-alt-present) exempts programmatically
+  // hidden images and that glossary term has no focusability carve-out, so a
+  // tabbable/IDREF-referenced role="img" inside aria-hidden stays out of
+  // scope here too; aria-hidden-focus reports that markup instead.
   const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
 
   const getAccessibleNameInfo =
     helpers && typeof helpers.getAccessibleNameInfo === 'function'
@@ -122,10 +140,21 @@ function runInPage(ctx) {
         }
       })();
       if (elig && elig.eligible === false) continue;
+      // isIncludedInAccessibilityTree returns a plain boolean, not an
+      // {eligible, reasons} object like isAccTreeEligible's fallback shape.
+      if (typeof elig === 'boolean' && elig === false) continue;
     }
 
     applicableCount += 1;
 
+    const matchedRole = (() => {
+      try {
+        return trim(el.getAttribute('role')).split(/\s+/)[0].toLowerCase();
+      } catch {
+        return 'img';
+      }
+    })();
+
     // Expectation: aria-label OR aria-labelledby. We use helper name-info when available,
     // but we also validate the source to keep this rule scoped/deterministic.
 
@@ -163,6 +192,25 @@ function runInPage(ctx) {
     })();
     const hasValidTitle = titleRaw !== null && trim(titleRaw).length > 0;
 
+    // SVG-AAM's own accessible-name mechanism: a first-child <title>
+    // element (not the HTML title attribute) is the standard way to name
+    // any element in the SVG namespace, not only the <svg> root -- a
+    // role="graphics-symbol" <circle> named only this way still has a real
+    // text alternative, same as a role="img" <svg>.
+    const svgTitleChildText = (() => {
+      try {
+        const isSvgNamespace = el.namespaceURI === 'http://www.w3.org/2000/svg';
+        if (!isSvgNamespace) return '';
+        const first = el.firstElementChild;
+        const firstTag = first ? (first.localName || first.tagName || '').toLowerCase() : '';
+        if (firstTag !== 'title') return '';
+        return trim(first.textContent);
+      } catch {
+        return '';
+      }
+    })();
+    const hasValidTitleSource = hasValidTitle || !!svgTitleChildText;
+
     let nameInfo = null;
 
     // Fast outcomes first (no helper needed)
@@ -170,19 +218,19 @@ function runInPage(ctx) {
     let hasName = false;
 
     if (!hasAriaLabelAttr && !hasAriaLabelledbyAttr) {
-      if (hasValidTitle) {
+      if (hasValidTitleSource) {
         hasName = true;
       } else {
         reasonCode = 'missingTextAlternative';
       }
     } else if (hasAriaLabelAttr && !hasValidAriaLabel) {
-      if (hasValidTitle) {
+      if (hasValidTitleSource) {
         hasName = true;
       } else {
         reasonCode = 'emptyAriaLabel';
       }
     } else if (hasAriaLabelledbyAttr && !hasValidAriaLabelledbyAttr) {
-      if (hasValidTitle) {
+      if (hasValidTitleSource) {
         hasName = true;
       } else {
         reasonCode = 'emptyAriaLabelledby';
@@ -214,12 +262,12 @@ function runInPage(ctx) {
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
     const baseOccurrence = {
-      summary: 'Missing text alternative on element with role="img".',
-      hint: 'Provide aria-label or aria-labelledby (referencing non-empty text) to give this image a text alternative.',
+      summary: `Missing text alternative on element with role="${matchedRole}".`,
+      hint: 'Provide aria-label or aria-labelledby (referencing non-empty text) to give this element a text alternative.',
       i18n: {
         summaryKey: 'roleImg_textAlternativePresent_summary_fail',
         hintKey: 'roleImg_textAlternativePresent_hint_fail',
-        params: { role: 'img' }
+        params: { role: matchedRole }
       },
       data: {
         details: {

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

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check searchbox-name-present
+ * @atomic true
+ * @summary Elements with role="searchbox" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="searchbox" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title.
+ *   role="searchbox" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom searchbox widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="searchbox">)
+ *   an associated <label> counts as well.
+ */
+
 const id = 'searchbox-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Searchboxes have an accessible name',
+  description: 'Checks that elements with role="searchbox" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'searchboxNamePresent_title',
     descriptionKey: 'searchboxNamePresent_description'
@@ -51,7 +71,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -68,7 +88,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -83,10 +103,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -96,7 +116,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -231,7 +251,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This element has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this searchbox's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this searchbox's accessible name.",
         i18n: {
           summaryKey: 'searchboxNamePresent_summary_fail',
           hintKey: 'searchboxNamePresent_hint_fail',

package/src/checks/automatic/server-side-image-map-absent.js

@@ -13,7 +13,7 @@
  * @expectation
  *   The image does not use ismap at all. Server-side image maps depend on
  *   the browser sending click coordinates to the server, which has no
- *   keyboard-operable equivalent — there is no way to determine or expose
+ *   keyboard-operable equivalent, there is no way to determine or expose
  *   individual clickable regions to assistive technology or keyboard
  *   users. Client-side image maps (<map>/<area>, each with real href/alt)
  *   are the accessible alternative and are not flagged by this rule.

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

@@ -2,6 +2,27 @@
 
 'use strict';
 
+/**
+ * @check slider-name-present
+ * @atomic true
+ * @summary Elements with role="slider" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="slider" (the attribute must name that
+ *   role alone, not a fallback list) that are included in the accessibility
+ *   tree. An element with the matching implicit role but no role attribute
+ *   is out of scope. A native <input type="range"> without the role belongs
+ *   to form-control-programmatic-label-present.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title.
+ *   role="slider" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom slider widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="slider">) an
+ *   associated <label> counts as well.
+ */
+
 const id = 'slider-name-present';
 
 const meta = {
@@ -67,7 +88,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -84,7 +105,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -99,10 +120,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -112,7 +133,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -209,7 +230,7 @@ function runInPage(ctx) {
     }
 
     // role="slider" is name-from-author-only per WAI-ARIA (unlike e.g.
-    // role="option"/"tab"), so it must NOT fall back to subtree content —
+    // role="option"/"tab"), so it must NOT fall back to subtree content,
     // visible text near/inside a custom slider widget is not reliably
     // exposed as its accessible name by assistive technologies.
     return { ok: false, method: 'none' };

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

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check spinbutton-name-present
+ * @atomic true
+ * @summary Elements with role="spinbutton" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="spinbutton" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title.
+ *   role="spinbutton" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom spinbutton widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="spinbutton">)
+ *   an associated <label> counts as well.
+ */
+
 const id = 'spinbutton-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Spinbuttons have an accessible name',
+  description: 'Checks that elements with role="spinbutton" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'spinbuttonNamePresent_title',
     descriptionKey: 'spinbuttonNamePresent_description'
@@ -51,7 +71,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -68,7 +88,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -83,10 +103,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -96,7 +116,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -231,7 +251,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This element has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this spinbutton's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this spinbutton's accessible name.",
         i18n: {
           summaryKey: 'spinbuttonNamePresent_summary_fail',
           hintKey: 'spinbuttonNamePresent_hint_fail',

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

@@ -2,6 +2,22 @@
 
 'use strict';
 
+/**
+ * @check summary-name-present
+ * @atomic true
+ * @summary <summary> elements must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to <summary> elements included in the accessibility tree,
+ *   wherever they appear, a <summary> outside a <details> is still matched.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or from its
+ *   own subtree text, where a descendant's own name (an <img alt>,
+ *   aria-label or title) counts as that descendant's contribution.
+ */
+
 const id = 'summary-name-present';
 
 const meta = {
@@ -51,7 +67,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -70,7 +86,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).

package/src/checks/automatic/svg-image-text-alternative-present.js

@@ -109,7 +109,7 @@ function runInPage(ctx) {
   }
 
   // <desc> counts when it is the first child, or the second child
-  // immediately following a <title> — the standard <title>+<desc> pairing.
+  // immediately following a <title>, the standard <title>+<desc> pairing.
   // A <desc> appearing later than that is not reliably read by AT.
   function descText(el) {
     try {

package/src/checks/automatic/svg-text-alternative-present.js

@@ -13,12 +13,15 @@
  *   "Intended to be conveyed" is approximated deterministically by at least one of:
  *     - role="img", role="graphics-symbol", or role="graphics-document"
  *       on the SVG root element itself (the WAI-ARIA Graphics Module
- *       roles, alongside img). Deliberately does NOT extend to arbitrary
- *       role="graphics-symbol" descendants nested inside an <svg> — this
- *       check's scope is the <svg> root only; a broader feature, not
- *       attempted here.
+ *       roles, alongside img). Does NOT extend to arbitrary
+ *       role="img"/"graphics-symbol"/"graphics-document" descendants
+ *       nested inside an <svg>. This check's scope is the <svg> root
+ *       only; role-img-text-alternative-present covers those same three
+ *       roles on any other element, including nested SVG shapes (ACT
+ *       7d6734's own failed example: a bare `<svg>` root with a nested
+ *       `<circle role="graphics-symbol">`).
  *     - aria-label / aria-labelledby present
- *     - <title> or <desc> present (desc alone is an applicability signal only — see @expectation)
+ *     - <title> or <desc> present (desc alone is an applicability signal only, see @expectation)
  *     - focusable/tabbable (e.g., tabindex, native focusability)
  *
  *   Images with role="presentation" or role="none" are excluded only when they are not focusable.
@@ -28,7 +31,7 @@
  *   Each applicable <svg> element provides a text alternative via:
  *     - non-empty <title> text, OR
  *     - an ARIA name (aria-label / aria-labelledby).
- *   A <desc> element alone does NOT satisfy this — per the SVG Accessibility
+ *   A <desc> element alone does NOT satisfy this, per the SVG Accessibility
  *   API Mappings spec §7.1, <desc> only ever contributes to the accessible
  *   DESCRIPTION, never the accessible NAME. An <svg> with only a
  *   <desc> and no <title>/ARIA name is still "applicable" (desc signals
@@ -40,7 +43,7 @@ const id = 'svg-text-alternative-present';
 const meta = {
   title: '<svg> must provide a text alternative',
   description:
-    'Checks that inline <svg> elements provide a text alternative via a <title> element or an ARIA name (a <desc> element alone does not count — it only contributes to the accessible description, not the name).',
+    'Checks that inline <svg> elements provide a text alternative via a <title> element or an ARIA name (a <desc> element alone does not count).',
   i18n: {
     titleKey: 'svg_textAltPresent_title',
     descriptionKey: 'svg_textAltPresent_description'
@@ -124,7 +127,7 @@ function runInPage(ctx) {
   }
 
   // <desc> counts when it is the first child, or the second child
-  // immediately following a <title> — the standard <title>+<desc> pairing
+  // immediately following a <title>, the standard <title>+<desc> pairing
   // (e.g. <svg><title>...</title><desc>...</desc>...</svg>). A <desc>
   // appearing later than that is not reliably read by AT.
   function nonEmptyDescText(svg) {
@@ -277,7 +280,7 @@ function runInPage(ctx) {
     }
 
     // Per SVG-AAM §7.1: <desc> contributes only to the accessible
-    // DESCRIPTION, never the accessible NAME — so descText does not
+    // DESCRIPTION, never the accessible NAME, so descText does not
     // count here even though it does count toward applicability above.
     const ok = !!titleText || hasAriaName;
     if (ok) continue;
@@ -293,7 +296,7 @@ function runInPage(ctx) {
 
     const baseOccurrence = {
       summary: 'Missing text alternative for <svg>.',
-      hint: 'Provide a <title> element with text, or an ARIA name (aria-label/aria-labelledby) — a <desc> element alone does not provide an accessible name.',
+      hint: 'Provide a <title> element with text, or an ARIA name (aria-label/aria-labelledby); a <desc> element alone does not provide an accessible name.',
       i18n: {
         summaryKey: 'svg_textAltPresent_summary_fail',
         hintKey: 'svg_textAltPresent_hint_fail',

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

@@ -2,6 +2,25 @@
 
 'use strict';
 
+/**
+ * @check tab-name-present
+ * @atomic true
+ * @summary Elements with role="tab" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="tab" (the attribute must name that
+ *   role alone, not a fallback list) that are included in the accessibility
+ *   tree. An element with the matching implicit role but no role attribute
+ *   is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or,
+ *   role="tab" being name-from-content, from its own subtree text, where a
+ *   descendant's own name (an <img alt>, aria-label or title) counts as that
+ *   descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'tab-name-present';
 
 const meta = {
@@ -51,7 +70,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -70,7 +89,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).