Define a consistent text treatment for help text underneath form fields

[kjellr]

As brought up in #15469 (comment), Gutenberg is currently inconsistent in its text styling for under-form-field help text. In most cases, it's using italic text, as defined in the BaseControl component:

We have many other cases where similar text is not italic however. In these cases, the text is the exact same weight and size as the form field labels:

We should settle on a global approach for this sort of help text. As @afercia pointed out, it's important to consider accessibility issues with italic text — among other potential concerns, italic text is known to be more difficult to read for those with dyslexia.

[kjellr]

Sharing some quick explorations to fuel discussion:

---

Option 1: Remove italic, no other changes

• ➕ Simple, easy to read.
• ➖ Unless there's a link, text is exactly the same size + style as the field label, which can be confusing if there's another field below this one.

---

Option 2: Italic

• ➕ Good differentiation between the help text and the field label.
• ➖ Italic text is widely regarded to be difficult to read for users with Dyslexia.

---

Option 3: Two gray colors

This version darkens the field label, and lightens the help text color. I used $dark-gray-900 and $dark-gray-300 for now, but we'd certainly refine if we went this direction.

• ➕ Passable, but not obvious differentiation between the help text and the field label.
• ➕ Darker field labels are easier for everyone to read.
• ❓ There may be unintended consequences to darkening field labels everywhere.

---

Option 4: Bold form field labels

• ➕ Good differentiation between the help text and the field label.
• ➖ We use bold for panel/section headers. Using it for all form fields will hurt differentiation there.
• ❓ There are surely other unintended consequences to bolding field labels everywhere.

---

Option 6: Font size differences

Here, I used 11px labels. Despite being super tiny (to my elder millennial eyes at least), this size is is used in many areas of Gutenberg.

• ➕ Good differentiation between the help text and the field label.
• ➖ 11px text is too small to comfortably read for many users.

---

Option 7: Font size differences (with larger text)

Since I think 11px is too small, I tried 14px labels (1px larger than they are currently) and 12px labels (1px smaller than they are currently).

• ➕ Good differentiation between the help text and the field label.
• ➕ Bigger label text is easier for everyone to read.
• ➖ Smaller label text is harder for everyone to read.
• ➖ This would be a really complicated change: If we're going to make this text larger, we should definitely make other 13px text larger too. That'll definitely have repercussions across the interface.

[melchoyce]

"Option 3: Two gray colors" looks much better to me than what we have now, just from scanning through the options, and seems to have the fewest negatives. I think this would be the best quick win of the options.

Edit: Might be worth exploring semibold for the label here as well.

That said, "Option 7: Font size differences (with larger text)" appeals to me most in the long-term, since our labels are pretty small across the admin — embiggening them everywhere would be a win. I think if we're able to make all our labels 14px (maybe even 15px?), we could potentially leave the help text 13px.

[mapk]

Yep, I like Option 3 the best. While the two grays may not be distinguishable by some, I feel that's okay and the positioning of the help text (under), as opposed to the positioning of the label (top or side), seems to help relate the purpose as well.

Adjusting the font size is something I've heard before and @jasmussen has recently shared some concerns with how small our text is too. Just pinging him for his input too!

[kjellr]

That said, "Option 7: Font size differences (with larger text)" appeals to me most in the long-term, since our labels are pretty small across the admin — embiggening them everywhere would be a win. I think if we're able to make all our labels 14px (maybe even 15px?), we could potentially leave the help text 13px.

One other thing to note about this direction: if we were to up the size of the form field labels, it would probably make sense to up the size of the field text itself. It feels a little weird (to me) to have the actual input text be smaller than the label:

Also worth noting: on smaller screens, our input field text size is actually bumped up to 16px already, to avoid browser zoom when focusing on the fields:

[jasmussen]

Great thoughts here.

One aspect that I increasingly test when thinking of accessibility in visual design, is to imagine the screen as grayscale. How can I differentiate two blocks of text in that case? This is one of the reasons why underlined text makes good sense.

In that vein, I'm personally mostly drawn to a combination of 4 and 7. 15px feels like too big a text bump unless we also bump font sizes elsewhere (which we should consider, but do in a holistic way). Maybe 14px and semi-bold?

[jasmussen]

Also worth noting: on smaller screens, our input field text size is actually bumped up to 16px already, to avoid browser zoom when focusing on the fields:

It's worth clarifying that this is done because otherwise mobile safari zooms in which is a super jarring effect. There's supposed to be a way to opt out of that zooming, but last I tried it didn't work. This is just to say that this is the mobile safari tax, and not necessarily one we should optimize towards.

[kjellr]

15px feels like too big a text bump unless we also bump font sizes elsewhere (which we should consider, but do in a holistic way). Maybe 14px and semi-bold?

I agree that 15px feels like too big of a bump. My gut here says that a tiny first step would be to try changing our standard 13px size to 14px, and our standard 11px size to 12px. That's a small change, but because of the cascading changes this creates, it makes sense to try small changes first.

Also, I wouldn't want to change this in just the form fields: we'd want to adjust these sizes globally. I wouldn't want to add a 14px size while keeping a 13px size too — 1px font-size increments aren't enough to establish clear hierarchy, and frequently look like mistakes when seen together. It's certainly a big change — but it seems like a 1px change has to be somewhat manageable... right? 😉

(All that said, I also feel like a global font size change may be out of the scope of just this one super-specific ticket. 😄)

This is just to say that this is the mobile safari tax, and not necessarily one we should optimize towards.

I agree that it's definitely a Safari hack, but it's also one that I really like in practice. On mobile, this feels like an excellent font size for these fields.

[jasmussen]

I'm very much in favor of bigger font sizes, it's one of the reasons for https://core.trac.wordpress.org/ticket/47012. The toolbars are even designed to be able to accommodate bigger (24x24px) icons.

The reason I'm careful is not lack of desire for better legibility, it's rooted in a past attempt to bump the font size across the board. It was sadly not as simple as changing a variable — there's a ton of invisible complexity in the shifting UI that still has to be able to accommodate translations and mobile viewports.

To circle back to this ticket specifically, it would seem that bumping the font size of headings, and un-italicizing the help text would be a great first step. Just consider subheadings too.

[afercia]

Note: for Core, I've created https://core.trac.wordpress.org/ticket/47327

[afercia]

For feedback and interesting resources, please refer to the Trac ticket https://core.trac.wordpress.org/ticket/47327

[melchoyce]

@davewhitley has a typography proposal that would cover these styles: https://make.wordpress.org/design/2019/10/11/proposal-a-consistent-type-scale-for-wordpress/

He made a PR to test them out: #18244

[davewhitley]

Yep! Thanks Mel.

Following the typescale:

• Labels would be "Body small"
• Input text would be "Body"
• Help text would be "Caption"

[wittwitsan]

In Design triage today, we agreed that the type scale brings a nice balance to the form field. At least settle on the help text should be a point or 2 smaller than the label and a little lighter grey, no italics.