Web Severity Scoring
This file describes the scoring that skills/a11y-core/scripts/merge-findings.mjs
computes for every rendered report. Where this file and the script differ, the
script decides. A score is not a conformance claim: only a finding-free review
against every criterion at the target level supports "conforms".
Score formula
penalty = sum over findings of severity_weight x confidence_factor
checks = max(number of findings + number of passed checks, 10)
score = max(0, round(100 - (penalty / checks) x 20))
Each severity, with its weight.
| Severity | Weight |
|---|---|
| critical | 10 |
| serious | 5 |
| moderate | 2 |
| minor | 1 |
Dividing by the number of checks keeps a large audit from scoring lower only because it looked at more. The floor of 10 checks stops a tiny audit with one finding from scoring near zero.
Example: one critical finding at high confidence and 9 passed checks gives penalty 10, checks 10, score 100 - (10 / 10) x 20 = 80, grade B.
Grades
Each score band, with its grade.
| Score | Grade |
|---|---|
| 90-100 | A |
| 80-89 | B |
| 70-79 | C |
| 60-69 | D |
| 0-59 | F |
Confidence
Each level, with its factor and when to use it.
| Level | Factor | When to use |
|---|---|---|
| high | 1.0 | Structural and certain (missing alt, no label, no lang), or found by two sources (for example axe-core and code review) |
| medium | 0.7 | One source, likely an issue (heading edge cases, questionable ARIA, possible keyboard trap) |
| low | 0.4 | Needs human review (alt text quality, reading order, context-dependent link text) |
A finding confirmed by a third source, such as a Playwright run that tabs
into the trap, stays high; the schema has no higher level. Merging keeps the
highest confidence any source reported for the same rule at the same location.
Scorecard Format
Single Page
## Accessibility Score
| Metric | Value |
|--------|-------|
| Page | [URL] |
| Score | [0-100] |
| Grade | [A-F] |
| Critical | [count] |
| Serious | [count] |
| Moderate | [count] |
| Minor | [count] |
Multi-Page
## Accessibility Scorecard
| Page | Score | Grade | Critical | Serious | Moderate | Minor |
|------|-------|-------|----------|---------|----------|-------|
| / | 82 | B | 0 | 2 | 3 | 1 |
| /login | 91 | A | 0 | 0 | 2 | 1 |
| /dashboard | 45 | F | 2 | 4 | 3 | 2 |
| **Average** | **72.7** | **C** | **2** | **6** | **8** | **4** |
Cross-Page Pattern Classification
Each pattern type, with its definition and remediation ROI.
| Pattern Type | Definition | Remediation ROI |
|---|---|---|
| Systemic | Same issue on every audited page | Highest - usually layout/nav, fix once |
| Template | Same issue on pages sharing a component | High - fix the shared component |
| Page-specific | Unique to one page | Normal - fix individually |
Remediation Tracking
Change Classification
Each status, with its definition.
| Status | Definition |
|---|---|
| Fixed | Issue was in previous report but no longer present |
| New | Issue not in previous report, appears now |
| Persistent | Issue remains from previous report |
| Regressed | Issue remains, at a higher severity than in the previous report |
Progress Metrics
- Issue reduction:
(fixed / previous_total) * 100 - Score change:
current_score - previous_score - Pages improved: count of pages with higher scores than previous audit
- Trend: improving (score up 5+), stable (within 5), declining (score down 5+)
Issue Severity Categories
Critical
- No keyboard access to essential functionality
- Missing form labels on required fields
- Images conveying critical information have no alt text
- Color is the sole means of conveying information
- Keyboard traps with no escape
Serious
- Missing skip navigation
- Poor heading hierarchy (skipped levels)
- Focus not visible on interactive elements
- Form errors not programmatically associated
- Missing ARIA on custom widgets
Moderate
- Redundant ARIA on semantic elements
- Suboptimal heading structure (multiple H1s)
- Missing autocomplete on identity fields
- Links to new tabs without warning
- Missing table captions
Minor
- Redundant title attributes
- Suboptimal button text
- Missing landmark roles where semantic elements exist
- Decorative images with non-empty alt text