[johnfinnerty-nz]

What?

Closes #55088.

Keep lightbox captions available to assistive technology while keeping them visually hidden. Exclude the duplicate animation image from the accessibility tree.

Why?

display: none removes the caption from the accessibility tree. This loses useful context, especially when an image has an empty alt attribute and its description is in the caption.

How?

Store the source caption as plain text, render one visually hidden figcaption for the selected image, and hide it when there is no caption. Mark the duplicate animation figure aria-hidden="true" and give its image an empty alt.

The Playwright regression checks caption text, duplicate-image exclusion, safe text rendering, and navigation between captioned and uncaptioned images.

Testing Instructions

1. Publish a gallery with lightbox enabled. Include an image with an empty alt attribute and a formatted caption, an image with a different caption, and an image without a caption.
2. Open the lightbox and inspect its accessibility tree. The selected caption should be available once, without a duplicate named animation image.
3. Navigate forward and back. The caption should follow the selected image, disappear for the uncaptioned image, and return when navigating back.
4. Confirm the caption stays visually hidden and its content is rendered as text rather than injected HTML.

Testing Instructions for Keyboard

Use Tab and Enter to open the lightbox. Navigate its controls using the keyboard, then close it and check focus return. With a screen reader, read through the dialog and check that the selected caption is available without duplicate image announcements. Repeat after changing images.

Recorded validation

The existing validation comment for 64515d2 reports a passing focused Chromium/Playwright regression in a local WordPress Docker environment, production build, typecheck, scoped JavaScript lint, PHP syntax, PHP coding standards, and commit hooks. This description update did not rerun those checks. Manual screen-reader testing remains unverified.

Screenshots or screencast

None attached. The caption remains visually hidden; the accessibility tree and screen-reader behavior are the relevant checks.

Use of AI Tools

Codex assisted with implementation and the recorded local automated validation. ChatGPT assisted with reviewing and editing this description. Manual accessibility testing remains outstanding.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @johnfinnerty-nz.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: johnfinnerty-nz.

Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: artemiomorales <artemiosans@git.wordpress.org>
Co-authored-by: joedolson <joedolson@git.wordpress.org>
Co-authored-by: afercia <afercia@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

🤖 PR meta 🤖

👋 Welcome

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @johnfinnerty-nz! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

🏷️ Labels

This pull request needs exactly one label indicating its type, and has 0.

• Required: any label starting with [Type].
• Found: none.

Read more about Type labels in Gutenberg. If you cannot add labels yourself, a reviewer can do it for you.

[johnfinnerty-nz]

Performing docker testing shortly

[johnfinnerty-nz]

Pushed the correction in 64515d2.

Automated validation, run with Codex against a local WordPress instance in Docker Desktop:

• Chromium/Playwright: the caption regression passed, including accessible caption text, exclusion of the duplicate image, safe text rendering, and navigation to an uncaptioned image and back.
• Production build, typecheck, scoped JavaScript lint, PHP syntax and repository PHP coding standards passed. Commit hooks also passed.

This was one focused browser regression, not the full E2E suite or a manual screen-reader test.

[mirka]

This still hides the caption, using clip-path and a 1px box instead of display: none. On #55088, Joe Dolson said that if the caption is available to a screen reader while the lightbox is open, it should also be visible, and Andrea Fercia asked to stop hiding it. The thread never agreed to a visually hidden caption. Any reason why this direction was chosen here?

[johnfinnerty-nz]

Thanks, that makes sense. I’ve had another go at this in #83325, with the caption visible below the image and links and formatting kept intact. Longer captions can scroll, including with the keyboard.

It’s still a draft as it needs proper screen reader testing. I’d be interested in your thoughts on the layout too, especially with #81500 looking at the same problem.