Text input component: enhance/clarify guidance re placeholder and helper text both being optional

[tomwaterton]

The guidance for the text input component needs clarifying / enhancing

Detailed description

On the usage tab of the text input component (here: https://carbondesignsystem.com/components/text-input/usage/), currently the helper text is referred to as Optional helper text but placeholder text is simply referred to as placeholder text which could lead people to assume that placeholder text is always required, which is not actually the intention.

Here is a screenshot of what is currently shown on the text input page:

Slack comment from @jeanservaas from earlier today:

@tomerton placeholder text AND helper text are optional, but I understand your point that we don’t explicitly say “Optional placeholder text” like with do with helper text. I think this could be cleared up with just, clearer guidance/visuals… so people know placeholder and helper text are both available AND optional and when to employ them.

Suggested resolution:

• make it clear that both placeholder text and helper text are optional.
• provide some different (valid) examples that demonstrate that designers should use their judgement to use or not use placeholder text and helper text, depending on the scenario.
  • Perhaps one example could be of a simple / common field such as "First name" where only the text input label is needed.
  • Perhaps one example could be for a "Date" field where placeholder text has also been used to indicate the date format (MM/DD/YYYY or similar) but no helper text has been used.
  • Perhaps one example where a field has a text input label, no placeholder text, but does have helper text. This could be an example where you want the info to always be visible to the user — even when they are typing into the input field.

Another suggestion (vai Slack) from @jeanservaas

One resolution I see is showing both type options (both helper and placeholder) in an anatomy image and flagging them as optional there. Our text input usage docs are very scant and it doesn’t look like they’ve even been updated to Jan’s new Usage doc template.

[abbeyhrt]

When we make this update, we should update the storybook to remove placeholder from relevant examples.

[mbgower]

currently the helper text is referred to as Optional helper text but placeholder text is simply referred to as placeholder text

I pointed out this along with a lot of other considerations in our review of the Input usage page . An anatomy section would really help clarify this as well.

[mbgower]

Perhaps one example could be for a "Date" field where placeholder text has also been used to indicate the date format (MM/DD/YYYY or similar) but no helper text has been used.

Note that that would be a date input, not a text input. And i strongly urge Carbon NOT to use this as a desirable example. As stated in our review of Date picker, using the placeholder for the input requirement is problematic.

I also have an issue open specifically about date input masks https://github.com/carbon-design-system/carbon/issues/11805

[aagonzales]

We have recently updated the text-input usage guidelines (updates are now live, PR for reference)

• Placeholder text is no longer in the anatomy image, as it is not added in the component by default.
• Placeholder text is clearly labeled as optional in the content section.
• Placeholder text has been removed by default in storybook.

Remaining tasks:

• Update the component demo to remove placeholder text (new default). This will need to be a dev issue and is a low priority in our backlog.
• Update style tab images to say "optional" where placeholder text in mentioned (design task)
• Add do/don't for good and bad placeholder use-cases

[aagonzales]

@tomwaterton @mbgower If y'all could read through the new docs when you have time and see if we have addressed this problem (outside the remaining issue mentioned in the above comment.

[tomwaterton]

Hi @aagonzales I've just read through the updated text-input guidelines and I think they are now good. Thank you. 👍

Obviously, to make the guidance really clear, the remaining tasks you mention need to be done as well, but I understand that some of those require dev work and design work — and therefore will take more time to happen.

[tomwaterton]

I'll also just mention, in case it helps, that I had also raised a separate but related bug:

Enhance guidance regarding the form component re placeholder text and helper text #1907

(Basically, requesting some improvements to the guidance relating to placeholder text and helper text within the Carbon form component.)

[mbgower]

Checking this morning...

[mbgower]

I feel like I already wrote much of the following as feedback. Maybe I failed to push the Comment button and it was lost...?

Live demo

As per @tomwaterton's comment, I think a very easy change would be to make the Live Demo (shown below) say "Optional placeholder text" instead of just "Placeholder text"

Anatomy

I think the Anatomy is a welcome addition (shown below). It's good to go, but I did want to mention a couple of things that gave me pause...

• using the word "Optional" in the illustration to demonstrate the optional required field is a bit of a brain twister, but I think it comes out better than if you'd said "Required" to describe the optional required. I wonder if it would be a bit clearer if you called this "Required vs optional" or "Completion indicator"?
• I wonder if you should put in any one-liner stating that "All components shown in text input apply to text area. I think it's sufficient this way, but I can't help wondering if someone is going to misread it and think the label for text area is optional.

Main elements

In the Main elements section, I think there needs to be a bit of attention on this line from labels:

Labels should clearly state the requirement status.

"Input requirement" is listed as optional in the anatomy, so this could be slightly confusing. I suggest two thing could help with this 1) use the same term in the anatomy (currently "Input requirement) and do some slight rewording 2) cross reference the Forms material on this. You'd end up with something like the following (and maybe this is enough you'd want to give it its own subsection?

The input requirement status, when used, appears at the end of the label. See Optional versus required fields in the Forms component for more information.

For Helper text, I think I flagged that before, but I don't understand where Carbon says a tooltip can be used for help -- is it covered somewhere? If not, since you've already said this is optional, I'd just take the whole following line out?

~Helper text is an optional feature and can be used in place of a tooltip.~

I also found the following line a little confusing:

When used, helper text is always available when the input is focused and appears underneath the field. The exceptions are when an error or warning message replaces the helper text.

I think it might work better as:

When used, helper text appears persistently underneath the field, except when an error or warning message replaces it.

For the Placeholder text, please state explicitly that it should not be used as a replacement for a label. I suggest modifying the second sentence from:

Placeholder text disappears after the user begins entering data into the input and should not contain crucial information.

to:

Placeholder text disappears after the user begins entering data into the input. As such, it should not be used as a replacement for a persistent label nor should it contain crucial information.

It's nice you've added an Accessibility best practices section, but I feel like these are already covered on the Accessibility page. Maybe it could be as simple as something like this:

Accessibility best practices The Accessibility tab covers how Carbon provides main element information to screen readers.

Universal behaviors

I wonder if this information could be offered once in Carbon and simply linked to from each component. Much is not unique to Text input.

I found the Default values section a bit of a curve ball. It seems like it may be better covered in Forms?

"Required vs. optional" You should probably spell out "versus". I put in notes on stuff that appeared earlier. Maybe you could just point to this later material? It seems a little out of place, but I get it's hard to put in this 'secondary' stuff in a main flow.

Interactions

"A separate click is required to activate any additional actions associated with the text input such as a tooltip..." Really? I wasn't aware of that!

---

This is all great! As mentioned earlier, both resize Text area and character count are not currently accessible. We should open 2 issues and put them in backlog. Both things require some exploration!

[aagonzales]

Link to stub issue about accessibility concerns with text area features: https://github.com/carbon-design-system/carbon/issues/12071

[aagonzales]

@tomwaterton @mbgower can either of you think of another example of acceptable placeholder text for a text input?

Are any of the following acceptable, or are these all don'ts?

• Instructions as a placeholder
• Example as a placeholder
• Formatting as a placeholder (if also included in helper text)

[mbgower]

Those seem to be the primary uses. I would remove "Example" from your second one. They don't tend to have that.

My primary piece of advice would be the placeholder should be redundant with other information. The true test? The interaction should still be easy to complete if the placeholder text is removed. "Removal" is the same basic test I use for colour and several other things, to confirm that I wasn't relying on that information.

[tomwaterton]

Hi @aagonzales

My thoughts, looking at the 3-part image example from your comment:

• 1st example: We recommend that people only use placeholder text where it adds value; we recommended they do not use placeholder text if it merely repeats the field label, so this first example ("Enter user name") is not one we'd want to recommend.
• 2nd example: I think this is good.
• 3rd example: Again, we recommend that people do not use placeholder text if it merely repeats existing helper text, so I think this also is not one we'd want to recommend.

My thoughts regarding your other question:

(I've added a, b, c to make it clear which one I'm referring to in the text that follows.)

Are any of the following acceptable, or are these all don'ts?

• a) Instructions as a placeholder
• b) Example as a placeholder
• c) Formatting as a placeholder (if also included in helper text)

a) No. Because placeholder text is hidden/becomes unavailable to users as soon as they start typing into the field, instructions should really be provided as helper text (which will remain visible/available to the user throughout).

b) Some examples are fine. They shouldn't contain essential information (such as format) because that should always be available and so should be provided as helper text. But sometimes providing an example of the kind of thing the user might enter is useful. Here's an example:

c) No. As mentioned above, we don't want people to be needlessly duplicating content — that just makes our UIs look overly busy. So if formatting information is given in the helper text below an input field, then there is no need to duplicate that same info as placeholder text.

A final thought:

I think some designers almost feel like they should use placeholder text, which often results in them just duplicating the field label (or helper text). To help prevent this, I think it would be great if we added an explicit statement addressing this. For example:

If you have usefully used placeholder text in one form field, do not think that the other form fields now need to have placeholder text also. Placeholder text should only be used where it adds value. Do not use placeholder text to merely repeat the field label (or helper text).

[tomwaterton]

I just spotted this example of placeholder text in a product UI, so thought I'd share it as another possible example for you, @aagonzales (though if you do choose to use this, please first correct the capitalization to sentence case!)

[mbgower]

Tom's comments are all valid (although his 2nd example became username instead of email). With his comments in mind, Anna, if you were looking for what to actually provide as placeholders in those examples, I think you'd likely need to change at least the first example:

Full name: Jane Smith Email: user@address.com Phone number: 123-456-7890 [where helper text is 000...]

I think the search example is useful, especially if you think of one where there IS no search label, since the magnifying glass serves as an after-the-fact label (and I'm not defending that) Search for assets, tags, types, or owners... [magnifying glass icon]

[aagonzales]

Side note, the example I showed wasn't supposed to be a form, just single examples of possible placeholder content (illustrating examples mentioned in the list).

Search is a good example of placeholder but that is its own component and not a text-input.

[aagonzales]

I believe most of the concerns and suggestions in this issue have been addressed. If anyone see's anything that is still incorrect, please comment but I am closing this as complete for now.

[mbgower]

@aagonzales In the Live demo area, still saying "Placeholder text" instead of "Optional placeholder text"

I note the anatomy section entirely leaves off Placeholder text now, which I didn't think was anyone's intention?

Finally, it looks like none of the substantial Sept 7 comments I made have been incorporated. I did a quick search on the first few (none changed), then noticed that it looks like no commits were pushed since August, so if so obviously my fairly numerous comments above may not have been seen?

On the other hand, last time I ventured a conjecture like this, I think maybe they were picked up in some revised component, so happy to be corrected :)

[mbgower]

Ah just noticed the prior comment:

Placeholder text is no longer in the anatomy image, as it is not added in the component by default.

Okay, that's fine, so you can ignore "I note the anatomy section entirely leaves off Placeholder text now, which I didn't think was anyone's intention?" Will the 'not added by default' also apply to future Figma library updates? I notice every single one of them has it (and not listed as optional)! Obviously if the main visual being pulled in contains it by default, the chances of it being left in (with updated text) and implemented goes up, IMO.

[aagonzales]

Website documentation has been updated (in Fluid branch that will be published soon) to address placeholder and helper text concerns. I will open a new issue to address adding additional clarity to the Figma kits.

https://github.com/carbon-design-system/carbon-design-kit/issues/619

[aagonzales]

Closing as complete for now (updates won't be live yet but are in staging) but in the future you still notice problems, please feel free to comment