@surea11y/core 1.6.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
   "keywords": [
     "accessibility",
@@ -14,6 +14,7 @@
     "aria",
     "contrast",
     "sarif",
+    "junit",
     "zero-dependencies",
     "jsdom",
     "playwright",
@@ -30,7 +31,12 @@
     "./baseline": "./src/baseline.js",
     "./report": "./src/report.js",
     "./sarif": "./src/sarif.js",
+    "./junit": "./src/junit.js",
+    "./earl": "./src/earl.js",
+    "./en301549": "./src/en301549.js",
+    "./wcag": "./src/wcag.js",
     "./browser": "./surea11y.browser.js",
+    "./i18n/*": "./surea11y.i18n.*.js",
     "./package.json": "./package.json"
   },
   "author": "Jorge Rumoroso",
@@ -39,7 +45,7 @@
     "type": "git",
     "url": "git+https://github.com/SureA11y/core.git"
   },
-  "homepage": "https://github.com/SureA11y/core#readme",
+  "homepage": "https://surea11y.dev/",
   "bugs": {
     "url": "https://github.com/SureA11y/core/issues"
   },
@@ -55,6 +61,18 @@
     "src/baseline.js",
     "src/report.js",
     "src/sarif.js",
+    "src/junit.js",
+    "src/earl.js",
+    "src/en301549.js",
+    "src/coverage/en301549-map.js",
+    "src/coverage/standards.js",
+    "src/wcag.js",
+    "src/profile-kit.js",
+    "src/coverage/wcag-facets.js",
+    "src/coverage/wcag-version-map.js",
+    "profiles/index.js",
+    "profiles/*/*.js",
+    "profiles/*/rules/**/*.js",
     "src/checks/**/*.js",
     "surea11y.browser.js",
     "surea11y.i18n.*.js",
@@ -70,27 +88,37 @@
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "format": "prettier --write \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
-    "format:check": "prettier --check \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
+    "format": "prettier --write \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"profiles/**/*.js\" \"eslint.config.js\"",
+    "format:check": "prettier --check \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"profiles/**/*.js\" \"eslint.config.js\"",
     "build": "node scripts/build-core.js && node scripts/build-browser.js",
     "pretest": "playwright install chromium",
-    "test": "npm run format:check && npm run build && node scripts/run-tests.js",
-    "test:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js",
+    "test": "npm run lint && npm run format:check && npm run build && npm run validate:rules && node scripts/run-tests.js",
+    "test:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js --test-coverage-include=profiles/**/*.js",
     "test:contrast-helpers": "node tests/contrast-helpers.test.js",
     "helpers-perf-bench": "node --expose-gc scripts/dom-helpers-perf-bench.js",
     "engine-perf-bench": "node --expose-gc scripts/engine-perf-bench.js  --profileRules=true --iters=25 --top=15",
     "engine-perf-bench-transparent": "node --expose-gc scripts/engine-perf-bench.js --profileRules=true --top=15 --iters=25 --generated=contrastTransparent",
     "engine-perf-bench-opaque": "node --expose-gc scripts/engine-perf-bench.js --profileRules=true --top=15 --iters=25 --generated=contrastOpaque",
     "test:typography-helpers": "node tests/contrast-typography.test.js",
-    "coverage": "node scripts/generate-wcag-coverage.js --rulesDir src/checks",
-    "coverage:strict": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --strictFacets",
-    "coverage:check": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --check",
+    "coverage": "node scripts/generate-wcag-coverage.js",
+    "coverage:strict": "node scripts/generate-wcag-coverage.js --strictFacets",
+    "coverage:check": "node scripts/generate-wcag-coverage.js --check",
+    "finding-ids": "npm run build && node scripts/generate-finding-ids.js",
+    "finding-ids:release": "node scripts/freeze-finding-ids.js",
     "fixtures:index": "node scripts/generate-fixture-index.js",
+    "fixtures:check": "node scripts/generate-fixture-index.js --check",
+    "fixtures:markers": "npm run build && node scripts/generate-fixture-markers.js",
+    "fixtures:markers:check": "npm run build && node scripts/generate-fixture-markers.js --check",
     "docs:rule-catalog": "npm run build && node scripts/generate-rule-catalog.js",
-    "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic",
-    "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual",
-    "validate:rules": "npm run validate:automatic-rules && npm run validate:manual-rules",
+    "docs:rule-catalog:check": "npm run build && node scripts/generate-rule-catalog.js --check",
+    "rule-examples:coverage": "npm run build && node scripts/generate-rule-examples-coverage.js",
+    "rule-examples:coverage:check": "npm run build && node scripts/generate-rule-examples-coverage.js --check",
+    "docs:rule-review": "npm run build && node scripts/generate-rule-review.js",
+    "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic profiles/*/rules/automatic",
+    "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual profiles/*/rules/manual",
+    "validate:rules": "npm run build && node scripts/validate-all-rules.js",
     "i18n:new": "node scripts/i18n-scaffold.js",
+    "profile:new": "node scripts/profile-new.js",
     "i18n:sync": "node scripts/i18n-sync.js",
     "i18n:check": "node scripts/i18n-sync.js --check",
     "i18n:report": "node scripts/i18n-report.js"
@@ -98,6 +126,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "aria-query": "^5.3.2",
+    "esbuild": "^0.28.2",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.8.0",

package/profiles/index.js

@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * The profiles built into the engine, in registry order. Each one is a
+ * standard whose verdicts are not WCAG's renumbered (see profiles/README.md),
+ * and exports `standard`, its registry entry, which src/coverage/standards.js
+ * appends after the standards core keeps for itself, `rulesDir`, the folder
+ * of its own rules, which the build compiles with core's, and `i18nDir`, the
+ * folder of its dictionaries, which the build adds to core's.
+ */
+
+module.exports = [];

package/src/checks/automatic/area-alt-present.js

@@ -11,19 +11,30 @@
  * @applicability
  *   Applies to <area> elements that:
  *   1) are in a <map> that is referenced by an <img usemap>, AND
- *   2) the referencing <img> is eligible in the accessibility tree (best-effort), AND
- *   3) the <area> itself is eligible in the accessibility tree (with engine exceptions).
+ *   2) carry a non-empty href (an <area> with no href is not a hyperlink
+ *      at all per the HTML spec, and has nothing for this rule to name), AND
+ *   3) the referencing <img> is actually rendered (hidden/display:none/
+ *      visibility exclude it; aria-hidden does not, since <area> is not a
+ *      DOM descendant of <img>), AND
+ *   4) the <area> itself is eligible in the accessibility tree. hidden,
+ *      display:none and inert on the <area> or its <map> do not exclude it:
+ *      neither element generates a box, so 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.
  * @expectation
- *   Each applicable <area> element has an alt attribute.
- *   The alt attribute may be empty (alt="").
+ *   Each applicable <area> element has a non-empty accessible name, from alt,
+ *   aria-label/aria-labelledby, or title. An <area> in a used map is always
+ *   a link, so alt="" is not decorative here as it is on <img>: an empty alt
+ *   fails the same as a missing one unless another mechanism names it.
  */
 
 const id = 'area-alt-present';
 
 const meta = {
-  title: '<area> must have an alt attribute',
+  title: '<area> must have an accessible name',
   description:
-    'Checks that <area> elements provide an alt attribute to support a text alternative mechanism.',
+    'Checks that <area> elements have a non-empty accessible name via alt, aria-label/aria-labelledby, or title.',
   i18n: {
     titleKey: 'area_altPresent_title',
     descriptionKey: 'area_altPresent_description'
@@ -76,6 +87,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 getAriaNameInfo =
     helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
 
@@ -156,17 +172,32 @@ function runInPage(ctx) {
     const img = getReferencingImgForArea(el);
     if (!img) continue;
 
-    // 1) The referencing <img> must itself be eligible in the acc tree.
-    // This is the "visibility of map/area doesn't matter; the image does" policy.
-    if (isAccTreeEligible) {
-      const imgElig = (() => {
+    // 0b) Without href an <area> is not a hyperlink at all per the HTML
+    // spec -- just a shape with no associated action -- so it has nothing
+    // for this rule to name.
+    const hrefRaw = el.getAttribute('href');
+    if (!hrefRaw || !hrefRaw.trim()) continue;
+
+    // 1) The referencing <img> must actually be rendered: a used map's
+    // hotspots depend on the img's box, not its accessibility-tree
+    // exposure. <area> is not a DOM descendant of <img> -- only linked by
+    // the usemap IDREF -- so aria-hidden on the img has nothing to
+    // propagate along (verified against Chromium and Firefox: the area
+    // stays reachable regardless). hidden/display:none/visibility on the
+    // img itself still excludes it, since that removes the box the
+    // hotspot geometry depends on.
+    if (isDomVisibleEligible) {
+      const imgVis = (() => {
         try {
-          return isAccTreeEligible(img, ctx);
+          return isDomVisibleEligible(img, ctx, {
+            visibilityMode: 'styleOnly',
+            disableGeometry: true
+          });
         } catch {
           return { eligible: true, reasons: [] };
         }
       })();
-      if (imgElig && imgElig.eligible === false) continue;
+      if (imgVis && imgVis.eligible === false) continue;
     }
 
     // 2) The <area> itself must be eligible (aria-hidden/inert exceptions handled by helper).
@@ -184,8 +215,18 @@ function runInPage(ctx) {
     // From here: applicable
     applicableCount += 1;
 
-    const hasAlt = el.getAttribute('alt') !== null;
-    if (hasAlt) continue;
+    let altRaw;
+    try {
+      altRaw = el.getAttribute('alt');
+    } catch {
+      altRaw = null;
+    }
+    const hasAltAttr = altRaw !== null;
+    const altGivesName = hasAltAttr && String(altRaw).trim() !== '';
+    if (altGivesName) continue;
+
+    // alt="" is not decorative on an <area>: a used map's area is always a
+    // link, so it needs a name from elsewhere or it fails.
 
     // aria-label / aria-labelledby is also a valid, standards-recognized
     // text-alternative mechanism for <area> (HTML-AAM accessible name
@@ -201,8 +242,8 @@ function runInPage(ctx) {
     }
 
     // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source once alt is entirely absent. Same gap img-alt-present handles
-    // for <img title="..."> with no alt.
+    // source once alt gives no name (missing or empty). Same gap
+    // img-alt-present handles for <img title="..."> with no alt.
     const titleRaw = (() => {
       try {
         return el.getAttribute('title');
@@ -214,21 +255,36 @@ function runInPage(ctx) {
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
-    const baseOccurrence = {
-      // Leave selector/html empty so the engine can fill them from __node.
-      selector: '',
-      html: '',
-      summary: 'Missing alt attribute on &lt;area&gt;.',
-      hint: 'Add an alt attribute (use alt="" only for decorative areas).',
-      i18n: {
-        summaryKey: 'area_altPresent_summary_fail',
-        hintKey: 'area_altPresent_hint_fail',
-        params: { element: 'area' }
-      },
-      data: {
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    };
+    const baseOccurrence = hasAltAttr
+      ? {
+          // Leave selector/html empty so the engine can fill them from __node.
+          selector: '',
+          html: '',
+          summary: 'Empty alt attribute leaves &lt;area&gt; link with no accessible name.',
+          hint: 'Describe the link destination in alt, or add aria-label/aria-labelledby (an <area> cannot be decorative once its map is used).',
+          i18n: {
+            summaryKey: 'area_altPresent_summary_fail_empty',
+            hintKey: 'area_altPresent_hint_fail_empty',
+            params: { element: 'area' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+          }
+        }
+      : {
+          selector: '',
+          html: '',
+          summary: 'Missing alt attribute on &lt;area&gt;.',
+          hint: 'Add an alt attribute describing the link destination (an <area> cannot be decorative).',
+          i18n: {
+            summaryKey: 'area_altPresent_summary_fail',
+            hintKey: 'area_altPresent_hint_fail',
+            params: { element: 'area' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+          }
+        };
 
     if (helpers && typeof helpers.reportOccurrence === 'function') {
       occurrences.push(helpers.reportOccurrence(el, baseOccurrence));

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

@@ -934,6 +934,12 @@ function runInPage(ctx) {
               hintKey: 'ariaAllowedAttr_hint_cantTell',
               params: { attr: name, role }
             },
+            uncertainty: {
+              code: 'spec-only',
+              needed:
+                'Whether the deprecated attribute is still honoured by the assistive technology in use.',
+              evidence: { attribute: name, role, status: 'deprecated-for-role' }
+            },
             data: {
               details: { reasonCode: 'ARIA_ATTR_DEPRECATED', attr: name, role }
             }

package/src/checks/automatic/aria-allowed-role.js

@@ -6,8 +6,7 @@
  * @check aria-allowed-role
  * @atomic true
  * @summary Explicit role must be permitted by the ARIA-in-HTML spec for its host element
- * @standard WCAG 2.2
- * @sc 4.1.2
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with an explicit, valid, non-abstract role, where
  *   the host element/attribute combination has an asserted permitted-roles
@@ -16,7 +15,18 @@
  * @expectation
  *   The explicit role is one of the roles the ARIA-in-HTML specification
  *   permits for that host element.
+ *   Reported at CANTTELL rather than FAIL: ARIA-in-HTML's permitted-roles
+ *   table is an author conformance requirement with no ACT rule and no WCAG
+ *   mapping in any source. The role the author asked for is still the role
+ *   assistive technology exposes, so whether the combination harms anyone
+ *   depends on the widget, not on the table.
  * @implementation-notes
+ * - Not WCAG-normative. ARIA-in-HTML's permitted-roles table is an author
+ *   conformance requirement of that specification; no ACT rule covers it and
+ *   no source maps it to a Success Criterion, so the rule reports the
+ *   violation without claiming a criterion is failed. Deterministic all the
+ *   same, so it stays `type: 'automatic'` and keeps deciding rather than
+ *   deferring to a reviewer -- see docs/RULE_TAXONOMY.md 1.1.
  * - Scoped to elements present in ALLOWED_ROLES_BY_ELEMENT;
  *   elements without an asserted constraint are treated as "no constraint"
  *   (not flagged) rather than guessed at, see that table's header comment.
@@ -36,22 +46,14 @@ const meta = {
     descriptionKey: 'ariaAllowedRole_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
-  wcagSc: ['4.1.2'],
-  normativeMappings: [
-    {
-      standard: 'WCAG',
-      version: '2.2',
-      requirement: '4.1.2',
-      title: 'Name, Role, Value',
-      conformanceLevel: 'A'
-    }
-  ],
+  tags: ['best-practice', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: [],
+  normativeMappings: [],
   defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
-  coverage: { facetsBySc: { '4.1.2': ['aria-role-allowed-for-element'] } }
+  coverage: {}
 };
 
 function runInPage(ctx) {
@@ -93,6 +95,16 @@ function runInPage(ctx) {
           hintKey: 'ariaAllowedRole_hint_fail',
           params: { role, element: tag }
         },
+        uncertainty: {
+          code: 'spec-only',
+          needed: 'Whether the role misstates this element to assistive technology in practice.',
+          evidence: {
+            role,
+            element: tag,
+            source: 'ARIA in HTML permitted-roles table',
+            wcagSc: []
+          }
+        },
         data: {
           details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
         }
@@ -103,15 +115,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 || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-braille-equivalent.js

@@ -23,6 +23,11 @@
  *   Using either braille-specific attribute as the ONLY naming mechanism
  *   leaves non-braille assistive technology (most screen readers, voice
  *   control, etc.) with no accessible name/role description at all.
+ *   Reported at CANTTELL rather than FAIL: aria-brailleroledescription
+ *   without aria-roledescription reaches no user at all, and a missing
+ *   accessible name is the naming rules' decision for the roles that require
+ *   one. The braille attribute being unpaired is worth surfacing, but it is
+ *   not itself a criterion failing.
  * @implementation-notes
  * - `aria-braillelabel`/`aria-brailleroledescription` do not participate
  *   in the standard accessible-name computation, so
@@ -52,7 +57,7 @@ const meta = {
       conformanceLevel: 'A'
     }
   ],
-  defaultSeverity: 'serious',
+  defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
@@ -108,13 +113,28 @@ function runInPage(ctx) {
         nameInfo && typeof nameInfo.value === 'string' ? nameInfo.value : ''
       );
       const name = programmaticName || getConservativeSubtreeText(el);
-      if (!name) missing.push({ attr: 'aria-braillelabel', requires: 'an accessible name' });
+      if (!name)
+        missing.push({
+          attr: 'aria-braillelabel',
+          requires: 'an accessible name',
+          messageKey: 'label',
+          summary:
+            'This element has aria-braillelabel but no accessible name, its non-braille equivalent.',
+          hint: 'aria-braillelabel is a Braille-specific supplement, not a replacement, so also give the element an accessible name (for example visible text, aria-label or aria-labelledby).'
+        });
     }
 
     if (brailleRoleDesc) {
       const roleDesc = trim(el.getAttribute('aria-roledescription'));
       if (!roleDesc)
-        missing.push({ attr: 'aria-brailleroledescription', requires: 'aria-roledescription' });
+        missing.push({
+          attr: 'aria-brailleroledescription',
+          requires: 'aria-roledescription',
+          messageKey: 'roleDescription',
+          summary:
+            'This element has aria-brailleroledescription but not aria-roledescription, its non-braille equivalent.',
+          hint: 'aria-brailleroledescription is a Braille-specific supplement, not a replacement, so also provide aria-roledescription.'
+        });
     }
 
     if (!missing.length) continue;
@@ -124,12 +144,21 @@ function runInPage(ctx) {
     for (const m of missing) {
       occurrences.push(
         helpers.reportOccurrence(el, {
-          summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
-          hint: `${m.attr} is a Braille-specific supplement, not a replacement, so also provide ${m.requires}.`,
+          // One message per missing equivalent rather than a shared template:
+          // `requires` is English prose for the label case, and interpolating
+          // it put English into every translated sentence.
+          summary: m.summary,
+          hint: m.hint,
           i18n: {
-            summaryKey: 'ariaBrailleEquivalent_summary_fail',
-            hintKey: 'ariaBrailleEquivalent_hint_fail',
-            params: { element: tag, attr: m.attr, requires: m.requires }
+            summaryKey: `ariaBrailleEquivalent_summary_fail_${m.messageKey}`,
+            hintKey: `ariaBrailleEquivalent_hint_fail_${m.messageKey}`,
+            params: { element: tag, attr: m.attr }
+          },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether any user reaches this attribute, given no braille equivalent is exposed.',
+            evidence: { element: tag, attribute: m.attr, requires: m.requires }
           },
           data: {
             details: {
@@ -146,15 +175,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(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -17,6 +17,11 @@
  *   An element with `aria-errormessage` but `aria-invalid` absent or
  *   `"false"` silently drops the error message from the accessibility
  *   tree, authors almost always intend it to be exposed.
+ *   Reported at CANTTELL rather than FAIL: aria-errormessage is only
+ *   exposed once aria-invalid is set, so the reference is currently inert.
+ *   Whether that costs the user anything depends on whether the message is
+ *   conveyed some other way (visible text next to the field, aria-describedby),
+ *   which static markup does not settle.
  * @implementation-notes
  * - This is narrow: the broader space is a table of many
  *   attribute/condition pairs. This rule implements only the one pairing
@@ -52,7 +57,7 @@ const meta = {
       conformanceLevel: 'A'
     }
   ],
-  defaultSeverity: 'serious',
+  defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
@@ -98,6 +103,11 @@ function runInPage(ctx) {
           hintKey: 'ariaConditionalAttr_hint_fail',
           params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
         },
+        uncertainty: {
+          code: 'spec-only',
+          needed: 'Whether the field is ever in an invalid state that should expose this message.',
+          evidence: { element: tag, ariaInvalid: invalidValue || null }
+        },
         data: {
           details: {
             reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
@@ -111,15 +121,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(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-deprecated-role.js

@@ -161,6 +161,12 @@ function runInPage(ctx) {
             hintKey: guidance.key,
             params: { role }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether this user-agent-reserved role misleads the assistive technology in use.',
+            evidence: { role, ariaStatus: 'discouraged-for-authors' }
+          },
           data: {
             details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance: guidance.text }
           }
@@ -178,6 +184,12 @@ function runInPage(ctx) {
             hintKey: guidance.key,
             params: { role }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether the deprecated role is still honoured, and what it should be replaced with.',
+            evidence: { role, ariaStatus: 'deprecated' }
+          },
           data: {
             details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance: guidance.text }
           }

package/src/checks/automatic/aria-hidden-body.js

@@ -33,7 +33,7 @@ const meta = {
     descriptionKey: 'ariaHiddenBody_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag131', 'wcag412', 'structure', 'atomic', 'automatic'],
+  tags: ['wcag2a', 'wcag131', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
   wcagSc: ['1.3.1', '4.1.2'],
   normativeMappings: [
     {