Fix: Content Guidelines: UX/UI Accessibility issues

[hbhalodia]

What?

Part of #80280

Why?

• PR fixes the A11y issues to the content guidelines experiment.

How?

PR fixes the issues that are shared in the mentioned issue.

Currently Fixed issues in the PR

• "Actions" should be an H2 heading to fix the hierarchy. Currently, "Site", "Copy", etc. are at the same level as "Import", "Export, etc. but they are visually at different hierarchical levels.
• Textarea fields have hidden labels that don't match any visible text, impacting voice command users and creating potential confusion for support. Recommend either making the existing label visible or using aria-labelledby pointing to the existing visible text.
• Block guidelines: when adding/saving a guideline, the buttons use plural "Save Guidelines", "Add Guidelines", but the action is really singular - you're adding only one guideline.
• Block guidelines: editing a block guideline, the button has aria-pressed, which isn't the appropriate ARIA status; it should have aria-haspopup with a value of dialog, instead.
• Block guidelines: button is read as table with 1 row and 2 columns row 1 column 1 Paragraph toggle button pressed ; this is because the button is inside a grid role, which forces a lot of excess semantics. Given the simplicity of this structure, I don't think that this is an appropriate organization.
• Import Guidelines button fails WCAG "Label in Name" requirement. The visible text must be included in the name of the control. The aria-label is 'Import Guidelines', and the visual text is 'Upload'.
• Export Guidelines button fails WCAG "Label in Name" requirement. The aria-label is "Export Guidelines" and the visual text is 'Download'.
• The 'View History' button passes WCAG, but in my opinion the extra 'of guidelines' isn't necessary; this should be clear from context and the aria-describedby text.
• Block Guideline: Focus lost abruptly on block guideline item removal. See - Content Guidelines: UX/UI Accessibility issues #80280 (comment)

Testing Instructions

1. Enable the 'Guidelines' experiment at Gutenberg > Experiments
2. Go to Settings > Guidelines
3. Check for the above checked issues.

Testing Instructions for Keyboard

• Check with keyboard and voice over.

Screenshots or screencast

Focus lost fix

Screen.Recording.2026-07-15.at.3.46.34.PM.mov

Use of AI Tools

• Claude Code.
• Opus 4.8
• Used for checking the A11y issue mentioned and asked to fix at code level. Implementation was reviewed by me.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: [Focus] Accessibility (a11y).

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[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.

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

Co-authored-by: hbhalodia <hbhalodia@git.wordpress.org>
Co-authored-by: aagam-shah <aagam94@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

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

[aagam-shah]

Thanks @hbhalodia - this looks really nice, and it's a good start on the list.

One doubt on the labelPosition: 'top' change: each section now shows a visible field label directly under the accordion header, so the "Site" section reads "Site" followed by "SITE GUIDELINES". The label fix itself is right, but the repetition looks a bit off.

@joedolson the issue suggested either making the label visible or pointing aria-labelledby at existing visible text. Since the header already says "Site", would you be okay with keeping the label visually hidden but changing its text to match the header (accessible name "Site")? Or is the visible label the better option here? One consideration: the accordion toggle button is also named "Site", so matching the header would give two controls the same name for voice users.

cc @jasmussen for the visual side.

[jasmussen]

It seems this could better use feedback possibly by @WordPress/gutenberg-components.

On the visuals, I'd suggest simpler CTAs: "Save" and "Clear", instead of repeating the "guidelines" term. And should they be right-aligned, with the primary button rightmost so it's the 2nd focus stop?

[mirka]

@hbhalodia To help prioritize, can you tell me whether this is something that needs to be backported to 7.1 or not?

[hbhalodia]

Hi @mirka, I do not think so this should be backported to wp/7.1. But this can be confirmed mostly by @aagam-shah or @gziolo.

Thanks,

[t-hamano]

This feature is not included in 7.1, so this PR should not be backported.

https://make.wordpress.org/core/2026/06/22/merge-proposal-guidelines-built-on-knowledge/#comment-49029