Interface guidelines for forms #261

mperrotti · 2022-04-27T00:18:09Z

These changes introduce high-level interface guidelines for designing forms.

More specific guidelines for each form-related component will follow in separate PRs.

vercel · 2022-04-27T00:18:11Z

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/primer/design/HB9nUYhJHRyZScuq3CRNy9UXr4BS
✅ Preview: https://design-git-mp-forms-docs-primer.vercel.app

src/@primer/gatsby-theme-doctocat/nav.yml

content/ui-patterns/forms.mdx

camertron

What a phenomenal amount of work, thank you for writing all this up! 🎉

content/ui-patterns/forms.mdx

vdepizzol

As a general note, we should revisit the alternate text from the images — Instead of saying like "diagrams labeling the anatomy of a text field and a checkbox field", the alternate text should describe what's present in the diagrams or screenshots.

content/ui-patterns/forms.mdx

vdepizzol · 2022-05-02T18:04:49Z

content/ui-patterns/forms.mdx

+
+If you're having trouble keeping label text short, consider using a [caption](#caption) to provide more context.
+
+In rare cases, a label may be hidden when the user has enough context to understand what the input does. When a label is visually hidden, label text must still be provided for assistive technology such as screen readers. For example: a search field with an icon that is placed in the spot a user would expect to find a search field may have a visually hidden label that says "Search".


In rare cases, a label may be hidden

For example: a search field with an icon that is placed in the spot a user would expect to find a search field may have a visually hidden label that says "Search".

Is a search field part of a forms pattern? Search fields appear throughout dotcom, and they're not rare =).

Is a search field part of a forms pattern?

It could be, but usually it isn't. I was trying to think of the most common and obvious example.

Do you (or any other reviewers) have any better examples?

@mperrotti I'm not sure. It's confusing to see an example about a search field while this page is specifically about [long-form] forms pattern.

Good point about these guidelines being for long-form forms. I think it might be best to exclude this paragraph. Visually hidden labels can be addressed in form component guidelines.

content/ui-patterns/forms.mdx

vdepizzol · 2022-05-02T18:10:08Z

content/ui-patterns/forms.mdx

+  </Dont>
+</DoDontContainer>
+
+### Validation message


The examples using checkbox groups have some weird application of bold. Do we really want to use bold labels for every checkbox or radio button item? Are the validation messages also meant to be bold? 🤔

These are all meant to be bold. That's how the components are currently designed.

I'd be happy to change the checkbox and radio labels from bold to regular weight in separate PCSS and PRC PRs. What do you think @vdepizzol?

I think the intent with the semibold label is that the styles are consistent through all form elements (so input, select etc.) But I don't feel that the validation messages should also be semibold.

The semibold error messages are kind of new: primer/react#2013

@colebemis and I think it helps the text feel more balanced with the leading icon, but I'm open to changing it back to regular weight it if it's causing an issue.

Other reviewers - please chime in if you agree with @langermank that validation text should go back to regular weight.

@mperrotti I'd keep it at a regular weight. Validation messages can appear multiple times to the user in the same form. The bolded font feels too heavy.

Ok, I'll update the example images and submit a PR to PRC to change the weight back to normal.

content/ui-patterns/forms.mdx

vdepizzol · 2022-05-02T18:27:34Z

content/ui-patterns/forms.mdx

+        <img
+            alt="Checkbox that progressively discloses a labeled text input"
+            src="https://user-images.githubusercontent.com/2313998/164065217-7969283a-6dbb-43b6-8f62-e4ab995de246.png"
+        />


This UI feels confusing, with the checkbox label and text input label having the same alignment and style. I don't think we should use a search icon in that case, but I'm afraid that's not the only thing that's adding to the confusion.

You're right - this isn't a great example. I'll come up with a better way to show a labeled input that is "nested" and progressively disclosed.

content/ui-patterns/forms.mdx

vdepizzol · 2022-05-02T18:33:12Z

content/ui-patterns/forms.mdx

+        alt="screen recording of valid repo name input showing loading indicator after blur"
+        src="https://user-images.githubusercontent.com/2313998/164065857-573ca6db-f2c7-49ac-a3cf-bf479a40973d.gif"
+    />
+    <Box as="p" mt="0">If the form control’s validation is likely to take more than 1 second, show a loading indicator.</Box>


If the form control’s validation is likely to take more than 1 second

Is this the right metric to decide whether to display a loading indicator? What if the process is known as a quick one but the user is on a slow connection?

Also, if we're extending the height of the input control based on an async request that may take long to process, how do we avoid the content to reflow unexpectedly?

Is this the right metric to decide whether to display a loading indicator? What if the process is known as a quick one but the user is on a slow connection?

It shouldn't matter what connection the user is on. This is a detail that would be handled in the implementation.

Also, if we're extending the height of the input control based on an async request that may take long to process, how do we avoid the content to reflow unexpectedly?

That's a great question, and I have no idea how we'd avoid reflow in that case.

Is this the right metric to decide whether to display a loading indicator? What if the process is known as a quick one but the user is on a slow connection?

It shouldn't matter what connection the user is on. This is a detail that would be handled in the implementation.

@mperrotti if there's a server request, wouldn't it make more sense to show the loading spinner regardless? I don't understand how that'd be handled in the implementation 🤔 .

if there's a server request, wouldn't it make more sense to show the loading spinner regardless?

@vdepizzol - I was trying to avoid showing too many loading indicators because they could make the app feel slower. If we wait 1 second, we're still giving the user feedback that something is happening, but only if it's something that's making the user wait a noticeable amount of time.

Does that make sense?

content/ui-patterns/forms.mdx

Co-authored-by: Inayaili León <yaili@github.com>

Co-authored-by: Cameron Dutro <camertron@gmail.com>

vdepizzol · 2022-05-23T17:38:31Z

content/ui-patterns/forms.mdx

+<Box sx={{fontSize: 3}} class="lead" as="p">
+    Forms are used to complete tasks that require data input from the user. For example: creating a new repo, configuring settings, and logging in.
+</Box>
+
+<Box sx={{fontSize: 3}} class="lead" as="p">
+    Primer's form design guidelines aim to minimize the effort and cognitive load required to complete a task that involves a form.
+</Box>


@mperrotti Can we simplify this leading description and make it into a single paragraph?

Forms are used to complete tasks that require data input from the user. For example: creating a new repo, configuring settings, and logging in.

Primer's form design guidelines aim to minimize the effort and cognitive load required to complete a task that involves a form.

vdepizzol · 2022-05-23T17:54:44Z

content/ui-patterns/forms.mdx

+    </div>
+</Box>
+
+### Inline validation


@mperrotti I'm finding it quite confusing to see these 3 gifs next to each other. There's a lot going on 😬 . I'm not sure I have any recommendations for now, but it's something we should pay more attention...

Screen.Recording.2022-05-23.at.10.49.45.mov

You're right - all this motion is overwhelming. I'm going to try converting these to <video> elements that can be played or paused individually.

vdepizzol · 2022-05-23T17:57:09Z

content/ui-patterns/forms.mdx

+
+<DoDontContainer>
+  <Do>
+    <img role="presentation" src="https://user-images.githubusercontent.com/2313998/166832266-c34634ec-2ade-4bf6-8401-df0bdc02b324.png" />


@mperrotti This "do" example feels quite redundant 🤔

content/ui-patterns/forms.mdx

vdepizzol · 2022-05-23T18:44:06Z

@mperrotti I think we should have a rationale for form widths when in a form composition. It's hard to parse from the examples what the recommendation should be:

From "Structure"	From "Progressively disclosed form controls"	From "Inline validation"

Co-authored-by: Vinicius Depizzol <vdepizzol@github.com>

…s-docs

mperrotti · 2022-05-25T15:54:47Z

@vdepizzol - I pushed a few commits to address your feedback.

I used a browser-native <video /> to address your comment about adjacent gifs, but the black gradient behind the player controls is pretty ugly. I'm working on a light custom video player component, but I can't figure out how to import it from src/@primer/gatsby-theme-doctocat/components 😅 . I reached out for help, so it should be resolved soon.

langermank · 2022-05-27T16:05:49Z

content/ui-patterns/forms.mdx

+    </Box>
+    <Box as="ul" pl="1rem">
+      <li>
+        Single-line text inputs get a default width set by the browser, but their width can be changed to fit the


What is the default width? It might be helpful to mention that here.

We don't define the default width - It's set by the browser.

mperrotti · 2022-08-05T15:09:39Z

All of the requested changes have been made and this has just been sitting here. I'm merging it.

If there are additional changes needed, we can file issues and create new PRs.

mperrotti added 4 commits January 24, 2022 17:04

WIP

5cc8cac

WIP

4c7222d

Merge branch 'main' of github.com:primer/design into mp/forms-docs

e8b570a

adds interface guidelines for forms

2a62bd5

mperrotti requested a review from a team as a code owner April 27, 2022 00:18

mperrotti temporarily deployed to github-pages April 27, 2022 00:21 Inactive

yaili requested changes Apr 28, 2022

View reviewed changes

camertron approved these changes May 2, 2022

View reviewed changes

ashygee reviewed May 2, 2022

View reviewed changes

content/ui-patterns/forms.mdx Outdated Show resolved Hide resolved

ashygee reviewed May 2, 2022

View reviewed changes

content/ui-patterns/forms.mdx Outdated Show resolved Hide resolved

vdepizzol suggested changes May 2, 2022

View reviewed changes

mperrotti and others added 4 commits May 4, 2022 10:35

Update content/ui-patterns/forms.mdx

0f1bc44

Co-authored-by: Inayaili León <yaili@github.com>

Update content/ui-patterns/forms.mdx

e06b2c6

Co-authored-by: Inayaili León <yaili@github.com>

Update content/ui-patterns/forms.mdx

3804436

Co-authored-by: Inayaili León <yaili@github.com>

Update content/ui-patterns/forms.mdx

a202e05

Co-authored-by: Inayaili León <yaili@github.com>

mperrotti temporarily deployed to github-pages May 4, 2022 14:43 Inactive

Update content/ui-patterns/forms.mdx

3c6e364

Co-authored-by: Inayaili León <yaili@github.com>

mperrotti temporarily deployed to github-pages May 4, 2022 14:47 Inactive

mperrotti and others added 5 commits May 4, 2022 10:51

Update content/ui-patterns/forms.mdx

a373809

Co-authored-by: Inayaili León <yaili@github.com>

Update content/ui-patterns/forms.mdx

32f4e6e

Co-authored-by: Inayaili León <yaili@github.com>

Update content/ui-patterns/forms.mdx

786bdcd

Co-authored-by: Cameron Dutro <camertron@gmail.com>

Update content/ui-patterns/forms.mdx

3a858fe

Co-authored-by: Cameron Dutro <camertron@gmail.com>

Update content/ui-patterns/forms.mdx

cee08d2

Co-authored-by: Cameron Dutro <camertron@gmail.com>

mperrotti temporarily deployed to github-pages May 4, 2022 14:58 Inactive

mperrotti and others added 4 commits May 4, 2022 11:02

Update content/ui-patterns/forms.mdx

67c15b3

Co-authored-by: Cameron Dutro <camertron@gmail.com>

Update content/ui-patterns/forms.mdx

d6e29a4

Co-authored-by: Cameron Dutro <camertron@gmail.com>

Update content/ui-patterns/forms.mdx

62492d4

Co-authored-by: Cameron Dutro <camertron@gmail.com>

Update content/ui-patterns/forms.mdx

91498ae

Co-authored-by: Cameron Dutro <camertron@gmail.com>

mperrotti temporarily deployed to github-pages May 4, 2022 15:06 Inactive

mperrotti temporarily deployed to github-pages May 17, 2022 23:24 Inactive

addresses feedback about unclear guidelines

5758eba

mperrotti temporarily deployed to github-pages May 17, 2022 23:38 Inactive

mperrotti requested a review from alliethu May 20, 2022 14:24

vdepizzol reviewed May 23, 2022

View reviewed changes

content/ui-patterns/forms.mdx Outdated Show resolved Hide resolved

Update content/ui-patterns/forms.mdx

b4ff765

Co-authored-by: Vinicius Depizzol <vdepizzol@github.com>

mperrotti temporarily deployed to github-pages May 23, 2022 20:57 Inactive

mperrotti added 5 commits May 24, 2022 11:21

adds guidance about form control sizing

9b6b785

Merge branch 'mp/forms-docs' of github.com:primer/design into mp/form…

e1b6e2c

…s-docs

shortens intro paragraph, removes guidance about hiding labels

8a4ad2c

updates example images

0d0c6c5

renders gifs as HTML video elements

265a168

mperrotti temporarily deployed to github-pages May 25, 2022 15:49 Inactive

mperrotti requested a review from vdepizzol May 25, 2022 15:54

adds custom video player

90544e0

mperrotti temporarily deployed to github-pages May 26, 2022 21:03 Inactive

adds aria labels to icon buttons

4e2265b

langermank reviewed May 27, 2022

View reviewed changes

mperrotti added 3 commits June 1, 2022 11:44

Merge branch 'main' of github.com:primer/design into mp/forms-docs

32e8aad

Merge branch 'main' of github.com:primer/design into mp/forms-docs

fe1aa91

addresses feedback about formcontrol anatomy diagrams

585268e

mperrotti temporarily deployed to github-pages June 2, 2022 17:44 Inactive

mperrotti merged commit 42797bd into main Aug 5, 2022

mperrotti deleted the mp/forms-docs branch August 5, 2022 15:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Interface guidelines for forms #261

Interface guidelines for forms #261

mperrotti commented Apr 27, 2022

vercel bot commented Apr 27, 2022

camertron left a comment

vdepizzol left a comment

vdepizzol May 2, 2022

mperrotti May 4, 2022

vdepizzol May 23, 2022

mperrotti May 23, 2022

vdepizzol May 2, 2022

mperrotti May 4, 2022

langermank May 9, 2022

mperrotti May 12, 2022

vdepizzol May 23, 2022

mperrotti May 23, 2022

vdepizzol May 2, 2022

mperrotti May 4, 2022

vdepizzol May 2, 2022

vdepizzol May 2, 2022

mperrotti May 4, 2022

mperrotti May 4, 2022

vdepizzol May 23, 2022

mperrotti May 23, 2022

vdepizzol May 23, 2022

vdepizzol May 23, 2022

mperrotti May 23, 2022

vdepizzol May 23, 2022

vdepizzol commented May 23, 2022

mperrotti commented May 25, 2022

langermank May 27, 2022

mperrotti Jun 1, 2022 •

edited

Loading

mperrotti commented Aug 5, 2022


		If you're having trouble keeping label text short, consider using a [caption](#caption) to provide more context.

		In rare cases, a label may be hidden when the user has enough context to understand what the input does. When a label is visually hidden, label text must still be provided for assistive technology such as screen readers. For example: a search field with an icon that is placed in the spot a user would expect to find a search field may have a visually hidden label that says "Search".

Interface guidelines for forms #261

Interface guidelines for forms #261

Conversation

mperrotti commented Apr 27, 2022

vercel bot commented Apr 27, 2022

camertron left a comment

Choose a reason for hiding this comment

vdepizzol left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vdepizzol commented May 23, 2022

mperrotti commented May 25, 2022

Choose a reason for hiding this comment

mperrotti Jun 1, 2022 • edited Loading

Choose a reason for hiding this comment

mperrotti commented Aug 5, 2022

mperrotti Jun 1, 2022 •

edited

Loading