@surea11y/core 1.6.0 → 1.7.0

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

@@ -7,7 +7,7 @@
  * @atomic true
  * @summary Roles that require a specific ancestor/owner context role must have one
  * @standard WCAG 2.2
- * @sc 4.1.2
+ * @sc 1.3.1
  * @applicability
  *   Applies to elements with an explicit, valid, non-abstract role that is
  *   also one of the roles with a documented, non-empty "required context
@@ -43,6 +43,16 @@
  *   aria-required-children/aria-prohibited-children, applied for
  *   consistency; an element that isn't currently exposed to the
  *   accessibility tree is skipped (notApplicable), not failed.
+ * - Also honors WAI-ARIA's escape hatch for a widget script has not
+ *   finished assembling: "When a widget is missing required owned elements due to
+ *   script execution or loading, authors MUST mark a containing element
+ *   with aria-busy equal to true." aria-required-children reads that from
+ *   the container it is checking; read from the item's side it is an
+ *   ancestor, so the walk looks up rather than at the element itself, and
+ *   only the exact string "true" counts. It also outranks the
+ *   roleless-generic-parent rule below, since aria-busy is itself a global
+ *   ARIA attribute and would otherwise block the context search and fail
+ *   the very markup the spec says to mark.
  */
 
 const id = 'aria-required-parent';
@@ -56,14 +66,14 @@ const meta = {
     descriptionKey: 'ariaRequiredParent_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
-  wcagSc: ['4.1.2'],
+  tags: ['wcag2a', 'wcag131', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['1.3.1'],
   normativeMappings: [
     {
       standard: 'WCAG',
       version: '2.2',
-      requirement: '4.1.2',
-      title: 'Name, Role, Value',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
       conformanceLevel: 'A'
     }
   ],
@@ -71,7 +81,7 @@ const meta = {
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'medium',
-  coverage: { facetsBySc: { '4.1.2': ['aria-role-required-context-parent'] } }
+  coverage: { facetsBySc: { '1.3.1': ['aria-role-required-context-parent'] } }
 };
 
 function runInPage(ctx) {
@@ -183,6 +193,21 @@ function runInPage(ctx) {
           return n && n.parentElement ? n.parentElement : null;
         };
 
+  // The escape hatch marks the container being assembled, not the item inside
+  // it, so this walks up instead of reading the element's own attribute.
+  function hasBusyAncestor(el) {
+    let cur = getComposedParent(el);
+    let guard = 0;
+    while (cur && guard++ < 200) {
+      if (cur.nodeType === 1 && cur.getAttribute) {
+        const v = cur.getAttribute('aria-busy');
+        if (v != null && String(v).trim().toLowerCase() === 'true') return true;
+      }
+      cur = getComposedParent(cur);
+    }
+    return false;
+  }
+
   function hasAcceptableAncestorContext(el, acceptableRoles, ownRole) {
     const allowsGroup = acceptableRoles.has('group');
     let cur = getComposedParent(el);
@@ -252,6 +277,7 @@ function runInPage(ctx) {
     if (!requiredContext || !requiredContext.length) continue; // no entry, or explicitly unconstrained
 
     if (!isEligibleAcc(el)) continue; // not currently exposed to the accessibility tree
+    if (hasBusyAncestor(el)) continue; // author has signaled transient incompleteness per WAI-ARIA
 
     applicableCount += 1;
 

package/src/checks/automatic/aria-role-name-present.js

@@ -45,7 +45,7 @@ const meta = {
     descriptionKey: 'ariaRoleNamePresent_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'navigation', 'atomic', 'automatic', 'name'],
+  tags: ['wcag2a', 'wcag412', 'aria', 'navigation', 'atomic', 'automatic', 'name'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
     {

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

@@ -11,16 +11,15 @@
  * @applicability
  *   Applies to any element with a non-empty role="" attribute in the composed DOM.
  * @expectation
- *   The role attribute's first token (the role actually used by assistive technology;
- *   later space-separated tokens are author-supplied fallbacks and are not evaluated
- *   here) must be a real WAI-ARIA role name, and must not be an abstract role
- *   (abstract roles exist only for the specification's own role taxonomy and must
- *   never be used directly in markup).
- * @implementation-notes
- * - Unlike this engine's accessible-name rules, ARIA validity is a static markup
- *   property independent of current visibility/eligibility, so this rule does not
- *   gate on isAccTreeEligible: an invalid role is a defect whether or not the
- *   element happens to be hidden right now.
+ *   At least one role token names a concrete, non-abstract ARIA role.
+ *   Graded by what the element falls back to when none does:
+ *   - FAIL on a roleless host (div, span, custom element), which is left
+ *     exposed as generic, so the role the author meant reaches no one.
+ *   - CANTTELL where the element has a native role (a <button>, <nav>,
+ *     <a href>), which the accessibility tree keeps using. ACT 674b10 lists
+ *     4.1.2 as a secondary requirement only, "satisfied through the implicit
+ *     role," so the bad token is worth reporting but is not itself the
+ *     criterion failing.
  */
 
 const id = 'aria-roles-valid';
@@ -64,7 +63,8 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart('[role]')
     : helpers.queryAll('[role]');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   // Programmatically hidden per the ACT glossary: display:none, visibility not
@@ -121,8 +121,42 @@ function runInPage(ctx) {
     const isKnown = tokens.some((t) => ariaHelpers.isKnownRole(t));
     const reasonCode = !isKnown ? 'ARIA_ROLE_INVALID' : 'ARIA_ROLE_ABSTRACT';
 
-    occurrences.push(
+    // An unusable role token leaves the element on its native role, when it
+    // has one: ACT 674b10 lists 4.1.2 as only a secondary requirement for
+    // exactly that reason. A roleless host (div, span, custom element) has
+    // nothing to fall back to and is exposed as generic instead.
+    const nativeRole =
+      typeof ariaHelpers.getNativeRoleForElement === 'function'
+        ? ariaHelpers.getNativeRoleForElement(el) || ''
+        : '';
+
+    if (nativeRole) {
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          occurrenceOutcome: 'cantTell',
+          summary: `The role attribute value is not usable, so this element is still exposed as its native role="${nativeRole}".`,
+          hint: 'Fix or remove the role token; assistive technology is using the native role in the meantime.',
+          i18n: {
+            summaryKey: 'ariaRolesValid_summary_cantTell',
+            hintKey: 'ariaRolesValid_hint_cantTell',
+            params: { role, nativeRole }
+          },
+          uncertainty: {
+            code: 'spec-only',
+            needed: 'Whether the native role this element falls back to is the one intended.',
+            evidence: { role, nativeRole, fallbackExposed: true }
+          },
+          data: {
+            details: { reasonCode, role, nativeRole }
+          }
+        })
+      );
+      continue;
+    }
+
+    failOccurrences.push(
       helpers.reportOccurrence(el, {
+        occurrenceOutcome: 'fail',
         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.',
@@ -146,15 +180,12 @@ 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 || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'serious'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -38,6 +38,19 @@
  *   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).
+ * - aria-controls is never a fail on a target that doesn't resolve, and
+ *   this is the one place the rule reports two tiers. The controlled
+ *   element is routinely built when the widget opens, so a static scan
+ *   that cannot find it has not found a defect; it has found markup it
+ *   cannot decide. A collapsed widget (aria-expanded="false" or
+ *   aria-selected="false") passes outright, since the absence is exactly
+ *   what that state means; anything else is a `cantTell` for human
+ *   review. Every other idref/idref-list attribute keeps its fail: a
+ *   dangling aria-labelledby or aria-owns names content that was supposed
+ *   to be there already.
+ * - Two tiers in one run means helpers.resolveTieredOutcome decides the
+ *   aggregate: a real fail elsewhere on the page still reports fail, and
+ *   the aria-controls occurrences ride along rather than being dropped.
  */
 
 const id = 'aria-valid-attr-value';
@@ -79,13 +92,15 @@ function runInPage(ctx) {
 
   const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('*') : helpers.queryAll('*');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   for (const el of nodes) {
     if (!el || !el.attributes || !el.getAttribute) continue;
 
     let invalid = null;
+    let review = null;
     const attrs = el.attributes;
     for (let i = 0; i < attrs.length; i++) {
       const name = String(attrs[i].name || '').toLowerCase();
@@ -95,21 +110,26 @@ function runInPage(ctx) {
       applicableCount += 1;
 
       const rawValue = el.getAttribute(name);
-      const result = ariaHelpers.validateAttrValue(name, rawValue);
-      if (!result.valid) {
+      const result = ariaHelpers.validateAttrValue(name, rawValue, el);
+      if (result.valid) continue;
+
+      const item = {
+        name,
+        value: rawValue == null ? '' : String(rawValue),
+        reason: result.reason
+      };
+
+      if (result.review) {
+        if (!review) review = [];
+        review.push(item);
+      } else {
         if (!invalid) invalid = [];
-        invalid.push({
-          name,
-          value: rawValue == null ? '' : String(rawValue),
-          reason: result.reason
-        });
+        invalid.push(item);
       }
     }
 
-    if (!invalid || !invalid.length) continue;
-
-    for (const item of invalid) {
-      occurrences.push(
+    for (const item of invalid || []) {
+      failOccurrences.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).',
@@ -129,20 +149,53 @@ function runInPage(ctx) {
         })
       );
     }
+
+    for (const item of review || []) {
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'No element with this id exists right now, so the engine cannot tell whether this reference is wrong.',
+          hint: 'Confirm the controlled element is created when the widget opens; if it never exists, remove or correct the reference.',
+          i18n: {
+            summaryKey: 'ariaValidAttrValue_summary_cantTell_idref',
+            hintKey: 'ariaValidAttrValue_hint_cantTell_idref',
+            params: { attr: item.name, value: item.value }
+          },
+          uncertainty: {
+            code: 'runtime-dependent',
+            needed: 'Whether the widget creates the referenced element when it opens.',
+            evidence: {
+              attribute: item.name,
+              referencedId: item.value,
+              resolvedAtScanTime: false
+            }
+          },
+          data: {
+            details: {
+              reasonCode: 'ARIA_ATTR_VALUE_TARGET_ABSENT',
+              attr: item.name,
+              value: item.value,
+              valueReason: item.reason
+            }
+          }
+        })
+      );
+    }
   }
 
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+
+  // See helpers.resolveTieredOutcome's own header comment
+  // (src/core/dom-helpers.js): a fail-tier finding never silently discards
+  // cantTell-tier findings from the same run.
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'serious'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -16,6 +16,12 @@
  *   specification (catches typos / made-up attribute names, which are
  *   silently ignored by assistive technology and therefore a real,
  *   deterministic defect).
+ *   Reported at CANTTELL rather than FAIL: an aria-* attribute the spec
+ *   does not define is inert, so nothing about the element's exposed name,
+ *   role or value changes because it is there. Where the author meant a real
+ *   attribute and the element ends up without a name, that absence is the
+ *   naming rules' decision, not this one's. ACT 5f99a7 maps 1.3.1/4.1.2 as
+ *   secondary requirements, "less strict" than the rule itself.
  * @implementation-notes
  * - Distinct from aria-valid-attr-value (which validates the VALUE
  *   of a recognized attribute), this rule only validates the attribute
@@ -96,6 +102,12 @@ function runInPage(ctx) {
             hintKey: 'ariaValidAttr_hint_fail',
             params: { attr: name }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether the misspelling cost the element a name or state it has no other source for.',
+            evidence: { attribute: name, definedInAria: false, exposedEffect: 'none' }
+          },
           data: {
             details: { reasonCode: 'ARIA_ATTR_INVALID', attr: name }
           }
@@ -107,15 +119,8 @@ 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 || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome([], occurrences, rule.defaultSeverity || 'serious');
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -25,8 +25,12 @@
  * - 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. Two shapes do
+ *   establish that no wrap is possible -- text not allowed to wrap, and a
+ *   fixed-width element inside a horizontally scrolling ancestor -- and those
+ *   are reported for review rather than failed. Anything else is treated as
+ *   wrapping, so a forced value on text that never wraps for some other reason
+ *   is still reported.
  */
 
 const id = 'avoid-inline-spacing';
@@ -83,6 +87,8 @@ function runInPage(ctx) {
 
   const occurrences = [];
   let applicableCount = 0;
+  const undecided = [];
+  const noWrap = [];
 
   // 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 +154,36 @@ 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;
+  }
+
   // 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 +264,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 +272,28 @@ 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.
+    if (cannotSoftWrap(el)) {
+      noWrap.push({ el, props: flagged.slice() });
+      continue;
+    }
 
     const tag = el.tagName.toLowerCase();
 
@@ -273,6 +324,82 @@ function runInPage(ctx) {
       occurrences
     };
   }
+  if (noWrap.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'moderate',
+      confidence: 'low',
+      occurrences: noWrap.map(({ el, props }) =>
+        helpers.reportOccurrence(el, {
+          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
+            }
+          }
+        })
+      )
+    };
+  }
+  if (undecided.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'moderate',
+      confidence: 'low',
+      occurrences: undecided.map(({ el, props }) =>
+        helpers.reportOccurrence(el, {
+          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
+            }
+          }
+        })
+      )
+    };
+  }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 

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

@@ -178,6 +178,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 }
       };
 

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

@@ -216,6 +216,17 @@ function runInPage(ctx) {
 
       const det = details && typeof details === 'object' ? details : { reasonCode: 'UNKNOWN' };
 
+      // The background is the only input this rule can fail to resolve; every other
+      // reason code here describes a ratio it did compute.
+      const uncertainty =
+        det.reasonCode === 'BACKGROUND_NOT_COMPUTABLE'
+          ? {
+              code: 'not-computable',
+              needed: 'The effective background colour behind this text.',
+              evidence: { reasonCode: det.reasonCode, foreground: det.fg || null }
+            }
+          : null;
+
       const occBase = {
         selector: '',
         html: '',
@@ -226,6 +237,7 @@ function runInPage(ctx) {
           hintKey: '',
           params: params && typeof params === 'object' ? params : {}
         },
+        ...(uncertainty ? { uncertainty } : {}),
         data: { details: det }
       };
 

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

@@ -213,6 +213,17 @@ function runInPage(ctx) {
 
       const det = details && typeof details === 'object' ? details : { reasonCode: 'UNKNOWN' };
 
+      // The background is the only input this rule can fail to resolve; every other
+      // reason code here describes a ratio it did compute.
+      const uncertainty =
+        det.reasonCode === 'BACKGROUND_NOT_COMPUTABLE'
+          ? {
+              code: 'not-computable',
+              needed: 'The effective background colour behind this text.',
+              evidence: { reasonCode: det.reasonCode, foreground: det.fg || null }
+            }
+          : null;
+
       const occBase = {
         selector: '',
         html: '',
@@ -223,6 +234,7 @@ function runInPage(ctx) {
           hintKey: '',
           params: params && typeof params === 'object' ? params : {}
         },
+        ...(uncertainty ? { uncertainty } : {}),
         data: { details: det }
       };