Skip to content

Commit 279ad8c

Browse files
michelengelenmichelengelen
committed
[docs] Add the accessibility conformance report page
A VPAT-style report of the library's WCAG 2.2 A/AA conformance, built from the per-component reports, for procurement and accessibility review. States its own limits up front: partial component coverage, no assistive-technology testing yet, and self-assessed rather than externally audited.
1 parent 7139cd3 commit 279ad8c

3 files changed

Lines changed: 128 additions & 0 deletions

File tree

‎docs/data/material/getting-started/accessibility/accessibility.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Accessibility conformance report
2+
3+
<p class="description">How Material UI components conform to WCAG 2.2 Level A and AA, reported in VPAT terms for procurement and accessibility review.</p>
4+
5+
:::warning
6+
**Draft — partial coverage.** This report covers the 12 components assessed so far, not the whole library. It has not been reviewed by an external auditor, and no assistive-technology testing has been performed yet. See [Scope and limitations](#scope-and-limitations) before relying on it for a procurement decision.
7+
:::
8+
9+
## About this report
10+
11+
This is a Voluntary Product Accessibility Template (VPAT®) style report: it states how far Material UI meets the [Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) at Levels A and AA, using the conformance vocabulary defined by the [Information Technology Industry Council](https://www.itic.org/policy/accessibility/vpat).
12+
13+
Each component is rated criterion by criterion in its own report, kept next to the source code at `packages/mui-material/src/<Component>/accessibility.md`. Those reports carry the reasoning, the responsibility split, and reproducible manual test steps for every criterion. **The table below summarizes them; follow a component link for the detail.**
14+
15+
| Field | Value |
16+
| :---------------- | :--------------------------------------------------------------------------------------------- |
17+
| Product | Material UI (`@mui/material`) |
18+
| Product type | React component library (software) |
19+
| Version assessed | Results track the `master` branch; see [releases](https://github.com/mui/material-ui/releases) |
20+
| Vendor | MUI |
21+
| Standards applied | WCAG 2.2 Level A and AA |
22+
| Report type | Self-assessment, published as source-controlled documentation |
23+
24+
## Conformance by component
25+
26+
Each row counts only the criteria that **apply** to that component; criteria that are Not Applicable are excluded. Levels are [cumulative](https://www.w3.org/WAI/WCAG2AA-Conformance) — AA includes all of A.
27+
28+
- **Rated** — applicable Level A and AA criteria.
29+
- **Verified** — criteria confirmed by a test or a recorded review. The remainder are assessed from the source but not yet re-verified; they are flagged 🚩 in the component report. The flag concerns evidence, not conformance.
30+
- **Automated** — criteria a deterministic test proves on its own, so they cannot silently regress.
31+
32+
<!-- scorecard:start -->
33+
34+
| Component | Level A | Level AA | Rated | ✅ Supports | ⚠️ Partially Supports | Verified | Automated |
35+
| :------------------------------------------------------------------------------------------------------------------------------- | ------: | -------: | ------: | ----------: | --------------------: | ----------: | --------: |
36+
| [Accordion](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Accordion/accessibility.md) | 11 | 8 | 19 | 19 | 0 | 16/19 | 9 |
37+
| [AccordionSummary](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/AccordionSummary/accessibility.md) | 13 | 11 | 24 | 23 | 1 | 20/24 | 11 |
38+
| [Avatar](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Avatar/accessibility.md) | 5 | 6 | 11 | 9 | 2 | 6/11 | 2 |
39+
| [Button](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Button/accessibility.md) | 15 | 12 | 27 | 23 | 4 | 19/27 | 11 |
40+
| [Checkbox](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Checkbox/accessibility.md) | 14 | 11 | 25 | 22 | 3 | 21/25 | 11 |
41+
| [LinearProgress](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/LinearProgress/accessibility.md) | 6 | 5 | 11 | 8 | 3 | 6/11 | 1 |
42+
| [Radio](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Radio/accessibility.md) | 14 | 11 | 25 | 23 | 2 | 22/25 | 11 |
43+
| [RadioGroup](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/RadioGroup/accessibility.md) | 6 | 1 | 7 | 7 | 0 | 4/7 | 2 |
44+
| [Switch](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Switch/accessibility.md) | 14 | 11 | 25 | 23 | 2 | 22/25 | 11 |
45+
| [TextField](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/TextField/accessibility.md) | 14 | 14 | 28 | 25 | 3 | 23/28 | 12 |
46+
| [ToggleButton](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/ToggleButton/accessibility.md) | 13 | 11 | 24 | 20 | 4 | 22/24 | 11 |
47+
| [ToggleButtonGroup](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/ToggleButtonGroup/accessibility.md) | 2 | 2 | 4 | 4 | 0 | 3/4 | 1 |
48+
| **12 components** | **127** | **103** | **230** | **206** | **24** | **184/230** | **93** |
49+
50+
<!-- scorecard:end -->
51+
52+
**No component records a ❌ Does Not Support rating for any Level A or AA criterion.**
53+
54+
Rolled up to the library level, where each criterion takes the worst rating any assessed component receives, 32 success criteria are exercised: **25 Supports, 7 Partially Supports, 0 Does Not Support.**
55+
56+
The Level A and AA criteria absent from every row apply at the page or application level — [2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks), [3.1.1 Language of Page](https://www.w3.org/WAI/WCAG22/Understanding/language-of-page), the [1.2.x Time-based Media](https://www.w3.org/TR/WCAG22/#time-based-media) set — and are the responsibility of the application.
57+
58+
## How to read the ratings
59+
60+
| Symbol | Term | Meaning |
61+
| :----- | :----------------- | :---------------------------------------------- |
62+
| ✅ | Supports | Met, with no known defects. |
63+
| ⚠️ | Partially Supports | Some functionality does not meet the criterion. |
64+
| ❌ | Does Not Support | Most functionality does not meet the criterion. |
65+
| ➖ | Not Applicable | The criterion does not apply to this component. |
66+
67+
Each criterion in a component report also records **who is responsible** for meeting it — ● the component, ◐ shared when used as documented, or ○ you, depending on your implementation and surrounding content. This distinction matters more for a component library than for an application, and the reports state it per criterion.
68+
69+
:::info
70+
An application built with Material UI is not automatically accessible. Material UI supplies accessible building blocks; meeting WCAG for a finished product remains the responsibility of the team building it.
71+
:::
72+
73+
## Known gaps
74+
75+
Four issues account for almost every ⚠️ rating. Three are properties of the **default theme** rather than of the components' structure, so a theme resolves them today.
76+
77+
| Gap | Criteria | Affected | Workaround |
78+
| :--------------------------------------------------------------------------------------------- | :------------ | :---------------------------------------------------- | :-------------------------------------------------- |
79+
| The keyboard focus indicator is the ripple, so `disableRipple`/`disableFocusRipple` removes it | 1.4.11, 2.4.7 | Button, Checkbox, Radio, Switch, Toggle Button | Style `.Mui-focusVisible` in your theme — see below |
80+
| Some default palette colors fall short of contrast minimums | 1.4.3, 1.4.11 | Avatar, Button, TextField, Toggle Button, and others | Override the affected palette entries |
81+
| Dynamic state changes are not announced | 4.1.3 | Button (`loading`), LinearProgress, TextField (error) | Render your own `aria-live` region alongside |
82+
| Indefinite animation cannot be paused | 2.2.2 | LinearProgress (`indeterminate`, `query`, `buffer`) | Show it only while an operation is in flight |
83+
84+
If you disable the ripple, restore a focus indicator in your theme:
85+
86+
```js
87+
const theme = createTheme({
88+
components: {
89+
MuiButtonBase: {
90+
styleOverrides: {
91+
root: {
92+
'&.Mui-focusVisible': {
93+
outline: '2px solid currentColor',
94+
outlineOffset: 2,
95+
},
96+
},
97+
},
98+
},
99+
},
100+
});
101+
```
102+
103+
One genuine defect sits outside those four: Checkbox's `indeterminate` state sets `aria-checked="mixed"` on a native checkbox whose `checked` property is `false` (4.1.2), which ARIA in HTML disallows. It is tracked for a fix.
104+
105+
## Scope and limitations
106+
107+
:::warning
108+
Read this section before citing the report.
109+
:::
110+
111+
- **Component coverage is partial.** 12 components are assessed. Widely used components including Select, Autocomplete, Dialog, Menu, Table, Tabs, Slider, Tooltip, Snackbar, and Drawer are **not yet assessed**, and this report says nothing about them.
112+
- **No assistive-technology testing.** No screen-reader passes have been performed. Criteria that depend on how a specific assistive technology behaves are assessed from the exposed accessibility tree, not from observed behavior.
113+
- **Level AAA is out of scope**, as it is for a standard VPAT.
114+
- **Components are rated in isolation**, as rendered with default props and the default theme. Customization, composition, and your surrounding page can change the result.
115+
- **Evidence strength varies.** See the Verified column above; the shortfall is assessed from the source but not yet re-verified.
116+
- **This is a self-assessment**, not audited by an independent third party.
117+
- **Section 508 and EN 301 549 chapters are not yet included.** The WCAG results above supply the substance those chapters incorporate by reference, but the chapter-by-chapter mapping has not been written.
118+
119+
## Feedback
120+
121+
Accessibility defects are treated as bugs. Report them on [GitHub](https://github.com/mui/material-ui/issues/new/choose) with the component, the success criterion, and steps to reproduce.

‎docs/data/material/pages.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ const pages: MuiPage[] = [
1717
{ pathname: '/material-ui/getting-started/learn' },
1818
{ pathname: '/material-ui/getting-started/design-resources' },
1919
{ pathname: '/material-ui/getting-started/faq', title: 'FAQs' },
20+
{ pathname: '/material-ui/getting-started/accessibility' },
2021
{ pathname: '/material-ui/getting-started/supported-components' },
2122
{ pathname: '/material-ui/getting-started/supported-platforms' },
2223
{ pathname: '/material-ui/getting-started/support' },

‎docs/pages/material-ui/getting-started/accessibility.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
import { MarkdownDocs } from '@mui/internal-core-docs/MarkdownDocs';
2+
import * as pageProps from 'docs/data/material/getting-started/accessibility/accessibility.md?muiMarkdown';
3+
4+
export default function Page() {
5+
return <MarkdownDocs {...pageProps} />;
6+
}

0 commit comments

Comments
 (0)