Make WordPress Core

Opened 6 years ago

Last modified 3 weeks ago

#50486 reopened defect (bug)

Improve the admin notices accessibility

Reported by: afercia Owned by: joedolson
Priority: normal Milestone: Future Release
Component: Administration Version:
Severity: normal Keywords: needs-dev-note
Cc: Focuses: ui, accessibility

Description

Follow-up to #47656. See also #50442/

The admin notices accessibility has room for improvements.

Currently, all the admin notices are just text printed out on the admin pages. They have no special semantics. There are no mechanisms to inform users some important information is printed on the page other than visuals. There are no methods to navigate directly to admin notices nor established standards on their placement.

This way, users with accessibility needs will likely miss important information, as they may have no clue whether and where these messages are printed out.

Depending whether the admin notices are PHP-generated notices that appear after a page load or JavaScript-generated ones that are "injected" into the DOM, there are ways to improve their accessibility. At the very least, the following improvements should be considered, some of them were mentioned in #47656.

All notices

  • establish standards for the admin notices placement in the page: there should be one, well defined, area where notices are printed out (recommended: after the main H1)
  • establish standards for the admin notices content: see the discussion related to the "text prefix" on #47656 and #50442
  • the above item should apply to the whole WordPress UI, including the block editor
  • "inline" notices (the ones printed out in the middle of the page): make a decision whether to keep them or allow only notices at the top of the page
  • if "inline" notices are kept, explore ways to make them more accessible
  • worth considering admin notice should be visually prominent and appear within the initial viewport anyways
  • consider the introduction of a dedicated PHP class with methods to get / print admin notices and additional features, also keeping into consideration ​the WP Notify project and the recent ​call for feedback on the WP Notify v1 requirements document

PHP notices

  • prepend to the document title a short text to inform users there are notices and their number: the document title is the first thing screen readers announce after a page load
  • the notices should be printed out after the main H1 heading as that's the part of the content with higher chances to be navigated to
  • define the page area where notices are printed out with an ARIA role that's also a landmark role, e.g. complementary (an <aside> element) or other role that is a landmark
  • add a new "skip link" after the "Skip to main content" one to allow all keyboard users to jump to the notices area: this skip link should only be printed out when there are notices

JavaScript notices

  • all notices injected in the DOM should have an ARIA role alert or status depending on their "politeness" level, so that they're automatically announced by screen readers

Any additional suggestion and/or technique to improve the admin notices accessibility is very welcome.

Change History (101)

This ticket was mentioned in ​Slack in #accessibility by ryokuhi. ​View the logs.


5 years ago

This ticket was mentioned in ​Slack in #feature-notifications by ryokuhi. ​View the logs.


5 years ago

This ticket was mentioned in ​Slack in #feature-notifications by raaaahman. ​View the logs.


5 years ago

#4 @psykro
5 years ago

@afercia thanks for detailing these issues. To clarify what you have raised here, I have a couple of questions.

"inline" notices (the ones printed out in the middle of the page): make a decision whether to keep them or allow only notices at the top of the page

  1. Can you give me an example of this type of inline notice?

the notices should be printed out after the main H1 heading as that's the part of the content with higher chances to be navigated to

  1. Is this not currently the case? If I use the example notice from the official documentation:
<?php
function sample_admin_notice__success() {
        ?>
        <div class="notice notice-success is-dismissible">
                <p><?php _e( 'Done!', 'sample-text-domain' ); ?></p>
        </div>
        <?php
}
add_action( 'admin_notices', 'sample_admin_notice__success' );

it's rendered just below the main h1 of that admin page.

#5 follow-up: @ryokuhi
5 years ago

Hello @psykro,
You can find a screenshot in ticket:47656#comment:29: I think this is an example both of an inline notice and of a notice that is printed in the middle of the page and not right after the H1 element.

This ticket was mentioned in ​Slack in #accessibility by ryokuhi. ​View the logs.


5 years ago

This ticket was mentioned in ​Slack in #feature-notifications by raaaahman. ​View the logs.


5 years ago

#8 in reply to: ↑ description @raaaahman
5 years ago

Replying to afercia:

It would be worth coordinating the effort on that class with the WP Notify project indeed. If we manage to define a common interface for the 'get/set' methods, we may be able to change its implementation for the new dispatch mechanism when it become fully operational. We are going for a [Repository](​https://github.com/WordPress/wp-notify/blob/develop/includes/persistence/interface-wp-notify-notification-repository.php), would this interface match your needs?

This ticket was mentioned in ​Slack in #feature-notifications by jon_bossenger. ​View the logs.


5 years ago

#10 in reply to: ↑ 5 @psykro
5 years ago

Replying to ryokuhi:

Hello @psykro,
You can find a screenshot in ticket:47656#comment:29: I think this is an example both of an inline notice and of a notice that is printed in the middle of the page and not right after the H1 element.

Thanks, @ryokuhi I see that this code is in the /wp-admin/plugin-editor.php file, like 283

​https://github.com/WordPress/wordpress-develop/blob/6d574d7cabfaf6cc9797d2119ba1a10d9cd78fa3/src/wp-admin/plugin-editor.php#L283

The "problem" we have here is that it seems there are two ways that WordPress core renders admin notices from the PHP side.

  1. using the admin_notices action hook
  2. hardcoded inline in specific pages (like the plugin-editor.php)

So the first, and most important step will be to look for any instances where notices are hardcoded in this way, and replace them with admin_notices callback functions.

Once all admin notices are registered in the same way, we can apply rules to all admin notices, and be sure that they will all receive the same updates/changes.

Please let me know if you have any questions here.

Version 0, edited 5 years ago by psykro (next)

This ticket was mentioned in ​Slack in #accessibility by alexstine. ​View the logs.


4 years ago

#12 @alexstine
4 years ago

  • Keywords needs-patch added

#14 @joedolson
4 years ago

  • Owner set to joedolson
  • Status new → accepted

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


4 years ago

#16 @joedolson
4 years ago

  • Milestone Awaiting Review → 6.3

This ticket was mentioned in ​Slack in #core by oglekler. ​View the logs.


3 years ago

#18 @oglekler
3 years ago

  • Keywords dev-feedback added
  • Milestone 6.3 → 6.4

This ticket was discussed in the recent bug scrub.

It looks like this cannot be ready to the Beta 1 and due to the existing project Feature notifications in needs to be revised, more info in #comment:8 but for now I am moving this ticket to 6.4

Additional props @mrinal

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


3 years ago

This ticket was mentioned in ​Slack in #core by oglekler. ​View the logs.


3 years ago

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


3 years ago

This ticket was mentioned in ​Slack in #core by marybaum. ​View the logs.


3 years ago

#23 @marybaum
3 years ago

Thanks to a note @joemcgill surfaced from @joedolson, this can move forward. That note is at ​https://wordpress.slack.com/archives/C02RP4X03/p1692376124664849

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


3 years ago

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


3 years ago

#26 @joedolson
3 years ago

  • Milestone 6.4 → 6.5

This will not be ready for 6.4, but following the work done in #57791 during 6.4, I think it's plausible for 6.5.

#27 @joedolson
3 years ago

Also pinging @costdev on this ticket, as it's another thing related to #57791 to look at.

#28 @swissspidy
3 years ago

@joedolson Is this on your radar still for 6.5? Looks like a punt candidate given the lack of activity.

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


3 years ago

#30 @joedolson
3 years ago

  • Milestone 6.5 → 6.6

Moving to 6.6; this will need more time.

This ticket was mentioned in ​Slack in #core by oglekler. ​View the logs.


2 years ago

This ticket was mentioned in ​Slack in #accessibility by rcreators. ​View the logs.


2 years ago

#33 @sabernhardt
2 years ago

  • Milestone 6.6 → Future Release

I'm moving this to Future Release, but please add a numbered milestone as soon as the ticket has more activity.

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


2 years ago

#35 @joedolson
2 years ago

  • Milestone Future Release → 6.8

This ticket was mentioned in ​Slack in #core by audrasjb. ​View the logs.


21 months ago

#37 @joedolson
21 months ago

  • Milestone 6.8 → 6.9

Moving this to 6.9. Piece by piece, admin notices are getting improved, but the task this ticket represents needs a broader assessment.

#38 @davidbaumwald
14 months ago

  • Milestone 6.9 → Future Release

It seems this ticket hasn't seen any momentum in a few years, just being punted to the next milestone several consecutive milestones.

Given that, moving this to Future Release. This can be pulled into a specific milestone if someone wishes to assume ownership during that cycle.

If any committer or maintainer feels this can be managed before 6.9's RC phase, feel free to pull i back into the milestone.

#39 @joedolson
13 months ago

  • Milestone Future Release → 7.0

This ticket was mentioned in ​Slack in #core by audrasjb. ​View the logs.


9 months ago

#41 @joedolson
9 months ago

  • Milestone 7.0 → Future Release

Bumping to future release. There's definitely things to be changed here, but there are simply a lot of notices.

One possible plan is to set up an observer script that can get all notices on the page and add a toggle to the adminbar that can provide access to them or summarize them. This would do a lot to increase the availability of notices, without requiring any significant changes to how individual notices are created or displayed.

#42 @sanket.parmar
7 months ago

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?

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


7 months ago

#44 @joedolson
7 months ago

  • Milestone Future Release → 7.1

Thanks for all your thoughts @sanketparmar!

There are a few details that I would probably change; in particular, I'd probably want to use an aside element instead of a div with role="complementary". But these are minor details that can be worked out in development.

I have a partial PR already for some of the outstanding admin notices to adjust. It's woefully out of date, but I could refresh it and complete it. ​https://github.com/WordPress/wordpress-develop/pull/5225.

The inline notices are definitely separate. I'm wondering if what we actually want to do is turn those into two separate classes of notices. There are sound reasons for using inline notices - in particular, for dynamic actions. We can consider that all inline notices should be delivered dynamically & should trigger a spoken notification, but not be included in the same class as notices that are loaded during a page load. They'll each need individual consideration, however, as there are a lot of variations in how these are used in core...

With your work on detailing a process and willingness to help out, I'm going to go ahead and milestone this for 7.1. It would be a great set of changes to get done.

#45 @joedolson
7 months ago

  • Keywords dev-feedback removed

#46 @sanket.parmar
7 months ago

Thank you for the feedback and for milestoning this for 7.1, @joedolson — great to have a concrete target!

On <aside> vs <div role="complementary">

Completely agree — native HTML5 semantics are always preferable over ARIA role overrides. An <aside> with an aria-label gives the same landmark without depending on ARIA alone, and is more robust across different AT implementations. Happy to use that in the patch.

On the existing PR

I had a look at ​PR #5225 — the branch was deleted when it was closed in March 2024, so there's nothing to rebase from directly. That said, the PR diff is still visible and gives a clear picture of the direction and scope of the changes. My suggestion would be to start a fresh PR using the closed PR as a reference for which notices were covered and how they were approached, rather than trying to recover the old code.

  • Would you be taking the lead on that, or would it help if I put together a fresh PR based on what was in that old PR?
  • Are there any notices from that PR that you'd want to handle differently now, given the two years since it was closed?

Happy to take on whichever part is most useful.

On inline / dynamic notices as a separate class

This distinction makes a lot of sense. The way I read it, there would be two separate categories going forward:

  • Page-load notices — PHP-generated, rendered once after page load, covered by the landmark + skip link + title prefix approach
  • Dynamic/inline notices — JS-injected or triggered by user actions mid-page, each needing individual assessment, and delivering a spoken notification via role="alert" or role="status" depending on urgency

The second category being treated individually is the right call given how varied the usages are across core. It also means the two tracks can progress independently without blocking each other.

Would it make sense to open a child ticket specifically for the dynamic notices audit, so the two tracks can be tracked and reviewed separately? That would help keep this ticket focused on the page-load side and avoid it ballooning in scope again.

This ticket was mentioned in ​PR #11923 on ​WordPress/wordpress-develop by ​@khokansardar.


6 months ago
#47

  • Keywords has-patch has-unit-tests added; needs-patch removed

Wrap PHP admin notices in a complementary landmark, prepend the notice count to the admin document title, add a conditional skip link, and assign ARIA live region roles to standardized and JavaScript-generated notices.

Props afercia, joedolson.
Fixes #50486.

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


5 months ago

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


4 months ago

#50 @joedolson
4 months ago

  • Keywords early added
  • Milestone 7.1 → 7.2

I think this is looking very promising, but I think that at this stage of the release cycle, it's too large to be a safe addition. I suspect there will be some side effects we haven't anticipated. But there's enough work done that I think it would be great to try and land early in 7.2.

​@ugyensupport commented on ​PR #11923:


3 months ago
#51

Per the note above, I've posted the full test report on the Trac ticket rather than here. Short summary: the core features (landmark, skip link, title count, ARIA roles) work correctly for server-rendered notices and the PR's own tests pass, but I found three integration issues its tests don't cover — a hook-timing shift (admin_notices now fires before admin_enqueue_scripts/set_parentage()), JS-driven update/bulk-action notices not actually landing inside the new #wp-admin-notices landmark on real pages, and false-positive notice counting from unrelated markup. Details and repro steps on Trac.

​@ugyensupport commented on ​PR #11923:


3 months ago
#52

Per the note above, I've posted the full test report on the Trac ticket rather than here. Short summary: the core features (landmark, skip link, title count, ARIA roles) work correctly for server-rendered notices and the PR's own tests pass, but I found three integration issues its tests don't cover — a hook-timing shift (admin_notices now fires before admin_enqueue_scripts/set_parentage()), JS-driven update/bulk-action notices not actually landing inside the new #wp-admin-notices landmark on real pages, and false-positive notice counting from unrelated markup. Details and repro steps on Trac.

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


3 months ago

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


8 weeks ago

#55 @williampatton
8 weeks ago

I spent some time testing this over the last week or so. I had claude take my mess of notes and form reproductions and put them into something readable. Apologies in advance for the AI speak. Everything below is the AI write up from my testing.

Test report: PR 11923 against real-world notice-registration patterns

Tested against WP core 7.1 with PR 11923 applied. Summary: the landmark/title-count/ARIA mechanism works for some notices, but two categories of very common notices are unaffected or actively regressed.

1. Notices printed via direct wp_admin_notice()/settings_errors() calls bypass the mechanism entirely

Many of core's most common notices are printed inline in a page template rather than via the admin_notices/all_admin_notices hooks that wp_capture_admin_notices() listens on:

  • "Plugin activated." (wp-admin/plugins.php:736)
  • "Settings saved." (Settings → General, via settings_errors())

These get no landmark, no title count, no ARIA role — completely untouched by the patch. This is the same gap flagged in comment:10 (2020) and comment:42's "Step 1 — audit hardcoded inline notices," which was called out as a prerequisite for the landmark work. It doesn't look like this PR addressed it.

Repro: Activate/deactivate any plugin from plugins.php, or save Settings → General. Inspect the resulting notice — it's outside #wp-admin-notices and the <title> isn't prefixed.

2. A properly-hooked notice still doesn't end up inside the landmark

new_user_email_admin_notice() (wp-includes/user.php) is genuinely registered via add_action('admin_notices', ...). Triggering it (via profile.php?updated=true with a pending _new_email) shows the title correctly gets the (1 notice) prefix and the notice HTML is captured server-side with role="status" — but in the rendered page, <aside id="wp-admin-notices"> is empty and the notice renders as a sibling outside it. Root cause not fully isolated on my end; worth a look with a JS-execution trace.

3. update_nag lands in the landmark, but is silently excluded from the title count

Faked a core-update-available transient. The "WordPress X is available!" notice does render correctly inside <aside id="wp-admin-notices"> with role="status" — so the core mechanism isn't broken across the board. But the title never gets the count prefix, because update_nag sets additional_classes => array('update-nag', 'inline'), and wp_count_admin_notices_from_html() excludes anything carrying .inline from the count (admin-notices.php:112). That .inline class is a long-standing convention meaning "don't let common.js relocate this" — unrelated to whether the notice should count toward the screen-reader-facing summary. The counting regex conflates the two meanings and undercounts.

4. admin_notices hooks registered from inside in_admin_header vanish completely (not just mis-placed)

This is the one I'd flag as most important. wp_capture_admin_notices() runs at admin-header.php:81, but do_action('in_admin_header') doesn't fire until line 279. Registering an admin_notices callback from inside an in_admin_header callback is a legitimate, documented pattern — commonly used to show a transient-backed notice correctly after a redirect (e.g. after an admin-post.php handler sets a transient and redirects back):

add_action(
    'in_admin_header',
    function () {
        add_action( 'admin_notices', function () {
            $notice = get_transient( 'my_plugin_notice_' . get_current_user_id() );
            if ( $notice ) {
                delete_transient( 'my_plugin_notice_' . get_current_user_id() );
                printf( '<div class="notice notice-%s"><p>%s</p></div>', esc_attr( $notice['type'] ), esc_html( $notice['message'] ) );
            }
        } );
    },
    1000
);

With PR 11923 applied, a notice registered this way doesn't render anywhere on the page at all — not landmarked, not outside the landmark, just silently dropped — because wp_capture_admin_notices() already ran and cached its (empty) result before the callback was even registered.

This is a concrete, reproducible instance of the hook-timing shift ugyensupport already flagged in comment:51 / comment:52 ("admin_notices now fires before admin_enqueue_scripts/set_parentage()"). It's worth noting this pattern is not exotic — deferring admin_notices registration to in_admin_header (or later) specifically to read post-redirect transient state is a common approach in plugins that need to show a "your action succeeded" message. Any plugin using it will have that notice silently disappear entirely under this PR, which is a worse outcome than the current "notice shown but not specially announced" behavior.

Repro: Register an admin_notices callback from inside in_admin_header (as above) that prints based on a transient; set that transient directly (or via whatever action normally sets it) and reload any wp-admin screen. The notice never appears in the DOM.

Takeaway

The landmark/count/role mechanism works when a notice is hooked to admin_notices/all_admin_notices before in_admin_header fires (finding 3 shows a passing case, modulo the counting bug). But a large share of real-world notices — both core's own hardcoded ones (finding 1) and legitimately-hooked-but-deferred ones from plugins (finding 4) — fall outside that window entirely, and finding 4 is a regression from current behavior rather than neutral. Given the milestone is close, it might be worth confirming the extent of finding 4 across popular plugins before this lands, since "notice silently disappears" is a worse failure mode than "notice appears but isn't specially announced."

This ticket was mentioned in ​Slack in #core by im3dabasia1. ​View the logs.


8 weeks ago

#57 @im3dabasia1
8 weeks ago

As per today's 7.2 bug scrub:

I see some testing has come in recently on the [PR]​https://github.com/WordPress/wordpress-develop/pull/11923 and surfaced a few issues. @joedolson, could you take a look and let us know if this is still safe to land in 7.2, or if it needs another round first?

#58 @afercia
7 weeks ago

In #66161 and ​the linked PR there, I'm proposing to refactor settings_errors() so that it uses wp_admin_notice() internally. By doing so, all the settings notices will also fire the hook wp_admin_notice. That may help the effort here to collect all the notices in a consistent, reliable, way.

This ticket was mentioned in ​PR #13671 on ​WordPress/wordpress-develop by ​@joedolson.


7 weeks ago
#59

This PR is an alternative to ​https://github.com/wordpress/wordpress-develop/pull/11923.

This PR only attempts to handle notices that are passed through wp_get_admin_notices(), which the intention that all core admin notices should do this. This simplifies the code by not attempting to capture all legacy variants that a notice could conceivably appear in.

It doesn't capture JS produced notices, but those already need to be handled separately.

It doesn't attempt to render the notices in a different location in PHP, keeping the existing DOM relocation, but wrapping the notices that are moved in an aside to provide better navigation.

This doesn't include a conditional skip link to navigate to those, although that could be added.

It also doesn't add ARIA roles into the PHP produced notices - these should not be there; ARIA is only necessary for empty notices where information will be inserted or modified with JS.

This should be considered a draft, although reviews are welcome. It is not in any way ready for merge.

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

Use of AI Tools

AI assistance: Yes
Tool(s): GitHub Copilot
Model(s): Claude Sonnet
Used for: Initial code skeleton; final implementation was reviewed and significantly modified by me.
-->

​@joedolson commented on ​PR #13671:


7 weeks ago
#60

@pattonwebz @afercia This is a rough draft of some alternative implementation for notices. Not thoroughly tested at this phase, but feel free to hammer at it.

​@afercia commented on ​PR #13671:


7 weeks ago
#61

Some more thoughts:

So far, this PR only works for notices that are printed via wp_admin_notice() / wp_get_admin_notice().

Other notices will not be collected. For example all the ones in the Settings pages that are rendered via settings_errors(). ​https://github.com/WordPress/wordpress-develop/pull/13669 would help with this because it refactors settings_errors() to use wp_admin_notice() internally. It can be merged into this PR for testing purposes and tested on the Settings pages.

There are other hooks that are used to render notices. As far as I can tell, they don't pass arguments, they are just hooks. As such, the notice can only be collected if the callback actually uses wp_admin_notice() internally. For example these are in various places in Core and will need to be checked:

add_action( 'admin_notices', 'default_password_nag' ); -> for exampe, this one uses `wp_admin_notice()` internally.
add_action( 'admin_notices', 'new_user_email_admin_notice' );
add_action( 'admin_notices', 'update_nag', 3 );
add_action( 'admin_notices', 'deactivated_plugins_notice', 5 );
add_action( 'admin_notices', 'paused_plugins_notice', 5 );
add_action( 'admin_notices', 'paused_themes_notice', 5 );
add_action( 'admin_notices', 'maintenance_nag', 10 );
add_action( 'admin_notices', 'wp_recovery_mode_nag', 1 );
add_action( 'admin_notices', array( 'WP_Privacy_Policy_Content', 'notice' ) );
add_action( 'admin_notices', array( 'WP_Privacy_Policy_Content', 'policy_text_changed_notice' ) );
add_action( 'user_admin_notices', 'new_user_email_admin_notice' );
add_action( 'network_admin_notices', 'new_user_email_admin_notice' );
add_action( 'admin_notices', 'site_admin_notice' );
add_action( 'network_admin_notices', 'site_admin_notice' );
add_action( 'network_admin_notices', 'update_nag', 3 );
add_action( 'network_admin_notices', 'maintenance_nag', 10 );

Also the bundled themes use these hooks, for example, twenty twemty one:
add_action( 'admin_notices', 'twenty_twenty_one_upgrade_notice' );

Extenders may not use wp_admin_notice() at all.

There is also the all_admin_notices hook which appears to not be used in Core, unless I'm missing something.

Suggesst for testing: test multiple notices on the same page.
For example, add ​here one more notice:

add_settings_error( 'general', 'settings_testnotice', __( 'Notice test.' ), 'warning' );

Test saving in one of the Settings pages:

This PRWith ​https://github.com/WordPress/wordpress-develop/pull/13669 merged
https://github.com/user-attachments/assets/04d6d137-588f-4544-9a12-8ecc2b33a7f5https://github.com/user-attachments/assets/e4072f41-edd0-4f58-94ea-011680e3b102

​@afercia commented on ​PR #13671:


7 weeks ago
#62

After merging #13669 I tested a few more cases. All seem to be collected and counted correctly.

A notice rendered directly in the middle of a page e.g. in the Reading Settings page:

wp_admin_notice(
	'My notice at the bottom of the page',
	array(
		'type'               => 'warning',
		'additional_classes' => array( 'inline' ),
	)
);

Two other notices hooked into hooks that fire late on a page:

add_action(
	'in_admin_footer',
	function () {
		wp_admin_notice(
			'My notice in the in_admin_footer hook',
			array(
				'type'               => 'warning',
				'additional_classes' => array( 'inline' ),
			)
		);
	},
	1
);

add_action(
	'admin_footer-options-reading.php',
	function () {
		wp_admin_notice(
			'My notice in the admin_footer-options-reading.php hook',
			array(
				'type'               => 'warning',
				'additional_classes' => array( 'inline' ),
			)
		);
	},
	1
);

Other findings reported by @pattonwebz especially the 4th one on https://core.trac.wordpress.org/ticket/50486#comment:55 need to be tested more in depth.

​@joedolson commented on ​PR #13671:


7 weeks ago
#63

This intentionally doesn't capture any notices that aren't passed through wp_get_admin_notice(). The intent is that all WordPress core notices should be updated to pass through the filter, so that we're internally consistent, and that these accessibility benefits would be for people using WordPress API paths to generate notices. Those have been available since version 6.4 now, and all plugins should be able to migrate to them.

In my opinion, directly printing a notice is _doing_it_wrong(), and we shouldn't need to support it. There are far too many possible ways that can be done to be reasonable to try and catch.

​@afercia commented on ​PR #13671:


7 weeks ago
#64

The wp_admin_notice action isn't viable, because it doesn't catch anything that uses a echo wp_get_admin_notice() or $message = wp_get_admin_notice() pattern.

Yes. It won't catch anything echoed when using wp_get_admin_notice() directly.

However, we can try to _add_ a new hook inside wp_get_admin_notice(). Then, try to detect whether the notice is actuallly echoed later and try to dedupe potential duplicates.

​@joedolson commented on ​PR #13671:


7 weeks ago
#65

I'm not sure I see the value of a new hook. Can you specify how you see a duplicate happening with this?

All calls to wp_admin_notice() call wp_get_admin_notice(), but no call to the getter should also call the printing function. The only case I'm thinking of where this would have a duplicate would be if a notice was created, never printed, then created a second time to be printed. In that case, the problem is that the caller is doing things wrong, and should be fixed.

I can appreciate wanting to try to catch duplicates, I'm just not seeing how what you propose would do that.

​@afercia commented on ​PR #13671:


7 weeks ago
#66

I'm not sure I see the value of a new hook. Can you specify how you see a duplicate happening with this?

Nevermind, I think I understand a little better now.

​@afercia commented on ​PR #13671:


7 weeks ago
#67

One more thing:
to my understanding, the id in wp_get_admin_notice() isn't a real unique ID. It may be empty or whatever it is passed to.

For future extensibility, should we consider to make wp_get_admin_notice() generate a unique ID and add it to:

  • a new argument passed to the wp_admin_notice_markup filter (or in the existing $args)
  • a data-* attribute in the notice markup

This way, any notice generated by wp_get_admin_notice / wp_admin_notice would carry a unique identifier. That would be useful for any future extension e.g. a notification center.

​@joedolson commented on ​PR #13671:


6 weeks ago
#68

Updates add a unique ID to all generated notices and key the array to those IDs; I think the future potential for a notification center, or even just making that an easily plugged extension, is definitely worthwhile.

I don't think that the issue about renderers is very significant; when we implemented wp_admin_notices(), we were pretty thorough in catching the output that was created. I believe that the only significant outliers are JS generated notices and the settings API errors, that you've already got a separate PR for.

​@afercia commented on ​PR #13671:


6 weeks ago
#69

One more thing worth considering. It's not strictly related to this PR and can be considered in a follow-up.

As far as I can tell, the 4 admin notice types 'error', 'success', 'warning', 'info' are not 'enforced' anywhere. They are only mentioned in the inline documentation.

I would consider adding a const in the most appropriate class (the collector?) to have a canonical source for the types so that it can be referenced when needed e.g.:

const NOTICE_TYPES = array( 'error', 'success', 'warning', 'info' );

then when in other parts of the codebase there is the need to get the Core notice types, this would be all that is needed

ClassName::NOTICE_TYPES;

#70 @afercia
6 weeks ago

In 63943:

Improve the Settings admin notices implementation.

The amdin notices rendered in the Settings pages use their own function to echo the notices, which is a little legacy. Today, Core provides a standardized way to render the admin notices by the means of wp_admin_notice().

  • Refactors settings_errors() to use wp_admin_notice() internally.
  • Expands the related tests.

Added bonus: The Settings pages notices will now fire the some hooks and filters fired by wp_admin_notice(), e.g. wp_admin_notice and wp_admin_notice_markup, which is a necessary preparation for #50486.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13669

Props afercia, westonruter, joedolson.
See #50486.
Fixes #66161.

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


6 weeks ago

​@joedolson commented on ​PR #13671:


5 weeks ago
#72

I can see some argument for having a canonical reference of notice types, but I agree that it's beyond the scope of this PR - it doesn't directly impact the accessibility of notices, just the stability of usage.

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


5 weeks ago

#74 @audrasjb
5 weeks ago

Hello, this ticket is marked early so it would be nice to have it committed this week as we are only two weeks from beta 1. If it doesn't look realistic, we should move it to Future Release.

#75 @afercia
5 weeks ago

  • Keywords commit added

​PR 13671 looks good to me. A couple notes:

1
The update_nag notice for core updates is counted correctly. It is not moved within the aside element though, because it carries the inline CSS class. That's expected but at this point I'd consider to remove the inline class. See screenshot below.

2
Re: The scenario 4) reported by @williampatton:

  1. admin_notices hooks registered from inside in_admin_header vanish completely

In that code example, the notice 'vanished' because it was directly output with printf(). It will be counted correctly if it uses wp_admin_notice().

#76 @peterwilsoncc
5 weeks ago

  • Keywords changes-requested added; commit removed

I've added a change request to the PR as invalid IDs types are dropped rather than replaced with the default. See an ID that is not a string in the data provider.

This ticket was mentioned in ​Slack in #core-test by jina_parekh. ​View the logs.


5 weeks ago

#78 @joedolson
4 weeks ago

  • Keywords commit added; changes-requested removed

Updated to resolve request by @peterwilsoncc; the intention was to always have an ID, so dropping the ID due to invalid values was not the intended behavior.

Also fixed missing since references and one other remaining broken test.

#79 @joedolson
4 weeks ago

  • Keywords needs-dev-note added

#80 @joedolson
4 weeks ago

  • Resolution → fixed
  • Status accepted → closed

In 64282:

Admin: Admin notice accessibility improvements.

Capture all admin notices with message content generated via wp_get_admin_notices(). Wrap all captured notices inside an aside so notices are identified within a navigable landmark. Add information about the number of notices produced on a page in the title element of the page.

Ensures users have awareness on page entry whether there are notices present, how many there are, and provides screen readers with a mechanism to locate them as a group. Inline notices are counted in the total, but not contained within the landmark.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13671.

Props afercia, psykro, ryokuhi, raaaahman, alexstine, sergeybiryukov, oglekler, marybaum, swissspidy, davidbaumwald, sanket.parmar, sabernhardt, peterwilsoncc, williampatton, im3dabasia1, audrasjb, khokansardar, ugyensupport, joedolson.
Fixes #50486.

#81 @peterwilsoncc
4 weeks ago

  • Resolution fixed
  • Status closed → reopened

#82 @peterwilsoncc
4 weeks ago

I've reopened this as I am seeing some issues with the collector placing the number of notices in the title.

The WP Dashboard with the default widget always shows the title (2 notices) Dashboard ... even though no notices are displayed.

The cause of the issue is that inline notices are triggered in the following locations but hidden if JavaScript is enabled:

  • wp_print_community_events_markup(): Warning the widget requires JS
  • wp_dashboard_cached_rss_widget(): Warning the widget requires JS

I'm seeing similar for inline notices elsewhere, eg on wp-admin/update-core.php there is an inline notice warning users to perform a backup before upgrading WordPress.

When bookmarking, the title of the page is showing the number of messages in the proposed title:

  1. Go to a settings pages
  2. Save the settings
  3. Click the browser UI to bookmark a page
  4. Observe suggested title includes (1 notice) prefix

#83 @peterwilsoncc
4 weeks ago

  • Keywords has-patch has-unit-tests early commit removed

#84 @wildworks
4 weeks ago

The same issue happens in the block editor. When editing any post, the browser title shows (1 notice) Edit Post ... even though no notice is visible.

The cause is the "The block editor requires JavaScript" notice in wp-admin/edit-form-blocks.php. It is always rendered via wp_admin_notice(), but hidden by the .hide-if-js wrapper when JavaScript is enabled.

One way to fix this would be to skip notices with the hide-if-js class when counting, but I don't think that's ideal. Users with JavaScript disabled do see these notices, so in that case they should be counted.

#85 @afercia
4 weeks ago

A note on the notice echoed by wp_dashboard_cached_rss_widget(): this notice ie now never shown. It carries the hide-if-js CSS class and the whole widget is now ​within a container that carries the hide-if-no-js class. From an usability perspective, the RSS feeds widget is displayed together with the Events widget, which already echoes a 'no-js' notice. As such I think the UI is OK and this notice could be removed.

There are other notices that are hidden or echoed conditionally after a call to wp_get_admin_notice(), which triggers the notices count. For example:

  • Notices with the 'hide-if-js' CSS class.
  • Notices with the hidden class. ​This one for example is initially hidden and then populated via JS. It's skipped by the collector only because the initial message is empty.

I'm not sure using a notice this way (with an empty initial message) is entirely correct but the current implementation allows it anyways. The 'hide-if-js' notices issue should be addressed though. Maybe the collector should catch them anyways but omit them from the count.

Couple more considerations:

eg on wp-admin/update-core.php there is an inline notice warning users to perform a backup before upgrading WordPress.

This is the intended behavior.

When bookmarking, the title of the page is showing the number of messages in the proposed title

Any modification of the document title, either via PHP or JS, will make the browser use the modified title for things like bookmarks and more importantly the names of the entries in the browser history. I would say this is the intended behavior and it's no different from what already happens in other places in WordPress, for example on the Comments page where the document title shows the count of comments awaiting moderation.

Last edited 4 weeks ago by afercia (previous) (diff)

#86 @joedolson
4 weeks ago

What I'm thinking is needed is a parameter in wp_get_admin_notices() that can be passed to the collector and inform it not to collect the notice. That would work for cases where a notice is rendered but not shown.

Notices triggered only by JS events would not generally be present when the page loads, so they shouldn't be counted or collected.

Collecting the notices that are hide-if-js is a little trickier, as the collector isn't aware whether JS is enabled or not. They could certainly be isolated in the collector, but they would still need to be included if JS isn't available.

The hidden class should probably be skipped in all cases, however, since I don't believe there are any instances of that which should be displayed on page load.

#87 @afercia
4 weeks ago

The same issue happens in the block editor.

All similar notices will trigger the issue. There are a few more 'no-js' notices e.g. in the Media Library > grid mode, Theme Installer. Not sure how the Fonts and Connectors pages call wp_admin_notice. They should be double checked,

I'd consider to let the collector collect them anyways, in a sub-array. The collector should not care whether a notice is visible or not. Its purpose is to collect all notices. Then, the rendering should only calculate the count for the visible ones.

This ticket was mentioned in ​PR #14223 on ​WordPress/wordpress-develop by ​@joedolson.


4 weeks ago
#88

  • Keywords has-patch added

This still omits collecting notices with no message, on the grounds that it's only useful for the collector to have populated notices.

Filters notices with either the 'hide-if-js' or the 'hidden' classes so that they aren't represented in the title notice count.

All notices with content are still collected, but the count is based on notices that are visible and have content.

Use of AI Tools

None.

#89 @joedolson
4 weeks ago

  • Keywords has-patch removed

Add a PR to adjust the notice counting to remove notices with the hidden or hide-if-js classes.

I've been thinking a little about the hide-if-js classes, and from a practical standpoint, I'm not sure we can do anything useful with them, since we can't do anything but plain text in the title element.

We could have a conditional skip link that is only visible if there's no JS and links to the notice, which would serve a similar purpose.

​@peterwilsoncc commented on ​PR #14223:


4 weeks ago
#90

I'm inclined to hide inline notices too as they are more akin to callouts than notices per se.

On the updates page, the inline notice to backup before upgrade results in (1 notice) WordPress Updates in the HTML title due to the inline warning to back up before upgrading.

As there is nothing the use can do to clear the notice, the information in the title is unhelpful.

https://github.com/user-attachments/assets/efbdd7bf-661c-46dc-b1cd-7c02f82dc904

I'm a little worried about the very well known issue of plugins throwing notices that are basically advertising (we've all seen the screen shots on social media) as the (x notices) texts reduces visibility for the page title for these unhelpful notices.

https://github.com/user-attachments/assets/696e9bd8-2620-431a-8bed-ecca88092012

​@joedolson commented on ​PR #14223:


4 weeks ago
#91

After discussing the issue with notice counts being inflated by counting content that runs through wp_get_admin_notice() but that doesn't serve the purpose of providing a user notification, we hashed out some ideas of how to make the collector generate a more representational notice count.

We should keep in mind that any count that doesn't actually reflect every notice on the page has the potential to create user confusion, but having persistent notices always appear in the title element when they can't be controlled by the user can just mean that the title element becomes fundamentally less useful.

We talked about two classes of notice: inline notices, which may only represent a display of information, and commercial notices, injected by extenders for promotional reasons. These may or may not belong in the count. Whether they do is outside of our scope, but providing a mechanism for them to control that does make sense.

The intention at this phase is to add an argument to wp_get_admin_notices(): include_in_count, with a ternary value set of true, false, or null, where null would represent a fallback to default handling. Setting include_in_count would override other checks, such as checks for empty content or for hidden notices.

The default value would be based on an analysis of core inline notices that are not already excluded, to assess what the most common case is in core usage.

​@afercia commented on ​PR #14223:


4 weeks ago
#92

In the Theme Installer page wp-admin/theme-install.php?browse=popular there's one more edge case to take into account.

If one or more of the themes listed in the installer is already installed, each theme's card shows an 'Installed` message at teh top of the car. ​That's a notice used in a JS template for the card.

Even with multiple 'Instlaled' notices, they are counted as 1 notice because the JS template executes the notice call once.

We could argue this is a wrong usage of wp_admin_notice(), still we should avoid it gets counted. Personally, I'd vote to refactor the JS template to not use wp_admin_notice() but this surfaces another potential edge case that should be considered.

https://github.com/user-attachments/assets/096ee887-b91f-4342-b50d-5cf4b918ded3

​@afercia commented on ​PR #14223:


4 weeks ago
#93

Regarding the 'inline' notices, I'm not sure they can all be considered 'callouts'. They should not be hidden unconditionally. Actually, some of them are notices, as in:

  • They appear after a specific user action.
  • They are not merely informational.
  • Users can take an action to make the notice disappear.

I would argue that even the notice in the Updates page is a notice.

As there is nothing the use can do to clear the notice, the information in the title is unhelpful.

Users can update and the notice will disappear. As such, there is an action users can take.

Regarding:

persistent notices always appear in the title element when they can't be controlled by the user

I would argue that in this case they should not be notices. When a message is merely informational, or a 'callout' or it can't be controlled by taking a specific action, then it should not be considered a notification.

Regardless, here's some examples of 'inline' notices that have different nature. Some of the are actual notifications.
There are more ones, for example: Broken theme, Incompatible plugins, Update network (update all your sites), etc.

https://github.com/user-attachments/assets/b761a21b-36dd-4a1d-ae27-24f985c2162b

commercial notices, injected by extenders for promotional reasons

Maybe a little radical but I believe WordPress should actively discourage this practice. One (radical) way to do it:

  • Force the 'dismissible' arg
  • Save the dismissed state in a user meta and prevent dismissed notices from being echoed.

However, even with that in place, WordPress can't control messages that visually look like notices but don't go through wp_get_admin_notice() / wp_admin_notice(). Material for a separate Trac ticket.

​@Mamaduka commented on ​PR #13671:


4 weeks ago
#94

I'm seeing title prefixes on the Dashboard and when editing a post, even though no notices are visible.

Screenshots

https://github.com/user-attachments/assets/6327b26a-b35d-4395-9671-b3ba185e35f1
https://github.com/user-attachments/assets/422f00c3-9008-48bd-942a-d25313d73240

This ticket was mentioned in ​Slack in #accessibility by joedolson. ​View the logs.


4 weeks ago

#97 @matt
4 weeks ago

Please revert all of this. @afercia you no longer hold any WordPress.org positions or titles or authority, and are invited to contribute your talents to another project.

#98 @joedolson
4 weeks ago

In 64347:

Admin: Revert admin notices accessibility fixes.

Following merge, it became evident that the complexity of notices as handled in the WordPress admin make this change premature. While it worked effectively handling standard notices, there are significant numbers of unusual notice cases. The follow-up PR (​https://github.com/wordpress/wordpress-develop/pull/14223) would have significantly limited the false positives, but not sufficiently for production.

Variant notices will need to have improved handling before these fixes can be implemented effectively.

Props joedolson, matt, peterwilsoncc, wildworks, mamaduka.
See #50486.

#99 @joedolson
4 weeks ago

  • Milestone 7.2 → Future Release

Moving to future release. This would be better handled as part of the proposed feature notifications in #43484.

#100 @matt
4 weeks ago

Please whoever turned off @afercia's account undo that. That wasn't what I asked for and isn't needed.

#101 @Rolle
3 weeks ago

My wife is deafblind, and I know many people in the local blind community. I can't speak for them, but I see every day what happens when information is only available visually.

In case you didn't notice, Darrell Hilliker, a blind screen reader user and accessibility professional, wrote about this ticket: ​An open letter on accessibility in WordPress

Admin notices tell people that something saved, failed or needs attention. For years, screen reader and keyboard users have had no reliable way to find them.

The revert in [64347] is understandable, since the title count reported notices that didn't exist, but moving the ticket back to Future Release is another thing. This ticket has been punted from release to release since 6.3, and Future Release has meant no progress. And while this gets debated, people who rely on assistive technology deal with it every day.

Feature Notifications is a separate, new feature with no timeline for core AFAIK. This ticket is an accessibility fix for notices that exist right now. Bundling the 2 means the fix waits for a feature that may take years.

What would help in my world:

  • A numbered milestone.
  • Not waiting for Feature Notifications.
Note: See TracTickets for help on using tickets.