Actions represent components and UI elements that a user interacts with to initiate a task or operation, or to navigate. Actions are typically represented as 

. Choosing the right component and component variants depends on the action’s importance and its context within a page.

Actions should almost always be labeled with a short, concise, 

If the action is a common action, the verb + noun rule can be ignored. Examples of common actions include:

Actions can also be displayed through an 

. These are typically used for a group of secondary actions localized to a single entity such as a table row or a detail page. Actions in this context should have equal importance with each other as there is no opportunity to establish visual hierarchy.

 are typically used for navigation, but in rare occurrences can be used to initiate an action where a tertiary 

 will not work. Use links as actions sparingly, and only for very unimportant actions.

Actions represent components that initiate a task or operation, or provide navigation

Actions

Empty states are areas of a user experience where content cannot be shown because there is no content to display. Some examples of an empty state include a list of resources that has no items in it, or a search results list that returns no results.

Empty states help users navigate through missing content by providing clear guidance on what to do next. Without empty states, users may become confused or frustrated, unclear as to how they are to proceed.

Example of a list's or table's empty state after being filtered.

Empty States are used to provide education or guidance to the user when there is no data to display

Empty States

There are different types of filtering selection methods for different situations. To find the best method, think about how the user would narrow down the data they are looking at.


Use a single filter when the user can only choose one attribute to narrow down results. This filtering method behaves like a radio button group. There are many different ways to use single selection filters. The UI element to display depends on the number of options available for selection.

Use multiple selection filters when the user can choose multiple attributes to narrow down results. This filtering method behaves like a checkbox group. Matchbox supports two ways of displaying multiple selection filters:

Use batch update filters to apply several filters at the end of selection. In most cases, filters should be applied immediately as soon as a filter is interacted with, but in certain situations, delaying filter application may be best. Typically, batch updates are used when the filter selection process is long, or API response times are slow.

Filtering is used to include, exclude, or segment data displayed in a UI

Filtering

Forms are common user interfaces that are used to get information or data from the user. They can be simple or complex and can be presented in a variety of ways depending on the situation.

Labels allow the user to quickly scan through forms and are required on every field:

Be clear and concise. Labels should not be longer than two to three words

Labels should be placed above and to the left of the relevant input control

Required fields should not be visually marked as required

Optional fields should be marked as optional

Forms should always have a title that describes the form.

Longer forms with several groups of fields can split each group with panel sections along with sub headers. Fields should be grouped together by relevance. Fields that are directly related to each other may be grouped horizontally.

Follow a logical and predictable order when placing fields. For example, a login form should display email before password.

Field placeholders should never be used as labels. This prevents a user from identifying the input required for the field once they begin to fill it.

Placeholder text should be limited to example text only in the (e.g.) format

Placeholder examples should be as short as possible to not overflow the width of the input

Placeholder examples should use anonymized examples rather than real values

Help text is used to assist the user with understanding how to complete a single form field. Help text can be presented to the user in two different ways, either below the relevant field or through tooltips.

Client side validation or error messaging assists the user with understanding how to properly complete a form. It informs the user what and where the issue is, and provides guidance on how to correct it. Error messaging should occur at the field level, to help identify which fields need correcting. If an error message pertains to multiple fields, a 

Field-level error messages should only be visible if:

Buttons in a form are used to either submit the form, or to discard changes. Use a filled blue button for the primary action, and an outlined blue button for the secondary action.

Submit buttons should always appear on the bottom left corner of the form. Submit buttons should never be top-aligned.

Submit button labels should always tell the user what to expect. Use a verb & noun combination to describe your submit action.

Forms are a collection of related inputs used to gather information from the user

Forms

Loading states are visual indicators used to communicate to the user that data is being loaded or an operation is taking place and the UI is not frozen. It is important to use loading states to keep the user’s attention on the page and make the waiting experience more bearable.

As a best practice, data should be loaded at the deepest or lowest possible level of a UI in order to show the user as much of a page as possible as soon as possible. For example, bring loading states down to the level of an atom, component, or module, and load a page’s structure to give the user an understanding of what the page will look like after data is loaded.

Loading errors are not guaranteed roadblocks

 is pressed to indicate an action is processing.

 when the structure of the loaded content is unknown.

 when the structure of the loaded content is known. Always default to using Skeletons over Spinners.

 for excessively long processes (over 10 seconds) where progress of the operation can be displayed.

Loading states tell the user that data is being loaded or that an operation is taking place

Loading

Messaging uses various types of  alerts and notifications to inform users of important and relevant information. They are frequently used to focus the user’s attention or provide immediate feedback following a user’s action.

Choosing the appropriate message type depends on the context of the message and whether it is initiated by a user’s action or by the application.

All messages convey tone and status which is represented through iconography and color.

Messaging describes UI elements that communicate important information to users

Messaging

, or dialogs, are stopping points in a user experience that intentionally introduce friction. They are disruptive by design. The purpose of a modal should be clear to the user as soon as it is presented, and a path to completion should be obvious.

Because of their intrusive nature, modals should only be used in a few situations:

Use to confirm a decision for potentially destructive or irreversible actions

 be initiated by clicking a button. A modal should be expected by a user through a user-triggered action and should never open unprompted.


Modals are disruptive and cause friction. Only use them when intentionally disrupting a user flow or experience. Modals can annoy the user if they are used too frequently.


Within a modal, content length should be short and concise so as to fit within the browser’s viewport. Never use a modal to display a large amount of information or data. Modals should be simple to complete or dismiss and have a clear call to action.

When a modal is opened, focus should be placed on the modal’s container. Focus should also be trapped to the modal’s contents. The underlying page should be unfocusable and unreachable through keyboard navigation.


A modal should be closed when the following happens:

 button in the modal’s footer is pressed

Clicking anywhere outside the modal’s container

Patterns