[wp-trac] [WordPress Trac] #50486: Improve the admin notices accessibility

[WordPress Trac]

#50486: Improve the admin notices accessibility
--------------------------------------+--------------------------------
 Reporter:  afercia                   |       Owner:  joedolson
     Type:  defect (bug)              |      Status:  accepted
 Priority:  normal                    |   Milestone:  Future Release
Component:  Administration            |     Version:
 Severity:  normal                    |  Resolution:
 Keywords:  needs-patch dev-feedback  |     Focuses:  ui, accessibility
--------------------------------------+--------------------------------

Comment (by sanket.parmar):

 Hello everyone,

 I've reviewed this ticket and all comments, including the related work in
 #47656 and #57791. Given that this has been bumped across several
 milestones, I'd like to propose breaking this into smaller, independently
 mergeable pieces rather than tackling it all at once.

 == Proposed incremental plan ==

 === Step 1 — Audit and migrate hardcoded inline notices (PHP) ===

 As noted in comment:10, some notices are hardcoded mid-page (e.g. `wp-
 admin/plugin-editor.php`) rather than hooked to `admin_notices`. These
 will never benefit from any landmark or skip-link improvements unless
 they're pulled into the standard hook first.

  * Audit all `wp-admin/*.php` files for inline `<div class="notice...">`
 output that is ''not'' via the `admin_notices` action
  * Refactor those to use the hook, or at minimum ensure they render after
 the main `<h1>`

 '''Why this is ordered first:''' This is a prerequisite for Step 2 only.
 If we add the landmark wrapper before fixing hardcoded notices, those
 notices will still render ''outside'' the landmark — giving false
 confidence that accessibility is fixed when it isn't for those edge-case
 admin pages. That said, Step 1 may turn out to be minor or a non-issue
 depending on what the audit finds.

 === Step 2 — Wrap the notices region in a landmark + add a skip link (PHP)
 ===

 In `wp-admin/admin-header.php`, the `admin_notices` / `all_admin_notices`
 actions can be wrapped in a labelled landmark:

 {{{
 <div id="wp-admin-notices" role="complementary" aria-label="<?php
 esc_attr_e( 'Admin notices', 'default' ); ?>">
     <?php do_action( 'all_admin_notices' ); ?>
     <?php do_action( 'admin_notices' ); ?>
 </div>
 }}}

 And a conditional skip link added alongside the existing "Skip to main
 content" one:

 {{{
 <?php if ( /* notices are present */ ) : ?>
 <a class="skip-link screen-reader-text" href="#wp-admin-notices">
     <?php esc_html_e( 'Skip to notices', 'default' ); ?>
 </a>
 <?php endif; ?>
 }}}

 '''Who this helps:''' Keyboard and screen reader users who currently have
 no way to navigate directly to the notices region.

 === Step 3 — Prepend notice count to `<title>` when notices exist (PHP)
 ===

 Screen readers announce the page `<title>` immediately after load. If
 there are notices, a short prefix helps:

 {{{
 /* translators: %d: number of admin notices */
 $title_prefix = sprintf( _n( '[%d notice]', '[%d notices]', $notice_count,
 'default' ), $notice_count );
 $admin_title  = $title_prefix . ' ' . $admin_title;
 }}}

 '''Why this is independent:''' This doesn't depend on the landmark, the
 skip link, or any JS work. It could be done first, last, or in parallel
 with any other step. Low implementation risk, high screen reader impact.

 === Step 4 — Ensure JS-injected notices carry ARIA live region roles ===

 All notices inserted into the DOM via JavaScript should carry either
 `role="alert"` (for errors — assertive announcement) or `role="status"`
 (for success/info — polite announcement). This is the standard WCAG 2.1
 live region pattern.

 This can be enforced in the `wp-admin/js/` notice-handling scripts (e.g.
 `common.js` dismissible notice logic) and in the `@wordpress/components`
 `Notice` component on the Gutenberg side.

 '''Why this is independent:''' This is entirely separate from the PHP-side
 work. It touches different files and could be tackled by a different
 contributor — or the Gutenberg team — simultaneously and without waiting
 for Steps 1–3.

 === Step 5 (complementary) — JS MutationObserver + admin bar summary ===

 As suggested in comment:41 by @joedolson, a `MutationObserver` script
 could:

  * Watch the `#wp-admin-notices` region for new notices
  * Display a count badge in the admin bar
  * Provide a toggleable panel listing all current notices

 This is a non-breaking enhancement that retroactively improves third-party
 plugin notices ''without'' requiring any changes to how those plugins
 register their notices. It doesn't depend on any of the prior steps,
 though its value is higher once Steps 1–2 have normalised where notices
 render.

 ----

 == Do we need all of these? ==

 No. Each step addresses a different user group and failure mode:

 ||= Step =||= Who benefits =||= Standalone value? =||
 || 1 — Audit inline notices || Everyone || Low alone; only needed to make
 Step 2 complete ||
 || 2 — Landmark + skip link || Keyboard & screen reader users ||
 '''High''' ||
 || 3 — Title prefix || Screen reader users || '''High, minimal effort'''
 ||
 || 4 — ARIA live regions (JS) || Screen reader users (dynamic notices) ||
 '''High, fully independent''' ||
 || 5 — Admin bar observer || All users || Medium, nice-to-have ||

 The '''minimum viable improvement is Steps 2 + 3'''. Together they fix the
 two most impactful screen reader problems — landmark navigation and page
 title announcement — with purely PHP changes and minimal regression risk.
 That alone would be meaningful, shippable progress for this ticket.

 Step 4 is the most important for the block editor side and can be handled
 independently, potentially by the Gutenberg team.

 Steps 1 and 5 can be decided based on what the audit reveals and available
 bandwidth.

 ----

 I'm happy to put together a patch for Steps 2 and 3 as a starting point.
 Does this approach align with @joedolson's current thinking?

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/50486#comment:42>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform