Merge pull request #2434 from department-of-veterans-affairs/megzehn-…

…formlabels

Update form-labels.md

src/_components/form/index.md

@@ -25,6 +25,7 @@ sub-pages:
   - sub-page: Text input
   - sub-page: Textarea
 anchors:
+  - anchor: Usage
   - anchor: Accessibility considerations for all form elements
   - anchor: Error handling
   - anchor: How to group form controls
@@ -38,84 +39,23 @@ anchors:
   <p>View documentation for the current forms library for VA.gov on <a href="{{ site.forms_system_link }}">the platform website</a>.</p>
 </va-featured-content>
 
+<a class="vads-c-action-link--blue" href="https://designsystem.digital.gov/components/form/">Refer to the U.S. Web Design System for usage guidance</a>
+
 ## Accessibility considerations for all form elements
 
 {% include a11y/do-not-disable-buttons.md %}
 
 ## How to group form controls
 
-- Group each set of thematically related controls in a `fieldset` element. Use the `legend` element as a heading within each one. The `fieldset` and `legend` elements make it easier for screen reader users to navigate the form.
-- Use a single legend for fieldset (this is required). One example of a common use of `fieldset` and `legend` is a question with radio button options for answers. The question text and radio buttons are wrapped in a fieldset, with the question itself being inside the `legend` tag.
-- Embed multiple fieldsets and legends for more complex forms if the form is not broken in separate chapters.
-- Keep your form inputs and labels arranged vertically along the same Y axis. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.
+* Group each set of thematically related controls in a `fieldset` element. Use the `legend` element as a heading within each one. The `fieldset` and `legend` elements make it easier for screen reader users to navigate the form.
+* Use a single legend for fieldset (this is required). One example of a common use of `fieldset` and `legend` is a question with radio button options for answers. The question text and radio buttons are wrapped in a fieldset, with the question itself being inside the `legend` tag.
+* Embed multiple fieldsets and legends for more complex forms if the form is not broken in separate chapters.
+* Keep your form inputs and labels arranged vertically along the same Y axis. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.
 
 ## Error handling
 
-<div class="site-showcase">
-{% include_relative html/error-text-inputs.html %}
-</div>
-
-In all cases, only show error validation messages or stylings after a user has interacted with a particular field.
-
-In general, when there is an error on a form, a few things must happen.
-
-* The form field and its corresponding `<label>` are wrapped in a container with a class name of `usa-input-error`. This will provide a thick border and padding to visual indicate an error message to users who might have difficulty perceiving contrast. It also changes the border of the input to red as a secondary indicator.
-* An error message is placed between the label and the form field.
-* The form field receives an `aria-describedby` attribute that references the `id` of the error message.
-* Prepending `<span class="sr-only">Error</span>` to error messages alerts screen screen readers clearly that an error exists.
-
-The HTML for a typical error is:
-
-```html
-<span class="usa-input-error-message undefined" role="alert" id="file-input-149-error-message">
-  <span class="sr-only">Error</span>
-  Error message
-</span>
-```
-
-<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/patterns/help-users-to/recover-from-errors">Review the help users to recover from errors pattern</a>
+{% include components/label-errors.html %}
 
 ## Hint text
 
-When a detailed form input label is not enough to convey the meaning or purpose of the input, we have three options for including additional context:
-
-1. [Beneath the label (default)](#default-hint-text)
-2. [Inline within the label](#inline-within-the-label)
-3. [Additional info](#additional-info)
-
-### Default hint text
-
-{% include component-example.html alt="The text-input component with hint text." file="/images/components/text-input/text-input-with-hint-text.png" caption="Hint text appears between the label and text-input field." width="50%" %}
-
-<div class="site-showcase">
-  <form class="usa-form">
-    <label class="vads-u-margin-top--0" for="input-type-text">
-      Case or docket number
-      <span class="vads-u-color--gray-medium vads-u-display--block">
-        You'll find this number on your case documents
-      </span>
-    </label>
-    <input class="usa-input" name="input-type-text" type="text">
-  </form>
-</div>
-
-This should be used in the case where the needed clarification is a little longer, but less than two sentences. These should ideally not wrap more than twice for a total of three lines.
-
-### Inline within the label
-
-<div class="site-showcase">
-  <form class="usa-form">
-    <label class="vads-u-margin-top--0" for="input-type-text">Street address (20 characters maximum)</label>
-    <input class="usa-input" id="input-type-text" name="input-type-text" type="text">
-  </form>
-</div>
-
-This should be used in the case where the needed clarification is very short.
-
-### With Additional info
-
-{% include storybook-preview.html story="components-va-text-input--with-hint-text" link_text="va-text-input--with-hint-text" %}
-
-Using the [additional info]({{ site.baseurl }}/components/additional-info) component should only be done in cases where the needed clarification is long, complex, requiring more than two sentences or multiple paragraphs, or special formatting (bullet points, links, etc.). 
-
-We want to avoid this variation when possible. Use of this component for this purpose is a last resort when attempts at reducing the content have failed. If a field needs a lot of explanation, it should ideally be moved to a distinct page with explanation on the page itself. 
+{% include components/hint-text.md %}

src/_components/form/label.md

@@ -3,9 +3,55 @@ layout: component
 permalink: /components/form/label
 has-parent: /components/form/
 title: Label
-intro-text: "A list of standardized form labels that appear on VA.gov forms. This list is a continued work in progress as each form is unique and has specific labels and questions. As we migrate more forms online, we'll continue to add plain-language labels to this list."
+intro-text: Labels associate a descriptive title with each form input used to collect information from the user.
 status: use-deployed
+anchors:
+  - anchor: Examples
+  - anchor: Usage
+  - anchor: Content considerations
 ---
 
+## Examples
 
-{% include content/form-labels-masterlist.md %}
+Examples shown here use the [va-text-input component]({{ site.baseurl }}/components/forms/text-input) to demonstrate form labels. Labels are used consistently across standard form components.
+
+### Default
+
+{% include storybook-preview.html story="uswds-va-text-input--default" link_text="Label default" %}
+
+### Required
+
+{% include storybook-preview.html story="uswds-va-text-input--required" link_text="Label required" %}
+
+## Usage
+
+### When to use label
+
+* **All form inputs must have a label.** All standard form inputs must have an associated label. Thus the label elements is built into our standard form components.
+
+### How this component works
+
+* **Show whether a field is required or optional.** Mark required fields using the required property on the web component.
+
+### Error handling
+
+{% include components/label-errors.html %}
+
+### Hint text
+
+{% include components/hint-text.md %}
+
+## Content considerations
+
+### Standardized labels by form pattern
+
+We're in the process of standardizing form field labels and their related hint text and error messages. We'll add to this list as we build out the set of standardized labels.
+
+### Ask uses for...
+
+* [Addresses](https://design.va.gov/patterns/ask-users-for/addresses#content-considerations)
+* [Dates](https://design.va.gov/patterns/ask-users-for/dates#content-considerations)
+* [Email address](https://design.va.gov/patterns/ask-users-for/email-address#content-considerations)
+* [Names](https://design.va.gov/patterns/ask-users-for/names#content-considerations)
+* [Phone numbers](https://design.va.gov/patterns/ask-users-for/phone-numbers#content-considerations)
+* [Social Security or VA file number](https://design.va.gov/patterns/ask-users-for/social-security-number#content-considerations)

src/_content-style-guide/form-labels.md

@@ -4,16 +4,17 @@ title: Form labels
 slug: form-labels
 ---
 
-# Form labels
+# Form labels (in progress)
 
-When adapting a paper form into an online application or tool on VA.gov, content writers and UX designers should consult our [Form labels](#form-label-masterlist) to see if a standardized label has already been created. Use the existing standardized labels when building a form rather than create new or custom labels with each new form.
+## Standardized labels by form pattern
 
-The masterlist documents labels and questions that appear on our online forms. This list is continually updated as more forms are brought online and new field labels and form questions are documented.
+We're in the process of standardizing form field labels and their related hint text and error messages. We'll add to this list as we build out the set of standardized labels.
 
-Because form fields have a lot of visual design and formatting that can affect copy, this masterlist is also included in the Components > Form guidance.
+### Ask uses for...
 
-## Form label masterlist
-
-A list of standardized form labels that appear on VA.gov forms. This list is a continued work in progress as each form is unique and has specific labels and questions. As we migrate more forms online, we'll continue to add plain-language labels to this list.
-
-{% include content/form-labels-masterlist.md %}
+- [Addresses](https://design.va.gov/patterns/ask-users-for/addresses#content-considerations)
+- [Dates](https://design.va.gov/patterns/ask-users-for/dates#content-considerations)
+- [Email address](https://design.va.gov/patterns/ask-users-for/email-address#content-considerations)
+- [Names](https://design.va.gov/patterns/ask-users-for/names#content-considerations)
+- [Phone numbers](https://design.va.gov/patterns/ask-users-for/phone-numbers#content-considerations)
+- [Social Security or VA file number](https://design.va.gov/patterns/ask-users-for/social-security-number#content-considerations)

src/_includes/components/hint-text.md

@@ -0,0 +1,25 @@
+When a detailed form input label is not enough to convey the meaning or purpose of the input, we have three options for including additional context:
+
+1. [Beneath the label (default)](#default-hint-text)
+2. [Inline within the label](#inline-within-the-label)
+3. [Additional info](#additional-info)
+
+### Default hint text
+
+{% include storybook-preview.html story="uswds-va-text-input--with-hint-text" link_text="Label with hint text" %}
+
+This should be used in the case where the needed clarification is a little longer, but less than two sentences. These should ideally not wrap more than twice for a total of three lines.
+
+### Inline within the label
+
+{% include storybook-preview.html story="uswds-va-text-input--with-inline-hint-text" link_text="Label with inline hint text" %}
+
+This should be used in the case where the needed clarification is very short.
+
+### With Additional info
+
+{% include storybook-preview.html story="uswds-va-text-input--with-additional-info" link_text="Label with additional info hint text" %}
+
+Using the [additional info]({{ site.baseurl }}/components/additional-info) component should only be done in cases where the needed clarification is long, complex, requiring more than two sentences or multiple paragraphs, or special formatting (bullet points, links, etc.).
+
+We want to avoid this variation when possible. Use of this component for this purpose is a last resort when attempts at reducing the content have failed. If a field needs a lot of explanation, it should ideally be moved to a distinct page with explanation on the page itself.

src/_includes/components/label-errors.html

@@ -0,0 +1,9 @@
+{% include storybook-preview.html story="uswds-va-text-input--error" link_text="Label with error" %}
+
+* In all cases, only show error validation messages or stylings after a user has interacted with a particular field.
+* The form field and its corresponding `<label>` are wrapped in a container which provides a thick border and padding to visual indicate an error message to users who might have difficulty perceiving contrast. It also changes the border of the input to red as a secondary indicator.
+* An error message is placed between the label and the form field.
+* The form field receives an `aria-describedby` attribute that references the `id` of the error message.
+* Prepending `<span class="sr-only">Error</span>` to error messages alerts screen screen readers clearly that an error exists.
+
+<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/patterns/help-users-to/recover-from-errors">Review the help users to recover from errors pattern</a>