Block Comments: Improve input labels #71843

karthick-murugan · 2025-09-23T12:46:14Z

What?

Improves comment input labels for better accessibility by implementing sequential numbering and visible labels for comment forms.

Why?

Currently, all comment inputs have the same generic "Comment" label, which provides no context for screen reader users. This makes the collaborative commenting feature largely unusable for users with assistive technologies, as they cannot distinguish between different comment contexts or know which comment they're replying to.

This PR addresses the accessibility issue by implementing unique, contextual labels for each comment input, following the recommendations from @joedolson in the issue discussion.

How

Sequential Comment Numbering: Comments are now numbered sequentially (Comment 1, Comment 2, etc.) based on creation order, not content order.
Contextual Labels:
- New comments: "Comment X" (where X is the next sequential number)
- Reply forms: "Reply to Comment X"
- Edit forms: "Edit Comment X"
Visible Labels: Labels are now visible to all users (not just screen readers) to facilitate team communication.
Smart Label Placement: Comment labels appear in the header area above the gravatar image for better visual hierarchy.

Implementation Details:

Enhanced CommentForm component with labelText props
Updated CommentBoard component with showLabel prop to control label visibility
Modified Comments component to pass sequential numbering to child components
Updated AddComment component to calculate next comment number
Added proper styling for visible labels

Testing Instructions

Open a post or page in the Gutenberg editor
Select a block and add a comment using the collaboration sidebar
Verify that the comment input shows "Comment 1" label
Add another comment to a different block
Verify that the second comment input shows "Comment 2" label
Click on the first comment to expand replies
Verify that the reply input shows "Reply to Comment 1" label
Add a reply and verify it appears without any label
Test editing a comment and verify it shows "Edit Comment X" label

Video

REC-20250923180954.mp4

github-actions · 2025-09-23T12:46:26Z

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: karthick-murugan <karthickmurugan@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: joedolson <joedolson@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>

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

Mamaduka · 2025-09-23T12:58:17Z

Return to Block Navigation: Added "Return to Block" button for improved accessibility navigation.

I think this can be done separately, and this PR can just focus on improving labeling.

karthick-murugan · 2025-09-23T13:02:27Z

Return to Block Navigation: Added "Return to Block" button for improved accessibility navigation.

I think this can be done separately, and this PR can just focus on improving labeling.

Sure thing, @Mamaduka. I’ll update both the description and the code so that this PR focuses solely on improving labeling. Thanks for pointing that out.

Mamaduka · 2025-09-23T13:45:40Z

@WordPress/gutenberg-design, would appreciate your feedback here.

t-hamano · 2025-09-24T01:08:43Z

I'm not sure if using sequential numbers for labels is the right approach. For example, someone asks someone else to review comment 3. Then someone else deletes comment 2. Now comment 3 has become comment 2. If we add a number, I think it should be a comment ID.

Personally, I think the visual label is too obtrusive. My suggestion is to make the comment container "truly" focusable and give it a more specific label.

For example, in Google Docs, the comment container is a list item and is focusable. When the container is focused, a screen reader will announce:

Comments dialog. Open comment. Author Aki Hamano. 1 replies. 0 new replies.  1 of 2  level 1

cc @joedolson

karthick-murugan · 2025-09-24T05:53:03Z

@t-hamano - Thank you for the detailed feedback! I've implemented the changes in my local as you suggested and tested them with VoiceOver. Still not yet pushed the code. Here's what I've addressed:

Changes Made

Removed Visual Labels: Eliminated the obtrusive visual labels as you suggested - the interface is now cleaner and less cluttered.
Enhanced Accessibility: Implemented rich, contextual aria-labels that provide comprehensive information to screen readers, including:
Comment context ("Comments dialog. Open comment")
Author information
Reply count
Status (active/resolved)
Posting date
Clear interaction instructions
Focusable Containers: Made comment containers truly focusable with proper keyboard navigation support.

Question About List Items

Regarding your mention of list items - could you clarify what you mean by "the contents of the comments container list items"?
Are you suggesting that each comment should be wrapped in <li> elements within a <ul>? Something else regarding the list structure?

Here is the video of the tested implementation. Please have a look and let me know your feedback.

REC-20250924110258.mp4

joedolson · 2025-09-24T20:19:15Z

@t-hamano I think sequential is fine; but the numbers should be persistent. If you delete comment 2, that should not change the labels on any other comment. Having an ID is fine, as long as they are easy to understand - a hash would be overwhelming, which is way sequential IDs makes more sense to me.

Practically, though, since we are only supporting comments at the block level, and not at the text level, it may not be that relevant, as long as it's easy to get the relationship between the comment you're writing and the block it relates to.

t-hamano · 2025-09-25T02:20:31Z

@karthick-murugan Sorry, my suggestions should be addressed in a separate PR. I have submitted #71883 to make threads focusable and improve keyboard navigation. In this PR (#71883), we should be able to simply focus on improving the labels.

I think sequential is fine; but the numbers should be persistent. If you delete comment 2, that should not change the labels on any other comment.

I'm not sure how to make the numbers persistent other than using the comment ID. Any ideas? The current PR generates sequential numbers based on the length of the thread, so the comment numbers could change.

t-hamano · 2025-09-25T02:26:38Z

Question: This PR improves the labels while also making them visible, but does every label need to be visible?

jasmussen · 2025-09-25T07:37:43Z

Thanks for the ping. I mulled over options and checked in with other folks pinged from the gutenberg-design group, and revisited some of these contexts based on the issue.

The general agreement validated the issue and suggested a need for a holistic solution that is not just technical, but also visual. In that vein there are two aspects to solve for:

Ensuring context between block and comments. "How do I know X comments go with X content?"
Technical: quick navigation between the block and its comments so I can actively review and assess feedback, make edits to the block, and reply to comments.

It connects, and so I put together this mockup:

Labels are there, but visually hidden.
The visual connection is made through the vertical alignment of the comment to the block, engaging the existing spotlight mode when clicking a comment, and showing the block toolbar for the block the selected comment is attached to.

The second half is feeling important. Which is that unless a comment vertically aligns to the block it's attached to, there's not going to be a clear connection between the two. Here's the present state:

2025-09-25 09 25 33 localhost 5ef30441cc5a

The sidebar drawer was always meant to be a way to access the archive of comments, but with the inline-comment, reminiscent of similar web-app implementations, the default experience for new comments. To that end, how likely is it we can add the vertical positioning to the "inline" sidebar variant as shown above?

Engaging spotlight mode, and showing the block toolbar, is about visually focusing on the block and enforcing the connection. At present in trunk, if there's a comment it shows up in the sidebar. But if you select it, the block it's attached to is not indicated at all. By engaging spotlight mode situationally (this wouldn't check the toggle, it would only use the underpinnings and classes ephemerally when engaging the mode). Engaging the toolbar is simply another indicator of "this block is selected".

I don't know that spotlight mode engagement has to happen for this to be usable, but the vertical alignment and showing the block toolbar for a block attached to a comment, that feels important. I realize that goes beyond just this PR. What do you think?

Mamaduka · 2025-09-25T07:53:17Z

First things first, let's keep this PR small and only focus on updating form labels, etc. We can continue the general discussion on tracking issues.

Thank you, @jasmussen, for the update. There're a couple of ongoing PRs that should improve the behavior you're describing.

At present in trunk, if there's a comment it shows up in the sidebar. But if you select it, the block it's attached to is not indicated at all.

Clicking on comments should scroll to the associated block and highlight it. The spotlight mode is a global setting, so I would avoid enabling it on comment click.

P.S. Why did we decide to use "scroll to + highlight" when a comment is selected, instead of selecting the block? The latter seems to be the most common UX in other apps.

jasmussen · 2025-09-25T08:22:34Z

Thanks for the updates.

Clicking on comments should scroll to the associated block and highlight it. The spotlight mode is a global setting, so I would avoid enabling it on comment click.

My mistake, I was using an old branch. Here's how that looks:

I still feel like we need a toolbar change. The previously selected block has a toolbar that's sticky to the top of the screen.

The spotlight mode is a global setting, so I would avoid enabling it on comment click.

I want to elaborate more on this, because just to be clear I'm not suggesting the user preference is changed at all. If you already have it on, you'll see no change. If you already have it off, the check in the dropdown will not be added, it's only the effect that will be applied, and only when the comment itself is selected or has focus inside. The idea is to use the scaffolding already built for spotlight mode, but apply it in more places. The feature itself is very underused right now.

To visualize it I created this prototype:

block.comments.mp4

As noted, I don't think it's a blocker, but let me know if the behavior makes sense!

Mamaduka · 2025-09-25T08:33:35Z

@jasmussen, I think I understand it better. We should probably create a separate issue for this and move the discussion there.

jasmussen · 2025-09-25T08:44:04Z

Created this issue, let me know if that works for you: #71891

I omitted mention of the select-block and toolbar change. I suspect there are some technical aspects there that you are perhaps better equipped to capture.

karthick-murugan · 2025-09-25T10:36:33Z

@Mamaduka @t-hamano

Updated the conflicts and I have updated the labels such like "Comments dialog: Open comment 196. Author admin 0 replies. Status: active. Posted 22/09/2025" where 196 is the commend id. This was implemented based on our earlier discussions. Please review the video, and let me know if further adjustments are needed.

REC-20250925155911.mp4

t-hamano · 2025-09-25T11:01:08Z

Although various issues are being discussed, let's clarify the purpose of this PR and make minimal changes.

I think the purpose of this PR is not to make threads focusable, but to only improve the label on the textarea itself in the comment form to make it clearer. What do you think?

Which block you're commenting on
Which comment you're replying to
Which comment you're editing

t-hamano · 2025-09-25T11:13:10Z

P.S. Why did we decide to use "scroll to + highlight" when a comment is selected, instead of selecting the block? The latter seems to be the most common UX in other apps.

selectBlock moves focus to the block, which I don't think is ideal from an a11y perspective, so we went with the scroll+highlight approach. See: #71308 (review)

Mamaduka · 2025-09-25T12:09:20Z

I think the purpose of this PR is not to make threads focusable, but to only improve the label on the textarea itself in the comment form to make it clearer. What do you think?

100%. Let's focus only on that. Atomic PRs/commits are always easy to review and merge.

Mamaduka · 2025-09-25T12:10:26Z

packages/editor/src/components/collab-sidebar/comments.js

 		<Thread
 			key={ thread.id }
 			thread={ thread }
+			commentId={ thread.id }


This value is already available via the thread object. There's no need to pass additional props.

Mamaduka · 2025-09-25T12:11:20Z

packages/editor/src/components/collab-sidebar/comments.js


 const CommentBoard = ( {
 	thread,
+	commentId,


@Mamaduka - Updated both the feedbacks. Thank You.

t-hamano · 2025-09-25T13:22:55Z

packages/editor/src/components/collab-sidebar/add-comment.js

+	// Generate contextual label for new comment
+	// For new comments, use a generic label since we don't have an ID yet
+	const commentLabel = _x( 'New Comment', 'Add new comment label' );


Suggested change

// Generate contextual label for new comment

// For new comments, use a generic label since we don't have an ID yet

const commentLabel = _x( 'New Comment', 'Add new comment label' );

const commentLabel = __( 'New Comment' );

The code comments and context seem redundant to me.

t-hamano · 2025-09-25T13:23:58Z

packages/editor/src/components/collab-sidebar/comment-form.js

+			<label
+				htmlFor={ inputId }
+				className="editor-collab-sidebar-panel__comment-label"
+			>
+				{ labelText || __( 'Comment' ) }
+			</label>


Instead of using a label element, I think it would be better to reuse the VisuallyHidden component.

t-hamano · 2025-09-25T13:24:48Z

packages/editor/src/components/collab-sidebar/comments.js

+			onKeyDown={ ( event ) => {
+				if ( event.key === 'Enter' || event.key === ' ' ) {
+					event.preventDefault();
+					handleCommentSelect( thread.id );
+				}
+			} }
+			role="button"
+			tabIndex={ 0 }
+			aria-label={ sprintf(
+				// translators: %1$s: comment identifier, %2$s: author name, %3$s: reply count, %4$s: status, %5$s: date.
+				_x(
+					'Comments dialog. Open comment %1$s. Author %2$s. %3$s replies. Status: %4$s. Posted %5$s. Click to focus.',
+					'Comment accessibility label with full context'
+				),
+				thread.id,
+				thread?.author_name || 'Unknown',
+				thread?.replies?.length || 0,
+				thread?.status === 'approved' ? 'resolved' : 'active',
+				thread?.date
+					? new Date( thread.date ).toLocaleDateString()
+					: 'unknown date'
+			) }
+			{ ...( thread?.replies?.length > 0 && {
+				'aria-expanded': isFocused,
+			} ) }


I don't think these changes are necessary; the aria-label on the thread container itself could be discussed in #71883.

t-hamano · 2025-09-25T13:25:11Z

packages/editor/src/components/collab-sidebar/comments.js

+								// translators: %1$s: comment identifier, %2$s: author name
+								_x(
+									'Reply to Comment %1$s by %2$s',
+									'Reply to specific comment with author context'
+								),


Suggested change

// translators: %1$s: comment identifier, %2$s: author name

_x(

'Reply to Comment %1$s by %2$s',

'Reply to specific comment with author context'

),

// translators: %1$s: comment identifier, %2$s: author name

__( 'Reply to Comment %1$s by %2$s' ),

t-hamano · 2025-09-25T13:25:33Z

packages/editor/src/components/collab-sidebar/comments.js

+						// translators: %1$s: comment identifier, %2$s: author name.
+						_x(
+							'Edit Comment %1$s by %2$s',
+							'Edit specific comment with author context'
+						),


Suggested change

// translators: %1$s: comment identifier, %2$s: author name.

_x(

'Edit Comment %1$s by %2$s',

'Edit specific comment with author context'

),

// translators: %1$s: comment identifier, %2$s: author name.

__( 'Edit Comment %1$s by %2$s' ),

@t-hamano - Updated all the changes.

joedolson · 2025-09-25T15:52:35Z

While I generally like visible labels, I think it's OK for these not to be visible. These are single-field forms, triggered using a button that says 'Comment', and with a submit button that visually says 'Comment' or 'Reply'. With good visual indication of which block a comment is associated with, there isn't a lot that a visible label on the field will add, and it doesn't need to be distinguished from other nearby input fields. It's very similar to a search input in that respect.

joedolson

LGTM!

packages/editor/src/components/collab-sidebar/style.scss

packages/editor/src/components/collab-sidebar/comment-form.js

Mamaduka · 2025-09-25T17:51:19Z

Thanks for your effort, @karthick-murugan!

Do you mind rebasing your branch on top of the latest trunk? We merged the end-to-end test coverage yesterday and want to ensure that we update locators as needed.

…prove-comment-input-labels

karthick-murugan · 2025-09-26T05:02:32Z

@Mamaduka - Rebased my branch with trunk. Thank You.

Improve comment input labels

2b57bff

Mamaduka mentioned this pull request Sep 23, 2025

Block Comments: Add general e2e test coverage #71844

Merged

2 tasks

Removed return to block function

8abb312

Mamaduka changed the title ~~Improve Comment Input Labels~~ Block Comments: Improve input labels Sep 23, 2025

This was referenced Sep 25, 2025

Block Comments Accessibility: improve comment input labels #71681

Closed

Align comments with their related block (when comment sidebar is not pinned) #71856

Closed

jasmussen mentioned this pull request Sep 25, 2025

Block Commenting: Highlight attached block using spotlight scaffolding #71891

Closed

karthick-murugan and others added 2 commits September 25, 2025 15:30

Feedback Changes

d227fd4

Merge branch 'trunk' into improve-comment-input-labels

eef4def

Removed few unwanted periods

bfc8c14

Mamaduka reviewed Sep 25, 2025

View reviewed changes

Updated the feedback

97615a9

t-hamano reviewed Sep 25, 2025

View reviewed changes

JS Lint fixes

7fa4066

joedolson approved these changes Sep 25, 2025

View reviewed changes

Mamaduka reviewed Sep 25, 2025

View reviewed changes

packages/editor/src/components/collab-sidebar/style.scss Outdated Show resolved Hide resolved

Mamaduka reviewed Sep 25, 2025

View reviewed changes

packages/editor/src/components/collab-sidebar/comment-form.js Show resolved Hide resolved

Feedback changes

0f35cd0

Merge branch 'trunk' of github.com:karthick-murugan/gutenberg into im…

3099d32

…prove-comment-input-labels

karthick-murugan and others added 2 commits September 26, 2025 11:29

Merge branch 'trunk' into improve-comment-input-labels

a0c530e

Js Lint errors

9dcf9c3

t-hamano mentioned this pull request Sep 26, 2025

Block Comments: Make comment thread focusable and improve keyboard navigation #71883

Merged

Mamaduka merged commit 13c3ecb into WordPress:trunk Sep 26, 2025
67 checks passed

github-actions bot added this to the Gutenberg 21.8 milestone Sep 26, 2025

karthick-murugan deleted the improve-comment-input-labels branch September 26, 2025 07:57

jasmussen mentioned this pull request Oct 3, 2025

contentOnly patterns: Allow re-entry into contentOnly mode after 'Edit contents' #72044

Merged

9 tasks

t-hamano added [Feature] Notes Phase 3 of the Gutenberg roadmap around block commenting and removed Collaborative Workflows Phase 3 of the Gutenberg roadmap around all-things related to collaborative workflows labels Oct 4, 2025

Block Comments: Improve input labels #71843

Block Comments: Improve input labels #71843

Uh oh!

Conversation

karthick-murugan commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How

Implementation Details:

Testing Instructions

Video

Uh oh!

github-actions bot commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mamaduka commented Sep 23, 2025

Uh oh!

karthick-murugan commented Sep 23, 2025

Uh oh!

Mamaduka commented Sep 23, 2025

Uh oh!

t-hamano commented Sep 24, 2025

Uh oh!

karthick-murugan commented Sep 24, 2025

Uh oh!

joedolson commented Sep 24, 2025

Uh oh!

t-hamano commented Sep 25, 2025

Uh oh!

t-hamano commented Sep 25, 2025

Uh oh!

jasmussen commented Sep 25, 2025

Uh oh!

Mamaduka commented Sep 25, 2025

Uh oh!

jasmussen commented Sep 25, 2025

Uh oh!

Mamaduka commented Sep 25, 2025

Uh oh!

jasmussen commented Sep 25, 2025

Uh oh!

karthick-murugan commented Sep 25, 2025

Uh oh!

t-hamano commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

t-hamano commented Sep 25, 2025

Uh oh!

Mamaduka commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joedolson commented Sep 25, 2025

Uh oh!

joedolson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Mamaduka commented Sep 25, 2025

karthick-murugan commented Sep 23, 2025 •

edited

Loading

github-actions bot commented Sep 23, 2025 •

edited

Loading

t-hamano commented Sep 25, 2025 •

edited

Loading

Mamaduka commented Sep 25, 2025 •

edited

Loading