Fix: Accessibility issue with links listing blocks. #(64051) #66866

im3dabasia · 2024-11-08T10:42:16Z

What?

Why?

This PR addresses accessibility by ensuring screen readers recognize these blocks as navigational elements, as per issue #64051.

How?

Added <nav> wrappers around the lists in core/page-list and core/tag-cloud blocks. For core/categories, the <nav> is conditionally added when displayed as a list (not as a dropdown), improving accessibility.

Screenshots or screencast

Before	After

github-actions · 2024-11-08T10:42:52Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @im3dabasia! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

github-actions · 2024-11-08T11:56:37Z

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: im3dabasia <[email protected]>
Co-authored-by: carolinan <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: afercia <[email protected]>
Co-authored-by: joedolson <[email protected]>
Co-authored-by: Hug0-Drelon <[email protected]>

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

carolinan · 2024-11-10T07:59:31Z

Hi @im3dabasia I do not believe that this is the correct solution for this problem. I also believe that the problem and use case needs to be described in more detail before a solution can be proposed. I recommend allowing some more time to discuss the issue first.

The <nav> element is intended to be used for navigations, and all lists of links are not necessarily navigations.

Also when there is more than one nav on a page, visitors need to be able to distinguish one nav from the other.
Consider a scenario where the user adds both a tag cloud and categories block in the same post content or template.
The navigations need to have labels describing their purpose.

packages/block-library/src/categories/edit.js

packages/block-library/src/categories/index.php

packages/block-library/src/page-list/edit.js

carolinan · 2024-11-10T11:22:11Z

packages/block-library/src/tag-cloud/index.php


 	return sprintf(
-		'<p %1$s>%2$s</p>',
+		'<nav %1$s>%2$s</nav>',


This works well in my test, but the nav needs a unique label. It also needs to take into the account that more than one of copy of the tag cloud block can be used on the same page.

Hey @carolinan ,

I have addressed the changes you suggested earlier. Could you please guide me on the changes I need to make based on this comment? I am unsure.

im3dabasia · 2024-11-11T08:51:11Z

Thank you for the feedback, @carolinan! I'll hold off on any additional changes until there's further discussion on the issue's scope and proposed solution.

carolinan · 2024-11-12T07:25:29Z

Thank you for the feedback, @carolinan! I'll hold off on any additional changes until there's further discussion on the issue's scope and proposed solution.

My concern is the page list block, if that can be separated I think work on the other two blocks can continue.

im3dabasia · 2024-11-12T09:42:27Z

Thank you for the feedback, @carolinan! I'll hold off on any additional changes until there's further discussion on the issue's scope and proposed solution.

My concern is the page list block, if that can be separated I think work on the other two blocks can continue.

Thank you for the reply @carolinan.

I will start working on the other 2 blocks but I need some guidance. In the category list block. The suggestion was to change the constant tagName to 'nav' instead of 'ul', Here I had a doubt since the function renderCategoryList() returns a array of <li>( renderCategoryList calls renderCategoryListItem() internally). If I change the TagName to 'nav' then the generated markup would be

<nav>
<li> </li>
<li> </li>
<li> </li>
</nav>

This would result in wrong markup. I am confused here on how to approach this. Any guidance on this would be much appreciated

carolinan · 2024-11-28T08:30:19Z

@im3dabasia I think you can change the <nav> element that you added around renderCategoryList() to a <ul>, and then change <ul> in the TagName constant to a nav?

carolinan · 2024-12-03T05:57:19Z

I found that the tag cloud has a format parameter where developers can choose between an unordered list and a flat list of items. But both formats can be inside a <nav> without any validation problems. https://developer.wordpress.org/reference/functions/wp_tag_cloud/

There aren't many examples of adding aria labels that are editable by the user. The navigation block uses one, and there is a suggestion to add one to the group block.

ariaLabel is a block support, it needs to be set to true in block.json.
After updating the block support, the documentation also needs to be updated. npm run docs:build.
The option needs to be a text input field in the Advanced section of the InspectorControls.
The option needs a suitable default value for when the user does not customize the label.
The option needs a suitable label. The label for the option in the navigation block is "Menu name" , so perhaps "Tag Cloud name"?

The categories are different because it already has a label text that is used when the dropdown option is selected.
This label text could be re-used as the aria label on the nav.

im3dabasia · 2024-12-03T06:21:59Z

Hey @carolinan

I am new to contributing and just want to verify if I need to do the following:

a) Enable ariaLabel support in block.json.
b) Add a text input field for the aria-label in the Advanced section of InspectorControls, ensuring it has appropriate default values and labels.
c) Update the documentation after the changes by running npm run docs:build.

Please let me know if I’m on the right track or if there’s anything I’m missing.

carolinan · 2024-12-03T07:45:40Z

Yes.
But also be prepared that there may be more discussions and reviews since this is not a common pattern in the existing blocks.

im3dabasia · 2024-12-06T11:02:53Z

Hi @carolinan,

I have implemented the requested changes and added support for the aria-label, allowing the user to customize it. By default, the name is set to "Tag Cloud", but the user has the option to modify it in the Advanced section of the Inspector Controls.

Attaching a video reference for the same:

Screen.Recording.2024-12-06.at.4.26.43.PM.mov

Please take a look at the changes, and I would appreciate any feedback you may have.

Thank you!

im3dabasia · 2025-01-08T08:20:37Z

Hi @carolinan,
When you have a moment, could you please review my PR and provide feedback on how I can improve it?

carolinan · 2025-01-08T09:56:39Z

packages/block-library/src/tag-cloud/index.php

 function render_block_core_tag_cloud( $attributes ) {
 	$smallest_font_size = $attributes['smallestFontSize'];
 	$unit               = ( preg_match( '/^[0-9.]+(?P<unit>[a-z%]+)$/i', $smallest_font_size, $m ) ? $m['unit'] : 'pt' );
+	$aria_label         = isset( $attributes['ariaLabel'] ) ? $attributes['ariaLabel'] : 'Tag Cloud';


The default text must be translatable, placed inside a translation function.

carolinan · 2025-01-08T10:51:42Z

Please solve the merge conflict first :)

…trols

t-hamano · 2025-02-06T08:05:07Z

This comment made me realize that the aria-label support is not complete. We are currently discussing how to address this in #68764.

About this PR: My biggest concern is backwards compatibility.

This PR changes the structure of the output HTML, which may have a significant impact on themes that already apply styles to these blocks via stylesheets.

If we replace the block wrapper element itself with a nav element

The HTML will change as follows:

<!-- From -->
<p class="wp-block-tag-cloud">
	<a href="">Tag</a>
</p>

<!-- To -->
<nav class="wp-block-tag-cloud">
	<a href="">Tag</a>
</nav>

Selectors like p.wp-block-cloud will no longer work.

If we wrap the block wrapper element in a `nav` element

The HTML will change as follows:

<!-- From -->
<p class="wp-block-tag-cloud">
	<a href="">Tag</a>
</p>

<!-- To -->
<nav>
	<p class="wp-block-tag-cloud">
		<a href="">Tag</a>
	</p>
</nav>

Selectors like .entry-content > .wp-block-cloud will no longer work. This may also affect margin support, layout, etc.

With this in mind, I think we need to have more discussion before moving forward, taking into account the impact on backward compatibility.

carolinan · 2025-02-06T08:33:43Z

Its not great but the accessibility is more important.

t-hamano · 2025-02-06T08:59:16Z

I agree that accessibility is important, but we cannot ignore the impact on backward compatibility for that reason. I think we need to investigate in advance how much of an impact it will have.

In any case, ariaLabel block support in dynamic blocks is not complete, so we may need to fix that first.

carolinan · 2025-02-06T09:11:45Z

I did a quick search on wpdirectory.net, which does not replace doing more research:
.wp-block-tag-cloud is in 1559 themes.
p.wp-block-tag-cloud is in 281 themes and 1 plugin.

t-hamano

If we proceed with this PR, I recommend that you thoroughly investigate the impact of this change, along with accessibility feedback. For example:

Is the global styles applied correctly?
Are there any visual changes in the default theme?
Are block support, especially spacing support, applied correctly?

Additionally, we should consider the impact of selectors like the following if a theme uses them:

.wp-block-categories-list > li
.wp-block-categories > li
.wp-block-tag-cloud > a

packages/block-library/src/tag-cloud/edit.js

packages/block-library/src/tag-cloud/index.php

t-hamano · 2025-03-03T15:02:56Z

I want to reaffirm whether moving forward with this PR approach is truly important from an accessibility perspective.

This PR will result in the following changes to the HTML:

Categories Block (as a list)

<!-- From -->
<ul class="wp-block-categories-list wp-block-categories">
  <li class="cat-item cat-item-1"><a href="">Category A</a></li>
  <li class="cat-item cat-item-2"><a href="">Category B</a></li>
  <li class="cat-item cat-item-3"><a href="">Category C</a></li>
</ul>

<!-- To -->
<nav class="wp-block-categories-list wp-block-categories">
  <ul>
    <li class="cat-item cat-item-1"><a href="">Category A</a></li>
    <li class="cat-item cat-item-2"><a href="">Category B</a></li>
    <li class="cat-item cat-item-3"><a href="">Category C</a></li>
  </ul>
</nav>

My concerns are:

Do these blocks need to be wrapped in a nav element?
Are nav elements without aria-label acceptable?
If nav elements without aria-label are not acceptable, do we need to expose the aria-label editing UI?
Blocks may be duplicated and have the same aria-label.

cc @afercia @joedolson @alexstine

afercia · 2025-03-03T16:06:24Z

whether moving forward with this PR approach is truly important from an accessibility perspective

I would say that at the very least the related blocks should provide feature parity with what was implemented in Core, although the Core implementation is behind opting-in for html5 support for navigation-widgets. Reference:

https://make.wordpress.org/core/2020/07/09/accessibility-improvements-to-widgets-outputting-lists-of-links-in-5-5/
https://core.trac.wordpress.org/ticket/48170
https://core.trac.wordpress.org/changeset/48349

Are nav elements without aria-label acceptable?

A nav element without appropriate labeling is only acceptable if there's only one nav element on a page.
If I remember correctly, the Core implementation for the classic widgets does allow to pass an aria-label and provides a default one.

joedolson · 2025-03-03T16:33:51Z

If a block is duplicated and has the same label, that's OK; a block with the same content is semantically the same block, so a duplicate label is accurate.

I would say that yes, they should be wrapped in nav elements. Like @afercia says, having feature compatibility with the core widgets is the base line, and those are wrapped in nav elements.

However, I note that while block themes mostly declare HTML5 by default, they are omitting the navigation widgets from that declaration; is that an oversight?

See: r52439 & https://github.com/WordPress/wordpress-develop/blob/b5e0c16c04edcebdf5e81c39796a9d2c22cfd6f7/src/wp-includes/theme.php#L4394

carolinan · 2025-03-05T06:26:01Z

If a block is duplicated and has the same label, that's OK; a block with the same content is semantically the same block, so a duplicate label is accurate.

Aha, yes that makes sense, thank you,

carolinan · 2025-03-05T06:30:24Z

However, I note that while block themes mostly declare HTML5 by default, they are omitting the navigation widgets from that declaration; is that an oversight?

See: r52439 & https://github.com/WordPress/wordpress-develop/blob/b5e0c16c04edcebdf5e81c39796a9d2c22cfd6f7/src/wp-includes/theme.php#L4394

I am not sure what a navigation widget is.

afercia · 2025-03-05T08:51:54Z

I am not sure what a navigation widget is.

navigation-widgets is one of the extra arguments for add_theme_support( 'html5', $args ). When supported, many classic widgets like the navigation menu widget, archives, categories, pages, recent posts, recent comments etc. wrap their html output within a labeled <nav> element.

As @joedolson pointed out, it appears block themes do not support the full 'html5 support' extra arguments as navigation-widgets is missing from the extra args array here.

carolinan · 2025-03-05T09:10:28Z

But where is it documented? it is not listed here under the html5 heading. https://developer.wordpress.org/reference/functions/add_theme_support/

carolinan · 2025-03-05T09:13:59Z

Yeah I would assume it was unintentionally missed because it is not clearly documented.

afercia · 2025-03-05T09:21:54Z

Yeah I would assume it was unintentionally missed because it is not clearly documented.

I guess so. I see the REST API doesn't support it as well? This new support was intended to be fully 'opt-in' but I'm not sure why it hasn't been documented.

joedolson · 2025-03-05T16:33:18Z

I feel like we need an option that allows a user to just pass 'all' or true to support all HTML5 options. The need to specifically iterate each individual support makes sense for older themes to have a gradual migration path, but it just creates extra labor and complication for most modern use cases.

Added a core ticket to propose this.

t-hamano · 2025-03-06T04:21:42Z

Thanks everyone for your feedback!

I would say that at the very least the related blocks should provide feature parity with what was implemented in Core, although the Core implementation is behind opting-in for html5 support for navigation-widgets. Reference:

Does this mean that if a theme doesn't have html5 theme support, we shouldn't use nav elements?

If so, I'm wondering if this argument applies to other blocks as well. For example:

Navigation and Query Pagination blocks always use nav elements:
- gutenberg/packages/block-library/src/navigation/index.php
  
  Line 710 in c196e9a
  
  '<nav %1$s>%2$s</nav>',
- gutenberg/packages/block-library/src/query-pagination/index.php
  
  Line 32 in c196e9a
  
  '<nav %1$s>%2$s</nav>',
A PR has been submitted to make the nav element selectable in the group block: Group: Make nav element selectable and add UI for ariaLabel #68611

carolinan · 2025-03-06T05:19:42Z

Does this mean that if a theme doesn't have html5 theme support, we shouldn't use nav elements?

No, the blocks should use modern HTML that is supported by the browsers that WordPress requires.

carolinan · 2025-03-06T05:24:05Z

The HTML theme support exists to make it easier for theme developers to use modern HTML, while keeping the features backwards compatible with older themes that has styles that expects a certain markup. As seen here: https://core.trac.wordpress.org/ticket/61183

afercia · 2025-03-06T07:50:55Z

Does this mean that if a theme doesn't have html5 theme support, we shouldn't use nav elements?

Ideally, blocks themes (and thus the blocks they use) should output modern html5 markup and use best practices by default. as @carolinan pointed out, the html5 support was introduced many years ago to allow themes to progressively, granularly, introduce new html5 features. I think blocks should support all these html5 features by default.

t-hamano · 2025-08-19T12:51:31Z

Sorry for the late reply.

I thought about how we could move this PR forward. I think it may be good to focus on just adding a wrapper nav element with the hard-coded aria-label text.

That is, remove the aria-label support from the Tag Cloud block. There is no block that exposes the aria-label editing UI, so it would need to be discussed more deeply. Additionally, I'm not sure if any users would want to change the aria-abel text, as both blocks have an obvious purpose.

I think the key here is probably to see what visual changes occur in the default themes.

Let me know what you think!

github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Nov 8, 2024

im3dabasia marked this pull request as ready for review November 8, 2024 11:56

im3dabasia requested a review from ajitbohra as a code owner November 8, 2024 11:56

skorasaurus added the [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). label Nov 8, 2024

carolinan reviewed Nov 10, 2024

View reviewed changes

packages/block-library/src/categories/edit.js Show resolved Hide resolved

carolinan reviewed Nov 10, 2024

View reviewed changes

packages/block-library/src/categories/index.php Outdated Show resolved Hide resolved

carolinan reviewed Nov 10, 2024

View reviewed changes

packages/block-library/src/page-list/edit.js Outdated Show resolved Hide resolved

carolinan reviewed Nov 10, 2024

View reviewed changes

carolinan added the [Type] Enhancement A suggestion for improvement. label Nov 10, 2024

im3dabasia requested a review from carolinan December 3, 2024 03:34

carolinan added [Block] Tag Cloud Affects the Tag Cloud Block [Block] Categories Affects the Categories Block labels Dec 3, 2024

im3dabasia requested review from fabiankaegy, juanmaguitar and ndiego as code owners December 6, 2024 10:52

carolinan mentioned this pull request Dec 20, 2024

New block: Post navigation #57664

Closed

carolinan reviewed Jan 8, 2025

View reviewed changes

im3dabasia added 3 commits February 5, 2025 19:31

feat: Add aria label textcontrol for tag cloud block in inspector con…

bfb32dc

…trols

fix: Default tag cloud name in translation function

6d86d71

fix: Remove ariaLabel attribute

e27d92c

im3dabasia force-pushed the fix/64051-accessibility-links-listing-blocks branch from 05ead12 to e27d92c Compare February 5, 2025 16:50

im3dabasia requested a review from t-hamano February 5, 2025 17:20

t-hamano mentioned this pull request Feb 6, 2025

Block support: Preserve aria-label value in comment delimiter #69002

Merged

t-hamano reviewed Feb 6, 2025

View reviewed changes

packages/block-library/src/tag-cloud/edit.js Outdated Show resolved Hide resolved

packages/block-library/src/tag-cloud/index.php Outdated Show resolved Hide resolved

im3dabasia added 2 commits February 24, 2025 17:14

Merge branch 'trunk' into fix/64051-accessibility-links-listing-blocks

0b07615

fix: Improve code quality in ariaLabel php code

228f349

im3dabasia requested a review from t-hamano February 24, 2025 11:50

t-hamano removed the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Aug 19, 2025

Fix: Accessibility issue with links listing blocks. #(64051) #66866

Are you sure you want to change the base?

Fix: Accessibility issue with links listing blocks. #(64051) #66866

Uh oh!

Conversation

im3dabasia commented Nov 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Screenshots or screencast

Uh oh!

github-actions bot commented Nov 8, 2024

Uh oh!

github-actions bot commented Nov 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

carolinan commented Nov 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

carolinan Nov 10, 2024

Choose a reason for hiding this comment

Uh oh!

im3dabasia Nov 28, 2024

Choose a reason for hiding this comment

Uh oh!

im3dabasia commented Nov 11, 2024

Uh oh!

carolinan commented Nov 12, 2024

Uh oh!

im3dabasia commented Nov 12, 2024

Uh oh!

carolinan commented Nov 28, 2024

Uh oh!

carolinan commented Dec 3, 2024

Uh oh!

im3dabasia commented Dec 3, 2024

Uh oh!

carolinan commented Dec 3, 2024

Uh oh!

im3dabasia commented Dec 6, 2024

Uh oh!

im3dabasia commented Jan 8, 2025

Uh oh!

carolinan Jan 8, 2025

Choose a reason for hiding this comment

Uh oh!

carolinan commented Jan 8, 2025

Uh oh!

t-hamano commented Feb 6, 2025

If we replace the block wrapper element itself with a nav element

If we wrap the block wrapper element in a nav element

Uh oh!

carolinan commented Feb 6, 2025

Uh oh!

t-hamano commented Feb 6, 2025

Uh oh!

carolinan commented Feb 6, 2025

Uh oh!

t-hamano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

t-hamano commented Mar 3, 2025

Tag Cloud Block

Categories Block (as a list)

Uh oh!

afercia commented Mar 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joedolson commented Mar 3, 2025

Uh oh!

carolinan commented Mar 5, 2025

Uh oh!

carolinan commented Mar 5, 2025

Uh oh!

im3dabasia commented Nov 8, 2024 •

edited

Loading

github-actions bot commented Nov 8, 2024 •

edited

Loading

carolinan commented Nov 10, 2024 •

edited

Loading

If we wrap the block wrapper element in a `nav` element

afercia commented Mar 3, 2025 •

edited

Loading

afercia commented Mar 5, 2025 •

edited

Loading

carolinan commented Mar 6, 2025 •

edited

Loading