@surea11y/core 1.4.1 → 1.6.0

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

@@ -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
@@ -96,13 +96,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 +154,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'
@@ -210,27 +262,24 @@ function runInPage(ctx) {
 
     if (hasContext) 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 role requires a specific ancestor/owner context role, which was not found.',
-      hint: 'Place this element inside (or aria-owns-reference it from) an element with an acceptable context role.',
-      i18n: {
-        summaryKey: 'ariaRequiredParent_summary_fail',
-        hintKey: 'ariaRequiredParent_hint_fail',
-        params: { role, requiredRoles: requiredContext.join(', ') }
-      },
-      data: {
-        details: {
-          reasonCode: 'ARIA_REQUIRED_PARENT_MISSING',
-          role,
-          requiredContextRoles: requiredContext
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This role requires a specific ancestor/owner context role, which was not found.',
+        hint: 'Place this element inside (or aria-owns-reference it from) an element with an acceptable context role.',
+        i18n: {
+          summaryKey: 'ariaRequiredParent_summary_fail',
+          hintKey: 'ariaRequiredParent_hint_fail',
+          params: { role, requiredRoles: requiredContext.join(', ') }
+        },
+        data: {
+          details: {
+            reasonCode: 'ARIA_REQUIRED_PARENT_MISSING',
+            role,
+            requiredContextRoles: requiredContext
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

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,14 +12,34 @@
  * - 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'
@@ -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

@@ -68,14 +68,28 @@ function runInPage(ctx) {
   let applicableCount = 0;
 
   // Programmatically hidden per the ACT glossary: display:none, visibility not
-  // visible, or aria-hidden on the element or an ancestor.
+  // visible, or aria-hidden on the element or an ancestor. inert is treated
+  // the same although the glossary predates it -- an inert subtree is out of
+  // the accessibility tree entirely, so a role on it reaches no one.
   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) {
+      // Walk the composed tree, not parentElement: that stops at a shadow
+      // root, so a host carrying aria-hidden or inert would never be seen
+      // from inside its own shadow content.
+      const up =
+        typeof helpers.composedParent === 'function'
+          ? helpers.composedParent
+          : (n) => n.parentElement;
+
+      // A shadow root has no getAttribute, so skip past it rather than
+      // stopping: the host one step further up is the node that matters.
+      for (let n = el; n; n = up(n)) {
+        if (!n.getAttribute) continue;
         if (String(n.getAttribute('aria-hidden') || '').toLowerCase() === 'true') return true;
+        if (n.hasAttribute && n.hasAttribute('inert')) return true;
       }
     } catch {
       return false;
@@ -106,27 +120,27 @@ function runInPage(ctx) {
     const role = tokens[0];
     const isKnown = tokens.some((t) => ariaHelpers.isKnownRole(t));
     const reasonCode = !isKnown ? 'ARIA_ROLE_INVALID' : 'ARIA_ROLE_ABSTRACT';
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      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.',
-      hint: !isKnown
-        ? 'Use a valid ARIA role token, or remove the role attribute if none applies.'
-        : 'Replace this abstract role with a concrete role appropriate for the widget/structure.',
-      i18n: {
-        summaryKey: !isKnown ? 'ariaRolesValid_summary_invalid' : 'ariaRolesValid_summary_abstract',
-        hintKey: !isKnown ? 'ariaRolesValid_hint_invalid' : 'ariaRolesValid_hint_abstract',
-        params: { role }
-      },
-      data: {
-        details: { reasonCode, role }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        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.',
+        hint: !isKnown
+          ? 'Use a valid ARIA role token, or remove the role attribute if none applies.'
+          : 'Replace this abstract role with a concrete role appropriate for the widget/structure.',
+        i18n: {
+          summaryKey: !isKnown
+            ? 'ariaRolesValid_summary_invalid'
+            : 'ariaRolesValid_summary_abstract',
+          hintKey: !isKnown ? 'ariaRolesValid_hint_invalid' : 'ariaRolesValid_hint_abstract',
+          params: { role }
+        },
+        data: {
+          details: { reasonCode, role }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/aria-valid-attr-value.js

@@ -15,9 +15,14 @@
  * @expectation
  *   Each attribute's value conforms to its WAI-ARIA-declared value type:
  *   boolean ("true"/"false"), tristate ("true"/"false"/"mixed"), a token
- *   from a fixed enumerated set, an integer, a real number, or an empty
- *   value or ID reference (list) that resolves to an existing element in
- *   the document.
+ *   from a fixed enumerated set, an integer, a real number, or an ID
+ *   reference (list) that resolves to an existing element in the document.
+ *   Per ACT 6a7281's own applicability ("any state or property that is
+ *   NOT empty"), an explicitly empty value, including a bare boolean-style
+ *   attribute with no "=value" at all, e.g. `aria-checked` alone, is out
+ *   of scope for every value type, not a violation: a common, deliberate
+ *   pattern in templated markup (e.g. React conditionally rendering
+ *   `aria-describedby={hasError ? errorId : ''}`).
  * @implementation-notes
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
@@ -25,16 +30,14 @@
  * - ID-reference resolution (see aria-helpers.js's idExists) only flags
  *   idref-list attributes (aria-labelledby, aria-describedby,
  *   aria-controls, aria-owns, etc.) when NONE of the space-separated ids
- *   resolve — a partially-dangling list (some ids exist, some don't) is
+ *   resolve, a partially-dangling list (some ids exist, some don't) is
  *   left unflagged (only invalidate when every token fails to resolve).
- *   Single-idref attributes (aria-activedescendant, aria-errormessage) are
- *   flagged whenever their one id doesn't resolve.
- * - An explicitly-EMPTY idref/idref-list value (e.g.
- *   `aria-describedby=""`) is valid, not a violation — `allowEmpty` holds
- *   for every idref/idref-list ARIA attribute. A common, deliberate pattern
- *   in templated markup (e.g. React conditionally rendering
- *   `aria-describedby={hasError ? errorId : ''}`); flagging it would be a
- *   false positive.
+ *   Of the two single-idref attributes, aria-activedescendant is flagged
+ *   whenever its one id doesn't resolve; aria-errormessage's existence is
+ *   never checked (format only), ACT 6a7281's own Background
+ *   text names it as a non-required property whose target "may be created
+ *   in response to an event that may or may not happen" (a validation
+ *   error message rendered only once the error actually occurs).
  */
 
 const id = 'aria-valid-attr-value';
@@ -105,29 +108,26 @@ function runInPage(ctx) {
 
     if (!invalid || !invalid.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const item of invalid) {
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This element has an ARIA attribute with an invalid value.',
-        hint: 'Use a value that matches the attribute’s expected type (see the WAI-ARIA specification for this attribute).',
-        i18n: {
-          summaryKey: 'ariaValidAttrValue_summary_fail',
-          hintKey: 'ariaValidAttrValue_hint_fail',
-          params: { attr: item.name, value: item.value }
-        },
-        data: {
-          details: {
-            reasonCode: 'ARIA_ATTR_VALUE_INVALID',
-            attr: item.name,
-            value: item.value,
-            valueReason: item.reason
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This element has an ARIA attribute with an invalid value.',
+          hint: 'Use a value that matches the attribute’s expected type (see the WAI-ARIA specification for this attribute).',
+          i18n: {
+            summaryKey: 'ariaValidAttrValue_summary_fail',
+            hintKey: 'ariaValidAttrValue_hint_fail',
+            params: { attr: item.name, value: item.value }
+          },
+          data: {
+            details: {
+              reasonCode: 'ARIA_ATTR_VALUE_INVALID',
+              attr: item.name,
+              value: item.value,
+              valueReason: item.reason
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -18,7 +18,7 @@
  *   deterministic defect).
  * @implementation-notes
  * - Distinct from aria-valid-attr-value (which validates the VALUE
- *   of a recognized attribute) — this rule only validates the attribute
+ *   of a recognized attribute), this rule only validates the attribute
  *   NAME.
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
@@ -86,24 +86,21 @@ function runInPage(ctx) {
 
     if (!invalidNames || !invalidNames.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const name of invalidNames) {
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This element has an attribute that is not a recognized ARIA attribute.',
-        hint: 'Correct the attribute name (check for typos), or remove it if not needed.',
-        i18n: {
-          summaryKey: 'ariaValidAttr_summary_fail',
-          hintKey: 'ariaValidAttr_hint_fail',
-          params: { attr: name }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ATTR_INVALID', attr: name }
-        }
-      });
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This element has an attribute that is not a recognized ARIA attribute.',
+          hint: 'Correct the attribute name (check for typos), or remove it if not needed.',
+          i18n: {
+            summaryKey: 'ariaValidAttr_summary_fail',
+            hintKey: 'ariaValidAttr_hint_fail',
+            params: { attr: name }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ATTR_INVALID', attr: name }
+          }
+        })
+      );
     }
   }
 

package/src/checks/automatic/autocomplete-valid.js

@@ -26,7 +26,7 @@
  *   order) with the full fixed field-name vocabulary from the HTML
  *   Standard, rather than validating every field-specific constraint
  *   (e.g. which contact-modality tokens are legal for which field
- *   names) — matches this engine's established "deliberately scoped"
+ *   names), matches this engine's established "scoped"
  *   precedent (see aria-helpers.js) for keeping high-confidence fail
  *   without reimplementing the entire spec.
  */
@@ -63,7 +63,7 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const FIELD_NAMES = new Set([
     'name',
@@ -193,23 +193,21 @@ function runInPage(ctx) {
     if (isValidAutocomplete(raw)) continue;
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This autocomplete attribute value is not a valid autofill value.',
-      hint: 'Use "on"/"off", or a valid autofill token list (e.g. "shipping street-address", "cc-number").',
-      i18n: {
-        summaryKey: 'autocompleteValid_summary_fail',
-        hintKey: 'autocompleteValid_hint_fail',
-        params: { element: tag, value: raw }
-      },
-      data: {
-        details: { reasonCode: 'AUTOCOMPLETE_VALUE_INVALID', element: tag, value: raw }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This autocomplete attribute value is not a valid autofill value.',
+        hint: 'Use "on"/"off", or a valid autofill token list (e.g. "shipping street-address", "cc-number").',
+        i18n: {
+          summaryKey: 'autocompleteValid_summary_fail',
+          hintKey: 'autocompleteValid_hint_fail',
+          params: { element: tag, value: raw }
+        },
+        data: {
+          details: { reasonCode: 'AUTOCOMPLETE_VALUE_INVALID', element: tag, value: raw }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/avoid-inline-spacing.js

@@ -245,23 +245,21 @@ function runInPage(ctx) {
     if (!flagged.length) continue;
 
     const tag = el.tagName.toLowerCase();
-    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's inline style forces ${flagged.join(', ')} with !important below the WCAG text-spacing metric, so the user cannot raise it.`,
-      hint: 'Remove !important from line-height/letter-spacing/word-spacing in inline styles, or set a value that already meets the metric (line-height 1.5, letter-spacing 0.12em, word-spacing 0.16em).',
-      i18n: {
-        summaryKey: 'avoidInlineSpacing_summary_fail',
-        hintKey: 'avoidInlineSpacing_hint_fail',
-        params: { element: tag, properties: flagged.join(', ') }
-      },
-      data: {
-        details: { reasonCode: 'INLINE_SPACING_IMPORTANT', element: tag, properties: flagged }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This element's inline style forces ${flagged.join(', ')} with !important below the WCAG text-spacing metric, so the user cannot raise it.`,
+        hint: 'Remove !important from line-height/letter-spacing/word-spacing in inline styles, or set a value that already meets the metric (line-height 1.5, letter-spacing 0.12em, word-spacing 0.16em).',
+        i18n: {
+          summaryKey: 'avoidInlineSpacing_summary_fail',
+          hintKey: 'avoidInlineSpacing_hint_fail',
+          params: { element: tag, properties: flagged.join(', ') }
+        },
+        data: {
+          details: { reasonCode: 'INLINE_SPACING_IMPORTANT', element: tag, properties: flagged }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {