Repository navigation
fix(a11y): accessible names for Tier 1 form controls, Select and Link - #1295
chad-agent wants to merge 19 commits into
Conversation
The row checkbox and the header select-all checkbox render a Checkbox without a label, so their accessible name was the string "undefined". Name them "Select row" and "Select all rows" (WCAG 2.2 SC 4.1.2). The mobile select-all checkbox keeps its visible label "Select All" as its name; a test guards it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each CheckboxMultiSelect item renders a Checkbox without a label, so its accessible name was the string "undefined". Point the checkbox at the item's label text with aria-labelledby (WCAG 2.2 SC 4.1.2). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Checkbox stringified its `label` prop into `aria-label`. A JSX label gave the name "[object Object]" and no label gave "undefined". The label is already wired with <label htmlFor>, so drop the aria-label and let the visible label name the control (WCAG 2.2 SC 4.1.2, 2.5.3). A consumer aria-label or aria-labelledby still wins. A Checkbox with no label now has no name instead of "undefined" and needs an aria-label. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Switch stringified its `label` prop into `aria-label`, the same defect as Checkbox: "[object Object]" for a JSX label, "undefined" without one. Drop the aria-label; the visible label already names the switch through <label htmlFor> (WCAG 2.2 SC 4.1.2, 2.5.3). Add Switch.test.tsx (none existed) with a click test and the name cases. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The group label used <label htmlFor> on the Radix root, a div with
role="radiogroup" that a label cannot name, so the group had no name.
Link the label with aria-labelledby instead (WCAG 2.2 SC 1.3.1, 4.1.2).
A consumer aria-label or aria-labelledby on the group still wins.
RadioGroup.Item stringified its label into aria-label ("[object Object]"
for a JSX label, "undefined" without one) and left a consumer aria-label
or aria-describedby on the wrapper div. Drop the stringified value and
pass aria-label, aria-labelledby and aria-describedby to the radio.
Other rest props stay on the wrapper as before.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An aria-label or aria-labelledby passed to Select landed on the wrapper div (and on the "no options" container), so the trigger kept the name "Select an option sort". Route both to the trigger button; triggerProps still win (WCAG 2.2 SC 4.1.2). Name the search input "Search options" (SC 4.1.2, 3.3.2) and its clear button "Clear search" instead of the icon name "cross" (SC 2.4.6). Hide the decorative sort and option check icons, which exposed their icon names (SC 1.1.1). This also covers MultiSelect and CheckboxMultiSelect, which share the same internal Select. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Link icon rendered as an image named by its icon name, so a link "Docs" with icon="arrow-right" was announced as "Docs arrow-right". Mark the icon aria-hidden; the link text names the link (WCAG 2.2 SC 1.1.1). The icon's data-testid stays. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The loading icon rendered as an image named "loading-animated", its icon name. Name it "Loading" (WCAG 2.2 SC 1.1.1). The clear button keeps its name "clear input". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
|
🦋 Changeset detectedLatest commit: 137da59 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Chromatic Storybook
Built from commit: Statuses as of the end of the run. The build link shows the live review state. |
A Checkbox without a label took its name from the indicator icon, so it was announced as "check" when checked and "minus" when indeterminate. The icon is decorative; the checked state is already exposed by the checkbox role. WCAG 2.2 SC 1.1.1, 4.1.2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The item checkbox pointed aria-labelledby at the whole icon wrapper, so its name also held the icon name and the option description, for example "Alpha user" or "Beta Second letter". It now points at the label text only, and the description is wired with aria-describedby, as the APG Checkbox pattern does. WCAG 2.2 SC 1.1.1, 4.1.2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Hiding the icon in every case left an icon-only Link with no name. The icon is now hidden only when the link has text, so an icon-only link is named by the icon, as before this change. WCAG 2.2 SC 2.4.4, 4.1.2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The group set its own aria-labelledby before spreading the rest props,
so a wrapper that forwarded aria-labelledby={undefined} erased the name
taken from the label. The consumer values are now read first and the
label is used only when neither aria-label nor aria-labelledby is set.
WCAG 2.2 SC 1.3.1, 4.1.2.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Without a visible label these stories now render controls with no accessible name, which the Storybook accessibility panel reports. They now show the documented way to name such a control: aria-label. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Default names change for unlabelled controls and aria-* props land on a different element, so a consumer test can fail. The changeset now follows the Breaking and Migration format and lists every observable change: MultiSelect and CheckboxMultiSelect, the hidden option check icon, the renamed clear button and loading icon. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ption children
In the children form, a CheckboxMultiSelect.ItemDescription child sat inside
the span that names the checkbox, so the description became part of the name
("Content3 Description of Content3") and the checkbox had no description.
ItemDescription children now render after the label span, and the checkbox
points aria-describedby at them (APG Checkbox; WCAG 2.2 SC 1.3.1).
aria-describedby is now set only for a description that is rendered. A
`label: ''` with a description no longer points at a missing id, and a
`description` of 0 is now used.
Adds hasRenderableContent, which tells a node that renders something (a
number, non-blank text or an element) from one that renders nothing.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The icon was hidden whenever `children` was truthy. `children={[]}` hid the
only name source, so the link had no name (WCAG 2.2 SC 2.4.4, 4.1.2), and
`children={0}` exposed the icon slug, giving "0 popout" (SC 1.1.1). The icon
is now hidden only when the children render a number, non-blank text or an
element.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`??` kept `aria-labelledby=""`, which wrappers often pass when they join an empty id list. An empty value points at nothing, so the group lost its visible label name "Plan" (WCAG 2.2 SC 1.3.1, 4.1.2). An empty aria-labelledby now falls back to the label, as an empty aria-label already did. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The description line now covers the ItemDescription children form, which round 3 wires to aria-describedby. The Migration step puts a visible label first: an aria-label is not visible, so on its own it does not meet WCAG 2.2 SC 3.3.2. aria-label stays as the option for a purpose already visible from context. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Replaced by #1298, which keeps only Checkbox and Switch and the checkboxes that use them. The other changes here follow in smaller PRs. |
Description
Form controls, Select and Link now give screen readers the right names. This is the first of the smaller PRs that split up #1189, and it follows the approach of #1189 for these components.
Checkbox,SwitchandRadioGroup.Itemtake their name from the visible label. They no longer copylabelintoaria-label, which gave "[object Object]" for a JSX label and "undefined" for no label (WCAG 2.2 SC 4.1.2 Name, Role, Value; AGENTS.md section 7).RadioGroupis named by itslabelthrougharia-labelledby. Before,<label htmlFor>pointed at thediv role="radiogroup", which a label cannot name (SC 1.3.1 Info and Relationships, 4.1.2). A wrapper that passesaria-labelledby={undefined}keeps that name.aria-label,aria-labelledbyandaria-describedbyonRadioGroup.Itemnow reach the radio, not the wrapperdiv.aria-labelandaria-labelledbyonSelectnow name the trigger button.triggerPropsstill win. This coversMultiSelectandCheckboxMultiSelecttoo.Selectsearch input is named "Search options" (SC 4.1.2), and its clear button "Clear search" instead of "cross" (SC 2.4.6 Headings and Labels).Checkboxcheck icon, theSelectsort and check icons, and theLinkicon when the link has text (SC 1.1.1 Non-text Content). An icon-onlyLinkkeeps the icon name, as onmain(SC 2.4.4 Link Purpose (In Context)). TheTextFieldloading icon is named "Loading".Checkboxwithout a label. They were named "undefined" and would have had no name after this change, so they get names in the same PR: theTablerow checkbox ("Select row"), theTableheader select-all ("Select all rows") and theCheckboxMultiSelectitem checkbox. The item checkbox is named by the option label only. The option description, or aCheckboxMultiSelect.ItemDescriptionchild, becomes its description (aria-describedby), as in the APG Checkbox pattern.How to review
Each commit is one change with its own tests, so you can review them one at a time.
First round:
fix(Table): name the row and header select-all checkboxes. The mobile select-all keeps its visible label "Select All".fix(Select): point eachCheckboxMultiSelectitem checkbox at its label witharia-labelledby.fix(Checkbox): remove the stringifiedaria-label.fix(Switch): the same, plus a newSwitch.test.tsx(none existed).fix(RadioGroup): name the group witharia-labelledby, and pass the itemaria-*props to the radio.fix(Select): routearia-label/aria-labelledbyto the trigger, name the search input and clear button, hide the sort and check icons.fix(Link): hide the icon.fix(TextField): name the loading icon.Commits 1 and 2 come first so that no internal checkbox loses its name when commit 3 lands.
Fix round, after a review of the first round:
fix(Checkbox): hide the check icon. Without it, a checkbox with no label was named "check" when checked and "minus" when indeterminate.fix(Select): name theCheckboxMultiSelectitem checkbox by the label text only. Commit 2 pointed at the whole item, so the name also held the icon name and the description ("Alpha user", "Beta Second letter").fix(Link): hide the icon only when the link has text. Commit 7 left an icon-only link with no name.fix(RadioGroup): read the consumeraria-labelandaria-labelledbybefore the spread, soaria-labelledby={undefined}keeps the group name.docs(Checkbox, Switch): add anaria-labelto the twoNoLabelstories, which now render controls with no name.Round 3, after a second review:
fix(Select): describe theCheckboxMultiSelectitem checkbox by itsItemDescriptionchildren. In the children form, which theOptionsAsChildrenstory uses, the description sat inside the label, so the name was "Content3 Description of Content3" and there was no description.aria-describedbyis now set only for a description that renders. This adds a small helper,hasRenderableContent.fix(Link): hide the icon only when the children render something.children={[]}gave no name, andchildren={0}gave "0 popout".fix(RadioGroup): treataria-labelledby=""as not set, so the group keeps the name "Plan".ItemDescriptionchildren, and the migration note puts a visible label first.Accessible names before and after, computed with
dom-accessibility-apiin jsdom. The Table and CheckboxMultiSelect rows come from the unit tests in this PR.mainaria-labelaria-labelidaria-labelledby={undefined}aria-labelledby=""aria-labelaria-label="Consumer name"div)aria-label="Fruit"icon="arrow-right"icon="popout"icon="popout"andchildren={[]}icon="popout"andchildren={0}icon: 'user'ItemDescriptionchild0These stay the same:
Icondefault "check",IconButtonwithoutaria-label"dots-vertical",Buttonwith an icon and a label "Add",TextFieldlabel "Name",TextFieldclear button "clear input".Links and tickets
Part of the split of #1189.
Good to know
No public prop changes and no visual change. Some things a consumer can observe do change, so the changeset is marked Breaking: and has a migration note:
Checkbox,SwitchandRadioGroup.Itemno longer setaria-labelfromlabel. A control with a string label keeps the same name. A control with no label goes from "undefined" to no name, so it needs a visiblelabel, oraria-labelledbythat points at visible text.aria-labelfits only when the purpose is already visible from context, such as a checkbox in a table row (SC 3.3.2 Labels or Instructions). axe flags a missing name, but it did not flag "undefined".aria-labelandaria-labelledbyon aSelectmove from the wrapperdivto the trigger button, sogetByLabelTextnow returns the button.Selecttrigger loses " sort", and aLinkwith text loses its icon name. Tests that query those names need the new name.This PR may need a rebase if #1291 (focus ring CSS for Checkbox, Switch and RadioGroup) or #1293 (vitest bump that edits some of the same test files) lands first.
Things I noticed and did not change, to keep this PR to names:
Iconis named by its icon name by default (role="img"). Each decorative use needsaria-hiddenby hand, as in this PR. MakingIcondecorative by default is a separate change.Selecttrigger does not expose the selected value, and options have no role. With anaria-label, the trigger name is that label without the value. That is the combobox/listbox pattern work (APG Combobox, Listbox), not a naming fix.CheckboxMultiSelectputs a focusable checkbox inside each option (nested interactive control).IconButtonwithoutaria-labelfalls back to the icon name. 13 call sites outside these components.aria-describedbyandaria-invalid. fix(A11Y): Low hanging fruit, aria labels #1189 also addsrole="alert", which is a live region, so it needs a maintainer decision first (AGENTS.md section 7).RadioGroup.Itemstill puts its other rest props (data-testid, handlers) on the wrapperdiv.Selectstill puts a consumeraria-describedbyon the wrapper.CheckboxMultiSelect.ItemDescriptionchild gets an internalid, which replaces anidthe consumer set on it. AnItemDescriptioninside a fragment or another element is not found, so it stays part of the name.Linkcounts an empty fragment (<></>) as content, so an icon with only that as children is hidden. An element that rendersnullis the same, and neither can be detected at render time.mainand on this branch alike: link text #437eef on #ffffff is 3.83:1 in the light theme (SC 1.4.3 Contrast (Minimum) needs 4.5:1); the openCheckboxMultiSelectpopover hasrole="dialog"with no name; and the Radix popover setsaria-hiddenon the page behind it while the trigger there stays focusable (axearia-hidden-focus).table-layout: autothe default #683 also changesTable.tsx. My two lines there are small, so a conflict is easy to resolve.Checklist
Breaking is ticked because default names change and some
aria-*props land on a different element, so a consumer test can fail. No props were removed or renamed. The changeset is a breakingminorwith a migration note.Contribution
buildandbuild-storybookwork locallyNot done: a manual check in Storybook. The only story change is an
aria-labelon the twoNoLabelstories.Accessibility
aria-labelNames is ticked for the controls in this PR only. Keyboard and Vision are not ticked because this PR does not change them, and I did not re-test them.
WCAG 2.2 criteria checked: 1.1.1 Non-text Content, 1.3.1 Info and Relationships, 2.4.4 Link Purpose (In Context), 2.4.6 Headings and Labels, 2.5.3 Label in Name, 4.1.2 Name, Role, Value.
Tested:
getByRole(role, { name })). Each test for a fixed defect failed before its fix and passes after it. A few tests guard behavior that must not change: a consumeraria-labeloraria-labelledbystill wins,triggerPropsstill win, the mobile select-all keeps "Select All", a labelled checked checkbox keeps its label, and a children item with noItemDescriptiongets noaria-describedby.aria-labelcondition, or moving the triggeraria-labelaftertriggerProps, makes tests fail.build:health_checkin the first round.eslint-suppressions.jsondid not change.ItemDescriptionchildren form, so I also compared screenshots of the openOptionsAsChildrenstory before and after commit 16, in both themes: 0 pixels differ.yarn test:visualcannot build its image locally right now, because Node 26 inmcr.microsoft.com/playwright:v1.64.1-nobleno longer ships corepack. So I ran the same specs in that image directly, withCI=true.node_modules, default rules, on the static Storybook build: all 58 stories of Checkbox, Switch, RadioGroup, CheckboxMultiSelect (menu open) and Link, on this branch and onmain. This PR adds no violation. It removes one: the unnamed search input in the openCheckboxMultiSelect. Round 3 gives the same result on every story. The older violations are listed under "Things I noticed".Not tested:
<label for>on the Radix<button role="checkbox">(orswitch,radio). HTML listsbuttonas labelable and Radix documents this pattern, but jsdom is the only engine I checked it in.Screenshots
No visual change. The visual tests above pass without new snapshots.
🤖 Generated with Claude Code