Skip to content

[WC-3404]: Fix tooltip accessibility for screenreader - #2175

Open
HedwigAR wants to merge 11 commits into
mainfrom
AT-239/tooltip-accessibility-improvement-screenreader
Open

HedwigAR wants to merge 11 commits into
mainfrom
AT-239/tooltip-accessibility-improvement-screenreader

Conversation

@HedwigAR

@HedwigAR HedwigAR commented Apr 16, 2026 •

Copy link
Copy Markdown
Contributor

Pull request type

Bug fix (non-breaking change which fixes an issue)


Description

Screen reader users who tab to an interactive tooltip trigger hear nothing, because tooltip content is only in the DOM while open, and the aria-describedby from Floating UI sits on the non-focusable trigger wrapper (WC-3404).

This PR:

  • Keeps one content element in the DOM. It is hidden with display: none while closed, and shown as the tooltip while open.
  • Adds its id to aria-describedby on focusable trigger elements, keeping existing values.
  • Uses a MutationObserver to cover late-mounted elements and attribute resets.
  • Treats content as empty when it renders no text or media, for example when conditional visibility hides all custom widgets or the text is only whitespace. Empty content adds no description and does not open the tooltip.
  • Skips aria-describedby handling in the Studio Pro preview.

I took over this PR from the original author. Since their last update, I rebased it on main, addressed the AI review comments, replaced the single hidden copy approach with one content element, fixed three QA findings, and replaced AGENTS.md with OpenSpec changes in openspec/changes/.

QA findings fixed:

  1. Tab and Shift+Tab got stuck around a trigger whose closed tooltip had focusable custom content. Closed content was inert, and is now display: none instead.
  2. With all custom content hidden by conditional visibility, the trigger referenced an empty description and an empty tooltip opened.
  3. Whitespace-only text gave the trigger an empty description.

Behavior change to review: custom content widgets now mount at page load instead of on first open, because a description needs content in the DOM. Data widgets inside a tooltip load earlier as a result.

Out of scope: default Hover mode still does not open on keyboard focus, which differs from the Deque tooltip pattern. This is tracked in WC-3663.

What should be covered while testing?

Unit tests and lint pass locally. Manual QA:

  • Tooltip opens, closes and positions as before in all Open on modes
  • VoiceOver and NVDA announce text and custom content on focus, with the tooltip closed and open
  • QA finding 1: with custom content containing a button, link or text box, Tab and Shift+Tab move past the trigger with the tooltip closed and after closing it with Escape
  • QA finding 2: with all custom content hidden by conditional visibility, the trigger has no aria-describedby and no tooltip opens; showing the content again restores both
  • QA finding 3: whitespace-only text gives no aria-describedby
  • Custom content with a data-loading widget: one request and no duplicate ids
  • Open custom content with a link or button is focusable and usable
  • Studio Pro preview shows one custom content drop zone
  • Validation message on an input inside the trigger stays announced
  • Trigger shown later through conditional visibility is announced

@HedwigAR
HedwigAR requested a review from a team as a code owner April 16, 2026 11:17
@HedwigAR
HedwigAR force-pushed the AT-239/tooltip-accessibility-improvement-screenreader branch from f727c6f to 1d9f4e3 Compare April 24, 2026 09:24
@HedwigAR HedwigAR changed the title [AT-239] Fix tooltip accessibility for screenreader [WC-3404]: Fix tooltip accessibility for screenreader Apr 24, 2026
@yordan-st
yordan-st force-pushed the AT-239/tooltip-accessibility-improvement-screenreader branch from 0a73e2d to 14f6b5a Compare November 2, 2026 15:50
@github-actions

This comment has been minimized.

@yordan-st yordan-st self-assigned this Nov 2, 2026
@github-actions

This comment has been minimized.

@yordan-st
yordan-st force-pushed the AT-239/tooltip-accessibility-improvement-screenreader branch from e333f0a to 77324f9 Compare November 4, 2026 10:45
@github-actions

This comment has been minimized.

@yordan-st yordan-st closed this Nov 9, 2026
@yordan-st yordan-st reopened this Nov 9, 2026
@github-actions

This comment has been minimized.

@yordan-st
yordan-st force-pushed the AT-239/tooltip-accessibility-improvement-screenreader branch from eecfa20 to 36de079 Compare November 9, 2026 10:40
@github-actions

This comment has been minimized.

@gjulivan

gjulivan commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

open questions on AI review is correct:

changelog updated.

@gjulivan
gjulivan force-pushed the AT-239/tooltip-accessibility-improvement-screenreader branch from 17bb09e to 1280782 Compare November 11, 2026 22:55
@github-actions

This comment has been minimized.

gjulivan
gjulivan previously approved these changes Nov 11, 2026
@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

leonardomendix
leonardomendix previously approved these changes Nov 17, 2026
samuelreichert
samuelreichert previously approved these changes Nov 18, 2026
HedwigJDoets and others added 9 commits November 18, 2026 13:21
Keep one content element in the DOM, hidden and inert while closed, so custom
content is not duplicated. Merge the tooltip id into existing aria-describedby
values and watch the trigger for late-mounted elements and attribute resets.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ptions

A nested tooltip's trigger and content got the outer tooltip's description
too, so screen readers read both texts.
@yordan-st
yordan-st force-pushed the AT-239/tooltip-accessibility-improvement-screenreader branch from af31d23 to ffa667a Compare November 18, 2026 12:28
@github-actions

Copy link
Copy Markdown
Contributor

AI Code Review

✅ Approved — no issues found


What was reviewed

File Change
tooltip-web/src/components/Tooltip.tsx Content stays in the DOM and is hidden while closed. It is added to aria-describedby on focusable trigger elements through a MutationObserver. Empty content is detected and neither described nor opened.
tooltip-web/src/components/__tests__/Tooltip.spec.tsx and snapshot Tests and snapshot updated for the new behavior
tooltip-web/CHANGELOG.md One Changed entry and one Fixed entry under Unreleased, both user-facing
tooltip-web/openspec/changes/* Three per-package OpenSpec changes (design, proposal, spec, tasks)

Skipped (out of scope): none. I did not read the new tests in detail.

CI: pending: Run code quality check, Plan E2E matrix, sigridci · unrelated failures: security/snyk (external scanner, Snyk's code and license checks pass)


Positives

  • The listener and observer lifecycle is clean. Both MutationObservers disconnect on cleanup, and the effect cleanup removes only this tooltip's id from aria-describedby, so existing values stay.
  • Nested tooltips are handled: elements are matched to their owning .widget-tooltip, so an inner tooltip's description isn't applied to the outer one.
  • The PR description and OpenSpec changes state the behavior change (custom content now mounts at page load), and the changelog entry for it is written for app developers.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants