[HedwigAR]

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 visually hidden and inert 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.
• Uses the selected render method to decide whether content exists.
• 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, and replaced AGENTS.md with OpenSpec changes in openspec/changes/.

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 needs a separate ticket.

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
• Custom content with a data-loading widget: one request and no duplicate ids
• Custom content with a link or button: closed content takes no focus, open content is 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

[gjulivan]

open questions on AI review is correct:

• Tooltip stays in the DOM when hidden -> this is alligned with https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tooltip_role , css only approach to hide tooltip,

• This cause that tooltip custom content is rendered on load. this should be mentioned in changelog.

changelog updated.

[github-actions]

AI Code Review

✅ Approved — no issues found

---

What was reviewed

File	Change
tooltip-web/src/components/Tooltip.tsx	The tooltip content element now stays in the DOM (visually hidden and inert while closed). Its id is added to aria-describedby on focusable trigger elements. A MutationObserver covers late-mounted elements and attribute resets.
tooltip-web/src/components/__tests__/Tooltip.spec.tsx and snapshot	New tests and updated snapshot
tooltip-web/src/ui/Tooltip.scss	Visually hidden style for the closed state, using a widget-tooltip- prefixed class
tooltip-web/CHANGELOG.md	Added Changed and Fixed entries under Unreleased
tooltip-web/openspec/changes/*	Two OpenSpec changes, located in the package as required

Skipped (out of scope): the package.json and package.xml version fields, the e2e PNG snapshots, and generated files.

CI: pending: sigridci · unrelated failures: security/snyk (external scanner)

---

Questions

• The changelog notes that custom content now mounts at page load. Have you checked that data widgets inside a tooltip, such as a data view or list view, don't cause extra requests or duplicate ids once the tooltip is open? This is the "one request and no duplicate ids" item in your manual QA list.

---

Positives

• The MutationObserver is disconnected on cleanup, and cleanup removes only this tooltip's id from aria-describedby. Existing values such as validation messages are kept.
• Preview mode is skipped for the aria-describedby handling, so the Studio Pro preview is unaffected.
• The changelog entries are written for app developers, and the behavior change is stated openly.