@surea11y/core 1.7.0 → 1.8.1

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

@@ -24,18 +24,22 @@
  *     offscreen positioning do NOT exempt text, per ACT's own failed
  *     examples for both, only actual non-rendering does.
  * @expectation
- *   The lang value matches a valid BCP47 language-tag syntax. WCAG 3.1.2
- *   (Language of Parts) requires that when a passage's language differs
- *   from the page's default, it is identified programmatically. An
- *   invalid tag fails to identify a real language at all.
+ *   The primary language subtag of the lang value (the part before the
+ *   first hyphen) is a registered language subtag, as ACT de46e4 requires.
+ *   WCAG 3.1.2 (Language of Parts)
+ *   requires that when a passage's language differs from the page's
+ *   default, it is identified programmatically. A tag whose primary subtag
+ *   is unknown fails to identify a real language at all; a malformed later
+ *   subtag (lang="en-US_x") still identifies English and passes here, since
+ *   it is a markup validity error rather than a missing language.
  * @implementation-notes
  * - Distinct, atomic decision from html-lang-attr-present (that
  *   rule covers the root <html> element only, for SC 3.1.1); this rule
  *   covers every other element, for SC 3.1.2.
- * - Same minimal BCP47 *syntax* check as html-lang-attr-present (primary
- *   subtag + optional subtags), not IANA Language Subtag Registry
- *   validation, same documented scope limitation (syntactically
- *   well-formed but unregistered tags like "xx-ZZ" are not flagged).
+ * - Same primary-subtag check as html-lang-attr-present: the shared
+ *   helper checks the subtag's shape and that the IANA Language Subtag
+ *   Registry lists it, so unregistered tags such as "xx-ZZ", "eng" or
+ *   "qaa" fail. Later subtags (region, script, variants) are not checked.
  */
 
 const id = 'valid-lang';
@@ -72,7 +76,8 @@ function runInPage(ctx) {
 
   // Shape alone accepts unregistered tags such as "eng" and "em-US", so the
   // primary subtag is checked against the IANA registry via the shared helper.
-  const BCP47_RE = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+  // Only the primary subtag is judged (see @expectation).
+  const BCP47_RE = /^[a-zA-Z]{2,3}$/;
   const isValidTag =
     typeof helpers.isValidLanguageTag === 'function'
       ? helpers.isValidLanguageTag
@@ -174,7 +179,7 @@ function runInPage(ctx) {
 
     // A whitespace-only value is in scope and has no primary language tag.
     const raw = String(rawAttr).trim();
-    if (isValidTag(raw)) continue;
+    if (isValidTag(raw.split('-')[0])) continue;
 
     const tag = el.tagName.toLowerCase();
 

package/src/checks/manual/area-alt-quality-manual.js

@@ -10,20 +10,33 @@
  * @sc 1.1.1
  * @type manual
  * @applicability
- *   Applies to <area> elements whose alt attribute is present and non-empty.
- *   The <area> must belong to a <map> that an <img usemap> actually
- *   references, and both that <img> and the <area> itself must be included
- *   in the accessibility tree; an <area> in an unused map is out of scope.
- *   role="presentation"/"none" takes an element out unless it is focusable.
+ *   Applies to <area> elements that get a non-empty text alternative from any
+ *   source: aria-labelledby (resolving to text), aria-label, alt or title.
+ *   The <area> must carry a non-empty href (otherwise it is not a hyperlink
+ *   at all per the HTML spec) and belong to a <map> that an <img usemap>
+ *   actually references; an <area> in an unused map is out of scope. The
+ *   referencing <img> must actually be rendered (hidden/display:none/
+ *   visibility exclude it; aria-hidden does not, since <area> is not a DOM
+ *   descendant of <img>), and the <area> itself must be eligible: hidden,
+ *   display:none and inert on the <area> or its <map> do not exclude it,
+ *   since neither generates a box and a real browser's image-map
+ *   hit-testing ignores all three there (verified against Chromium and
+ *   Firefox); only those mechanisms on a genuine ancestor of the whole
+ *   <img>+<map> pairing do. role="presentation"/"none" takes an element out
+ *   unless it is focusable.
  * @expectation
- *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
+ *   Human review is required to confirm that the provided text alternative is
+ *   accurate and appropriate. Each occurrence lists every source present
+ *   (data.details.sources), so the reviewer checks each one: a title or
+ *   aria-label that is not the name still reaches some users.
  */
 
 const id = 'area-alt-quality';
 
 const meta = {
-  title: '<area> alt text must be appropriate (manual review)',
-  description: 'Flags <area> elements with non-empty alt text for human review of appropriateness.',
+  title: '<area> text alternative must be appropriate (manual review)',
+  description:
+    'Flags <area> elements with a non-empty text alternative (alt, aria-label, aria-labelledby or title) for human review of appropriateness.',
   i18n: {
     titleKey: 'area_altQuality_title',
     descriptionKey: 'area_altQuality_description'
@@ -76,6 +89,11 @@ function runInPage(ctx) {
   const isAccTreeEligible =
     helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
+  const isDomVisibleEligible =
+    helpers && typeof helpers.isDomVisibleEligible === 'function'
+      ? helpers.isDomVisibleEligible
+      : null;
+
   const __accEligCache = new WeakMap();
   function accEligibleCached(node) {
     if (!isAccTreeEligible) return { eligible: true, reasons: [] };
@@ -93,6 +111,23 @@ function runInPage(ctx) {
     return r;
   }
 
+  const __domVisCache = new WeakMap();
+  function domVisibleCached(node) {
+    if (!isDomVisibleEligible) return { eligible: true, reasons: [] };
+    if (!node || typeof node !== 'object') return { eligible: true, reasons: [] };
+    const c = __domVisCache.get(node);
+    if (c) return c;
+    let r;
+    try {
+      r = isDomVisibleEligible(node, ctx, { visibilityMode: 'styleOnly', disableGeometry: true });
+    } catch {
+      r = { eligible: true, reasons: [] };
+    }
+    r = r && typeof r === 'object' ? r : { eligible: !!r, reasons: [] };
+    __domVisCache.set(node, r);
+    return r;
+  }
+
   // --- image-map semantics (rule-local; match automatic <area> applicability) ---
   function normUsemap(val) {
     try {
@@ -149,6 +184,53 @@ function runInPage(ctx) {
     return !focusable;
   }
 
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
+
+  // Every non-empty text-alternative source on the element, in accessible-name
+  // order: aria-labelledby (when it resolves to text), aria-label, alt, title.
+  // aria-labelledby wins over aria-label in the name, but a present aria-label
+  // is still listed, so each attribute present is asked about.
+  function collectTextAlternativeSources(el) {
+    const attr = (name) => {
+      try {
+        const v = el.getAttribute(name);
+        return v == null ? '' : String(v).trim();
+      } catch {
+        return '';
+      }
+    };
+    const sources = [];
+    let name = '';
+    let aria = null;
+    if (getAriaNameInfo) {
+      try {
+        aria = getAriaNameInfo(el, ctx);
+      } catch {
+        aria = null;
+      }
+    }
+    if (aria && aria.present && aria.value) {
+      name = String(aria.value).trim();
+      sources.push(aria.mechanism);
+      if (aria.mechanism === 'aria-labelledby' && attr('aria-label')) sources.push('aria-label');
+    } else if (!getAriaNameInfo && attr('aria-label')) {
+      name = attr('aria-label');
+      sources.push('aria-label');
+    }
+    const altText = attr('alt');
+    if (altText) {
+      sources.push('alt');
+      if (!name) name = altText;
+    }
+    const titleText = attr('title');
+    if (titleText) {
+      sources.push('title');
+      if (!name) name = titleText;
+    }
+    return { sources, name, alt: altText };
+  }
+
   const els = (() => {
     try {
       return Array.from((queryAllSmart ? queryAllSmart('area') : queryAll('area')) || []);
@@ -188,10 +270,18 @@ function runInPage(ctx) {
     }
     if (!img) continue;
 
-    // The referencing <img> must be eligible in the accessibility tree.
-    if (isAccTreeEligible) {
-      const imgElig = accEligibleCached(img);
-      if (imgElig && imgElig.eligible === false) continue;
+    // Without href an <area> is not a hyperlink at all per the HTML spec,
+    // so there is nothing here for this rule to review.
+    const hrefRaw = el.getAttribute('href');
+    if (!hrefRaw || !hrefRaw.trim()) continue;
+
+    // The referencing <img> must actually be rendered. <area> is not a DOM
+    // descendant of <img>, so aria-hidden on the img has nothing to
+    // propagate along; hidden/display:none/visibility on the img still
+    // excludes it, since that removes the box the hotspot depends on.
+    if (isDomVisibleEligible) {
+      const imgVis = domVisibleCached(img);
+      if (imgVis && imgVis.eligible === false) continue;
     }
 
     if (isAccTreeEligible) {
@@ -201,38 +291,30 @@ function runInPage(ctx) {
 
     if (isRolePresentationExcluded(el)) continue;
 
-    // Rule-specific applicability (only elements that already have a text alternative mechanism)
-    let alt;
-    try {
-      alt = el.getAttribute('alt');
-    } catch {
-      alt = null;
-    }
-    if (alt === null) continue;
-    if (String(alt).trim() === '') continue; // only non-empty alt is applicable here
+    // Applies when any text-alternative source gives the area a non-empty
+    // name; each present source is listed so the reviewer checks all of them.
+    const alt = collectTextAlternativeSources(el);
+    if (!alt.sources.length) continue;
 
     applicableCount += 1;
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+    const sourcesText = alt.sources.join(', ');
 
-    let altVal;
-    try {
-      altVal = String(el.getAttribute('alt') || '');
-    } catch {
-      altVal = '';
-    }
+    const details = { name: alt.name, sources: alt.sources.slice() };
+    if (alt.alt) details.alt = alt.alt;
 
     const baseOccurrence = {
-      summary: 'Review alt text on <area> for accuracy and appropriateness.',
-      hint: 'Ensure the alt text identifies the destination/action of the image map area in context.',
+      summary: `Review the text alternative of this <area> (${sourcesText}) for accuracy and appropriateness.`,
+      hint: 'Ensure each listed text alternative identifies the destination/action of the image map area in context.',
       i18n: {
         summaryKey: 'area_altQuality_summary_cantTell',
         hintKey: 'area_altQuality_hint_cantTell',
-        params: { element: (el.tagName || '').toLowerCase() }
+        params: { element: (el.tagName || '').toLowerCase(), sources: sourcesText }
       },
       data: {
         visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-        details: { alt: altVal.trim() } // optional but useful for manual review
+        details
       }
     };
 

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

@@ -165,8 +165,6 @@ function runInPage(ctx) {
         ? helpers.getTextAlternativeInfo
         : null;
 
-    const trim = (v) => (v == null ? '' : String(v)).trim();
-
     // Rule-specific applicability (only elements that already have a text alternative mechanism)
     let textAltInfo = null;
     if (getTextAlternativeInfo) {

package/src/checks/manual/css-focus-indicator-suppressed-manual.js

@@ -10,15 +10,19 @@
  * @sc 2.4.7
  * @applicability
  *   Elements in sequential focus navigation (tabbable and rendered) on a
- *   page whose accessible stylesheets contain at least one `:focus` or
- *   `:focus-visible` rule. With no focus rule anywhere, every element
- *   keeps the user agent's own indicator and there is nothing to check.
+ *   page whose accessible stylesheets contain at least one rule that
+ *   removes the outline. With no such rule anywhere, every element keeps
+ *   the user agent's own indicator and there is nothing to check.
  * @expectation
- *   No element is matched by a `:focus`/`:focus-visible` rule that removes
- *   the outline (`outline: none`, `outline: 0`, `outline-color:
- *   transparent`, ...) unless some other focus rule matching it draws a
- *   replacement: a border, box-shadow, background, color change, a
- *   positive outline of its own, or a `::before`/`::after` decoration.
+ *   No element is matched by a rule that removes the outline (`outline:
+ *   none`, `outline: 0`, `outline-color: transparent`, ...) unless some
+ *   focus rule matching it draws a replacement: a border, box-shadow,
+ *   background, color change, a positive outline of its own, or a
+ *   `::before`/`::after` decoration. The removing rule is either a
+ *   `:focus`/`:focus-visible` rule, or a rule with no state at all
+ *   (`a { outline: none }`, `* { outline: 0 }`): an author declaration
+ *   outranks the user agent's focus outline whatever its specificity, so
+ *   it removes the indicator in the focused state too (WCAG F78).
  * @implementation-notes
  * - Authored as `type: 'manual'` (cantTell-capped, never fail). CSS is
  *   only one of the ways a page can indicate focus: ACT oj04fd's own
@@ -54,7 +58,7 @@ const id = 'css-focus-indicator-suppressed';
 const meta = {
   title: 'Focus indicator must not be removed without a replacement',
   description:
-    'Flags elements in the tab order whose focus outline is removed by a :focus/:focus-visible rule with no replacement indicator (border, box-shadow, background, ...) in any other focus rule matching them.',
+    'Flags elements in the tab order whose focus outline is removed, by a :focus/:focus-visible rule or by a rule with no state such as a { outline: none }, with no replacement indicator (border, box-shadow, background, ...) in any focus rule matching them.',
   i18n: {
     titleKey: 'cssFocusIndicatorSuppressed_title',
     descriptionKey: 'cssFocusIndicatorSuppressed_description'
@@ -272,7 +276,16 @@ function runInPage(ctx) {
     if (!suppresses && !provides) return;
 
     for (const part of splitSelectorList(cssRule.selectorText)) {
-      if (!hasFocusPseudo(part)) continue;
+      if (!hasFocusPseudo(part)) {
+        // A rule with no focus state still applies while the element has
+        // focus, and an author declaration beats the user agent's focus
+        // outline. Other states (:hover, :active) never match the static
+        // element, so el.matches() leaves them out below.
+        if (suppresses && !hasPseudoElement(part)) {
+          suppressors.push({ selector: trim(part), base: trim(part) });
+        }
+        continue;
+      }
 
       const compounds = splitCompounds(part);
       let focusIndex = -1;

package/src/checks/manual/css-hidden-focus.js

@@ -13,11 +13,25 @@
  *   via CSS techniques that can leave them in the tab order.
  * @expectation
  *   No element should be tabbable while visually hidden (e.g., opacity:0, clipped, off-screen).
+ *   An element that CSS brings back into view when it takes focus is not
+ *   hidden while focused, and is not flagged: the usual skip-link pattern
+ *   (`.skip { position: absolute; left: -9999px } .skip:focus { left: 0 }`),
+ *   or a hiding rule that stops applying on focus
+ *   (`.visually-hidden-focusable:not(:focus) { clip: rect(0 0 0 0) }`).
  *
  * Notes:
  * - This rule intentionally targets CSS techniques that *can* keep an element focusable.
  * - Elements removed from rendering (display:none, visibility:hidden, [hidden]) are excluded.
  * - The rule uses deterministic heuristics (computed style parsing) and does not rely on layout geometry.
+ * - The focused style is worked out from the stylesheets, not by focusing the
+ *   element: a DOM emulator does not restyle `:focus`. Rules whose subject
+ *   carries `:focus`, `:focus-visible` or `:focus-within` (or an ancestor
+ *   carries `:focus-within`) are laid over the computed style in document
+ *   order; a rule written `:not(:focus)` / `:not(:focus-within)` /
+ *   `:not(:focus-visible)` has its declarations reset to their initial values.
+ *   Inline style outranks a stylesheet rule unless the rule is `!important`.
+ *   The overlay ignores specificity among the focus rules, and cross-origin
+ *   stylesheets cannot be read, so their focus rules are not seen.
  */
 
 const id = 'css-hidden-focus';
@@ -106,9 +120,14 @@ function runInPage(ctx) {
 
   // Returns deterministic "visually hidden but can remain focusable" hints.
   function getVisibilityHints(el) {
+    if (!el) return [];
+    return hintsFromStyle(getComputedStyleSafe(el));
+  }
+
+  // The same hints, read off any object carrying the computed-style fields
+  // used below (a CSSStyleDeclaration, or the focused-state overlay).
+  function hintsFromStyle(cs) {
     const out = [];
-    if (!el) return out;
-    const cs = getComputedStyleSafe(el);
 
     // opacity:0
     try {
@@ -187,6 +206,177 @@ function runInPage(ctx) {
     return uniq;
   }
 
+  // ---- Focused state, worked out from the stylesheets ----
+  const CSS_STYLE_RULE = 1;
+  const MAX_RULE_DEPTH = 10;
+  const FOCUS_STATE = /:focus(?:-visible|-within)?(?![-\w])/g;
+  const OWN_FOCUS_STATE = /:focus(?:-visible)?(?![-\w])/;
+  const NOT_FOCUS_STATE = /:not\(\s*:focus(?:-visible|-within)?\s*\)/g;
+  // Longhand name -> computed-style field read by hintsFromStyle.
+  const HINT_PROPS = {
+    opacity: 'opacity',
+    clip: 'clip',
+    'clip-path': 'clipPath',
+    width: 'width',
+    height: 'height',
+    overflow: 'overflow',
+    position: 'position',
+    left: 'left',
+    top: 'top',
+    'text-indent': 'textIndent'
+  };
+  const INITIAL_VALUES = {
+    opacity: '1',
+    clip: 'auto',
+    'clip-path': 'none',
+    width: 'auto',
+    height: 'auto',
+    overflow: 'visible',
+    position: 'static',
+    left: 'auto',
+    top: 'auto',
+    'text-indent': '0px'
+  };
+
+  function splitTopLevel(text, separators) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of String(text || '')) {
+      if (ch === '(') depth += 1;
+      if (ch === ')') depth = Math.max(0, depth - 1);
+      if (depth === 0 && separators.indexOf(ch) !== -1) {
+        parts.push(current);
+        current = '';
+        continue;
+      }
+      current += ch;
+    }
+    parts.push(current);
+    return parts.map(trim).filter(Boolean);
+  }
+
+  function hasPseudoElement(part) {
+    return /::[a-z-]+/i.test(part) || /:(before|after)\b/i.test(part);
+  }
+
+  // Selector for the element while it has focus, or null when the rule
+  // cannot apply to it then (`.a:focus .b`: .a cannot have focus while .b
+  // does).
+  function focusedBase(part) {
+    const compounds = splitTopLevel(part, [' ', '>', '+', '~']);
+    for (let i = 0; i < compounds.length - 1; i++) {
+      if (OWN_FOCUS_STATE.test(compounds[i])) return null;
+    }
+    // `:focus` standing alone in a compound becomes `*`, then every focus
+    // state is dropped: while focused, the element matches them all.
+    return trim(part.replace(/(^|[\s>+~(])(?=:focus)/g, '$1*').replace(FOCUS_STATE, '')) || '*';
+  }
+
+  let focusRules = null;
+  function getFocusRules() {
+    if (focusRules) return focusRules;
+    focusRules = [];
+    function consider(cssRule) {
+      const style = cssRule.style;
+      if (!style) return;
+      const props = Object.keys(HINT_PROPS).filter((p) => trim(style.getPropertyValue(p)));
+      if (!props.length) return;
+      for (const part of splitTopLevel(cssRule.selectorText, [','])) {
+        if (hasPseudoElement(part)) continue;
+        NOT_FOCUS_STATE.lastIndex = 0;
+        if (NOT_FOCUS_STATE.test(part)) {
+          const base = trim(part.replace(NOT_FOCUS_STATE, '')) || '*';
+          FOCUS_STATE.lastIndex = 0;
+          if (!FOCUS_STATE.test(base)) focusRules.push({ kind: 'notFocus', base, style, props });
+          continue;
+        }
+        FOCUS_STATE.lastIndex = 0;
+        if (!FOCUS_STATE.test(part)) continue;
+        const base = focusedBase(part);
+        if (base) focusRules.push({ kind: 'focus', base, style, props });
+      }
+    }
+    function walk(rules, depth) {
+      if (!rules || depth > MAX_RULE_DEPTH) return;
+      for (const cssRule of rules) {
+        if (!cssRule) continue;
+        if (cssRule.type === CSS_STYLE_RULE && cssRule.selectorText) {
+          consider(cssRule);
+          continue;
+        }
+        let nested;
+        try {
+          nested = cssRule.cssRules || null;
+        } catch {
+          nested = null;
+        }
+        if (nested) walk(nested, depth + 1);
+      }
+    }
+    try {
+      for (const sheet of document.styleSheets || []) {
+        let rules = null;
+        try {
+          rules = sheet && sheet.cssRules ? sheet.cssRules : null;
+        } catch {
+          continue; // cross-origin, not inspectable
+        }
+        if (rules) walk(rules, 0);
+      }
+    } catch {
+      // no readable stylesheets
+    }
+    return focusRules;
+  }
+
+  function matchesSafe(el, selector) {
+    try {
+      return typeof el.matches === 'function' && el.matches(selector);
+    } catch {
+      return false;
+    }
+  }
+
+  // The visibility hints the element would have while focused, or null when
+  // no focus-dependent rule reaches it.
+  function focusedVisibilityHints(el) {
+    const rules = getFocusRules().filter((r) => matchesSafe(el, r.base));
+    if (!rules.length) return null;
+    const inline = el.style || null;
+    const inlineHas = (p) => {
+      try {
+        return !!(inline && trim(inline.getPropertyValue(p)));
+      } catch {
+        return false;
+      }
+    };
+    const overlay = {};
+    for (const r of rules) {
+      if (r.kind !== 'notFocus') continue;
+      for (const p of r.props) if (!inlineHas(p)) overlay[p] = INITIAL_VALUES[p];
+    }
+    for (const r of rules) {
+      if (r.kind !== 'focus') continue;
+      for (const p of r.props) {
+        const important = String(r.style.getPropertyPriority(p) || '') === 'important';
+        if (inlineHas(p) && !important) continue;
+        overlay[p] = trim(r.style.getPropertyValue(p));
+      }
+    }
+    const cs = getComputedStyleSafe(el);
+    const focused = {};
+    for (const p of Object.keys(HINT_PROPS)) {
+      const field = HINT_PROPS[p];
+      focused[field] = Object.prototype.hasOwnProperty.call(overlay, p)
+        ? overlay[p]
+        : cs
+          ? cs[field]
+          : '';
+    }
+    return hintsFromStyle(focused);
+  }
+
   function getFocusableInfoSafe(el) {
     if (!getFocusableInfo) return null;
     try {
@@ -400,6 +590,10 @@ function runInPage(ctx) {
     const hints = getVisibilityHints(el);
     if (!hints.length) continue; // <-- applicability gate
 
+    // Brought back into view when it takes focus: visible while focused.
+    const whenFocused = focusedVisibilityHints(el);
+    if (whenFocused && !whenFocused.length) continue;
+
     const tagName = (() => {
       try {
         return lower(el.tagName || '');
@@ -419,17 +613,31 @@ function runInPage(ctx) {
 
     const baseOccurrence = {
       summary: downgradedToRedirectReview
-        ? `Focusable ${tagName} appears visually hidden but focus moved immediately to another element. Verify sentinel/focus-trap behavior.`
-        : `Focusable ${tagName} appears visually hidden (${hintsArr.join(',')}). Verify it becomes visible on keyboard focus.`,
+        ? `Focusable ${tagName} appears visually hidden, but focus moved immediately to another element. Verify sentinel/focus-trap behavior.`
+        : `Focusable ${tagName} is visually hidden (${hintsArr.join(',')}).`,
       hint: downgradedToRedirectReview
         ? 'Verify this is an intentional focus sentinel/focus-trap handoff and that keyboard users never remain on visually hidden focus targets.'
-        : 'Manually tab to the element and confirm a visible focus indicator and that the element is visible when focused. If it remains hidden while focused, fix CSS/JS so it becomes visible or is removed from the tab order until visible.',
+        : 'Make the element visible when it can receive keyboard focus, or remove it from the tab order until it is visible.',
       i18n: downgradedToRedirectReview
-        ? null
+        ? {
+            summaryKey: 'cssHidden_focus_summary_cantTell_redirect',
+            hintKey: 'cssHidden_focus_hint_cantTell_redirect',
+            params: { element: tagName }
+          }
         : {
             summaryKey: 'cssHidden_focus_summary_cantTell',
             hintKey: 'cssHidden_focus_hint_cantTell',
-            params: { element: tagName, visibilityHints: hintsArr.join(',') }
+            // One flag per technique, so each locale words them as sentences
+            // instead of showing the internal codes. visibilityHints stays
+            // for callers that read params directly.
+            params: {
+              element: tagName,
+              visibilityHints: hintsArr.join(','),
+              opacityZero: hintsArr.includes('opacityZero'),
+              offscreen: hintsArr.includes('offscreen'),
+              clipped: hintsArr.includes('clipped'),
+              zeroSizeOverflowHidden: hintsArr.includes('zeroSizeOverflowHidden')
+            }
           },
       data: {
         details: {