Make WordPress Core

Opened 5 years ago

Closed 10 months ago

Last modified 8 months ago

#47125 closed defect (bug) (fixed)

Admin: clarify the "Add New" links for better accessibility

Reported by: afercia's profile afercia Owned by: joedolson's profile joedolson
Milestone: 6.4 Priority: normal
Severity: normal Version:
Component: Administration Keywords: has-screenshots has-patch needs-dev-note commit
Focuses: ui, accessibility, administration Cc:


In the admin menu and in some of the admin pages, various links use "Add New" as link text. While these links are clarified by the visual context, they are not so meaningful when read out of context.

Assistive technologies provide tools to list all the links in a page and dedicated keyboard shortcuts to navigate through links. In this scenario, a link that only says "Add New" isn't sufficiently clear: users won't have a clue what the purpose and destination of the link is.

One more scenario: users who use speech input software (e.g. Dragon) will voice a command like "Click add new". However, in a standard WordPress page there are at least 5 "Add New" links. The software will display choices to users (usually by displaying numbers close to all the links that it has identified as "Add New"). Then, users will have to:

  • visually identify on the screen the highlighted links
  • voice an additional command, e.g. "Choose 3"

This makes the process inefficient and time consuming.

Ideally, all these links should be self-explanatory and provide more context by adding the "what" new is in the text link. For example:

  • Add New Post
  • Add New Media
  • Add New Page
  • Add New Plugin
  • Add New User

Attachments (8)

add new.jpg (118.8 KB) - added by afercia 5 years ago.
VoiceOver links list
47125-patch.diff (25.3 KB) - added by gonzomir 5 years ago.
47125-patch.2.diff (6.3 KB) - added by alexstine 10 months ago.
47125-patch.3.diff (6.3 KB) - added by alexstine 10 months ago.
Change _x() to ().
add new.png (225.3 KB) - added by afercia 10 months ago.
47125-patch.4.diff (24.4 KB) - added by alexstine 10 months ago.
More replacements.
47125-patch.5.diff (24.4 KB) - added by alexstine 10 months ago.
Doc block improvement.
47125.6.diff (24.7 KB) - added by joedolson 10 months ago.
Remove translators comments & restore textdomain arg

Download all attachments as: .zip

Change History (31)

5 years ago

VoiceOver links list

#1 @afercia
5 years ago

  • Keywords has-screenshots added

In the screenshot above, the VoiceOver links list showing some of the "Add New" links.

As mentioned previously, this applies also to the "Add New" links within the various pages, e.g. in wp-admin/edit.php and also the ones on multisite.

Related: #47124 and #47012.

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

5 years ago

#3 @afercia
5 years ago

  • Milestone changed from Awaiting Review to Future Release

Discussed during today's accessibility bug scrub and agreed this is something that should be addressed, especially for speech recognition software users.

5 years ago

#4 @gonzomir
5 years ago

I've submitted a patch that updates all "Add New" links (that I could find in the source) together with "Add Existing" links for users and some comments, theme readmes that reference these links. I'm not sure though that my approach for the post types "Add New" menu items is the best one.

#5 @afercia
5 years ago

  • Keywords has-patch added

#6 @joedolson
10 months ago

  • Owner set to joedolson
  • Status changed from new to accepted

10 months ago


#7 @alexstine
10 months ago

  • Focuses administration added
  • Keywords needs-testing added
  • Milestone changed from Future Release to 6.4

#8 @afercia
10 months ago

Just noting that if this proposed change gets approved we could consider to not use the _x() translation function any longer. Specifying the context would be pointless as the new strings are already in context. For example:

_x( 'Add New Link', 'link' )

The provided context 'link' is not necessary, as the string is already clear enough.

__( 'Add New Link' )

would be simpler and cleaner.

10 months ago

Change _x() to ().

#10 @afercia
10 months ago

  • Keywords needs-refresh needs-design-feedback added; needs-testing removed

Thanks for updating the patch. While testing, I noticed there are still around 30 occurrences of 'Add New' in the codebase that would need to be checked. A few of them are in comments or help text but they should be updated as well.

Also, making the search case sensitive I found a couple places where the letter 'n' of the word 'new' is lowercase:

__( 'Add new Pattern' )
_e( 'Add new Comment' )

This is inconsistent with the well established pattern in WordPress, where all similar strings use title case for the word 'New', for example:

__( 'Add New Template' )

'Add new Pattern' was recently Introduced in [56030]

Adding a screenshot to illustrate some examples of what the current patch does.

Last edited 10 months ago by afercia (previous) (diff)

10 months ago

#11 @afercia
10 months ago

Related GitHub issue on the Gutenberg repository:

10 months ago

More replacements.

#12 @alexstine
10 months ago

  • Keywords needs-refresh removed

Probably not perfect, but I think this moves us closer.

Anything I missed this go around @afercia?


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

10 months ago

#14 @marybaum
10 months ago

Love this! @afercia would you review the design so this ticket could land in 6.4?

Last edited 10 months ago by joedolson (previous) (diff)

#15 @swissspidy
10 months ago

Looking at 47125-patch.4.diff, I'd slightly adjust the change to the docblock of get_post_type_labels()

Right now it says "Default is 'Add New Type' for both hierarchical and non-hierarchical types." and "matching your post type. Example: __( 'Add New Type' );."

I would change this to "Default is 'Add New Post' / 'Add New Page'" and "matching your post type. Example: __( 'Add New Product' );.", respectively.

Also, that change warrants a mentioned in a dev-note somewhere so developers update labels in their plugins.

10 months ago

Doc block improvement.

#17 @joedolson
10 months ago

Removed a few translator comments that are no longer needed with the removal of _x() calls. Also restored the 'textdomain' argument in the get_post_type_labels() docblock, as that is still an important instruction for extenders.

Last edited 10 months ago by joedolson (previous) (diff)

10 months ago

Remove translators comments & restore textdomain arg

#18 @joedolson
10 months ago

  • Keywords commit added; needs-design-feedback removed

I'm don't see that this requires design feedback. These are all text changes. I don't see anything design wise that requires comment.

I'm marking this for commit. There may be further strings that would merit changing, but I don't think those should stop this from getting resolved; we can always add follow-up commits. I searched the code and there's nothing obvious remaining.

#20 @joedolson
10 months ago

  • Resolution set to fixed
  • Status changed from accepted to closed

In 56515:

Administration: Add improved context for add new links.

Consistently expand Add New links to include the type of content to add. Improve consistency of text casing to use initial caps throughout.

Props afercia, gonzomir, alexstine, swissspidy, joedolson.
Fixes #47125.

#21 @SergeyBiryukov
10 months ago

In 56519:

Docs: Add a @since note for add_new labels change in get_post_type_labels().

Includes removing an obsolete recommendation to use a gettext context matching the post type for disambiguation, which would be redundant with the new labels, as they already include the type of content.

Follow-up [14571], [56515].

See #47125.

#22 @webcommsat
8 months ago

@swissspidy following up your comment above on a mention in dev note for plugin devs to update their labels, does something on this need to go in the email to plugin devs too that Marcomms are drafting (cc @meher )?

Is there a paragraph or sentence on the change that could be used in a Miscellaneous dev note, assuming from the discussion above it does not need a single dev note? It may be that accessibility are including this in a dev note on accessibility areas? @joedolson @afercia

Thank you everyone and for bringing this fix.

#23 @swissspidy
8 months ago

@webcommsat Yes this can go in a Miscellaneous dev note as it does not need a dedicated one. No need for a special mention in the plugins email, as those emails just link to the field guide anyway.

A paragraph like this should work:

In WordPress 6.4, the default values for the `add_new` label changed to include the type of content. This matches `add_new_item` and provides more context for better accessibility.
The default value is 'Add New Type' for both hierarchical and non-hierarchical types.
If you've previously used a label such as `'add_new' => _x( 'Add New', 'Book', 'my-plugin' )`, you are encouraged to change it to `'add_new' => __( 'Add New Book', 'my-plugin' )`.
Note: See TracTickets for help on using tickets.