` with no `aria-describedby`, so helper and error text are not associated with the control, and a tri-state "select all" parent is not linked to its children. The author must associate them with `aria-describedby` and the appropriate group markup. + +**Manual testing steps** + +1. For a requiredlabelledcheckbox (`Checkbox required` inside a `FormControlLabel`), confirm `role=checkbox`, the name, `required`, and the wrapping ``. +2. Toggle indeterminate and confirm the accessibility tree exposes the mixed state (from the native `.indeterminate` property). +3. In a fieldset group (`FormControl component="fieldset"` + `FormLabel component="legend"` around a `FormGroup`), confirm the ``/`` name is exposed but any error or required constraint is not (no `aria-describedby`/`aria-invalid`). + +**Pass:** role, states, label association, and group name are programmatically determinable, and any helper/error text is tied to the control via author-supplied `aria-describedby`. + +#### 1.4.1 Use of Color · A + +`🚩` · `✅ Supports` · `◐ Shared` + +- State is conveyed by the checkmark icon's shape, not color: an empty square (unchecked), a square with a check (checked), and a square with a dash (indeterminate). A color-blind user can tell all three apart. +- The group error state is color-only: `FormHelperText` conveys it through red text. Pair it with text or an icon. (Required, by contrast, shows a visible `*`, which is a non-color cue, so it is fine.) That is author content. + +**Manual testing steps** + +1. View unchecked, checked, and indeterminate checkboxes in grayscale (DevTools Rendering, Emulate vision deficiencies, Achromatopsia); confirm all three remain distinguishable. +2. View a checkbox with an error `FormHelperText` in grayscale and confirm "error" is still perceivable without the red. + +**Pass:** the three states are distinguishable by shape, and any error state is conveyed by more than color. + +#### 1.4.3 Contrast (Minimum) · AA + +`✅ Supports` · `◐ Shared` + +- This criterion governs the visible text (the label and helper text), not the checkmark icon (that is 1.4.11). +- The label uses `text.primary` (about `16:1` on white, `18:1` on dark) and helper text uses `text.secondary` (about `5.7:1`). Error helper text `error.main` is the tightest at `4.98:1`, still above `4.5:1`. +- axe-core `color-contrast` passes on the labeled demos (recorded in `checkboxes.a11y.json`); disabled label text is exempt. +- The component renders no text on a colored fill, so unlike a contained button there is no label-on-background risk. Custom label colors or a colored container behind the row are the author's to check. Disabled text is exempt. + +**Manual testing steps** + +1. Measure the label and helper text against the real background in light and dark themes. +2. Pay attention to light-mode error text (`#d32f2f`, about `5:1`) on any non-white background. +3. Re-check any custom label color. + +**Pass:** label and helper/error text meet `4.5:1` (`3:1` for large text) against the actual background. + +#### 1.4.11 Non-text Contrast · AA + +`🚩` · `⚠️ Partially Supports` · `● Component` + +- This criterion (not 1.4.3) governs the checkmark icon at `3:1`, and every default state passes against the page background (`#fff` light, `#121212` dark). +- Light mode: `warning` is the tightest at `3.11:1`, then `info` `3.86:1`, `primary` `4.60:1`, the unchecked `text.secondary` outline `5.74:1`, and the white check on the fill `4.60:1`. Dark mode clears `3:1` easily (lowest is error at about `5:1`). +- `warning.main` is tuned to just clear `3:1`, so a colored container behind the checkbox can push it under. +- The keyboard focus indicator's contrast is untested, and `disableRipple`/`disableFocusRipple` removes it. +- Custom icons can fall below `3:1`: a faint custom unchecked box (for example a `#f5f8fa` fill) measures about `1.1:1` against the page (`1.5:1` at its border). +- Disabled (`action.disabled`, about `1.9:1`) is exempt. + +**Manual testing steps** + +1. Measure the unchecked outline and each checked color (`primary` through `warning`) against the background; confirm `3:1`, checking `warning` specifically. +2. Measure the keyboard focus indicator against the colors next to it. +3. Audit any custom icons against `3:1` (a faint custom unchecked box is a common fail); treat disabled as exempt. + +**Pass:** the indicator in every active state (unchecked outline, checked fill, indeterminate dash) and the focus indicator are `3:1` against adjacent colors; disabled is exempt. + +#### 2.4.6 Headings and Labels · AA + +`✅ Supports` · `◐ Shared` + +- The component renders whatever label and group legend the author supplies; descriptiveness is a content decision. This criterion does not require a label to exist, only that any provided label describes its purpose. axe-core `label` confirms a name is present across the demos; whether it is descriptive is a manual review. +- A vague label ("Option 1") would fail, and the component cannot enforce wording. + +**Manual testing steps** + +1. Read each checkbox label and group legend. +2. Confirm each describes the option ("Email notifications", not "Option 1"). + +**Pass:** every provided label and legend describes its purpose. + +#### 2.4.7 Focus Visible · AA + +`🚩` · `⚠️ Partially Supports` · `● Component` + +- `ButtonBase` removes the user-agent outline (`outline: 0`). In the default configuration keyboard focus adds the `.Mui-focusVisible` class plus a centered focus ripple, so an indicator is shown. +- `disableRipple` or `disableFocusRipple` removes the default focus indicator (the focus ripple), leaving none unless the author adds `.Mui-focusVisible` styles (for example, a 2px outline). + +**Manual testing steps** + +1. Press Tab to a default `` and confirm a visible focus indicator appears. +2. Press Tab to a `` (or `disableFocusRipple`) with no custom styles and confirm none appears. +3. Click with the mouse and confirm the indicator is keyboard-only. + +**Pass:** every keyboard-focused checkbox shows a visible indicator, including `disableRipple` via author-supplied styles. Today a bare `disableRipple` checkbox shows none. + +#### 3.3.2 Labels or Instructions · A + +`🚩` · `✅ Supports` · `◐ Shared` + +- Used as documented, the component meets this: `FormControlLabel` wraps the control in a real `` whose text is presented to all users. +- An `aria-label` is a name for assistive technology, not a visible label, so on its own it satisfies 4.1.2 but not this criterion. Using `aria-label` alone is fine for a control shown in isolation; in product UI, provide a visible label via `FormControlLabel` or a clear contextual one. + +**Manual testing steps** + +1. Confirm each checkbox in product UI has a visible label (`FormControlLabel`) or a clear contextual one. +2. Where only an `aria-label` is used, confirm the purpose is clear from surrounding context (for example, a column header). + +**Pass:** every checkbox has a label or instruction presented to all users, via `FormControlLabel`, adjacent text, or clear context. + +#### 4.1.2 Name, Role, Value · A + +`✅ Supports` · `◐ Shared` + +- Role, checked, and disabled are met natively: the native `` exposes `role=checkbox`, the checked state, and change notification with no ARIA needed, and `disabled` maps to native `disabled`. axe-core (`aria-allowed-attr`, `aria-valid-attr-value`, `label`, `nested-interactive`) confirms them. +- The `indeterminate` state sets the native `.indeterminate` property and no `aria-checked` attribute, so browsers expose the mixed state through the standard mechanism. axe `aria-conditional-attr` passes across the demos, and unit tests cover the property (set, kept after a click, restored when the input slot changes). +- The name is the shared part: it comes from the author's `FormControlLabel` or `aria-label`. One caveat: `readOnly` sets the native `readonly` attribute, which has no effect on a checkbox and is not exposed to assistive technology, so a read-only checkbox is not announced as such. Use `disabled` or `aria-readonly` if that state must be conveyed. +- Confirmed by unit tests in [`./Checkbox.test.js`](./Checkbox.test.js) (role, `checked`, and `disabled` are exposed). + +**Manual testing steps** + +1. Inspect alabelledcheckbox (`Checkbox` inside a `FormControlLabel`) and confirm `role=checkbox` with a non-empty name in the accessibility tree. +2. Toggle it with a screen reader running and confirm the state change is announced. +3. With `indeterminate` set, confirm "mixed" or partially checked is announced. + +**Pass:** the role, the checked/unchecked/mixed/disabled state with change notification, and an author-supplied accessible name are all programmatically determinable. + +### ⚙️ Automated + +#### 1.4.4 Resize Text · AA + +`✅ Supports` · `◐ Shared` + +- The checkmark icon is an `SvgIcon` whose size comes from `fontSize` in `rem` (medium 24px = 1.5rem, small 20px = 1.25rem) with a `1em` box, so it scales with browser zoom or root font size; the label is normal text. Nothing is pixel-fixed. +- A fixed-pixel container in the surrounding layout could clip at 200%. Covered by a Playwright test at 200% text size. + +#### 1.4.10 Reflow · AA + +`✅ Supports` · `◐ Shared` + +- The checkbox is a small inline-flex control with no fixed min-width and no horizontal-overflow layout of its own, so it reflows into a 320 CSS pixel viewport. +- Real failures usually come from the surrounding layout, such as a wide non-wrapping row of checkboxes overflowing at 320 pixels. Covered by a Playwright test at a 320px viewport. + +#### 1.4.12 Text Spacing · AA + +`✅ Supports` · `◐ Shared` + +- The component sets no text styles of its own and no fixed heights that would clip under user text-spacing overrides; the label is normal flowing text that wraps, and the checkmark icon is a fixed vector unaffected by spacing. +- Whether a long label clips depends on the author's container, not the checkbox. Covered by a Playwright test applying the WCAG text-spacing overrides. + +#### 2.1.1 Keyboard · A + +`✅ Supports` · `● Component` + +- The native `` is the single focusable control (the root span is `role: undefined`, `tabIndex: null`), so the browser provides Tab focus and Space toggle with no timing or path dependence, matching the [APG checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/). Disabled leaves the tab order. +- Confirmed by a unit test in [`./Checkbox.test.js`](./Checkbox.test.js) (Space toggles the checked state). + +#### 2.1.2 No Keyboard Trap · A + +`✅ Supports` · `● Component` + +- A single native input with standard Tab in and out. It installs no focus-capturing handlers and no containment logic, so focus cannot be trapped. +- Confirmed by a unit test in [`./Checkbox.test.js`](./Checkbox.test.js) (Tab is not intercepted, and focus moves away freely). + +#### 2.4.3 Focus Order · A + +`✅ Supports` · `◐ Shared` + +- The checkbox is one focusable element in natural DOM order, with no positive `tabIndex` and no reordering, and a disabled checkbox leaves the order, so it is one correct focus stop. Whether that order preserves meaning in a given layout stays a manual check. +- Order across controls, and group order, is the surrounding layout's responsibility. +- Confirmed by a unit test in [`./Checkbox.test.js`](./Checkbox.test.js) (default `tabIndex` is `0`; a disabled checkbox leaves the order). + +#### 2.5.2 Pointer Cancellation · A + +`✅ Supports` · `● Component` + +- Toggling runs on the native input's `click`, fired on pointer-up over the target. Nothing toggles on the down event (the ripple starts there but is decorative), and releasing off the control cancels. +- Confirmed by a unit test in [`./Checkbox.test.js`](./Checkbox.test.js) (releasing off the target does not toggle; `click` does). Covered by unit tests. + +#### 2.5.3 Label in Name · A + +`✅ Supports` · `◐ Shared` + +- With `FormControlLabel` and a string label, the accessible name equals the visible text, so the name contains the label. The required `*` is symbolic punctuation, not part of the label, so it is correctly excluded from the name; native `required` conveys that state instead. +- A `slotProps.input` `aria-label` that differs from the visible text breaks this. Keep the visible words in the name. +- Confirmed by a unit test in [`./Checkbox.test.js`](./Checkbox.test.js) (the accessible name matches the visible label). Covered by unit tests. + +#### 2.5.8 Target Size (Minimum) · AA + +`✅ Supports` · `◐ Shared` + +- The target is the padded root, not the icon (the input fills it at 100%): medium is a 24px icon plus 2 by 9px padding = 42px, and `size="small"` is 38px, both above the 24 by 24 CSS pixel minimum. A custom 16px icon still yields 34px. axe-core `target-size` confirms this across the demos in `checkboxes.a11y.json`. +- It would drop below 24px only if an author both shrinks the icon and removes the padding. Custom `sx`/`size` overrides and hit-area changes under browser zoom are not covered. + +#### 3.2.1 On Focus · A + +`✅ Supports` · `● Component` + +- Focusing the input only moves focus and shows the focus indicator. There is no navigation, dialog, or content change on focus, and the component registers no `onFocus` side effects. +- Confirmed by a unit test in [`./Checkbox.test.js`](./Checkbox.test.js) (focusing the checkbox does not activate it). + +#### 3.2.2 On Input · A + +`✅ Supports` · `◐ Shared` + +- Toggling only flips the checked or indeterminate state and fires `onChange`; per the Understanding document, changing a control's value is not a change of context. `readOnly` short-circuits the change. +- An author `onChange` that navigates or submits without warning would be an author-side failure. +- Confirmed by a unit test in [`./Checkbox.test.js`](./Checkbox.test.js) (toggling changes only the checked value). + +## Not applicable + +- **1.3.5 Identify Input Purpose (AA).** Covers inputs that collect information about the user through `autocomplete`. A boolean checkbox is not one of those input purposes. +- **1.4.13 Content on Hover or Focus (AA).** Needs additional content such as a tooltip or popover. The checkbox only restyles itself; a `Tooltip` wrapper would own this. +- **2.1.4 Character Key Shortcuts (A).** The only key is Space, and only while focused. There is no single-character shortcut. +- **2.2.2 Pause, Stop, Hide (A).** No auto-starting moving, blinking, or auto-updating content. +- **2.4.4 Link Purpose (In Context) (A).** The component renders no links. +- **2.5.7 Dragging Movements (AA, new in 2.2).** Covers drag operations. The checkbox toggles by tap or click. +- **3.1.1 Language of Page (A), 3.1.2 Language of Parts (AA).** The component emits no `` and no text of its own. A foreign-language label is the author's phrase to mark. +- **3.2.3 Consistent Navigation (AA).** Covers repeated navigation across a set of pages, not a single control. +- **3.2.6 Consistent Help (A, new in 2.2).** Covers consistent placement of help across pages. +- **3.3.7 Redundant Entry (A, new in 2.2).** Covers repopulating previously entered data. The checkbox captures none. +- **3.3.8 Accessible Authentication (Minimum) (AA, new in 2.2).** The paste, autofill, and cognitive-test duty falls on the credential fields, not a checkbox. +- **4.1.3 Status Messages (AA).** The checkbox emits no status messages; its checked-state change is covered by 4.1.2. +- **Time-based media (1.2.1 to 1.2.5).** No audio or video. +- **Audio Control (1.4.2).** Emits no audio. +- **Orientation (1.3.4).** Sets no orientation lock; a layout concern. +- **Bypass Blocks (2.4.1), Page Titled (2.4.2), Multiple Ways (2.4.5).** Page or site structure, not a single control. +- **Timing Adjustable (2.2.1).** Sets no time limit. +- **Three Flashes or Below Threshold (2.3.1).** Nothing flashes. +- **Pointer Gestures (2.5.1), Motion Actuation (2.5.4).** Toggles on a simple click; reads no device motion. +- **Error Identification (3.3.1), Error Suggestion (3.3.3), Error Prevention (3.3.4).** The checkbox collects and validates no input; these belong to the form or process. When an author surfaces an error, identify it in text and tie it to the control with `aria-describedby` (tracked under 1.3.1). + +## Level AAA + +The following SC are applicable but out of scope: + +- **2.3.3 Animation from Interactions.** The ripple's `scale()` animation honors `prefers-reduced-motion` when the theme sets `motion.reducedMotion` to `system` (follows the OS) or `always`; `disableRipple` also removes it. The default is `never`, so OS reduced-motion is not honored by default. `🚩` +- **2.4.13 Focus Appearance.** The focus ripple is unlikely to meet the area and 3:1 thresholds, and `disableRipple` removes it. `🚩` +- **2.5.5 Target Size (Enhanced), 44 px.** Default sizes (42px medium, 38px small) are below 44px. `🚩` +- **1.4.6 Contrast (Enhanced), 7:1.** The label (`text.primary`, about 16:1) clears 7:1, but helper text (about 5:1) and the checkmark icon fall short where the 7:1 text bar applies. `🚩` +- Also touched, in the same shape as their A and AA siblings: **1.3.6 Identify Purpose, 1.4.9 Images of Text (No Exception), 2.1.3 Keyboard (No Exception), 2.4.12 Focus Not Obscured (Enhanced)**. + +## Scope and test environment + +- **Standard.** WCAG 2.2, Level A and AA. +- **Component version.** `@mui/material` 9.x. +- **Scope.** The Checkbox component and its documented composition with `FormControlLabel`, `FormControl`/`FormGroup`, `FormLabel`, and `FormHelperText`, rendered through the documented API. +- **Automated.** axe-core via the Playwright visual-regression harness (results in [`checkboxes.a11y.json`](../../../../docs/data/material/components/checkboxes/checkboxes.a11y.json)), plus interaction tests in [`Checkbox.test.js`](./Checkbox.test.js). Checkmark icon contrast is computed from the theme tokens, since no axe rule covers non-text contrast. +- **Assistive-technology review.** Not yet performed. Flagged criteria are assessed from source pending a review with NVDA, JAWS, and VoiceOver. diff --git a/packages/mui-material/src/accessibility.md b/packages/mui-material/src/accessibility.md index b57bd2d3a000e2..80234337ae6c20 100644 --- a/packages/mui-material/src/accessibility.md +++ b/packages/mui-material/src/accessibility.md @@ -69,6 +69,7 @@ Components are rated in isolation against WCAG 2.2 A and AA. The levels are [cum | [AccordionSummary](./AccordionSummary/accessibility.md) | 23 | 1 | 0 | 31 | | [Avatar](./Avatar/accessibility.md) | 9 | 2 | 0 | 44 | | [Button](./Button/accessibility.md) | 23 | 4 | 0 | 28 | +| [Checkbox](./Checkbox/accessibility.md) | 23 | 2 | 0 | 30 | | [LinearProgress](./LinearProgress/accessibility.md) | 8 | 3 | 0 | 44 | | [Radio](./Radio/accessibility.md) | 23 | 2 | 0 | 30 | | [RadioGroup](./RadioGroup/accessibility.md) | 7 | 0 | 0 | 30 | diff --git a/test/regressions/demoMeta.ts b/test/regressions/demoMeta.ts index 42a882a29b8d67..e5fb0ea091e5a5 100644 --- a/test/regressions/demoMeta.ts +++ b/test/regressions/demoMeta.ts @@ -242,6 +242,18 @@ const RADIO_A11Y_DEMOS = [ 'UseRadioGroup', ]; +const CHECKBOX_A11Y_DEMOS = [ + 'Checkboxes', + 'CheckboxLabels', + 'ColorCheckboxes', + 'ControlledCheckbox', + 'CustomizedCheckbox', + 'IconCheckboxes', + 'SizeCheckboxes', + 'CheckboxesGroup', + 'IndeterminateCheckbox', +]; + // Switch docs demos enrolled for axe assertions. FormControlLabelPosition is // excluded: its `aria-label` on a role-less FormGroup div trips // `aria-prohibited-attr`, a demo quirk unrelated to Switch. @@ -347,6 +359,14 @@ export const A11Y_RULES: A11yRule[] = [ assertions: 'all', skipAssertions: ['color-contrast'], }, + // IndeterminateCheckbox needs no skip: the component sets the native + // `.indeterminate` property and no aria-checked attribute (#49053), so + // axe's aria-conditional-attr passes. + { + test: `docs/data/material/components/checkboxes/{${CHECKBOX_A11Y_DEMOS.join(',')}}`, + enabled: true, + assertions: 'all', + }, { test: `docs/data/material/components/progress/{${LINEARPROGRESS_A11Y_DEMOS.join(',')}}`, enabled: true,