Add help texts for category block settings

[samikeijonen]

Description

Adds Display post date help text in Categories block as mentioned in #2146.

How has this been tested?

• Run npm test without errors.
• Tested toggling toggle settings in Categories block.

Types of changes

Adds help texts for category block settings.

Screenshots

Off state

On state

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.

[paulwilde]

I gotta be honest, I'm not a fan of adding these descriptions as they seem to pretty much repeat what the initial label says. It also makes it look kinda busy/cluttered with the label and description looking identical besides the italic.

If the issue this is trying to solve is that it's not obvious what the 'On' state of the toggle is, then I believe this is more of an issue with the toggle itself.

[samikeijonen]

Yeah the copy itself is hard. But there needs to be some kind of text what the toggle do. See more info in #2146. In short:

• Give hint is the toggle on or off.
• Explain the meaning off the toggle.

[samikeijonen]

In this case help text might even be On/Off.

[jasmussen]

Sami, thank you for your pull requests. I really appreciate your desire to help here. I'm a little concerned about us duplicating text just to indicate the on/off state of the switch.

I know there are differing opinions on this, but in my capacity as just a contributor to this project, in my perception the switch element has these properties:

• It is a form element like the checkbox, but one that implies immediate effect (like a lightswitch)
• A switch needs a descriptive label for what it does
• Some switch controls need additional help text to further clarify — drop cap is a good example because few know what a "drop cap" is
• Some switches can benefit from contextual help text, to further clarify both the on or off state

In this PR, every switch control, to me, feels like it has a sufficiently descriptive help text not to need help text at all, let alone contextual help text. And when we do use contextual help text, we should be mindful not to just make it a simple "On/Off" text, as that should ideally be redundant by the switch itself.

I recognize that there is no widely agreed upon consensus on this issue. But we are all adults, and we should all feel safe to share our thoughts, controversial or not. When a switch control design is being discussed in isolation, it's easy to generalize. But in order to create a good overall design for the entire editor, we have to zoom out and look holistically to form a full picture.

There are many switches, and once you've learned how to use a switch once — like how you learned how to use the checkbox — you should have learned how it works. This is about re-using patterns to simplify complicated concepts, and it is a balancing act we have to always keep in mind — because for every icon we add, for ever bit of text we add, we add to the cognitive load of the entire editor. This is a usability issue as much as anything.

We all want the same — a user friendly and welcoming editor that's easy to use for everyone regardless of skill level. If the current switch design is truly a blocker for that, let's discuss that design. But as we discuss this, please, let's consider text translations and the intrinsic value that whitespace has on the perception of difficulty an interface exudes.

CC: @pento @karmatosed @mtias

[michelleweber]

We could change the label to just Dropdown/Post Counts/Hierarchy, and then the subtext stays the same and specifics whether the feature is on or off. Unless the lack of detail in the label presents an accessibility problem?

[samikeijonen]

At this point I'd say the current label is enough. There might be a small learning curve at first: is the switch on or off.

And the switch design is definitely much much better now.

I'm not going to close this yet if someone has another opinions on this.

[afercia]

Sorry but I thought a consensus was reached on this matter, I'm a bit surprised to have to discuss again this issue. All the accessibility concerns were illustrated at length on #2146, I'm not going to repeat them here and those who are interested in more details can refer to that issue.

The key point is that the state of these switches needs to be reflected in some textual form too.

Some consensus was expressed here by @pento: #2146 (comment)

After that, as accessibility team we're proceeding to add help text to all the switches. Of course, the copy can be improved. It should just reflect the switch state, as it does in the Gallery block settings.

But in order to create a good overall design for the entire editor, we have to zoom out and look holistically to form a full picture.

Sorry but what do you mean by "design" in this context? To me, something that makes a feature less functional for some users, it's not design.

for every icon we add, for ever bit of text we add, we add to the cognitive load of the entire editor. This is a usability issue as much as anything.

I'd say an UI control that doesn't provide a clear indication of its state adds a lot of cognitive load every time users try to use it.

[afercia]

@samikeijonen thanks for your PR! I'd suggest to refactor a bit the copy of the help text. It shouldn't be used to inform about the available action, e.g. "Toggle to show ...". Instead, it should exclusively indicate the state of the setting. For example:

• Post counts are not displayed
• Post count are displayed

I recognize in some cases finding a proper wording could be a bit difficult. 🙂

[karmatosed]

Lots of discussion here which is good as it's a point we totally need to air and work through. Whilst some work has been done, sometimes decisions need thinking about at point of code. Generally we avoid it but sometimes a step back is needed, this is one of those.

I do standby @jasmussen, in believing once it has been learnt then a label doesn't need to be for every single one. What we have here is causing a negative impact on usability, whilst I know that wasn't the intent. For example thinking of those with different reading experiences and even translations.

Let's take a pause and consider also other options.

@pento can you perhaps explain your thoughts on this seeing as a pull request?

[folletto]

I checked the currently released Gutenberg release, and I noticed the source is already a native checkbox implementation, with the correct for attribute and reference:

<div class="components-panel__row">
<label for="pending-toggle-1">Pending Review</label>
<span class="components-form-toggle">
<input class="components-form-toggle__input" id="pending-toggle-1" type="checkbox">
<span class="components-form-toggle__track"></span>
<span class="components-form-toggle__thumb"></span>
<svg class="components-form-toggle__off" width="6" height="6" aria-hidden="true" role="img" focusable="false" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 6 6">
...</svg>
</span>
</div>

This means the component should already natively respond correctly to a screen reader (which should pick up correctly the checkbox).

If it's not the case, we could also consider aria-checked that allows to create that behaviour on non-checkbox components afaik:
https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_checkbox_role

I tested with the Mac screen reader and it correctly says when selected:

What am I missing here? I read the comment pointed to above, but why isn't the standard checkbox implementation enough with the visual marking?

---

Update — as re-reading my comment I feel I'm going to get as reply "the comment you mention already answers it".

1. It's accessible from screen readers
2. It has a marking that distinguish on and off (exactly like accessible toggle labels in iOS)
3. Duplicating text is going to make it harder to read for dyslexic people, and will impair readability and scannability for everyone

I'm not sure there's anything missing here. Adding the text seems to decrease the usability and readability to everyone.

[afercia]

@folletto reading the referenced issues and comments on the other issues may help 🙂 Accessibility is not just about screen readers.

#2146 (comment)

In this specific case, a bit ironically, blind users will find these switch toggles perfectly accessible because, under the hood, they're native checkboxes and they will be announced as such by assistive technologies.
My concern is more about visuals. I'd say that's also an usability issue, not just an accessibility one. There are no "universal symbols" that can be understood by everyone. We can't rely on colors, we can't rely on symbols or icons alone. So yes, there's the need to use some textual representation as also recommended by the material design.

Please read the rest of the issue, I can't copy the whole thread on #2146 🙂

[folletto]

@afercia I updated the message above because I understood before the edit it could have been interpreted as I didn't read the thread you linked — I'm aware updates don't get notified. Sorry about the misunderstanding.

---

As I noted in the update, the toggle already provides a visual indication (which is standard across industry, using I/O). While adding a text is surely even clearer, we must consider that adding an explicit text has consequences. Expanding on my comment above:

1. People with dyslexia will have twice the text to read to understand the control. This is a major issue.
2. The text will dynamically update on switch, causing an extra screen change to manage. As you mention correctly aria-hidden="true" would solve the problem for screen readers, it would still cause extra reading for people with reading impairments, because now they have to read it again to know what the text says (3x the amount of text to read).
3. Everyone (intended as everyone, not everyone but the people for which this change is useful) will end up having to read twice/thrice the content, thus making the whole interface harder to scan.

As you rightfully state above, accessibility isn't just about screen readers, it's about universal access, everyone has their own needs:

• We minimise the amount of text, with good copy, for people with dyslexia and other perceptive and reading disabilities.
• We use a semantic control, which provides accessibility to not just screen reader, but to any library and control that leverage standard checkboxes.
• We use color markings to signify an enabled state which work also on inverted screens, providing visual support for certain cognitive impairments.
• We provide a visual indication of on/off status that doesn't rely on color alone, using industry standard I/O markers (like iOS does) that also support a general understanding of the toggle as enabled for everyone.

If we zoom out from this specific discussion, we also can see how this control is already on par if not outperforming in accessibility standard native checkboxes.

Your concern is well put here, and raising the point was important to review the control and make sure it was able to achieve as much as possible universal access.

The extra changing label however, while beneficial under a certain perspective, will create problems for everyone under another, and doesn't seem to me a step forward for universal access.

[pento]

There's certainly a balancing act to be made here. I agree that we need to ensure that everyone is able to clearly understand the state of a switch, which was my thinking behind my earlier comment. I agree with @jasmussen that #6415 is a good example of where adding the help text makes sense: "Drop Cap" is a jargon-y term, expanding on what the switch is doing in the help text clarifies that.

In the case of this PR, however, several folks have made the point that this extra text makes the interface harder to read, which is true. @folletto makes the point that this reduces accessibility for dyslexic people in particular, which is a blocker for this PR at any rate.

With that in mind, it's worth taking some time to consider whether the switch itself clearly communicates its state. I agree with @folletto's analysis here: the switch provides multiple cues to indicate its state. In addition to the points above, there are a couple of extra points that occurred to me while I was thinking about this:

• The switch is on the left for "off", and on the right for "on". Every UI library I've looked at has the same behaviour. Just for fun, I also checked all of the electronic devices in my house: the ones that use a left/right switch followed the same pattern. Even if people don't actively think about it, this is a pattern we should be able to assume that they're aware of, just like we assume they know that a button is for pressing, a text field is for typing, and a dropdown is for opening. Should this pattern be different in some cultures (say, I can imagine it being different in cultures that use RTL languages), we can pretty easily allow switching the direction.
• It's been mentioned a few times that the I/O markers are industry standards, it's worth re-iterating that they're literal ISO standards: Off, and on. It doesn't get much more standard than ISO.

@afercia: You've mentioned Material Design several times, but I think it's possible to misread the statement "The option that the switch controls, as well as the state it’s in, should be made clear from the corresponding inline label." The Android Switch control has three label properties: text, textOn, and textOff. text is the label you see visually displayed, while textOn and textOff are the labels you hear when enabling the screen reader. This is reflected in Google's use of the Switch control: they will occasionally update the label or help text when the Switch state changes for more complex options (as we're doing in #6415), but almost all options will show no visual text change when the Switch changes state.

Indeed, this behaviour explicitly mentioned in Apple's Human Interface Guidelines, which says to "avoid adding labels to describe the values of a switch."

Given that Material Design is the only guideline I'm aware of that alludes to the idea of changing a text label to match the state of a switch, Apple's HIG unambiguously says to not do that, and I haven't come across any other references stating that a visible text label should always be updated to match the state of a switch control, then I think this PR can be closed, and #2146 can remain open while we evaluate whether each instance of ToggleControl requires additional help text to clarify what the switch is doing.

[samikeijonen]

Thanks for all your input. In this case it comes down to this:

we need to ensure that everyone is able to clearly understand the state of a switch

The learning curve for this is very small in this switch, like explained in great detail in above comments.

So I'm going to close this PR. But in the same time we need to remember that not all switches are born equal. Drop Cap was one example. Without help text it would be really hard to understand what does it mean.

Wrap text is another in #6567 and perhaps Hide the teaser before in #6561.

[folletto]

But in the same time we need to remember that not all switches are born equal. Drop Cap was one example. Without help text it would be really hard to understand what does it mean.

Solid agreement there! Either working on the copy of the label, or adding an extra informative line can help a lot in some instances.

[afercia]

@folletto what I'm arguing about here and in the other issue is precisely that a thing like a standard across industry, using I/O doesn't make much sense in this context. Does it applies to all cultures, languages, level of expertise, cognitive impairments, etc.? Do you really think, honestly, that two very small symbols like I and O can really solve the problem? 🙂
WordPress is a global project and aims to be inclusive, it shouldn't rely on arguable standards.

@pento re: Material Design, corresponding inline label. has a clear meaning to me. It's about the inline label. Also, this should be read in the context of the change they've made from the previous version which provided the On/Off text. They've deprecated the On/Off text in favor of the inline label.

Re: regardless the I/O markers are ISO standards, do you really think all users will easily understand their meaning, users from all countries, all cultures, all different expertise level, different cognitive abilities, etc., etc.?

I'd agree usability and accessibility are, as usual, a matter of balance. There are several different needs to take into account. Often, a solution that improves things for one specific need, can worsen things for another need. Dyslexia is one of these cases, as @folletto correctly pointed out.

However, the only form of really universal communication on the web is text. Not icon, not symbols and the like. As always, some short and simple text can be understood by everyone.

To clarify, I haven't asked for this help text to be a long explanation of what the control does. I do believe a long text is inappropriate. This text should be just a bit more verbose replacement of the missing On/Off text.

That said, at this point I'm going to repeat what I've already pointed out in #2146. These switches are controversial and there's no consensus about them. In this conversation some good argumentations were made to point out there are different kind of user needs that would require different solutions. At this point, I don't see a great value added by these switches compared to native checkboxes. Native checkboxes are universal, simple, and clear. It's just how the web works. Can anyone explain me what value these switches add? Apart from the fact they look prettier, of course 🙂

[afercia]

Just for reference, some screenshots from Microsoft Edge, Win 10, and Linkedin. Seems I'm not the only one who thinks a textual indication of the state is necessary: