<form class="usa-form">
  <div class="usa-fieldset">
    <div class="usa-legend usa-legend--large">
      A simple form
    </div>

    <div class="usa-form-group">
      <label class="usa-label" for="input-type-text">Text input label</label>
      <input class="usa-input" name="input-type-text" />
    </div>

    <div class="usa-form-group">
      <label class="usa-label" for="input-type-textarea">Text area label</label>
      <textarea class="usa-textarea" name="input-type-textarea"></textarea>
    </div>
  </div>

  <button class="usa-button" type="submit">Submit</button>
</form>

• Form
  • Fieldset (optional)
    • Legend (required if fieldset used)
    • Form group (required)
      • Label (required)
      • Form control (required)
    • Submit button (required)

• MDN the form element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form
• USWDS on the form component: https://designsystem.digital.gov/components/form/

The purpose of the large form is to constrain the form and its contents. Default sets the max-width of units("mobile") while large increases the max-width to units("mobile-lg") on the mobile-lg breakpoint. See spacing documentation for details on those units.

• Don’t control element order with CSS. Display form controls in the same order in the HTML as they appear on screen. Don’t use CSS to rearrange the form controls. Screen readers narrate form elements in the order they appear in the HTML.
• Align validation with form controls. Visually align validation messages with the form controls so people using screen magnifiers can read them quickly.
• Use simple vertical layouts. Keep your form blocks in a vertical pattern. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.
• Avoid placeholder text. Avoid using placeholder text that appears within a text field before a user starts typing. If placeholder text is no longer visible after a user clicks into the field, users will no longer have that text available when they need to review their entries. People who have cognitive or visual disabilities have additional problems with placeholder text. Most browsers’ default rendering of placeholder text does not provide a high enough contrast ratio.
  • Use hint or label instead.

• Show whether a field is required or optional. Mark required fields as required by using a red asterisk (). Use text descriptions. Combine red asterisks () with a text description at the top of the form instructing the user of its meaning.
• Example: “A red asterisk (*) indicates a required field.”
• Use the required attribute. Add the required attribute to your form elements to indicate that a field must be filled out before submitting the form.
• Mark optional fields as "optional." Label optional fields with the word “optional” placed in parentheses. Example: (optional)
• Let users know if there is an error. Use a message or alert to notify the user if a field that is required was not completed, and indicate which field was not completed. Additionally, include an error notification in the page title (title element) for screen readers.
• Note: One-field forms are the exception and do not need to be marked with a required label or symbol.

• Forms
  • Form elements
    • Form
      • Default
        • Default state (See note)
      • Variants
        • Large form (See note)
      • Modifiers
      • Test cases
  • Form controls

• MDN the fieldset element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset
• USWDS on the fieldset component: undocumented component

• Fieldsets are not required to be used in forms. However, if a fieldset is used, a single legend must be present.

• Use proper markup. Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each one. The fieldset and legend elements make it easier for those who use screen readers to navigate the form.
• Use legends. Use a single legend for fieldset (this is required). One common use of the fieldset and legend elements 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.

• Forms
  • Form elements
    • Fieldset
      • Default
        • Default state (See note)
        • Disabled state (See note)
      • Variants
      • Modifiers
      • Test cases
  • Form controls

• MDN the legend element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend
• USWDS on the legend component: undocumented component

The large legend sets the text to the xl size token.

• Fieldsets are not required to be used in forms. However, if a fieldset is used, a single legend must be present.

• Use proper markup. Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each one. The fieldset and legend elements make it easier for those who use screen readers to navigate the form.
• Use legends. Use a single legend for fieldset (this is required). One common use of the fieldset and legend elements 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.

• Forms
  • Form elements
    • Legend
      • Default
        • Default state
      • Variants
        • Large legend
      • Modifiers
      • Test cases
  • Form controls

• Not an HTML element
• USWDS on the from group component: undocumented component

The error form group adds a red border plus padding to the left of the form group to call attention to an input with errors.

• All form controls must be wrapped in this component for to ensure correct default and error styling.

• MDN the label element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label
• USWDS on the label component: undocumented component

The error label bolds the label text to call attention to an input with errors.

The required label sets the label text to the error color token to call attention to a required field (for sighted users).

• Do not place interactive elements such as anchors or buttons inside a label. Doing so makes it difficult for people to activate the form input associated with the label.
• Do not place heading elements Placing heading elements within a label. Doing so interferes with many kinds of assistive technology, because headings are commonly used as a navigation aid.
  • Use nci-heading classes instead if needed for styling.

<div class="usa-form-group">
  <label class="usa-label">
    <input class="usa-input" />
  </label>
</div>

<div class="usa-form-group">
  <label class="usa-label" for="input-type-text">Text input label</label>
  <input class="usa-input" name="input-type-text" />
</div>

• Forms
  • Form elements
    • Label
      • Default
        • Default state
      • Variants
      • Modifiers
        • Error state
        • Required state
      • Test cases
  • Form controls

• Not an HTML element
• USWDS on the hint component: undocumented component

The required hint sets the hint text to the error color token to call attention to a required field (for sighted users).

• Use hint text to highlight input restrictions or to show users the expected format.

• Forms
  • Form elements
    • Hint
      • Default
        • Default state
      • Variants
      • Modifiers
        • Required state
      • Test cases
  • Form controls

• Not an HTML element
• USWDS on the error message component: undocumented component

The inverse error message allows the error message to pass contrast for forms used on dark backgrounds.

• Let users know if there is an error. Use a message or alert to notify the user if a field that is required was not completed, and indicate which field was not completed. Additionally, include an error notification in the page title (title element) for screen readers.
• Long forms. On long forms, always include in-line validation in addition to any error messages that appear at the top of the form.
• Align validation with inputs. Visually align validation messages with the input fields so people using screen magnifiers can read them quickly.

• Forms
  • Form elements
    • Error message
      • Default
        • Default state
      • Variants
      • Modifiers
        • Inverse (dark backgrounds)
      • Test cases
  • Form controls

• Not an HTML element
• USWDS on the password component: undocumented component

• Forms
  • Form elements
    • Password
      • Default
        • Default state
        • Toggled state
      • Variants
      • Modifiers
      • Test cases
  • Form controls

Form buttons are not components, but are an important part of forms.

They may be used as input or button elements as long as the attribute type="submit" is correctly applied.

• MDN on the button element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button
• USWDS on the button component: https://designsystem.digital.gov/components/button/

• Always set the type attribute. Define the purpose and behavior of a button with the type attribute. The type attribute can accept three values: submit, button, and reset. If no type attribute is defined, the button will behave as a submit button.
• Use the disabled or aria-disabled attributes to turn on disabled button styles.
• Avoid reset. This behavior tends to annoy users.

<input class="usa-button" type="submit" value="Submit" />

<button class="usa-button" type="submit">Submit</button>

• MDN on submit input: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/submit
• USWDS on submit button: undocumented

<input class="usa-button" type="reset" value="Reset" />

<button class="usa-button" type="reset">Reset</button>

• MDN on reset input: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/reset
• USWDS on reset button: undocumented

• USWDS component: https://designsystem.digital.gov/components/validation/

This appears to be a variant of usa-alert.

• Validation
  • Default
  • Test Cases
    • Input validation
    • Textarea validation

• Forms
  • Form elements
  • Form controls
    • Input
      • Default
        • Default state
        • Disabled state
      • Variants
        • 2xs
        • xs
        • sm, small
        • md, medium
        • lg
        • xl
        • 2xl
      • Modifiers
        • Error state
        • Success state
      • Test cases

• Forms
  • Form elements
  • Form controls
    • Input group (prefix/suffix)
      • Default
        • Default state
        • Disabled state
      • Variants
      • Modifiers
        • 2xs
        • xs
        • sm, small
        • md, medium
        • lg
        • xl
        • 2xl
        • Error state
        • Success state
      • Test cases

Each form template has important usability and accessibility guidance from USWD:

• Address form - https://designsystem.digital.gov/templates/form-templates/address-form/
• Name form - https://designsystem.digital.gov/templates/form-templates/name-form/
• Password reset form - https://designsystem.digital.gov/templates/form-templates/password-reset-form/
• Sign-in form - https://designsystem.digital.gov/templates/form-templates/sign-in-form/

All form patterns have additional guidance from USWDS:

• Create a user profile - https://designsystem.digital.gov/patterns/create-a-user-profile/
  • Address
  • Contact preferences
  • Date of birth
  • Email address
  • Gender identity and sex
  • Name
  • Phone number
  • Pronouns
  • Social Security Number
• Complex form - https://designsystem.digital.gov/patterns/complete-a-complex-form/