USWDS-Site - Feature: Guidance for `usa-form-group--error`

mahoneycm commented 8 months ago

Is your feature request related to a problem? Please describe.

We offer an error state for form elements under the usa-form-group--error class but do not offer any guidance on it's usage.

Describe the solution you'd like

We should:

Confirm usa-form-group--error is in a usable state
Define the form components that should be able to use it
Provide guidance on the form component page and/or specific component pages.

Describe alternatives you've considered

No response

Additional context

No response

Code of Conduct

[X] I agree to follow this project's Code of Conduct.
[X] I checked the current issues for duplicate feature requests.

jaclinec commented 7 months ago

Wanted to add some research on error states that the pattern team did as we think of ways forward.

They found some opportunities for us to offer more guidance, examples, and code for error states across the design system. Here are a few screenshots from their deck I found helpful:

mahoneycm commented 6 months ago

@jaclinec So I wanted to show that it's possible to add the error state styling to any form element by wrapping it in a div with the classes usa-form-group usa-form-group--error. You can then add an error span using the class usa-error-message.

Here's an example of adding the markup to checkbox and date picker.

Checkbox

Code example (The green lines were added to get the error state. The rest is standard markup)

+ <div class="usa-form-group usa-form-group--error">
    <fieldset class="usa-fieldset">
      <legend class="usa-legend">Select any historical figure</legend>
+    <span class="usa-error-message">Please make a selection</span>
      <div class="usa-checkbox">
        <input class="usa-checkbox__input" id="check-historical-truth" type="checkbox" name="historical-figures" value="sojourner-truth" checked="">
        <label class="usa-checkbox__label" for="check-historical-truth">Sojourner Truth</label>
      </div>
      <div class="usa-checkbox">
        <input class="usa-checkbox__input" id="check-historical-douglass" type="checkbox" name="historical-figures" value="frederick-douglass">
        <label class="usa-checkbox__label" for="check-historical-douglass">Frederick Douglass</label>
      </div>
      <div class="usa-checkbox">
        <input class="usa-checkbox__input" id="check-historical-washington" type="checkbox" name="historical-figures" value="booker-t-washington">
        <label class="usa-checkbox__label" for="check-historical-washington">Booker T. Washington</label>
      </div>
      <div class="usa-checkbox">
        <input class="usa-checkbox__input" id="check-historical-carver" type="checkbox" name="historical-figures" value="george-washington-carver" disabled="">
        <label class="usa-checkbox__label" for="check-historical-carver">George Washington Carver</label>
      </div>
    </fieldset>
+</div>

Date picker Note that date picker cannot use the input error styling to add a red box around the input itself

In this code example, the date picker already had the usa-form-group div and I only needed to add the error variant and the error message

- <div class="usa-form-group">
+ <div class="usa-form-group usa-form-group--error">
  <label class="usa-label" id="appointment-date-label" for="appointment-date">Appointment date</label>
+ <span class="usa-error-message">Please enter a valid date</span>
  <div class="usa-hint" id="appointment-date-hint">mm/dd/yyyy</div>
  <div class="usa-date-picker usa-date-picker--initialized" data-min-date="0000-01-01">
    <input class="usa-input usa-date-picker__internal-input" type="text" aria-labelledby="appointment-date-label" aria-describedby="appointment-date-hint" aria-hidden="true" tabindex="-1" style="display: none;">
  <div class="usa-date-picker__wrapper"><input class="usa-input usa-date-picker__external-input" id="appointment-date" name="appointment-date" type="text" aria-labelledby="appointment-date-label" aria-describedby="appointment-date-hint">
    <button type="button" class="usa-date-picker__button" aria-haspopup="true" aria-label="Toggle calendar"></button>
    <div class="usa-date-picker__calendar" role="application" hidden=""></div>
    <div class="usa-sr-only usa-date-picker__status" role="status" aria-live="polite"></div></div></div>
</div>

I'd love to discuss the best way to provide guidance to users so they can use this in their projects.

bryanpizzillo commented 6 months ago

@mahoneycm Hi, this is a really interesting topic and one our team has been struggling with to find a consistent approach. The approach of wrapping with the usa-form-group--error works well for simple fields, but what is the recommendation for something like Memorable Date that actually wraps 3 form groups?

mahoneycm commented 6 months ago

Hey there @bryanpizzillo

If you want to display an error state for memorable date, you could wrap the entire component in the usa-form-group usa-form-group--error div then add the usa-input--error class to the specific inputs that cause the error.

I would follow also place a usa-error-message span beneath the label and hint elements. It'll come out looking like this:

uswds / uswds-site