Why these deviations exist

• Reducing the opacity of disabled buttons helped the affordance in cases where a button was employed as part of a large component (e.g. Document).
• If the default disabled button is on a gray background it does not have enough contrast and affordance for being disabled.

Usability

When to use

• Use the default style for all disabled buttons.

Usability

When to use

• The alert secondary button is intended for destructive actions or actions that will take the user outside of USAJOBS.
• The gray button retains a button that had been in the U.S. Design System but was dropped. It's still in use on the site and we'll continue to support use when deemed appropriate.

Usability

When to use

• Use the .usa-button-primary class to style a link like a button.

Usability

When to use

• For micro-interactions where the user must select from a list and the act of making a selection takes immediate action.

Usability

When to use

• A concise explanation of the intent of the question or data being requested can be provided without the need for deeper explanation.
• As a replacement for placeholder text in order to provide an example of the type of data being requested.

When to consider something else

• When a more detailed explanation is needed.
• When you want to provide supporting documentation or policy.

Guidance

• Help text must not begin with a "-" (dash) or other punctuation.

Usability

When to use

• A detailed explanation of the data being requested is necessary.
• Additional context for why the request is being made is desired.

When to consider something else

• A more detailed explanation is not necessary.

Usability

When to use

• Use the chosen plugin when there are more than 25 options in a dropdown.

When to consider something else

• When the select menu is 25 items or less use of the chosen plugin is not necessary.

Usability

Guidance

• Labels are concise text that describes the data being requested by a form input.
• Labels should appear directly above form controls as seen in the U.S. Web Design Standards.
• Labels do NOT end in a colon.

Usability

The US Standards have been updated to only indicate optional fields and we will be following their guidance.

When to use

• To identify optional fields only.

When to consider something else

• If all fields are required consider the form legend to communicate that to the user.

Form legend

When to use

• When all fields for a form are required use the text "All fields are required".
• When all fields for a form are optional use the text "All fields are optional".
• When most of the form fields are required use the text "All fields are required unless otherwise noted" in conjunction with the Optional Field Indicator to indicate the optional fields.

When not to use form legend

• The form legend may be omitted in cases where the form is extremely short or the fields are obviously required. For example, a form that consists of one checkbox or a sign in form.

Guidance

• The form title is often long enough to cause a collision with the legend, thus it was moved to be on the line below the form title.

Fieldset legend

When to use

• When multiple fieldsets are in use within a form.

Visual

• Input boxes and dropdowns in error should be outlined in red.
• A vertical red bar should run along the left side of all failed form fields. The red bar should run the length of each individual question, including the radio buttons or answer options.
• Input boxes and dropdowns no longer in error should be outlined in green.
• The styling should follow the U.S. Design Standards.

Labels

• When a field is required the help text "This field is required" should be placed directly under the field label or required question.
• The help text related to character issues or unmet requirements should use the text "This field" rather than the actual field name.

Timing

Errors

• Inline error validation should occur on all required input fields and dropdowns. The error styling should be triggered after the field has lost focus (the user has clicked or tabbed away from the input field without meeting field requirements).
• Do not display an alert at the top of the page when using inline error validation.
• Inline error validation should also occur if a user enters a character that does not meet the requirements of the field. For example, entering a number in the first name text input. This should occur for optional and required fields.

Success

• Success styling should be triggered when a form error (red styling) is corrected. The success validation should appear once the user clicks or tabs out of the input and meets the basic requirements of that field.
• Success styling should be removed when the page is saved.

Dependent fields

• When you have dependent fields (i.e. Start Date & End date) you should not receive an error on either field until the user leaves the set (both fields). After the set has been left, error styling should be triggered on one or both of the fields.

Error alert

• If a user saves a form with known errors or skipped required fields, reload the page with the errors styling displayed and an alert at the top of the page.
• The alert should appear above the form but not within the form.
• The alert should read "We can’t save your information because there are one or more errors. Please correct the information below and then save your changes."

Usability

When to use

• Use this layout sparingly as the standard error handling was not designed to be used in side-by-side columns. Our only current approved use is in Saved search which is depicted above.

Usability

When to use

• Use this pattern to reveal form fields based on user input.

Usability

When to use

• Use each icon in conjunction with a user group that matches the represented set of experience.
• Use whenever a specific hiring path is mentioned.

When to consider something else

• Do not use these icons in isolation. Icons should appear alongside text describing the hiring path.

Implementation

• These icons are collected in an SVG defs file at includes/icons/hiring-paths.svg and then referenced via the use element.

Implementation

• We've swapped in Font Awesome version 5 which is backward compatible with version 4 (with a JS shim) and uses SVG inline instead of an icon font file.

Guidelines

When to use

• All designs and implementations using the USAJOBS design system MUST align to this spacing progression in order for the inter-relationships of components to operate properly.
• The SM (2rem/20px) is an exception that we're trying to remove. Any instances that can be removed should be replaced by either the default or M size.