Form pattern

[designertyler]

Pattern describes the form element, it's multiple variants and its application for product and system level tasks. It covers the various inputs, actions and hierarchies that comprise a form and their usage, along with behaviors like errors and validation, progressive disclosure and inline verification.

Questions will arise around how we separate the Form component and Form pattern in the same way we separate Shell components from Navigation patterns. The form and and of itself is more of a pattern comprised of components, not a component and possibly should not be categorized as such. It's often a self-contained UI, in which layotus and relationshiops are critical to user experience — this aspect presents its own unique issues.

Carbon:
https://www.carbondesignsystem.com/components/form/code/

Cloud data and AI
https://github.ibm.com/CloudIntegrationDesign/DesignSystemAdoptionGuild/issues/38

Cloud data and AI
https://github.ibm.com/CloudIntegrationDesign/DesignSystemAdoptionGuild/issues/60

Cloud data and AI
https://github.ibm.com/CloudIntegrationDesign/DesignSystemAdoptionGuild/issues/62

IoT
https://pages.github.ibm.com/Watson-IoT/IoT-Design-Site/patterns/forms/

WCE
http://billboard1.fyre.ibm.com/component-library

• Look at any existing form guidance from other BU's
• Do any other components have relevant form guidance in their usage tab? (button does)
• Create an outline for a Form pattern page.
• Create any supporting images.
• When to use a number input vs. a select (when there's a large amount of options)

[connor-leech]

Additional form patterns:
https://www.patternfly.org/v4/design-guidelines/usage-and-behavior/forms

[connor-leech]

---
title: Forms
---

<PageDescription>

Forms collect structured data from users.

</PageDescription>

<AnchorLinks>
  <AnchorLink>Overview</AnchorLink>
  <AnchorLink>Behavior guidance</AnchorLink>
  <AnchorLink>Assets</AnchorLink>
  <AnchorLink>References</AnchorLink>
  <AnchorLink>Metadata</AnchorLink>
</AnchorLinks>

## Overview

### Keep it short

Forms are used for submitting data so be as concise as possible when designing. Think about each field and what value the data will provide. What do you gain by collecting this information?

#### Begin by asking:

* Is this a piece of information that is valuable to us?
* Is this a piece of information that is so valuable that it’s worth preventing the user from continuing if they choose not to provide it?

### Labels

Effective form labeling helps users understand what information to enter into a Text Input. Using a placeholder text as a label is often applied as a space-saving method. However, this is not recommended because it hides context and presents accessibility issues.

### Accessibility best practices for labels:

* Labels must be visible when an input gets focus.
* Labels must be announced to the screen reader on focus.
* Ensure the helper text that appears under an input is read when an assistive technology user stops at an input using ARIA.
* Use sentence-style capitalization (only the first word in a phrase and any proper nouns capitalized).

### Default values

Where possible, add programmatic assistance. Detect and pre-fill inputs to reduce errors and save time. When the software can’t determine the value that belongs in an input, use type-ahead to make suggestions. Use sentence-case for default values, detected values, and auto-completion text.

### Help text

Help text is pertinent information that assists the user in completing a field. Help text is always available when the input is focused and appears underneath the label. Use sentence-style capitalization, and in most cases, write the text as full sentences with punctuation.
Placeholder text

Placeholder text provides hints or examples of what to enter. Placeholder text disappears after the user begins entering data into the Input and should not contain crucial information. Use sentence-style capitalization, and in most cases, write the text as a direct statement without punctuation.

### Format

All forms are comprised of 6 elements:

* Labels: Inform users what the corresponding input fields mean.
* Input fields: Enable users to provide information. Information can be entered through a variety of different input fields ranging from text fields, checkboxes, and many other types.
* Help text: Provides assistance on how to fill out a field. Help text is optional.
* Placeholder text: Hints at what goes into a field. Placeholder text is optional.
* Actions: Allow users to submit a form.
* Validation: Ensures the data submitted by the user conforms to acceptable parameters.
    
## Behavior guidance

### Multi step forms

When the primary action implies a navigation step forward, as in a wizard, align single buttons or Secondary/Primary button groups to the right. This position conveys the “next step” intention.

## Assets

### Form logic

* **Radio buttons** are used when there is a list of two or more options that are mutually exclusive and the user must select exactly one choice. In other words, clicking a non-selected radio button will deselect whatever other button was previously selected in the list.
* **Checkboxes** are used when there are lists of options and the user may select any number of choices, including zero, one, or several. In other words, each checkbox is independent of all other checkboxes in the list, so checking one box doesn’t uncheck the others. A stand-alone checkbox, or a toggle can be used for a single option that the user can turn on or off.
* **Select elements** are used for fields in which a single selection is required and there are a large number of possible options.

### Validation and errors

#### Error messaging

Effective error messaging can help the user to understand the problem and how to fix it. First, inform the user what has happened, then provide guidance on next steps or possible resolutions. Inline notifications can be used to state the general problem with the users input, such as “Please input the required fields.” Inline Notifications can occur pre or post submission, depending on the type of data the user is inputting.

#### Form validation

We recommend validating the users data before form submission. Use visual cues to guide the user as to where the problem lies within the form. This will help to easily identify the elements that need to be corrected.

The validation should appear when the user has clicked away from the text field. Once the user corrects the errors within the text field, the validation should disappear once the data is rendered as valid.

The validation label below the field should be as informative as possible when describing the issue with the users data. For example, if password limitations require 16 characters, but the user inputs a password with only six characters, the text should read something like, “Password must be at least 16 characters.”

#### Optional vs. required fields

All fields in a form are assumed required, with optional fields being tagged as so.

## References

**Explain any accessibility testing you conducted.** No individual component or pattern can be accessible, but they can be used in an accessible way to create an accessible experience. Include any research and proof you may have in your pattern documentation.

**Include any citations.** Research, books, and articles you found helpful offer legitimacy to your pattern and help designers understand your decisions.

**Offer any development notes you may have.** Many patterns don't require specific developer attention to implement. If you have any developer guidance, include it here.

## Metadata

### Components used

* Radio buttons
* Checkboxes
* Select
* Text entry

### Related patterns

* Empty states
* Error states

### Awaiting work

* User testing
* Research

[jeanservaas]

Hi all, I'm out for the week of thanksgiving, but I wanted to post a first draft of my form pattern here. @connor-leech, I haven't made the image assets yet.. but if you have time next week (and since you offered tee hee) — the copy can go into markdown!

I'm attaching my WIP sketch file and a (gulp) PDF of my design for @petervachon, diana tran and @joshblack to review. @chrisconnors-ibm and @mjabbink went through most of it with me today and I've already made some of their changes.

Sketch file:

https://ibm.box.com/s/2cotywq7y6vrf9rjxw87c9b4d5f4gnbh

PDF:

form_pattern_WIP.pdf

[joshblack]

Leaving feedback here, let me know if there is a better place!

High-level feedback

Seems like it really covers all the bases, would it help to split up the content so that the page itself isn't overwhelming? Forms in general seem like one of the most complicated patterns and there is just so much content for it.

General feedback

Forms can be simple or complex, and may be presented as dedicated pages, side panels or dialogs

Do we want to encourage the dialog use-case? In general, will we offer guidance on what should happen with a form that exists in a panel or dialog that can be dismissed? Meaning that if the user has supplied information and the panel/dialog is dismissed would we want to keep it around, lost it, refresh state, etc.

When designing be mindful of password managers and browser capabilities that populate data for users

This point is so good 💯 on the dev side, we could speak about how this relates to the autocomplete attribute which is available on <input> elements that accept text or numeric values as input.

There are a ton of great values for autocomplete that could help folks design forms that work really well with auto-fill or password managers listed here: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete#Values

Help: Provides in-context guidance like tooltips, placeholder text, or helper text

How do we feel about Nielsen's article on placeholders? https://www.nngroup.com/articles/form-design-placeholders/

Labels should clearly state the required input

Would we want to follow the guidance in: https://www.nngroup.com/articles/required-fields/ and choose either the word "required" or the "" pattern? Maybe "required" would be easier since I'm not sure if "" is universal language-wise?

Separately, this seems to contradict later down with the line "All fields in a form are assumed required" in that we state that it should clearly state being required, but then we say that fields are assumed required.

Top-aligned labels are Carbon's default (vs left-aligned labels)

When we talk about positioning, would it make sense to communicate it using relative terms? Or are we expecting that forms would always be left-aligned even in a right-to-left situation?

The way CSS is going it looks like they're using "block" and "inline" to refer to top/bottom and left/right accordingly, along with "start" and "end" to refer to either left or right side (or flipped for RTL). In other words, by default LTR would have the following alignments for these words:

• block-start: top
• block-end: bottom
• inline-start: left
• inline-end: right

So top-left would be inline-start and block-start, which would go between top/left for LTR and top/right for RTL

Technical reference: https://adrianroselli.com/2019/11/css-logical-properties.html

Deciding what to use

Would we want to incorporate any dev feedback for folks on what the corresponding type attribute would be for the <input>? e.g.

Control	Usage	Context	type
Text input	-	-	type="text"
Password	-	-	type="password"

Truncate when an input is too long to be fully displayed in the field

Would we truncate or allow the input to overflow and be scrollable?

The first required input field should receive focus on presentation to a user

Not sure if this is something we would recommend doing, might be the case if the form is presented in a dialog or side panel but not necessarily on a page itself

Offering help
Tooltip

Would we prefer help text to tooltips generally in form design?

Errors and validation
Real-time validation

When an error occurs, do we clear the input value? Do we have any preferences on how often a user should be receiving inline feedback on validity? Is it as they type? When the focus is moved away from the input?

---

Some content that might be helpful to add for accessibility (or not):

• Color contrast requirements for text/labels, along with container target (WCAG 2.1 I think is 3:1 now?)
• Color contrast requirements for placeholder text
• Placeholders in Form Fields Are Harmful
  • https://www.nngroup.com/articles/form-design-placeholders/

Some broader concepts that we might need to touch on:

• Every control needs a corresponding <label>
• Related concept might be from notification where we do the status banner at the top of the form region, this would be aria-live and role="status" if we want to talk about that
• Errors should be coordinated with aria-describedby
• When to move focus to certain form items when they fail validation

---

Some links and resources for accessibility:

• Nielsen Norman Group
  • https://www.nngroup.com/articles/web-form-design/
  • https://www.nngroup.com/articles/form-design-white-space/
  • https://www.nngroup.com/articles/required-fields/
• Accessibility
  • https://www.w3.org/WAI/tutorials/forms/
  • https://www.deque.com/blog/anatomy-of-accessible-forms-best-practices/
  • https://www.deque.com/blog/anatomy-of-accessible-forms-error-messages/