Skip to content

Administration: Clean up counter item accessible names - #12850

Open
sanketio wants to merge 2 commits into
WordPress:trunkfrom
sanketio:feat/65793
Open

Administration: Clean up counter item accessible names#12850
sanketio wants to merge 2 commits into
WordPress:trunkfrom
sanketio:feat/65793

Conversation

@sanketio

@sanketio sanketio commented Aug 5, 2026

Copy link
Copy Markdown

In the admin menu and toolbar, several items show a count in a circle (Updates, Comments, Themes, Plugins, Site Health). Today the count is exposed inconsistently in each item's accessible name — Updates/Themes/Plugins/Site Health leak the raw number ("Updates 2"), Comments folds descriptive text into the name ("Comments 3 Comments in moderation"), and the icon-only toolbar items use the count text as the whole name. The result: the accessible name doesn't match the visible label, so voice-control users can't activate the item by name, and announcements are inconsistent.

This standardizes them so each link's accessible name is just the item name ("Updates", "Comments", …) and the count is exposed as a description via aria-describedby, per the approach in the ticket.

How it works — for every counter: the visible bubble is aria-hidden="true"; the count text lives in a visually-hidden screen-reader-text element with a unique id; the link references it with aria-describedby.

  • Admin menu (menu.php): each counter title carries a marker description span; menu-header.php generically lifts its id onto the link (top-level and submenu anchors) and strips the span from the repeated wp-submenu-head so the id is never duplicated.
  • Toolbar (admin-bar.php): Comments/Updates get an explicit hidden name plus a described-by count span; class-wp-admin-bar.php allows aria-describedby as a node meta attribute.

JS-updated classes (comments-in-moderation-text, updates-available-text, pending-count, *-count) are preserved so live count updates keep working.

How to test

  1. As an admin, load the Dashboard.
  2. Inspect the menu links for Updates, Comments, Themes, Plugins, Tools → Site Health, and the toolbar Comments/Updates items.
  3. Confirm each link has aria-describedby → a hidden screen-reader-text span, the number span is aria-hidden="true", and each description id appears exactly once in the DOM.
  4. With a screen reader, confirm the link is announced as its name plus the count as a description.

Automated teststests/phpunit/tests/admin/wpMenuOutput.php (new, describedby wiring + duplicate-id regression) and additions to tests/phpunit/tests/adminbar.php (toolbar + meta whitelist).

Open questions — exact wording of the new hidden strings; and the menu Updates/Themes/Plugins descriptions aren't yet refreshed by the AJAX count updater (Comments and toolbar are), so a follow-up would keep the described count from going stale.

Trac ticket: https://core.trac.wordpress.org/ticket/65793

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 4.8
Used for: Root cause analysis, locating the affected menu/toolbar rendering paths, initial patch and test implementation; final implementation, accessibility markup review, and correctness of the capability guards reviewed and edited by me.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props sanketparmar.

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

@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant