@surea11y/core 1.6.0 → 1.8.0

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

@@ -25,8 +25,17 @@
  * - Within one declaration block, importance outranks order, so the effective
  *   declaration is the last `!important` one for that property.
  * - ACT 78fd32/24afc2/9e45ec additionally require the text to contain a soft
- *   wrap break, which cannot be determined without layout. Not implemented, so
- *   a forced value on text that never wraps is still reported.
+ *   wrap break, which layout would settle and this cannot. Three shapes
+ *   establish that no wrap is possible -- text not allowed to wrap, a
+ *   fixed-width element inside a horizontally scrolling ancestor, and text
+ *   with no break opportunity (one word, no CJK characters) -- and those are
+ *   reported for review rather than failed.
+ * - Text short enough to fit on one line may never wrap either, so it is also
+ *   reviewed rather than failed. "Short" is an estimate made without layout:
+ *   the text's length at half an em per character (a full em for CJK and
+ *   other wide characters) fits within 320 CSS pixels, the narrowest width
+ *   WCAG 1.4.10 asks content to reflow to. Longer text is treated as wrapping
+ *   and fails.
  */
 
 const id = 'avoid-inline-spacing';
@@ -83,6 +92,9 @@ function runInPage(ctx) {
 
   const occurrences = [];
   let applicableCount = 0;
+  const undecided = [];
+  const noWrap = [];
+  const shortText = [];
 
   // Within one declaration block, importance wins over order, so the last
   // important declaration is the one that takes effect. Passed Example 5 of ACT
@@ -148,6 +160,62 @@ function runInPage(ctx) {
     return null;
   }
 
+  // ACT 78fd32/24afc2/9e45ec apply only to text that contains a soft wrap
+  // break. Layout settles that; short of it, two shapes establish that no wrap
+  // can happen -- text not allowed to wrap, and a fixed-width element inside a
+  // horizontally scrolling ancestor, which narrowing the viewport cannot reach.
+  function cannotSoftWrap(el) {
+    const cs = computedStyleOf(el);
+    const whiteSpace = cs ? String(cs.whiteSpace || '').toLowerCase() : '';
+    if (whiteSpace === 'nowrap' || whiteSpace === 'pre') return true;
+
+    if (!/(^|;)\s*width\s*:/i.test(String(el.getAttribute('style') || ''))) return false;
+
+    const chain =
+      helpers && typeof helpers.ancestorsIncludingSelf === 'function'
+        ? helpers.ancestorsIncludingSelf(el)
+        : null;
+    const ancestors = chain || [];
+    if (!chain) {
+      for (let a = el.parentElement; a; a = a.parentElement) ancestors.push(a);
+    }
+
+    for (const ancestor of ancestors) {
+      if (ancestor === el) continue;
+      const acs = computedStyleOf(ancestor);
+      if (!acs) continue;
+      const overflowX = String(acs.overflowX || acs.overflow || '').toLowerCase();
+      if (overflowX === 'scroll' || overflowX === 'auto') return true;
+    }
+    return false;
+  }
+
+  // Text with no break opportunity cannot take a soft wrap break: a single
+  // word of a script that separates words with spaces. CJK text can break
+  // between most characters, so it never counts as unbreakable here.
+  const WIDE_CHAR =
+    /[\u1100-\u115f\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/;
+  function blockText(el) {
+    return String(el.textContent || '')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  function hasNoBreakOpportunity(text) {
+    return !!text && !/\s/.test(text) && !WIDE_CHAR.test(text);
+  }
+
+  // Whether the text may fit on one line at the narrowest width WCAG 1.4.10
+  // asks content to reflow to (320 CSS pixels), estimated without layout at
+  // half an em per character and a full em per wide character.
+  const REFLOW_WIDTH_PX = 320;
+  function mayFitOnOneLine(el, text) {
+    const fontSize = fontSizeOf(computedStyleOf(el)) || 16;
+    let ems = 0;
+    for (const ch of text) ems += WIDE_CHAR.test(ch) ? 1 : 0.5;
+    return ems * fontSize <= REFLOW_WIDTH_PX;
+  }
+
   // ACT scopes these rules to text visible on screen, and text pushed far off
   // canvas is the one hidden shape the shared eligibility check keeps eligible.
   function isOffScreen(el) {
@@ -228,6 +296,7 @@ function runInPage(ctx) {
     if (!hasVisibleTextChild(el) || !isRendered(el) || isOffScreen(el)) continue;
 
     const flagged = [];
+    const unresolved = [];
     let inScope = false;
     for (const prop of SPACING_PROPS) {
       const decl = effectiveDeclaration(raw, prop);
@@ -235,14 +304,33 @@ function runInPage(ctx) {
       if (INHERITED_KEYWORDS.indexOf(decl.value.toLowerCase()) !== -1) continue;
       inScope = true;
       const ratio = spacingRatio(el, prop, decl.value);
-      // Unresolvable spacing is left alone: this engine reserves fail for
-      // high-confidence violations.
-      if (ratio === null) continue;
+      // Not flagged, since `fail` needs a measured value -- but recorded, so
+      // the element does not fall through to `pass` unmeasured.
+      if (ratio === null) {
+        unresolved.push(prop);
+        continue;
+      }
       if (ratio < MIN_RATIO[prop]) flagged.push(prop);
     }
 
     if (inScope) applicableCount += 1;
-    if (!flagged.length) continue;
+    if (!flagged.length) {
+      if (unresolved.length) undecided.push({ el, props: unresolved.slice() });
+      continue;
+    }
+
+    // A forced value on text that cannot wrap is outside these ACT rules'
+    // applicability, and whether it wraps is not decidable here, so it is
+    // reported for review rather than failed.
+    const text = blockText(el);
+    if (cannotSoftWrap(el) || hasNoBreakOpportunity(text)) {
+      noWrap.push({ el, props: flagged.slice() });
+      continue;
+    }
+    if (mayFitOnOneLine(el, text)) {
+      shortText.push({ el, props: flagged.slice() });
+      continue;
+    }
 
     const tag = el.tagName.toLowerCase();
 
@@ -265,15 +353,119 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+
+  const cantTellOccurrences = noWrap
+    .map(({ el, props }) =>
+      helpers.reportOccurrence(el, {
+        occurrenceOutcome: 'cantTell',
+        summary: `This element's inline style forces ${props.join(', ')} with !important, but its text does not appear able to wrap, so the text-spacing criterion may not apply to it.`,
+        hint: 'Confirm whether this text ever wraps. If it cannot, the criterion does not apply; if it can, remove !important or set a value that already meets the metric.',
+        i18n: {
+          summaryKey: 'avoidInlineSpacing_summary_cantTell_noSoftWrap',
+          hintKey: 'avoidInlineSpacing_hint_cantTell_noSoftWrap',
+          params: {
+            element: (el.tagName || '').toLowerCase(),
+            properties: props.join(', ')
+          }
+        },
+        uncertainty: {
+          code: 'not-computable',
+          needed: 'Whether this text ever contains a soft wrap break, which needs layout.',
+          evidence: {
+            element: (el.tagName || '').toLowerCase(),
+            properties: props,
+            reasonCode: 'INLINE_SPACING_NO_SOFT_WRAP'
+          }
+        },
+        data: {
+          details: {
+            reasonCode: 'INLINE_SPACING_NO_SOFT_WRAP',
+            element: (el.tagName || '').toLowerCase(),
+            properties: props
+          }
+        }
+      })
+    )
+    .concat(
+      shortText.map(({ el, props }) =>
+        helpers.reportOccurrence(el, {
+          occurrenceOutcome: 'cantTell',
+          summary: `This element's inline style forces ${props.join(', ')} with !important, but its text is short enough to fit on one line, so it may never wrap and the text-spacing criterion may not apply to it.`,
+          hint: 'Confirm whether this text wraps at narrow widths. If it always fits on one line, the criterion does not apply; if it can wrap, remove !important or set a value that already meets the metric.',
+          i18n: {
+            summaryKey: 'avoidInlineSpacing_summary_cantTell_shortText',
+            hintKey: 'avoidInlineSpacing_hint_cantTell_shortText',
+            params: {
+              element: (el.tagName || '').toLowerCase(),
+              properties: props.join(', ')
+            }
+          },
+          uncertainty: {
+            code: 'not-computable',
+            needed: 'Whether this text ever contains a soft wrap break, which needs layout.',
+            evidence: {
+              element: (el.tagName || '').toLowerCase(),
+              properties: props,
+              reasonCode: 'INLINE_SPACING_SHORT_TEXT'
+            }
+          },
+          data: {
+            details: {
+              reasonCode: 'INLINE_SPACING_SHORT_TEXT',
+              element: (el.tagName || '').toLowerCase(),
+              properties: props
+            }
+          }
+        })
+      )
+    )
+    .concat(
+      undecided.map(({ el, props }) =>
+        helpers.reportOccurrence(el, {
+          occurrenceOutcome: 'cantTell',
+          summary: `This element's inline style sets ${props.join(', ')} with !important, but the value could not be resolved, so whether it meets the WCAG text-spacing metric could not be determined.`,
+          hint: 'Check this value by hand against the metric (line-height 1.5, letter-spacing 0.12em, word-spacing 0.16em), or express it in a unit the engine can resolve against the element’s computed font size.',
+          i18n: {
+            summaryKey: 'avoidInlineSpacing_summary_cantTell',
+            hintKey: 'avoidInlineSpacing_hint_cantTell',
+            params: {
+              element: (el.tagName || '').toLowerCase(),
+              properties: props.join(', ')
+            }
+          },
+          uncertainty: {
+            code: 'not-computable',
+            needed: 'A resolved value for the spacing declarations marked !important.',
+            evidence: {
+              element: (el.tagName || '').toLowerCase(),
+              properties: props,
+              reasonCode: 'INLINE_SPACING_NOT_RESOLVABLE'
+            }
+          },
+          data: {
+            details: {
+              reasonCode: 'INLINE_SPACING_NOT_RESOLVABLE',
+              element: (el.tagName || '').toLowerCase(),
+              properties: props
+            }
+          }
+        })
+      )
+    );
+
+  // See helpers.resolveTieredOutcome (src/core/dom-helpers.js): a fail-tier
+  // finding never silently discards the cantTell-tier findings from the same
+  // run, so an undecided element survives a failure elsewhere on the page.
+  const resolved = helpers.resolveTieredOutcome(
+    occurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return {
+    ruleId: rule.ruleId,
+    ...resolved,
+    ...(resolved.outcome === 'cantTell' ? { confidence: 'low' } : null)
+  };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -22,7 +22,8 @@
  *   "Submit"/"Reset" default, which is why those two are never nameless.
  *   Failing both, a button whose role is name-from-content falls back to its
  *   subtree text, counting each descendant's own name (an <img alt>,
- *   aria-label or title) rather than only text nodes.
+ *   aria-label, an <svg>'s <title> child, or title) rather than only text
+ *   nodes.
  */
 
 // NOTE: Repo ruleId contract requires ENGINE_TAG prefix in the rule id.

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

@@ -12,7 +12,16 @@
  *   Applies to <canvas> elements included in the accessibility tree.
  *   Hidden elements are excluded whether or not they are focusable.
  * @expectation
- *   Each applicable <canvas> provides a text alternative via fallback content or an accessible name.
+ *   Each applicable <canvas> provides a text alternative via fallback content
+ *   or an accessible name, with two exceptions:
+ *   - role="img" (first role token) makes the canvas's children
+ *     presentational and its name comes from the author only, so fallback
+ *     content does not count: aria-labelledby, aria-label or title must name
+ *     it.
+ *   - role="none"/"presentation" marks the canvas decorative, and it passes.
+ *     The role is ignored (presentational role conflict) when the canvas is
+ *     focusable or carries aria-label/aria-labelledby, and the canvas is then
+ *     judged like any other.
  */
 
 const id = 'canvas-text-alternative-present';
@@ -85,6 +94,64 @@ function runInPage(ctx) {
       ? helpers.getTextAlternativeInfo
       : null;
 
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
+
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+
+  function attrText(el, name) {
+    try {
+      const v = el.getAttribute(name);
+      return v == null ? '' : String(v).trim();
+    } catch {
+      return '';
+    }
+  }
+
+  function firstRoleToken(el) {
+    const raw = attrText(el, 'role').toLowerCase();
+    return raw ? raw.split(/\s+/)[0] : '';
+  }
+
+  // ARIA's presentational role conflict: a focusable element, or one with a
+  // global naming attribute, keeps its native role.
+  function isPresentationHonoured(el) {
+    if (attrText(el, 'aria-label') || attrText(el, 'aria-labelledby')) return false;
+    if (getFocusableInfo) {
+      try {
+        const fi = getFocusableInfo(el, ctx);
+        if (fi && fi.focusable) return false;
+      } catch {}
+    } else if (attrText(el, 'tabindex') !== '') {
+      return false;
+    }
+    return true;
+  }
+
+  // role="img": the name comes from the author (aria-labelledby, aria-label,
+  // then title), never from the children.
+  function getRoleImgNameInfo(el) {
+    let aria = null;
+    if (getAriaNameInfo) {
+      try {
+        aria = getAriaNameInfo(el, ctx);
+      } catch {
+        aria = null;
+      }
+    }
+    if (aria && aria.present && aria.value) {
+      return { present: true, value: aria.value, mechanism: aria.mechanism };
+    }
+    if (!getAriaNameInfo) {
+      const label = attrText(el, 'aria-label');
+      if (label) return { present: true, value: label, mechanism: 'aria-label' };
+    }
+    const title = attrText(el, 'title');
+    if (title) return { present: true, value: title, mechanism: 'title' };
+    return { present: false, value: '', mechanism: 'none' };
+  }
+
   const canvases = (() => {
     try {
       return Array.from((queryAllSmart ? queryAllSmart('canvas') : queryAll('canvas')) || []);
@@ -118,16 +185,25 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
+    const role = firstRoleToken(el);
+
+    // A decorative canvas needs no text alternative.
+    if ((role === 'none' || role === 'presentation') && isPresentationHonoured(el)) continue;
+
+    const isRoleImg = role === 'img';
+
     // Expectation: must provide a text alternative.
-    const ti = getTextAlternativeInfo
-      ? (() => {
-          try {
-            return getTextAlternativeInfo(el, ctx);
-          } catch {
-            return null;
-          }
-        })()
-      : null;
+    const ti = isRoleImg
+      ? getRoleImgNameInfo(el)
+      : getTextAlternativeInfo
+        ? (() => {
+            try {
+              return getTextAlternativeInfo(el, ctx);
+            } catch {
+              return null;
+            }
+          })()
+        : null;
 
     const hasTextAlt = !!(ti && ti.present);
 
@@ -135,14 +211,29 @@ function runInPage(ctx) {
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
+    const messages = isRoleImg
+      ? {
+          summary:
+            'This <canvas role="img"> has no accessible name; with role="img" its fallback content does not count.',
+          hint: 'Name it with aria-label or aria-labelledby, or remove role="img" so that its fallback content can serve as the text alternative.',
+          summaryKey: 'canvas_textAltPresent_summary_fail_roleImg',
+          hintKey: 'canvas_textAltPresent_hint_fail_roleImg'
+        }
+      : {
+          summary: 'Missing text alternative for <canvas>.',
+          hint: 'Provide fallback text inside <canvas> or an accessible name (e.g., aria-label/aria-labelledby).',
+          summaryKey: 'canvas_textAltPresent_summary_fail',
+          hintKey: 'canvas_textAltPresent_hint_fail'
+        };
+
     const baseOccurrence = {
       selector: '',
       html: '',
-      summary: 'Missing text alternative for <canvas>.',
-      hint: 'Provide fallback text inside <canvas> or an accessible name (e.g., aria-label/aria-labelledby).',
+      summary: messages.summary,
+      hint: messages.hint,
       i18n: {
-        summaryKey: 'canvas_textAltPresent_summary_fail',
-        hintKey: 'canvas_textAltPresent_hint_fail',
+        summaryKey: messages.summaryKey,
+        hintKey: messages.hintKey,
         params: { element: 'canvas' }
       },
       data: {

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

@@ -20,6 +20,9 @@
  *   accepted: text sitting inside a custom combobox widget is not reliably
  *   exposed as its name. On a labelable element (<input role="combobox">) an
  *   associated <label> counts as well.
+ *   On a text-like <input> or a <textarea>, the placeholder counts last
+ *   (HTML-AAM's final name source): a placeholder-only label is a 3.3.2
+ *   question, not a missing name.
  */
 
 const id = 'combobox-name-present';
@@ -70,21 +73,6 @@ function runInPage(ctx) {
     }
   }
 
-  function buildLabelForMap(doc) {
-    const map = new Map(); // id -> label element (first)
-    try {
-      const labels = doc && doc.getElementsByTagName ? doc.getElementsByTagName('label') : [];
-      for (let i = 0; i < labels.length; i += 1) {
-        const lab = labels[i];
-        if (!lab || !lab.getAttribute) continue;
-        const f = normalizeWs(lab.getAttribute('for'));
-        if (!f) continue;
-        if (!map.has(f)) map.set(f, lab);
-      }
-    } catch {}
-    return map;
-  }
-
   function getConservativeSubtreeText(document, container) {
     // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
@@ -172,45 +160,30 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);
 
-  // Precompute label[for] map for combobox elements that are labelable
-  // native form controls (e.g. <input role="combobox">).
-  const labelForMap = buildLabelForMap(document);
-
+  // Delegates to the shared, spec-guarded lookup (dom-helpers.js's
+  // getAssociatedLabelElements): a <label> -- wrapping or via `for` --
+  // only ever associates with a genuinely labelable element, so this
+  // correctly returns nothing for role-only widgets a <label> merely sits
+  // next to, and the real thing for a labelable element like
+  // <input role="combobox">.
   function getNativeLabelText(el) {
+    if (!helpers || typeof helpers.getAssociatedLabelElements !== 'function') return '';
+    let labels;
     try {
-      if ('labels' in el && el.labels && el.labels.length) {
-        const parts = [];
-        const max = Math.min(4, el.labels.length);
-        for (let i = 0; i < max; i += 1) {
-          const lab = el.labels[i];
-          const t = lab ? getLabelText(lab) : '';
-          if (t) parts.push(t);
-        }
-        const joined = normalizeWs(parts.join(' '));
-        if (joined) return joined;
-      }
-    } catch {}
-    try {
-      if (el.closest) {
-        const wrap = el.closest('label');
-        if (wrap) {
-          const t = getLabelText(wrap);
-          if (t) return t;
-        }
-      }
-    } catch {}
-    try {
-      const idAttr = getAttr(el, 'id');
-      if (idAttr && labelForMap.has(idAttr)) {
-        const lab = labelForMap.get(idAttr);
-        const t = lab ? getLabelText(lab) : '';
-        if (t) return t;
-      }
-    } catch {}
-    return '';
+      labels = helpers.getAssociatedLabelElements(el) || [];
+    } catch {
+      labels = [];
+    }
+    const parts = [];
+    const max = Math.min(4, labels.length);
+    for (let i = 0; i < max; i += 1) {
+      const t = getLabelText(labels[i]);
+      if (t) parts.push(t);
+    }
+    return normalizeWs(parts.join(' '));
   }
 
-  function evaluate(el, controlType) {
+  function evaluate(el) {
     const ariaLabel = getAttr(el, 'aria-label');
     if (ariaLabel) return { ok: true, method: 'aria-label' };
 
@@ -224,6 +197,16 @@ function runInPage(ctx) {
     const lab = getNativeLabelText(el);
     if (lab) return { ok: true, method: 'label' };
 
+    // HTML-AAM's last name source for a text-like <input> or a <textarea>,
+    // after title: the placeholder. A placeholder-only label is a 3.3.2
+    // question, not a missing name.
+    if (helpers.getNativeHostNameInfo) {
+      try {
+        const host = helpers.getNativeHostNameInfo(el, ctx, { placeholder: true });
+        if (host && host.present) return { ok: true, method: host.mechanism };
+      } catch {}
+    }
+
     // role="combobox" is name-from-author-only per WAI-ARIA: it must NOT
     // fall back to subtree content. Visible text near/inside a custom
     // combobox widget is not reliably exposed as its accessible name.
@@ -239,7 +222,7 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    const res = evaluate(el, 'combobox');
+    const res = evaluate(el);
     if (res.ok) continue;
 
     const eligInfo = getEligibilityInfo

package/src/checks/automatic/contrast-computable.js

@@ -115,6 +115,25 @@ function runInPage(ctx) {
 
   const seenFailEls = new Set();
 
+  // Defined inside runInPage, which is serialized into the page and cannot
+  // reach module scope. English fallbacks for the dictionary keys below.
+  const CANT_TELL_HINT_KEYS = {
+    background: 'contrastComputable_hint_cantTell_background',
+    effect: 'contrastComputable_hint_cantTell_effect',
+    rootNotOpaque: 'contrastComputable_hint_cantTell_rootNotOpaque',
+    generic: 'contrast_hint_cantTell_manual'
+  };
+  const CANT_TELL_HINTS = {
+    background:
+      'Measure the contrast by hand on the rendered page, where the background behind the text gives the least contrast. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA).',
+    effect:
+      'Measure the contrast by hand on the rendered page with the effect applied, since the declared CSS colors are not what ends up on screen. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA).',
+    rootNotOpaque:
+      'No element behind this text, up to the root, has a fully opaque background, so the color it sits on depends on where the page is displayed. Set an opaque background color on html or body, or measure the contrast against the background the page is actually shown on.',
+    generic:
+      "Measure this text's contrast by hand on the rendered page. Normal text needs at least 4.5:1 and large text 3:1 (7:1 and 4.5:1 for AAA)."
+  };
+
   function pushCantTellOccurrence(el, reasonCode, extraDetails) {
     try {
       if (!el || seenFailEls.has(el)) return;
@@ -151,6 +170,18 @@ function runInPage(ctx) {
         summaryKey = 'contrastComputable_cantTell_rootNotOpaque';
       else if (rc === 'TEXT_SHADOW') summaryKey = 'contrastComputable_cantTell_textShadow';
 
+      // Every cantTell leaves a person to measure the contrast, so each one
+      // says how, grouped by what blocked the calculation.
+      let hintKind = 'generic';
+      if (rc === 'BACKGROUND_IMAGE_OR_GRADIENT') hintKind = 'background';
+      else if (
+        rc === 'MIX_BLEND_MODE' ||
+        rc === 'BACKGROUND_FILTER_OR_BACKDROP_FILTER' ||
+        rc === 'TEXT_SHADOW'
+      )
+        hintKind = 'effect';
+      else if (rc === 'BACKGROUND_NOT_OPAQUE_AT_ROOT') hintKind = 'rootNotOpaque';
+
       const details = Object.assign(
         { reasonCode: rc },
         extraDetails && typeof extraDetails === 'object' ? extraDetails : {}
@@ -160,10 +191,10 @@ function runInPage(ctx) {
         selector: '',
         html: '',
         summary: '',
-        hint: '',
+        hint: CANT_TELL_HINTS[hintKind],
         i18n: {
           summaryKey,
-          hintKey: '',
+          hintKey: CANT_TELL_HINT_KEYS[hintKind],
           params: Object.assign(
             { reasonCode: rc },
             details && typeof details === 'object'
@@ -178,6 +209,16 @@ function runInPage(ctx) {
               : {}
           )
         },
+        uncertainty: {
+          code: 'not-computable',
+          needed: 'A contrast ratio for this text, which this page composition blocks.',
+          evidence: {
+            reasonCode: rc,
+            blockerProperty: details.blockerProperty || null,
+            blockerValue: details.blockerValue || null,
+            backgroundAlpha: details.backgroundAlpha === undefined ? null : details.backgroundAlpha
+          }
+        },
         data: { details }
       };
 
@@ -364,11 +405,11 @@ function runInPage(ctx) {
           {
             selector: '',
             summary: '',
-            hint: '',
+            hint: CANT_TELL_HINTS.generic,
             html: '',
             i18n: {
               summaryKey: 'contrastComputable_cantTell_engineFailure',
-              hintKey: '',
+              hintKey: CANT_TELL_HINT_KEYS.generic,
               params: { reasonCode: 'ENGINE_EXCEPTION' }
             },
             data: { details: { reasonCode: 'ENGINE_EXCEPTION' } }