Give editable fields better labels

[afercia]

Splitting this out from #1477

Screen readers and other assistive technologies (for example speech recognition software) use the aria-label attribute to announce the name (the "accessible name") of UI controls to users.

contenteditable regions in the editor use an aria-label attribute and a visible placeholder text with the same value. For example, a quote block uses a Write quote… text for both.

One important thing to consider is that contenteditable regions tend to be reported by screen readers as sort of form fields. The behavior differs across screen readers but they understand it's an editable region. Thus, an aria-label gets announced as it was the label of a form field:

NVDA instead tends to announce as editable the actual HTML element, for example it announces:
paragraph editable for the text block
list editable for the list block
text frame editable for the button block (because it's a span)

Regardless, it does announce the aria-label. So what happens, in a few words?
There's the risk the visible placeholder text is reported as content of the editable text, so hearing, for example: Write label ... Write label should be avoided. One option could be hiding the visible placeholder from assistive technologies with aria-hidden.

However, I'm not sure we should use Write label…, Write…, etc., as aria-label in the first place. They behave like labels of a form field so they are announced even after users enter some content, for example:

This could be confusing, as the aria-label text in this scenario is not so appropriate. Wondering how to improve the overall way editable regions are exposed to assistive technologies. Any feedback welcome!

[mtias]

Closing in favor of #3412. (I think it is appropriate, but feel free to reopen and clarify.)

[afercia]

@mtias not exactly the same thing. This is about how those fields are labeled. I can detail this issue on #3412 if you prefer, but they're really two different things.

[afercia]

Agreed to reopen.

More details: See screenshot below:

The main title is a special case, so let's ignore it for now.

Instead, all the other editable regions use an aria-label attribute Add text or type... which is not appropriate. The aria-label attribute works as a <label> element and gives a name to its control. So both when the Editable is empty or already filled up with content, screen readers will announce the Editable with the name given by the aria-label.

For example, landing on a paragraph screen reader users will hear:
Add text or type / to insert content

This is OK as a visual instruction, but doesn't tell anything useful to users. In a standard form, this would be the equivalent of, for example, a "first name" field with a label that doesn't say it's about the first name, and says instead Add text or type / to insert content.

Instead, the aria-label should identify what the Editable is. For a paragraph, it should say: Paragraph content or similar wording.

[afercia]

This is even more important now that most of the editable fields use a role="textbox", see #4074, and thus are announced by screen readers as real input fields or textareas.

[tofumatt]

This issue probably requires more triage or context because right now it's quite broad, but the gist of it is: we should use aria-labels that give more context and act less like placeholders. Labels and placeholders (probably) shouldn't have the same content and it's confusing/redundant when they do.

To start with: this issue could aim to clarify/reconcile the labels/placeholders of the following (RichText) blocks:

• paragraph
• list
• button

(We can always add more.)

[afercia]

Agree #5981 was sort of a duplicate. Some recommendations made there should be taken into account though, especially #5981 (comment)

It's not just about paragraph, list, and button. Here's a list of placeholder used also as aria-labels I've made a while ago (it may be out of date):

audio
placeholder={ __( 'Enter URL here…' ) }
placeholder={ __( 'Write caption…' ) }

button
placeholder={ __( 'Add text…' ) }

code
placeholder={ __( 'Write code…' ) }

cover image
placeholder={ __( 'Write title…' ) }

embed
placeholder={ __( 'Enter URL to embed here…' ) }
placeholder={ __( 'Write caption…' ) }

gallery
placeholder={ __( 'Write caption…' ) }

heading
placeholder={ placeholder || __( 'Write heading…' ) }

image
placeholder={ __( 'Write caption…' ) }

list
placeholder={ __( 'Write list…' ) }

paragraph
placeholder={ placeholder || __( 'Add text or type / to add content' ) }

preformatted
placeholder={ __( 'Write preformatted text…' ) }

pullquote / quote
placeholder={ __( 'Write quote…' ) }
placeholder={ __( 'Write citation…' ) }

shortcode
placeholder={ __( 'Write shortcode here…' ) }

subheading
placeholder={ placeholder || __( 'Write subheading…' ) }

text columns
placeholder={ __( 'New Column' ) }

verse
placeholder={ __( 'Write…' ) }

video
placeholder={ __( 'Enter URL here…' ) }
placeholder={ __( 'Write caption…' ) }

All these values are used also as aria-label for the editable fields, which doesn't make sense for users. These values are more "suggestions" that should go in a description (see #5981 (comment)). Instead, each editable field should be labelled to communicate what it is, as one would normally do for form fields. E.g.: "Paragraph content".

[afercia]

Labels and placeholders (probably) shouldn't have the same content

I'm pretty sure we can remove the word "probably" 🙂 To further clarify why these aria-label values are far from ideal, imagine:

• you are blind and you're using a screen reader
• you land on something that is announced as a textarea (role=textbox aria-multiline=true)
• whether the textarea is empty or already has content, you don't have a clue what this textarea is about, because it's labelled as Add text or type / to add content

Visually, this is equivalent to the following:

The above is exactly what screen readers users perceive. As said, it applies to all the RichText instances listed above.

Worth noting using a proper aria-label would help screen reader users but wouldn't entirely solve the problem. For example, speech recognition software users need the control name (i.e. label) to be visible to be able to voice commands and directly activate the control. In the case of RichText editable fields there's no visible label though. More details:
https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html
https://www.levelaccess.com/considerations-testing-speech-recognition-software-dragon-naturally-speaking/

[timwright12]

@tofumatt @afercia Do we still have open items here or did #11560 and #11653 take care of it? If it's still open, I can take a run at it (via @10up). Let me know!

[afercia]

@timwright12 labelling of the RichText field is still a problem, as the value used for aria-label is the same used for the placeholder. For example:

These fields are the equivalent of a textarea (role="textbox" aria-multiline="true") and need a proper label as if they were standard textareas. In a form, we wouldn't ever label a textarea: "write quote" or "write citation". We'd use "Quote content" and "Citation content" or simply "Quote" and "Citation".

Nothing new to add to the previous comment #1659 (comment)

[timwright12]

@afercia on it.

[timwright12]

@tofumatt @afercia Just so we're on the same page and we don't have to go back and forth in a PR about the actual aria-label and placeholder content, this is the update I'm proposing (below). Using placeholder the way we're using it is technically a WCAG parsing violation (as to my understanding of it: https://www.w3.org/TR/2016/NOTE-UNDERSTANDING-WCAG20-20161007/ensure-compat-parses.html) since it isn't "fully conforming to the specification" in certain places (https://www.w3.org/TR/WCAG20-TECHS/G192.html) by using placeholders as labels or actions (like "write...") instead of hints to, or examples, of what the user should insert into the field (https://www.w3.org/TR/html52/sec-forms.html#the-placeholder-attribute). The ones I updated below should closer meet that requirement, but I'm obviously happy to modify them.

Please let me know if these are OK to move forward with or if we think some of them need to be changed. Some guidance on "Text Columns" would be much appreciated as well.

audio
placeholder={ __( 'Add URL for audio here: https://...' ) }
label={ __( 'Audio URL' ) }

button
placeholder={ __( 'Add button text here' ) }
label={ __( 'Button' ) }

code
placeholder={ __( 'Add code here' ) }
label={ __( 'Code' ) }

cover image
placeholder={ __( 'Add cover image title here' ) }
label={ __( Cover image title' ) }

embed
placeholder={ __( 'Add URL embed URL: https://...' ) }
label={ __( 'Embed URL' ) }
placeholder={ __( 'Add caption' ) }
label={ __( 'Embed caption' ) }

gallery
placeholder={ __( 'Add gallery caption here' ) }
label={ __( 'Gallery caption' ) }

heading
placeholder={ placeholder || __( 'Add heading here' ) }
label={ label || __( 'Heading' ) }

image
placeholder={ __( 'Add image caption here' ) }
label={ __( 'Image caption' ) }

list
placeholder={ __( 'Add list items here' ) }
label={ __( 'List' ) }

paragraph
placeholder={ placeholder || __( 'Add text or type / to add content' ) }
label={ label || __( 'Paragraph' ) }

preformatted
placeholder={ __( 'Add preformatted text here' ) }
label={ __( 'Preformatted text' ) }

pullquote / quote
placeholder={ __( 'Add quote here' ) }
label={ __( 'Quote' ) }
placeholder={ __( 'Add quote citation here' ) }
label={ __( 'Quote citation' ) }

shortcode
placeholder={ __( 'Add shortcode here' ) }
label={ __( 'Shortcode' ) }

subheading
placeholder={ placeholder || __( 'Add subheading here' ) }
label={ label || __( 'Subheading' ) }

text columns (I couldn't find this one, but I'm sure I will)
placeholder={ __( 'New Column, add content here' ) }
label={ __( 'Text Column' ) }

verse
placeholder={ __( 'Add verse content here' ) }
label={ __( 'Verse' ) }

video
placeholder={ __( 'Add URL to video here: https://... ) }
label={ __( 'Video URL ) }
placeholder={ __( 'Add video caption here' ) }
label={ __( 'Video caption' ) }

Once we work out the actual content, the update should be relatively quick to implement.

[anevins12]

^

audio
placeholder={ __( 'Add URL for audio here: https://...' ) }
placeholder={ __( 'Audio URL' ) }

You mean..:
audio
placeholder={ __( 'Add URL for audio here: https://...' ) }
label={ __( 'Audio URL' ) }
?

[timwright12]

@anevins12 yup, sorry about that (updated)

[anevins12]

I agree with the approach of using the (aria)label as the most useful information and the placeholder as supplementary information. It shouldn't matter if the placeholder text is not read out at all, but yes if it is then it shouldn't duplicate information for that field.

[tofumatt]

Because there isn't yet a PR to review on this one, I'm moving this out of the 5.0 release milestone. I've moved it to the 5.0.x follow-up milestone for now. I think we can probably get this in a 5.0.x release; if it was ready for review today (or anytime before we release 4.5) I'd be happy to land it for WordPress 5.0 😄

[samikeijonen]

@timwright12 Suggestions looks good. I'm not sure do we need word "here" though.

[ellatrix]

@afercia What's the status of this one? Any actionable items?

[mapk]

It doesn't look like there are really actionable items here that can be ported into Gutenberg when Gutenberg's desire is to mimic the frontend. Maybe closing this for now is okay.

[afercia]

This issue has nothing to do with visual things that may impact the front end.

It's about the way the various editable fields (including contenteditables) are labelled, in combination with their visual placeholders.

I see something has changed in the meantime but still some fields are labelled improperly. Specifically, the aria-label attribute should only indicate what the editable is about and omit any "action". Then, the visible placeholder text should match the text used for the aria-label attribute.

Specifically, all the action verbs like "Add", "Write", etc should be removed. For some of the editable, they're still used even when users already entered some text. For example:

In the screenshot above: though the block itself is correctly labelled as Block: Button, its editable is labelled as Add text... even when it's filled with some text.

Screen readers will announce the editable as Add text... because that's the accessible name given by the aria-label attribute:

This is extremely confusing for users and not helpful at all.

In a classic web form, this would be equivalent to labelling the form fields in the following way:

which is arguably something no one would ever do.

Reopening this issue for the second time, in the hope I've been finally able to clarify what this issue is about.

[mapk]

My mistake. Thanks for reopening and updating it, @afercia.