core(a11y): adjust weights and document a consistent approach to determining weights

Ben Gibson · Ben Gibson · commit 816c5e3daa5a · 2025-08-06T17:05:35.000-07:00
diff --git a/core/audits/accessibility/aria-allowed-role.js b/core/audits/accessibility/aria-allowed-role.js
@@ -35,6 +35,7 @@ class ARIAAllowedRole extends AxeAudit {
       title: str_(UIStrings.title),
       failureTitle: str_(UIStrings.failureTitle),
       description: str_(UIStrings.description),
+      scoreDisplayMode: AxeAudit.SCORING_MODES.INFORMATIVE,
       requiredArtifacts: ['Accessibility'],
     };
   }
diff --git a/core/audits/accessibility/image-redundant-alt.js b/core/audits/accessibility/image-redundant-alt.js
@@ -36,6 +36,7 @@ class ImageRedundantAlt extends AxeAudit {
       title: str_(UIStrings.title),
       failureTitle: str_(UIStrings.failureTitle),
       description: str_(UIStrings.description),
+      scoreDisplayMode: AxeAudit.SCORING_MODES.INFORMATIVE,
       requiredArtifacts: ['Accessibility'],
     };
   }
diff --git a/core/audits/accessibility/landmark-one-main.js b/core/audits/accessibility/landmark-one-main.js
@@ -34,7 +34,6 @@ class LandmarkOneMain extends AxeAudit {
       title: str_(UIStrings.title),
       failureTitle: str_(UIStrings.failureTitle),
       description: str_(UIStrings.description),
-      scoreDisplayMode: AxeAudit.SCORING_MODES.INFORMATIVE,
       requiredArtifacts: ['Accessibility'],
     };
   }
diff --git a/core/audits/accessibility/table-duplicate-name.js b/core/audits/accessibility/table-duplicate-name.js
@@ -35,6 +35,7 @@ class TableDuplicateName extends AxeAudit {
       title: str_(UIStrings.title),
       failureTitle: str_(UIStrings.failureTitle),
       description: str_(UIStrings.description),
+      scoreDisplayMode: AxeAudit.SCORING_MODES.INFORMATIVE,
       requiredArtifacts: ['Accessibility'],
     };
   }
diff --git a/core/config/default-config.js b/core/config/default-config.js
@@ -496,68 +496,86 @@ const defaultConfig = {
       description: str_(UIStrings.a11yCategoryDescription),
       manualDescription: str_(UIStrings.a11yCategoryManualDescription),
       supportedModes: ['navigation', 'snapshot'],
-      // Audit weights are meant to match the aXe scoring system of
-      // minor, moderate, serious, and critical.
-      // See the audits listed at dequeuniversity.com/rules/axe/4.7.
-      // Click on an audit and check the right hand column to see its severity.
+      // Audit weights weights are derived from the axe-core "Impact",
+      // with adjustments based on axe-core "Tags":
+      //
+      // ┌────────────┬───────────────────────────────────────────────┐
+      // │ Impact     │ Weight Based on Tags                          │
+      // │            ├──────────────┬─────────────────┬──────────────┤
+      // │            │  wcag A+AA   │  best-practice  │ experimental │
+      // │            │ (ex: wcag2aa)│ (w/o wcag tag)  │              │
+      // ├────────────┼──────────────┼─────────────────┼──────────────┤
+      // │ Minor      │       1      │        0        │      0       │
+      // │ Moderate   │       3      │        3        │      0       │
+      // │ Serious    │       7      │        7        │      0       │
+      // │ Critical   │      10      │       10        │      0       │
+      // └────────────┴──────────────┴─────────────────┴──────────────┘
+      //
+      // Notes:
+      //  • Experimental rules always have weight 0
+      //  • Best practice rules only affect scores when tagged with wcagA+AA
+      //    and are moderate, serious, or critical.
+      //
+      // To find the latest axe-core Impact and Tag values:
+      //   1. Browse to https://dequeuniversity.com/rules/axe/html.
+      //   2. Click on the latest rule set (ex: https://dequeuniversity.com/rules/axe/html/4.10)
+      //   3. Review the tables
       auditRefs: [
-        {id: 'accesskeys', weight: 7, group: 'a11y-navigation'},
-        {id: 'aria-allowed-attr', weight: 10, group: 'a11y-aria'},
-        {id: 'aria-allowed-role', weight: 1, group: 'a11y-aria'},
-        {id: 'aria-command-name', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-conditional-attr', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-deprecated-role', weight: 1, group: 'a11y-aria'},
-        {id: 'aria-dialog-name', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-hidden-body', weight: 10, group: 'a11y-aria'},
-        {id: 'aria-hidden-focus', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-input-field-name', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-meter-name', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-progressbar-name', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-prohibited-attr', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-required-attr', weight: 10, group: 'a11y-aria'},
-        {id: 'aria-required-children', weight: 10, group: 'a11y-aria'},
-        {id: 'aria-required-parent', weight: 10, group: 'a11y-aria'},
-        {id: 'aria-roles', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-text', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-toggle-field-name', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-tooltip-name', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-treeitem-name', weight: 7, group: 'a11y-aria'},
-        {id: 'aria-valid-attr-value', weight: 10, group: 'a11y-aria'},
-        {id: 'aria-valid-attr', weight: 10, group: 'a11y-aria'},
-        {id: 'button-name', weight: 10, group: 'a11y-names-labels'},
-        {id: 'bypass', weight: 7, group: 'a11y-navigation'},
-        {id: 'color-contrast', weight: 7, group: 'a11y-color-contrast'},
-        {id: 'definition-list', weight: 7, group: 'a11y-tables-lists'},
-        {id: 'dlitem', weight: 7, group: 'a11y-tables-lists'},
-        {id: 'document-title', weight: 7, group: 'a11y-names-labels'},
-        {id: 'duplicate-id-aria', weight: 10, group: 'a11y-aria'},
-        {id: 'form-field-multiple-labels', weight: 3, group: 'a11y-names-labels'},
-        {id: 'frame-title', weight: 7, group: 'a11y-names-labels'},
-        {id: 'heading-order', weight: 3, group: 'a11y-navigation'},
-        {id: 'html-has-lang', weight: 7, group: 'a11y-language'},
-        {id: 'html-lang-valid', weight: 7, group: 'a11y-language'},
-        {id: 'html-xml-lang-mismatch', weight: 3, group: 'a11y-language'},
-        {id: 'image-alt', weight: 10, group: 'a11y-names-labels'},
-        {id: 'image-redundant-alt', weight: 1, group: 'a11y-names-labels'},
-        {id: 'input-button-name', weight: 10, group: 'a11y-names-labels'},
-        {id: 'input-image-alt', weight: 10, group: 'a11y-names-labels'},
-        {id: 'label', weight: 7, group: 'a11y-names-labels'},
-        {id: 'link-in-text-block', weight: 7, group: 'a11y-color-contrast'},
-        {id: 'link-name', weight: 7, group: 'a11y-names-labels'},
-        {id: 'list', weight: 7, group: 'a11y-tables-lists'},
-        {id: 'listitem', weight: 7, group: 'a11y-tables-lists'},
-        {id: 'meta-refresh', weight: 10, group: 'a11y-best-practices'},
-        {id: 'meta-viewport', weight: 10, group: 'a11y-best-practices'},
-        {id: 'object-alt', weight: 7, group: 'a11y-names-labels'},
-        {id: 'select-name', weight: 7, group: 'a11y-names-labels'},
-        {id: 'skip-link', weight: 3, group: 'a11y-names-labels'},
-        {id: 'tabindex', weight: 7, group: 'a11y-navigation'},
-        {id: 'table-duplicate-name', weight: 1, group: 'a11y-tables-lists'},
-        {id: 'target-size', weight: 7, group: 'a11y-best-practices'},
-        {id: 'td-headers-attr', weight: 7, group: 'a11y-tables-lists'},
-        {id: 'th-has-data-cells', weight: 7, group: 'a11y-tables-lists'},
-        {id: 'valid-lang', weight: 7, group: 'a11y-language'},
-        {id: 'video-caption', weight: 10, group: 'a11y-audio-video'},
+        {id: 'accesskeys', weight: 7, group: 'a11y-navigation'}, // Serious, best-practice
+        {id: 'aria-allowed-attr', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'aria-command-name', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-conditional-attr', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-deprecated-role', weight: 1, group: 'a11y-aria'}, // Minor, wcag2a
+        {id: 'aria-dialog-name', weight: 7, group: 'a11y-aria'}, // Serious, best-practice
+        {id: 'aria-hidden-body', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'aria-hidden-focus', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-input-field-name', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-meter-name', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-progressbar-name', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-prohibited-attr', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-required-attr', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'aria-required-children', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'aria-required-parent', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'aria-roles', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'aria-text', weight: 7, group: 'a11y-aria'}, // Serious, best-practice
+        {id: 'aria-toggle-field-name', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-tooltip-name', weight: 7, group: 'a11y-aria'}, // Serious, wcag2a
+        {id: 'aria-treeitem-name', weight: 7, group: 'a11y-aria'}, // Serious, best-practice
+        {id: 'aria-valid-attr-value', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'aria-valid-attr', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'button-name', weight: 10, group: 'a11y-names-labels'}, // Critical, wcag2a
+        {id: 'bypass', weight: 7, group: 'a11y-navigation'}, // Serious, wcag2a
+        {id: 'color-contrast', weight: 7, group: 'a11y-color-contrast'}, // Serious, wcag2aa
+        {id: 'definition-list', weight: 7, group: 'a11y-tables-lists'}, // Serious, wcag2a
+        {id: 'dlitem', weight: 7, group: 'a11y-tables-lists'}, // Serious, wcag2a
+        {id: 'document-title', weight: 7, group: 'a11y-names-labels'}, // Serious, wcag2a
+        {id: 'duplicate-id-aria', weight: 10, group: 'a11y-aria'}, // Critical, wcag2a
+        {id: 'form-field-multiple-labels', weight: 3, group: 'a11y-names-labels'}, // Moderate, wcag2a
+        {id: 'frame-title', weight: 7, group: 'a11y-names-labels'}, // Serious, wcag2a
+        {id: 'heading-order', weight: 3, group: 'a11y-navigation'}, // Moderate, best-practice
+        {id: 'html-has-lang', weight: 7, group: 'a11y-language'}, // Serious, wcag2a
+        {id: 'html-lang-valid', weight: 7, group: 'a11y-language'}, // Serious, wcag2a
+        {id: 'html-xml-lang-mismatch', weight: 3, group: 'a11y-language'}, // Moderate, wcag2a
+        {id: 'image-alt', weight: 10, group: 'a11y-names-labels'}, // Critical, wcag2a
+        {id: 'input-button-name', weight: 10, group: 'a11y-names-labels'}, // Critical, wcag2a
+        {id: 'input-image-alt', weight: 10, group: 'a11y-names-labels'}, // Critical, wcag2a
+        {id: 'label', weight: 10, group: 'a11y-names-labels'}, // Critical, wcag2a
+        {id: 'link-in-text-block', weight: 7, group: 'a11y-color-contrast'}, // Serious, wcag2a
+        {id: 'link-name', weight: 7, group: 'a11y-names-labels'}, // Serious, wcag2a
+        {id: 'list', weight: 7, group: 'a11y-tables-lists'}, // Serious, wcag2a
+        {id: 'listitem', weight: 7, group: 'a11y-tables-lists'}, // Serious, wcag2a
+        {id: 'meta-refresh', weight: 10, group: 'a11y-best-practices'}, // Critical, wcag2a
+        {id: 'meta-viewport', weight: 10, group: 'a11y-best-practices'}, // Critical, wcag2aa
+        {id: 'object-alt', weight: 7, group: 'a11y-names-labels'}, // Serious, wcag2a
+        {id: 'select-name', weight: 10, group: 'a11y-names-labels'}, // Critical, wcag2a
+        {id: 'skip-link', weight: 3, group: 'a11y-names-labels'}, // Moderate, best-practice
+        {id: 'tabindex', weight: 7, group: 'a11y-navigation'}, // Serious, best-practice
+        {id: 'target-size', weight: 7, group: 'a11y-best-practices'}, // Serious, wcag22aa
+        {id: 'td-headers-attr', weight: 7, group: 'a11y-tables-lists'}, // Serious, wcag2a
+        {id: 'th-has-data-cells', weight: 7, group: 'a11y-tables-lists'}, // Serious, wcag2a
+        {id: 'valid-lang', weight: 7, group: 'a11y-language'}, // Serious, wcag2aa
+        {id: 'video-caption', weight: 10, group: 'a11y-audio-video'}, // Critical, wcag2a
+        {id: 'landmark-one-main', weight: 3, group: 'a11y-best-practices'}, // Moderate, best-practice
         // Manual audits
         {id: 'focusable-controls', weight: 0},
         {id: 'interactive-element-affordance', weight: 0},
@@ -569,13 +587,17 @@ const defaultConfig = {
         {id: 'offscreen-content-hidden', weight: 0},
         {id: 'custom-controls-labels', weight: 0},
         {id: 'custom-controls-roles', weight: 0},
-        // Hidden audits
-        {id: 'empty-heading', weight: 0, group: 'hidden'},
-        {id: 'identical-links-same-purpose', weight: 0, group: 'hidden'},
-        {id: 'landmark-one-main', weight: 0, group: 'hidden'},
-        {id: 'label-content-name-mismatch', weight: 0, group: 'hidden'},
-        {id: 'table-fake-caption', weight: 0, group: 'hidden'},
-        {id: 'td-has-header', weight: 0, group: 'hidden'},
+        // Low-impact best-practices
+        {id: 'table-duplicate-name', weight: 0, group: 'a11y-best-practices'}, // Minor, best-practice
+        {id: 'empty-heading', weight: 0, group: 'a11y-best-practices'}, // Minor, best-practice
+        {id: 'aria-allowed-role', weight: 0, group: 'a11y-best-practices'}, // Minor, best-practice
+        {id: 'image-redundant-alt', weight: 0, group: 'a11y-names-labels'}, // Minor, best-practice
+        // WCAG AAA
+        {id: 'identical-links-same-purpose', weight: 0, group: 'a11y-best-practices'}, // Minor, wcag2aaa
+        // Hidden audits (ie. experimental)
+        {id: 'label-content-name-mismatch', weight: 0, group: 'hidden'}, // Serious, experimental
+        {id: 'table-fake-caption', weight: 0, group: 'hidden'}, // Serious, experimental
+        {id: 'td-has-header', weight: 0, group: 'hidden'}, // Critical, experimental
       ],
     },
     'best-practices': {
diff --git a/core/scoring.js b/core/scoring.js
@@ -57,7 +57,7 @@ class ReportScoring {
         const member = {...configMember};
 
         // If a result was not applicable, meaning its checks did not run against anything on
-        // the page, force it's weight to 0. It will not count during the arithmeticMean() but
+        // the page, force its weight to 0. It will not count during the arithmeticMean() but
         // will still be included in the final report json and displayed in the report as
         // "Not Applicable".
         const result = resultsByAuditId[member.id];
diff --git a/core/test/fixtures/user-flows/reports/sample-flow-result.json b/core/test/fixtures/user-flows/reports/sample-flow-result.json
diff --git a/core/test/results/sample_v2.json b/core/test/results/sample_v2.json
diff --git a/report/test/generator/report-generator-test.js b/report/test/generator/report-generator-test.js

Original file line number	Diff line number	Diff line change
`@@ -35,6 +35,7 @@ class ARIAAllowedRole extends AxeAudit {`
`35`	`35`	`title: str_(UIStrings.title),`
`36`	`36`	`failureTitle: str_(UIStrings.failureTitle),`
`37`	`37`	`description: str_(UIStrings.description),`
	`38`	`+ scoreDisplayMode: AxeAudit.SCORING_MODES.INFORMATIVE,`
`38`	`39`	`requiredArtifacts: ['Accessibility'],`
`39`	`40`	`};`
`40`	`41`	`}`
Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@ class ImageRedundantAlt extends AxeAudit {`
`36`	`36`	`title: str_(UIStrings.title),`
`37`	`37`	`failureTitle: str_(UIStrings.failureTitle),`
`38`	`38`	`description: str_(UIStrings.description),`
	`39`	`+ scoreDisplayMode: AxeAudit.SCORING_MODES.INFORMATIVE,`
`39`	`40`	`requiredArtifacts: ['Accessibility'],`
`40`	`41`	`};`
`41`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,6 @@ class LandmarkOneMain extends AxeAudit {`
`34`	`34`	`title: str_(UIStrings.title),`
`35`	`35`	`failureTitle: str_(UIStrings.failureTitle),`
`36`	`36`	`description: str_(UIStrings.description),`
`37`		`- scoreDisplayMode: AxeAudit.SCORING_MODES.INFORMATIVE,`
`38`	`37`	`requiredArtifacts: ['Accessibility'],`
`39`	`38`	`};`
`40`	`39`	`}`
Original file line number	Diff line number	Diff line change
`@@ -35,6 +35,7 @@ class TableDuplicateName extends AxeAudit {`
`35`	`35`	`title: str_(UIStrings.title),`
`36`	`36`	`failureTitle: str_(UIStrings.failureTitle),`
`37`	`37`	`description: str_(UIStrings.description),`
	`38`	`+ scoreDisplayMode: AxeAudit.SCORING_MODES.INFORMATIVE,`
`38`	`39`	`requiredArtifacts: ['Accessibility'],`
`39`	`40`	`};`
`40`	`41`	`}`