[test] Automate 2.4.7 Focus Visible by michelengelen · Pull Request #48945 · mui/material-ui

michelengelen · 2026-08-11T09:40:36Z

Automates 2.4.7 Focus Visible across the seven components that rate it, by comparing each control focused and unfocused in a real browser.

axe has no rule for this criterion, and the unit tests that exist for it are skipIf(isJsdom()) — so they never actually run. It was rated on source review alone.

Why a pixel comparison rather than a computed-style diff: MUI's focus indicator is usually the ripple, a child element that appears in the DOM. Diffing styles on the control itself would miss it entirely and report a false failure. The capture is padded by 8px so an outline painted outside the control's box still counts.

I mutation-tested the assertion rather than trusting a green run: stripping outlines, box-shadows and the ripple makes 4 of the 7 fail. The remaining three have additional real indicators the sabotage did not remove — TextField's notched-outline border colour, for instance.

The rating stays 🔁 Hybrid, not ⚙️ Automated. The test proves an indicator exists, not that it has enough contrast — that is 1.4.11, which is still manual. What changes is the evidence flag: six components drop their 🚩, taking verified coverage from 184/230 to 190/230.

Follow-up is 1.4.11 itself. A spike confirmed it can be measured without new dependencies by screenshotting an element, letting the browser decode it into a canvas, and sampling pixels — that reproduced the Switch thumb-vs-track ratio at 2.26:1, inside the 1.8–2.6:1 range measured by hand in the report.

Important

How to review this PR

Layer 13 of 14 in a stacked series (#48915 → #48926). Its branch is built on a11y/stack/scorecard (#48925). GitHub cannot chain PR bases across a fork, so every PR in the series targets master instead.

Review only the last commit — fda28fb. Everything above it belongs to the layers below, and disappears as those merge.

Part of the WCAG conformance effort (#14187).

code-infra-dashboard · 2026-08-11T09:43:58Z

Deploy preview

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	0B^(0.00%)	0B^(0.00%)
@mui/lab	0B^(0.00%)	0B^(0.00%)
@mui/private-theming	0B^(0.00%)	0B^(0.00%)
@mui/system	0B^(0.00%)	0B^(0.00%)
@mui/utils	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Check out the code infra dashboard for more information about this PR.

Lets a fixture assert every axe rule it exercises rather than only the CSS-dependent visual ones, which is what the per-component WCAG reports need.

Adds a table-driven Playwright suite covering 1.4.10 Reflow, 1.4.4 Resize Text and 1.4.12 Text Spacing across the assessed components. axe has no rule for any of them, so they were rated Manual on evidence from source review.

Adds `pnpm a11y:scorecard`, which parses the count table out of every `<Component>/accessibility.md`, regenerates the index table, and emits the JSON that the public conformance page is built from. `--check` fails when either output is stale so a new report cannot land without its rollup.

Compares each control focused and unfocused in a real browser. axe has no rule for this criterion, and the existing unit tests for it are skipped under jsdom, so it rested on source review alone. Drops the evidence flag on the six components that carried one. The rating stays Hybrid rather than Automated: the test proves an indicator exists, not that it has enough contrast, which is 1.4.11 and still manual.

michelengelen · 2026-08-18T09:20:07Z

PR review

The pixel-comparison approach is sound — animations: 'disabled' plus Playwright's default caret hiding remove the incidental-difference sources, and the padded clip catches indicators that paint outside the control. The report bookkeeping checks out: 46→40 flags, one per updated report, and ToggleButton correctly needs no update because its browser-gated unit test already covers 2.4.7. Nothing blocking; one logic slip and two stack-hygiene items.

Bugs (2)

1. 🟡 `tabTo` treats a null `activeElement` as "reached"

Location: test/regressions/index.test.js:645

(target) => document.activeElement?.closest(target) !== null,

When activeElement is null, the optional chain yields undefined, and undefined !== null is true — the helper reports the target reached in exactly the case the ?. guards against.

Failure scenario: focus lands nowhere (rare in Chromium, but that is the case this guard exists for); the test proceeds and fails with the misleading "looks identical focused and unfocused" error instead of "could not reach with the Tab key".

Fix: use loose inequality: document.activeElement?.closest(target) != null.

2. 🟡 The `pnpm-lock.yaml` hunk commits drift caused by #48925

Location: pnpm-lock.yaml (execa specifier ^10.0.1 → ^10.0.0)

This hunk records the accidental execa downgrade that #48925 made in package.json (see the 🔴 finding there). It does not belong to the Focus Visible work.

Failure scenario: #48925 restores master's ^10.0.1; this hunk then reintroduces a mismatched lockfile.

Fix: drop the hunk once #48925's package.json is restored.

Docs (1)

3. 🟡 The suite's JSDoc block appears twice in the merged file

Location: test/regressions/index.test.js:565 and :575

#48936 shipped the "Registers 2.4.7 Focus Visible" comment ahead of the function; this PR adds the identical block again above registerFocusVisibleSuites. The merged file carries both. Best fixed by removing the orphan from #48936 and keeping this PR's copy.

Verdict

Approve after nits - the mechanism and bookkeeping are correct; fix the null-check and the two cross-PR leftovers.

🤖 Review generated with Claude Code

michelengelen added test accessibility a11y labels Aug 11, 2026

michelengelen requested review from silviuaavram and siriwatknp August 11, 2026 09:40

michelengelen mentioned this pull request Aug 11, 2026

[docs] Add the accessibility conformance report page #48926

Open

mj12albert and others added 13 commits August 11, 2026 13:50

[test] Add an assertions mode to the axe regression harness

a0b8a93

Lets a fixture assert every axe rule it exercises rather than only the CSS-dependent visual ones, which is what the per-component WCAG reports need.

[test] Automate the CSS-dependent WCAG criteria

8e3e84e

Adds a table-driven Playwright suite covering 1.4.10 Reflow, 1.4.4 Resize Text and 1.4.12 Text Spacing across the assessed components. axe has no rule for any of them, so they were rated Manual on evidence from source review.

[test][button] Add axe test coverage and WCAG conformance report

5c23780

[test][avatar] Add axe tests and WCAG conformance report

1482433

[test][checkbox] Add axe tests and WCAG conformance report

2ee61e1

[test][switch] Add axe tests and WCAG conformance report

4aad137

[test][radio] Add axe tests and WCAG conformance reports

d2b70c8

[test][toggle button] Add axe tests and WCAG conformance reports

5ef975a

[test][linear progress] Add axe tests and WCAG conformance report

2db86bf

[test][text field] Add axe tests and WCAG conformance report

4b8f12c

[test][accordion] Add axe tests and WCAG conformance reports

c53a6f9

michelengelen force-pushed the a11y/stack/focus-visible branch from da38130 to fda28fb Compare August 11, 2026 12:25

github-actions Bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Aug 17, 2026

This was referenced Aug 18, 2026

[test] Automate the CSS-dependent WCAG criteria #48936

Open

[test][toggle button] Add axe tests and WCAG conformance reports #48921

Open

michelengelen mentioned this pull request Aug 18, 2026

[test] Roll the per-component reports up into a library scorecard #48925

Open

Navigation Menu

Uh oh!

Uh oh!

[test] Automate 2.4.7 Focus Visible - #48945

[test] Automate 2.4.7 Focus Visible#48945
michelengelen wants to merge 13 commits into
mui:masterfrom
michelengelen:a11y/stack/focus-visible

michelengelen commented Aug 11, 2026 •

edited

Loading

Uh oh!

code-infra-dashboard Bot commented Aug 11, 2026 •

edited

Loading

Uh oh!

michelengelen commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

michelengelen commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

code-infra-dashboard Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy preview

Bundle size

Uh oh!

michelengelen commented Aug 18, 2026

PR review

Bugs (2)

1. 🟡 tabTo treats a null activeElement as "reached"

2. 🟡 The pnpm-lock.yaml hunk commits drift caused by #48925

Docs (1)

3. 🟡 The suite's JSDoc block appears twice in the merged file

Verdict

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

michelengelen commented Aug 11, 2026 •

edited

Loading

code-infra-dashboard Bot commented Aug 11, 2026 •

edited

Loading

1. 🟡 `tabTo` treats a null `activeElement` as "reached"

2. 🟡 The `pnpm-lock.yaml` hunk commits drift caused by #48925