Skip to content

fix(Accordion): announce header content in the expected order - #1769

Open
MurilloLeoni wants to merge 6 commits into
Telefonica:masterfrom
MurilloLeoni:fix/accordion-accessibility-adjustments
Open

MurilloLeoni wants to merge 6 commits into
Telefonica:masterfrom
MurilloLeoni:fix/accordion-accessibility-adjustments

Conversation

@MurilloLeoni

@MurilloLeoni MurilloLeoni commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

This PR updates the Accordion component so screen readers announce the full header text when navigating to an accordion button, following the specified reading order.

Changes

  • Removes the generated aria-label that limited the button’s accessible name to the title and asset text.
  • Allows the header text to be announced in the order verified with NVDA: title, subtitle, detail, and slot.

Related

@MurilloLeoni
MurilloLeoni requested a review from a team as a code owner October 13, 2026 20:13
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Preview deployment

Step 2/3 — safe-to-deploy label added, fork preview workflow dispatched.

Important

A reviewer must approve the workflow run before it can access deploy secrets.
Open the run and click Review deployments to approve it.

@yceballost

Copy link
Copy Markdown
Contributor

Is this change updated in specs?

Comment thread src/accordion.tsx

const assetText = getAssetText(props.asset);

const computedAriaLabel = ariaLabel ?? [props.title, assetText].filter(Boolean).join(' ');

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By removing the calculated label, we also stop displaying the asset’s alt/aria-label, because its container in HeaderContent has the aria-hidden attribute. Is it intended that it should now always be purely decorative? If it contains relevant information, we fix the way the subtitle is read but lose that information.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review! Yes, this is intentional. According to the accessibility spec, the asset on the left is decorative and should be ignored by screen readers. The button’s default accessible name is derived from its header text in the specified order: title, subtitle, detail, and right-side slot. Custom aria-label and aria-labelledby values are still supported.

I agree that a test for the button’s accessible name would help prevent regressions. I’ll add one covering the header text and its expected order.

@AlexandraGallipoliRodrigues

Copy link
Copy Markdown
Contributor

Shall we add a test with a title, subtitle, detail and content in the ‘right’ column, checking the full accessible name and its order using getByRole(“button”, {name: …})? That way, we’ll cover the regression caused by this PR

@MurilloLeoni

Copy link
Copy Markdown
Contributor Author

Is this change updated in specs?

Hi!
Yes, the reading order (title, subtitle, detail, slot) is already described in the Accordion spec.

Comment thread src/__tests__/accordion-test.tsx
@brtbrt brtbrt added the safe-to-deploy Allow preview deploys in external PRs label Oct 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

safe-to-deploy Allow preview deploys in external PRs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants