Accordion

Accordions present a list of concise topic labels that when clicked, expand to show additional content.

Usage

Properly used accordion menus reduce scrolling and help users accomplish tasks more efficiently by giving a quick overview of what topics are available. The user can choose to expand the content that interests them and ignore the rest.

However, poorly implemented accordions increase interaction cost by adding extra, unnecessary clicks and hiding useful content. If all or most of the content is important to the user, then an accordion is not a good design option. Accordions can also hinder the ability of users to print the webpage.

Helpful hints

checkmark Use an accordion menu when the majority of users will need only a few key pieces of content on the page.
checkmark Use accordions on mobile pages where the content requires excessive scrolling.
checkmark Keep accordion labels concise yet descriptive. Don't force users to guess what content will be displayed when clicked.
warning-indicator Don’t use accordions when users will need most or all of the content.
warning-indicator Don’t put an excessive amount content into each accordion. If the body content of a single accordion requires multiple levels of headers, consider either separating it into multiple accordions or place the content directly on the page.
warning-indicator Don’t automatically scroll an accordion to the top of the page when a user expands it. The position of the accordion should always remain the same.

Buttons

Buttons trigger actions. A button communicates what will happen when it is interacted with. Buttons indicate that an operation will be performed and should not be used for navigation.

Button types

Primary (solid)

Use a primary button for the most important action on a page. Limit the number of primary buttons on a page.

Secondary (outline)

Use a secondary button for actions that are secondary to the primary call to action. This is the default button that should be used in most cases.

Tertiary (flat)

Use a tertiary button for non-critical actions. While the tertiary button visually looks like a link, it should be used as a button. Tertiary buttons should always be paired with another button.

Helpful hints

information-indicator Buttons should be used sparingly. Each additional button on a page has the potential to create confusion and reduce the visual prominence of the primary action.

checkmark Always use the colors provided by the Digital Design System.

warning-indicator Don’t use colors outside of those documented in this section.


Disabled

To disable a button, simply add the class .is-disabled.


Reversed (white)

The default buttons work well on light-colored backgrounds, but get lost against darker colors. When using a button on a dark background add the class .Button--white.


Full width

A full-width button inherits the width of its parent container. This allows you to align the button with relevant content on the screen. To make a button full-width, add the class .Button--full.

Buttons are limited to a max width of 600px to avoid losing context.

Helpful hints

checkmark It’s recommended to use full-width buttons for the default breakpoint, and occasionally for the small breakpoint.
information-indicator Full-width buttons work well within contained content areas such as cards.
Full-width buttons work well in contained areas, such as cards.
Use full-width buttons on smaller screen sizes.

Button text

The text within a button must clearly indicate what happens when it’s clicked. Text should be written in title case.

Helpful hints

checkmark Keep it short; strive for approximately three words or 20 characters.
warning-indicator Never wrap text to two lines; instead shorten the text or consider using a link.
Examples of buttons with text that makes it clear what action will take place when clicked.

Button form alignment

A button or button group should be right aligned in a form.

Helpful hints

checkmark The alignment should only happen at tablet and desktop breakpoints. Center align the button and stack a button group for the mobile breakpoint.
Example of a single button aligned in a form.

warning-indicator Don’t left align a button or button group

warning-indicator Don’t center align a button or button group


Button groups

Buttons can be grouped together when there are multiple actions a user can take. In order to guide the user and not overwhelm, it’s recommended that a group be limited to a maximum of four buttons.

There should be 8px of padding between buttons.

Leave 8px of space between buttons in a group.

checkmark Limit a group to no more than four buttons

warning-indicator Don’t use an excessive number of buttons in a group


Stacked button groups

A button group should be stacked vertically when:

  • full-width buttons are put together to form a group
  • an inline button group starts to break to two lines

Stacked button groups should be always be full-width. This allows the group to appear consistent, regarless of text lenght in each individual button. (so there aren’t varying widths of buttons regardless of text length)

Helpful hints

information-indicator On smaller screens it’s recommended to stack button groups.
Leave 8px of space between vertically stacked buttons.

checkmark Always make stacked groups full-width in their containers

warning-indicator Don’t allow button groups to wrap to two lines

checkmark Always make stacked buttons the same width

warning-indicator Don’t allow stacked button widths to vary based on text


Mixing button types

Mixing buttons allows you to emphasize important functions.

Helpful hints

checkmark Use only one Primary button in a single group.
checkmark Always pair Tertiary buttons with another button.
It is acceptable to use a mix of different kinds of buttons depending upon the actions available to users.

Button order

Buttons should appear in order of importance, with the most important action closest to the user.

For inline groups, the most important button is on the right.

For stacked groups, the most important button is on the bottom.

When using a horizontal group of buttons, the most important button is placed to the right. Vertical groups place the most important button at the bottom.

Button accessibility

When necessary, use aria-label, aria-labelledby or aria-described to describe a button with short context. When there are multiple instances of the same button text on the page, visually hidden labels can enhance a users experience and help guide their decision and navigation. If a button doesn’t contain any useful verbale content, labeling the button can also help the user understand what’s going on. For example, an X or icon to close a modal is not be informative enough and needs a hidden or aria label.


Cards

A card is a container that displays information about a single subject. It groups different elements to form one coherent piece of content. A card serves as an entry point to more detailed information about that subject.

Usage

A card must include:

  • Title
  • Description text (a short summary)
  • Interactive content – a button or link to more detailed content

Optional card elements:

  • Illustration
  • Meta data such as date, timestamp, tags, etc.
  • Social or share links

Cards work best for content that:

  • Has multiple types of data
  • Doesn’t require direct comparison (a table may work better in this case)
  • Is highly variable in length
  • Needs to be organized into digestible groups or sections

Helpful hints

information-indicator Text links are generally not suitable within a card. Instead use a button or link element as a call to action.

Card content

A card is a container that displays information about a single subject. It groups different elements to form one coherent piece of content. A card serves as an entry point to more detailed information about that subject.

Length

Limit content on cards to give users a quick overview of information, and link to more details if necessary.

checkmark Do make card content short and skimmable.

warning-indicator Avoid excessively large blocks of text or information.


Hierarchy

Use hierarchy within the card to direct users’ attention to the most important information. For example, place primary content at the top of the card, or use typography to emphasize leading content.

checkmark Do keep all information related to the title of the card.

warning-indicator Don’t include multiple subjects in one card.


Card examples

Cards allow for varying height to accommodate differing amounts or types of content, but typically the width is fixed from one card to the next.

Groups of cards

When multiple cards are used together, it’s recommended that all cards be the same height and width. If a button or link is placed at the bottom of a card, it should be in the same location on all cards.

There should be a minimum of 16px between cards, and it’s recommended that flex be used to create a unifom layout.


Checkboxes

Overview

Checkboxes allow users to select any number of options (zero, one, or multiple). Each checkbox functions independently; when used in a list, checking one box doesn’t uncheck the others.

Single checkboxes

A single checkbox works best for yes or no choices, such as agreeing to terms of service or remembering login information.

Labels and content

The checkbox option description should make it clear what the user is selecting. For legibility, keep it short and on a single line.

Helpful hints

checkmark Use first person, especially when a user is agreeing to something.
An example of a single checkbox in use.

checkmark Use positive language

warning-indicator Avoid negative statements that imply checking the box would cause something to not happen


Checkbox lists

A checkbox list works best for allowing the user to make a selection from a range of options. It is recommended to use checkbox lists when there are 7 or fewer options.

Lists can be created by wrapping checkboxes in a .Field-group container.

Helpful hints

information-indicator When there are only a few options, the user benefits from seeing all avaiable items.

Labels and content

A list must have a label to give users context about the group of items they are choosing from. Create a list label by adding a .Field-groupLabel element.

Checkbox labels and option descriptions should make it clear what the user is selecting. For legibility, keep options to a single line.

Helpful hints

checkmark List options in a logical order for the use case (i.e. alphabetical, numeric, time-based).
Checkbox lists should always have a clear, descriptive label.

checkmark Use a checkbox list when users could select more than one option.

warning-indicator Don't use a checkbox list for yes and no options (binary decisions).


In-line lists

Checkbox lists with only a few options can also be laid out horizontally. To create an inline list, add the modifier .Field-group--inline to the .Field-group container.

Checkboxes can be placed horizontally when there are only a few, short options.

Disabled checkbox

To disable a checkbox, add the class .is-disabled to the .Field container. You will also need to add the attribute disabled to the input type="checkbox".

When checkboxes are disabled, they become grayed out.

Required vs. optional

The input field label informs users which fields are required or optional.

One way to designate a field is required is to add a single asterisk (*) next to the input field label. When using this option, there must be an additional label stating "* Required field" under the fillable form.

Alternatively, a text label can be used showing which field(s) are required or optional.

  • If there are more optional fields than required fields, add the text "(required)" next to the input field label.
  • If there are more required fields than optional fields, add the text “(optional)” next to the input field label.

In this example, most questions on the form are required, so the one non-required question is labeled "optional."

Checkbox validation

By adding .is-invalid to the .Field container, the checkbox list will be marked as invalid and the .Field-error element will appear.

A clear validation state lets the user quickly find errors that need to be corrected.

Checkbox accessibility

Form components require semantic information to help people using assistive technology understand the structure and information conveyed in the form field.

While not required, it’s recommended to add the attribute aria-describedby=“checkbox-legend” to each checkbox element and the .Field container. Other states that can be utilized are aria-invalid, aria-required and aria-labelledby. See www.w3.org for more information.

An alternative approach to checkbox groups that is more accessible, would be to wrap your checkbox group in an unordered list. Point the group label at the unordered list with aria-labelledby and wrap each checkbox in a list item. This will provide your list with more helpful explanation as to what's going on and how many options the user has to choose from. See example for alternative approach.


Definitions

A definition is a styled overlay that displays an explanation of what a term or phrase means.

Usage

Definitions help users understand industry terms and rules without requiring them to leave the current screen. When the user clicks on an underlined term or question mark icon, the definition panel opens. Users can dismiss the panel by clicking outside of the definition, or by clicking on the ‘X’ icon.

Helpful hints

warning-indicator Don‘t include images or buttons in definitions
information-indicator Links can be used sparingly in definitions

Writing definitions

Definitions should clearly define a term in a concise manner.

  • Try to limit text to 280 characters or less
  • Use sentence case
  • Consider your audience. Use plain English and avoid industry jargon and highly-technical words
Definitions explain industry terms to users in plain English.

Feature Box

Overview

A Feature Box is a container that highlights a section of content on a page. It visually contains different elements about a single subject and separates them from the rest of the content on the page.

Usage

Feature boxes include:

  • Spot Illustration (Optional)
  • Title - Required
  • Other types of basic content such as paragraphs, images, and links

Feature boxes work well for:

  • Important information that needs to be highlighted
  • Useful information that supplements the page's main content

Helpful hints

information-indicator The spot illustration should follow illustration guidelines
warning-indicator Never put two feature boxes directly next to each other.
warning-indicator Feature boxes should not contain all or the majority of a page’s content.

Content

A Feature Box should include content about a single topic. The layout of the content inside the feature box can be up to three columns wide.

Helpful hints

information-indicator Test Feature Box content on each screen breakpoint to ensure text always remains legible and follows line length guidelines.
information-indicator When using multiple columns, try to keep the vertical length of the content consistent across columns.
information-indicator The Feature Box's title should be descriptive of the box’s content.
warning-indicator Never nest feature boxes inside one another.

Tips

checkmark Do make the vertical length of each column consisten.

Tips

warning-indicator Don't use a Feature Box inside another Feature Box, or next to each other.

Global Message Bar

The global message bar contains a message that effects an entire site or application and sits at the top of every page.

Usage

Global messaging is reserved for notifications that effect the entirety of a site or application. The global message bar appears at the very top of the page and pushes down the rest of the page‘s content. It does not stick when scrolling or float above content.

Global messaging can contain a single hyperlink. It should not prompt dialogs or other notifications to appear. The bar can be closed by the user by clicking the “x” icon. Once the user has chosen to close a particular global message, that message should not reappear, even if the user navigates to another page or if they return to the site at a later time.

Helpful hints

warning-indicator Don‘t put general news or marketing messages in the global messaging bar. Consider having a news feed or updates section on the site‘s homepage instead
warning-indicator Don‘t put validation messages in the global messaging bar. Use a toast or inline message instead

checkmark Use global messaging for important service updates.

warning-indicator Don‘t use global messaging for marketing messages.


Types of global message bars

Depending on the type of message, there are two different styles of global messaging bars:


Informational

Informational messages notify users of news or changes that may be of interest to them.

Examples include:

  • Natural disasters, mass shootings, and deaths of individuals significant to the company
  • Upcoming scheduled service outages
  • System updates
An upcoming service notice should be styled as an informational global message.

checkmark Do combine related messages into a single global message bar.

warning-indicator Don‘t have multiple informational or critical message bars at the same time.


Critical

Critical messages notify users of a major issues that are currently effecting all or most users. The ability to dismiss the message bar may be disabled and the close “X” icon removed if the site or application is experiencing a significant outage that is effecting core functionality.

Examples include:

  • Current system outage
  • Site-wide/application-wide issues
  • Outage effecting customers’ ability to reach the call center

Helpful hints

information-indicator In rare cases, an informational message bar and a critical message bar may be used at the same time (ex: an informational hurricane message and a critical system error message)
A critical message is appropriate for an outage of the customer call center.

Writing global messages

Global messages should be concise.

  • Write full sentences and use end punctuation
  • Consider your audience. Use plain English and avoid highly-technical words
Keep global messages short and to the point. A link for more information allows interested users to get further details.

Inline Messages

An inline message is a notification embedded in the content of the page that appears near the object or section it is referencing.

Usage

Inline messages are versatile and can be used in forms, page content, and inside other components. They alert the user to new, important information related to an action they have just taken, or are about to take.

Inline messages are context-related and are placed in close proximity to where the user is interacting. Generally, other content is moved down to accomodate the appearance of a new inline message.

Helpful hints

information-indicator Inline messages can contain hyperlinks

Types of inline messages

Depending on the type of message, there are four different styles of inline messaging:


Informational

Informational messages give the user additional information that may be of use to them. This information should be useful but not critical to the user's ability to complete their primary task.

An informational message doesn‘t require the user to take more action, but it may offer details for the user to learn more.

Confirmation

Confirmation messages give the user positive feedback that an action was successful.

Inline confirmation messages work well when there are multiple small actions the user must take to complete their full task.

Warning

Warning messages alert the user to a potential problem that may happen. Warning messages should appear before there is a critical issue and should suggest an alternative action to prevent the problem.

Warning messages help prevent errors and explain how the user can move forward effectively.

Error

Error messages notify the user of a problem related to an action they have taken. The problem can be caused by the user or by the system. Error messages should explain what has gone wrong and should suggest how to resolve the problem, if appropriate.

Inline error messages ideally offer users a way to help correct the problem.

Writing inline messages

Inline messages should be concise.

  • Write full sentences and use end punctuation
  • Consider your audience. Use plain English and avoid highly-technical words
Keep inline messages short and avoid jargon.

Form Inputs

Overview

Form inputs allow users to enter text.

The length of a form input should be appropriate for the amount of text the user needs to enter. If a field is too long or too short, users may wonder if they understood the label correctly.


Input labels

An input label should make it clear what the user should enter into the field. For legibility, keep the label short and limit to a few words.

Helper text

Helper text can be added below an input field in order to better clarify how the user should answer.

Helpful hints

warning-indicator Don’t use placeholder text or prepopulate an input field. Users may miss a field that is already populated and submit with incorrect data.
Inputs should have a clear, short label. Helper text under the input can help give the user additional information or instructions about the field.

Styled inputs

Styled input fields work well for short forms and within sentence structure forms. On focus, the input underline highlights, making styled inputs a friendly way to ask users for information.

Helpful hints

warning-indicator Styled inputs are not recommended for heavy data entry.

checkmark Choose one input style for a single form.

warning-indicator Don't mix styled and default input fields in a single form.


Disabled inputs

To disable an input field, add the class .is-disabled to the .Field container.
When inputs are disabled, they become grayed out.

Required vs. optional

The input field label informs users which fields are required or optional.

One way to designate a field is required is to add a single asterisk (*) next to the input field label. When using this option, there must be an additional label stating "* Required field" under the fillable form.

Alternatively, a text label can be used showing which field(s) are required or optional.

  • If there are more optional fields than required fields, add the text "(required)" next to the input field label.
  • If there are more required fields than optional fields, add the text “(optional)” next to the input field label.

This example shows the asterisk option to label required fields. With this option, there is also disclaimer text under the form informing user what the asterisk represents.
This example shows the text option to label required fields. Optional fields are not labeled.
This example shows the text option to label optional fields. Required fields are not labeled.

Input validation

By adding .is-invalid to the .Field container, the input field will be marked as invalid and the .Field-error element will appear. In the case that an error message and helper text is needed, both shall appear under the input, helper text above error message.
A clear validation state lets the user quickly find errors that need to be corrected.

Input accessibility

Form components require semantic information to help people using assistive technology understand the structure and information conveyed in the form field.

The class .Field-label should be associated with the label element. This helps identify what information each input is collecting. If a label is not needed for any reason, use CSS to move it out of the visual range of the user leaving it for screen readers to see. The class .Field-detail gives further instruction when needed. Aria-describeby should be used and pointing at the .Field-detail node's ID for the best experience. Label for, Input id can be changed to meet your needs, but must match. Input aria-describedby and Field Detail id can be changed, but must match as well.


Links

A link navigates users to a new location. It can take them to a new section in the same site, or to an external site.

Link element

When a link is outside a copy block, use a link element. A carrot is added to the text, indicating movement to another page within the site.

To make a link an element, simply add the class Link.

Links vs. buttons

Unlike a button, a link isn’t a call to action. Links are used as navigation, and buttons allow users to take a direct action (see the Buttons section).


Reversed

When a link is over a darker background, use the is-reversed class to ensure adequate contrast for readability.


Helpful hints

information-indicator For text links inside a copy block, see the Core Typography Styles.
Links in copy blocks are underlined. Link elements sit away from other text and have a carrot.

Link text

Link text helps the user understand where the link is taking them.

  • Write in title case
  • Make it clear and descriptive
  • Keep it short and to the point

checkmark Use descriptive language

warning-indicator Don't use vague text, such as “Click Here” or “Learn More.”


External links

When linking to an external site, add the attribute target=“_blank”. This opens the site in a new tab, preventing users from losing their place.

For greater accessibility, it is recommended you include some text to indicate the link will open in a new viewport; this can be safely hidden from view by using the classname .u-hiddenVisually. It is also recommended you add the attribute rel=“noopener”, to safeguard from “Tabnabbing”.

.
External links automatically add a small "exit" icon to let the user know they are leaving the current site.

Loader

A loader element lets users know that content is loading. It provides visual feedback when the progress is indeterminate and ongoing.

Loader icon

A loader should be a general indication of the time it takes to load content. It doesn’t represent real time loading and should not be confused with a progress bar. If page content takes longer than a few seconds to load, consider improving page performance.

When placing a loader inside a button, the loader icon should have a width and height of 20.

When using a loader as a placeholder for content, the icon should have a width and height of 60.

checkmark Use a loader as a placeholder for content.

warning-indicator Don’t replace or obscure navigation or page elements.

checkmark Use a loader for a single component and only one time a page.

warning-indicator Don’t use loaders in multiple parts of a component.


Reversed (white)

When a loader is needed on a dark colored background (for example, within a primary button), add the class.

A white, reversed loader is also availble for use on dark backgrounds.

Duration

The loader should finish its rotations before any content appears. It should last long enough for the user to acknowledge the ongoing process without its seeming to prolong the wait.

Multiselects

Overview

Multiselects allow users to select one or multiple options from a contained list.

It is recommended that multiselect be used as infrequently as possible when designing and building for accessibility. Users may not know to use CTRL/Command or Shift + click to select multiple items. A set of check boxes can provide similar, yet more accessible functionality.


Multiselect labels

Multiselect labels and option descriptions should make it clear what the user is selecting. For legibility, keep options to a few words.

Helper text

Helper text can be added below a select field in order to better clarify how the user should answer.

Helpful hints

checkmark List options in a logical order for the use case (i.e. alphabetical, numeric, time-based).
Multiselects should have clear, short labels. Helper text can be added below an input field in order to better clarify how the user should answer.

Disabled multiselect

To disable a multiselect, add the class .is-disabled to the .Field container.
When a multiselect is disabled, it becomes grayed out.

Required vs. optional

The input field label informs users which fields are required or optional.

One way to designate a field is required is to add a single asterisk (*) next to the input field label. When using this option, there must be an additional label stating "* Required field" under the fillable form.

Alternatively, a text label can be used showing which field(s) are required or optional.

  • If there are more optional fields than required fields, add the text "(required)" next to the input field label.
  • If there are more required fields than optional fields, add the text “(optional)” next to the input field label.

In this example, most questions on the form are optional, so the one required question is labeled "required."

Multiselect validation

By adding .is-invalid to the .Field container, the multiselect will be marked as invalid and the .Field-error element will appear.

A clear validation state lets the user quickly find errors that need to be corrected.

Multiselect accessibility

Form components require semantic information to help people using assistive technology understand the structure and information conveyed in the form field.

When using helper text or invalid states, make sure to use aria-labelledby to convey the additional information to the user.

When using mulit-selects without a label, include the attribute aria-label="Your Label Here" to describe what the select element is asking for. See www.w3.org for more information.


Overlays

An overlay is a content box that is displayed on top of the main page. Overlays are used to show additional information while maintaining the context of the current page.

Basic overlay

Overlays obsures the main page to present the user with additional information. It’s recommended that overlays be intitiated by the user to ensure the content is relevant to the task at hand. The goal is to provide the least amount of disruption to the user’s flow as possible.

When an overlay is open, a user cannot interact with or scroll within the main window. It can be dismissed using the close button, the Escape key, or clicking outside the overlay.

Helpful hints

checkmark The width of an overlay is 90% of the window with a max width of 800px.
checkmark Only one can be open at a time.
information-indicator Overlay code is typically placed at the bottom of the page between the footer and the closing body tag, but before any script or link tags.

Overlay content

It’s important to consider whether an overlay is the best way to present the content. There should be a compelling case for why the content shouldn’t be presented within the page.

Copy should be short and not require scrolling within the overlay.

Helpful hints

information-indicator An alternative to an overlay is to call out the content on the page. If a large amount of copy is necessary, consider creating a separate page.
information-indicator Consider utilizing header and paragraph styles to create hierarchy.

Overlay accessibility

When using overlays, it is recommended to implement a tab trapping approach to help guide the user. It can be confusing when a user selects an overlay trigger and then they are not immediately refocused to that modal.

Dialog (actionable overlay)

Dialogs (sometimes called “modals”) are actionable overlays. They are used for critical messages requiring an immediate answer from the user. They should only be used when the flow is dependent on the user’s response.

Dialogs must have at least one action. A user can close a dialog by selecting one of the actions or clicking outside the box. Clicking outside the box is the equivalent of “cancel”.

Helpful hints

checkmark Use dialogs very sparingly and only for urgent messages to avoid user irritation and frustration.
information-indicator Dialogs work well for actions that have serious consequences or are difficult to reverse.

Dialog content

Dialogs should be limited to 1-2 sentences. It is recommended that they have 2 or 3 of the following types of actions:

  • A positive choice (agreeing with the question)
  • A negative choice (ex. Cancel)
  • A neutral option (ex. Remind me later)

Helpful hints

information-indicator Using clearly written button text helps prevent users from quickly dismissing the dialog without reading the options.

Pagination

Pagination affords navigation between pages of content by breaking it up into digestible sets for the user.

Usage

Pagination is a component that allows the user to see which page is currently in view, how much content exists, and navigate across multiple pages. It is used when a user needs to find a particular item from a large data set. A common example is a search page which commonly returns dozens or more results.

Items to show per page

The recommended items per page is 10. This number could be adjusted to meet the needs of the projects for optimized performance and better experience. Items requiring less space may have more items per page. Items requiring more space may have fewer items per page.


Navigation buttons

Standard pagination includes four buttons: "First", "Last", "Prev", "Next", and one page indicator "Page X of Y". All buttons should be included whenever the pagination is used.

  • Disable "First" and "Prev" when user is on the first page.
  • Disable "Last" and "Next" when user is on the last page.
  • Disable ALL buttons when there's only one page of content.

Disable the buttons by using a span or similar non-interactive element with the "is-disabled" class (ex: "First" and "Prev" in the example), or by using the "disabled" attribute on the anchor or button element(ex: "Next" and "Last")

Helpful hints

information-indicator The responsive format of pagination will automatically adapt to different screen sizes.
checkmark Center align the pagination to its parent container with a max width of 520px. (This should occur by default.)
checkmark Always use the color provided by the Digital Design System.

Pills

Labels used to give visual emphasis to an important characteristic of a piece of content.

Usage

Pills should be used as a visual aid to indicate status/categorization. They are not clickable or interactive.

Pill backgrounds can be either solid fill or white with an outline using any color in the Design System, as long as the color contrast between the background and the pill text is at least 4.5:1. Pill label text should be either White (#FFFFFF) or GrayDarkest (#222222).

Pill Text

Pill text should be short and clear.

Helpful hints

information-indicator Strive for 1-2 words.
information-indicator Text should be written in ALL CAPS.
warning-indicator Avoid using icons or emojis in pills.

checkmark Do use pills consistently for the same category of information on repeating elements.

warning-indicator Don't mix categories of information in the pills within the same set of elements.

Radio Buttons

Overview

Radio button lists require users to select a single option from a list. One radio button must be selected at all times. It is recommended to use radio button lists when there are 7 or fewer options.

Helpful hints

information-indicator When there are only a few options, the user benefits from seeing all available items.

Labels and content

A list must have a label to give users context about the group of items they are choosing from. Radio button labels and option descriptions should make it clear what the user is selecting. For legibility, keep options to a single line.

Helpful hints

checkmark Options should be mutually exclusive and distinct.
checkmark List options in a logical order for the use case (i.e. alphabetical, numeric, time-based).
checkmark Preselect the safest, most common or default item. “None” is an acceptable option.
Radio button lists should have mutually exclusive options. If a question could ever have more than one option selected by the user, use a checkbox list instead.

In-line radio button lists

Radio button lists can also be laid out horizontally. To create an inline list, add the modifier Field-group--inline to the Field-group container.
Radio buttons can be placed horizontally when there are only a few, short options.

Disabled radio buttons

To disable a radio button list, add the class .is-disabled to the .Field container. A single radio should never be disabled.

When radio buttons are disabled, they become grayed out.

Required vs. optional

The input field label informs users which fields are required or optional.

One way to designate a field is required is to add a single asterisk (*) next to the input field label. When using this option, there must be an additional label stating "* Required field" under the fillable form.

Alternatively, a text label can be used showing which field(s) are required or optional.

  • If there are more optional fields than required fields, add the text "(required)" next to the input field label.
  • If there are more required fields than optional fields, add the text “(optional)” next to the input field label.

In this example, most questions on the form are optional, so the one required question is labeled "required."

Radio button validation

By adding .is-invalid to the .Field container, the radio button list will be marked as invalid and the .Field-error element will appear.

A clear validation state lets the user quickly find errors that need to be corrected.

Radio button accessibility

Form components require semantic information to help people using assistive technology understand the structure and information conveyed in the form field.

Radio button lists can be used to enhance the user experience. By wrapping a group of radio's in an unorder list, you can convey label and count to the user. The following example has more information about how to execute this. See www.w3.org for more information.


Selects

Overview

A select allows users to choose one item from a list of options. Use a select for a list of items that a user does not need to see all the time. This generally works best for 7-15 options.

Helpful hints

warning-indicator Avoid using selects when typing may be faster for the user. For example, information that is very familiar to the user, like their date of birth. This may require more validation on the backend, but it provides better usability.

Select labels and content

Select labels and option descriptions should make it clear what the user is selecting. For legibility, keep the options to a few words.

Placeholders

The first option acts as a placeholder, and it should be descriptive about the type of options within the select. Distinguish between the placeholder and the options by using a dash (“—“) before and after the placeholder text.
Selects should have clear, short labels. The first option in the list is the placeholder for the select.

Helper text

Helper text can be added below a select field in order to better clarify how the user should answer.
Helper text under the input can help give the user additional information or instructions about the field.

Helpful hints

checkmark List options in a logical order for the use case (i.e. alphabetical, numeric, time-based).
checkmark Options should be mutually exclusive and distinct.
information-indicator Users may miss a field that is already populated and submit with an incorrect option selected.

checkmark Use a placeholder to let users know that they must make a selection.

warning-indicator Don’t preselect an option.

checkmark Do describe the type of options the user will see before the open the select.

warning-indicator Avoid using generic language like “None” or “Please select”.


Disabled select

To disable a select, add the class .is-disabled to the .Field container.
When a select is disabled, it becomes grayed out.

Required vs. optional

The input field label informs users which fields are required or optional.

One way to designate a field is required is to add a single asterisk (*) next to the input field label. When using this option, there must be an additional label stating "* Required field" under the fillable form.

Alternatively, a text label can be used showing which field(s) are required or optional.

  • If there are more optional fields than required fields, add the text "(required)" next to the input field label.
  • If there are more required fields than optional fields, add the text “(optional)” next to the input field label.

Helpful hints

checkmark For required fields, set up validation to ensure the user can’t submit the placeholder option. Options should be mutually exclusive and distinct.
In this example, most questions on the form are required, so the one non-required question is labeled "optional."

Select validation

By adding .is-invalid to the .Field container, the select will be marked as invalid and the .Field-error element will appear.
When a select is disabled, it becomes grayed out.

Select accessibility

Form components require semantic information to help people using assistive technology understand the structure and information conveyed in the form field.

When using helper text or invalid states, make sure to use aria-labelledby to convey the additional information to the user.

When using selects without a label, include the attribute aria-label="STRING" to describe what the select element is asking for. Other states that can be utilized are aria-invalid, aria-required, and aria-labelledby. See www.w3.org for more information.


Text Areas

Overview

Text areas are taller versions of input fields and wrap overflow text to a new line. They allow users to input free-form text.

The length of a text area should be appropriate for the amount of text the user needs to enter. If a field is too long or too short, users may wonder if they understood the label correctly.


Text area labels

A text area label should make it clear what the user should enter into the field. For legibility, keep the label short and limit to a few words.

Helper text

Helper text can be added below a text area in order to better clarify how the user should answer.

Text areas should have a clear, short label. Helper text under the input can help give the user additional information or instructions about the field.

Disabled text areas

To disable a text area, add the class .is-disabled to the .Field container.

When text areas are disabled, they become grayed out.

Required vs. optional

The input field label informs users which fields are required or optional.

One way to designate a field is required is to add a single asterisk (*) next to the input field label. When using this option, there must be an additional label stating "* Required field" under the fillable form.

Alternatively, a text label can be used showing which field(s) are required or optional.

  • If there are more optional fields than required fields, add the text "(required)" next to the input field label.
  • If there are more required fields than optional fields, add the text “(optional)” next to the input field label.

In this example, most questions on the form are required, so the one non-required question is labeled "optional."

Text area validation

By adding .is-invalid to the .Field container, the text area will be marked as invalid and the .Field-error element will appear.

A clear validation state lets the user quickly find errors that need to be corrected.

Text area accessibility

Form components require semantic information to help people using assistive technology understand the structure and information conveyed in the form field.

The class .Field-label should be associated with the label element. This helps identify what information each input is collecting. If a label is not needed for any reason, use CSS to move it out of the visual range of the user leaving it for screen readers to see. The class .Field-detail gives further instruction when needed. Aria-describeby should be used and pointing at the .Field-detail or .Field-error node's ID for the best experience.

There are no explicit declerations that are needed for textareas. Options that exist are role=“textbox” and aria-multiline can be used if you are not using semantic markup.


Tables

Tables are structured grids of information that helps users view, process and understand data. They can be used to show information across multiple categories, filter and sort data, or to compare similar items.

Default table

The direction and styling of a table can be customized based on content and the user’s need. Consider setting up multiple versions of a table so that users on both large screens and small screens can understand the data equally.

Helpful hints

warning-indicator Don’t assume that a table that works on a desktop computer should be set up the same way for a mobile device.
checkmark Tables require thead and tbody elements in order to work correctly. The .Table is used only with table html elements. It won't work with any div that has been assigned the same class as the .Table counterparts.

Table headers

Most tables should have a header row to give context about each column. Headers should have short, clear labels for columns or rows.

Helpful hints

warning-indicator Don’t use vague labels, leaving users guessing what a row or column is about.
checkmark Headers should align with their content. See Table Content for specific alignment rules.
checkmark If a table requires many rows and requires scrolling, the header can be made sticky so it follows the user as they scroll.

Table content

Each table cell should contain a single data point or idea. Don't force multiple ideas into a single cell. Instead, consider adding more rows or columns to divide this information out.

If a cell does not contain any data, include "N/A" or "–" to show it has intentionally been left blank.

For consistency, there are a few alignment guidelines:

  • Text is left-aligned
  • Numbers are right-aligned
  • Short status words and icons are center-aligned

Helpful hint

checkmark In a column, be consistent with the number of digits after a decimal point (ex: 1.25, 3.00, 10.15)
Text alignment is determined by the kind of information displayed in a column.

checkmark Use N/A or "-" if a cell is intentionally left blank.

warning-indicator Don't have empty data cells.

checkmark Let the data be the hero of the table.

warning-indicator Avoid adding decorative elements to add visual interest.


Highlighted areas

Zebra striped rows

One way to make tables more legible is to add a zebra stripe. A gray background is applied to every other row, guiding users as they move their eye across the table. This aids in scannability and prevents users from getting confused about which row they’re looking at.

To create zebra stripes, add the modifier .Table--striped to the tbody rows.

Helpful hint

warning-indicator Don’t use zebra stripes on tables with fewer than 4 rows. It can cause confusion for users and they may think the highlighted rows hold more significance.
Tables with large numbers of rows may benefit from the addition of zebra stripes to increase their scannability.

Row highlight on hover

For tables that have a lot of columns, it can be helpful to highlight a row when the user hovers over it. This allows the user to focus on a specific row as they move across the table. Hover can be used on table with or without zebra stripes.

To add a row highlight on hover, add the modifier .Table--hover to the tbody row.


Column highlight

A column highlight can be added to emphasize important content. This can help distinguish one column from the rest of the table. It can also draw the user's attention to the most important information.

To highlight a column, add the class .is-highlighted to the cell element.

Column highlight can be used to distinguish one column from the rest of the information.
Highlighting a column can draw the user's attention to important information, such as a total or summary.

Condensed table

When space is limited or the table requires a large amount of content, consider using a condesed table. It can help display more items without making the user scroll.

Helpful hint

information-indicator It's recommended to use zebra stripes with condensed tables. The decreased white space can affect scannability and lead to parsing errors.

Toggle Buttons

Overview

A toggle switch is a control used to change between two states, most commonly On and Off. By default, the switch is in one state on page load and toggles state when selected.

Helpful hints

checkmark Do use when change should be displayed immediately.
checkmark Do use when there are exactly two states.
checkmark Display toggle to right (with color) for "On" and to the left (gray) for "Off".
checkmark Do use concise labels to clearly explain what is switching on and of (i.e. "Email Notifications", "Alerts").
warning-indicator Don't use the label to describe state of the switch ("Alerts On"/"Alerts Off").
warning-indicator Don't use a question as a label.
warning-indicator Don't use two labels for one switch.

ADA considerations

information-indicator It's best to use a single label to describe the toggle switch's state. Using two labels can be confusing for individuals using assistive technology, like screen readers. When there is a need to compare multiple operations, consider other controls like a drop-down menu.

checkmark Do use toggles to switch between on and off states.

warning-indicator Don't use two labels for one switch.