Components are the main building blocks for user interfaces. Building a reusable component library enhances your product development workflow by reducing design and tech debt and speeding up the process. Core components can’t be broken down into granular pieces without losing their meaning.

Focusing the content area with assistive technologies should announce additional context from the trigger element.

Content and trigger relation

Accordion comes in two states for toggling its content visibility. If an accordion trigger displays an icon, it should be visually distinct between states.

Active state

Content area should be flexible enough to support various types of content, including other components.

Composition

Add a subtle animation to help users understand and follow the component behavior when switching between states.

Toggle transition

Accordion toggles the visibility of content regions when the trigger element gets pressed.

Accordion

When using assistive technologies, alerts should announce their accessibility role correctly.

Accessibility roles

Actions in the alert should relate to their text and provide a way to react to the message sent to the user.

Supplementary actions

It's crucial to differentiate the alert's visual appearance based on its role. If you're using background colors for role differentiation, ensure there's enough contrast ratio with the content displayed inside the alert.

Colors

Icon illustrates the role of the alert and provides an additional hint about it for colorblind people.

Icon support

Alert can adapt to the viewport size, usually becoming full-width for mobile to save some space.

Responsiveness

Supporting a title can help your user understand the context of the message faster for longer alert messages.

Title support

Alert displays a prominent message about the whole page or its specific area.

Alert

Avatar should provide an accessibility label when used for non-decorative images and has no text representation of its contents.

Accessibility label

A background color should be applied to the avatar shape when used without an image. Make sure that icons and text have enough contrast ratio with the background according to the WCAG AA standard.

Multiple avatars can be stacked together to represent a group of users.

Avatar groups

Avatars should mask an image into their shape and work with any image size since they may get this image from unknown data sources.

Image

When not passing an image or there is an image loading error, avatars should be able to show a fallback with a different image, icon, or text initials.

Image fallback

Avatars might support multiple shapes, like square or circle, based on the area they are used in.

Shape

There are many contexts to use an avatar, which require different sizes for the component. Use at least 2-3 different sizes for average projects and ensure there’s at least a small size available.

Sizes

Thumbnail of a user photo, organization, or a visual representation of other types of content.

Avatar

Badges may play various roles in your product, and having a predefined color for each role should help users understand their meaning. When changing colors, make sure the text has enough contrast ratio with the background according to the WCAG AA standard.

Badges can be used as a dynamic way to display selected values, and there should be a way to dismiss them.

Dismissible action

Badges can be used without any text content inside. That usually requires changing their styles to preserve the correct shape.

Empty state

To better illustrate the meaning of a badge, you can display an icon next to the text. Make sure that for small badges, icon contents are still recognizable.

When used as a status badge, like a notification indicator – you should be able to position it relative to those elements.

Positioning

Badges can come in multiple sizes depending on where a badge is used. For example, you can use the large size for marketing pages.

Based on where in the product badges are rendered, you might support multiple component variants. For example, you can have some badges using a faded background to avoid drawing too much attention.

Variants

Compact element that represents the status of an object or user input.

Badge

If breadcrumbs items don’t fit into the parent container, the list should support collapsing items only to keep the relevant ones visible to the user.

Collapsed state

Each item in the list can be disabled separately to prevent users from navigating to the page.

Disabled state

Icons help to communicate the roles of the pages to which breadcrumbs items link. Most of the time, you want to ensure they’re used consistently, not only for random items in the list.

Depending on the usage context, items in the breadcrumbs list can use different separator styles.

Custom separator

Top-level product navigation that helps user understand the location of the current page and navigate back to its parents.

Breadcrumbs

Button should have a visible focus indicator when it’s focused using the keyboard or assistive technologies.

Focus indicator

Button should correctly announce the button or link accessibility roles and automatically resolve it based on the properties passed to it.

Accessibility role

Provide a visual cue when a button is pressed, used for selecting a value, or toggles other elements on the page.

Buttons may play various roles in your product, and having a predefined color for each role should help users understand their meaning. When changing colors, make sure the text has enough contrast ratio with the background according to the WCAG AA standard.

Visually shows that the button is not interactive and restricts it from being pressed.

Clearly show that the button is interactive when hovered with a mouse cursor.

Hover state

Icons easily communicate the button's purpose when used next to its label or can be used without text when there's insufficient space. Ensure the accessibility label is provided when used with an icon only.

Indicate when users have to wait for the result of their action after pressing a button. If a spinner is used to display this state, ensure it’s not changing the original button width or height.

Loading state

Depending on where a button will be used, it can come in multiple sizes. For example, you can use the small size for dense areas of your application.

When using multiple buttons, there should be a way to differentiate between primary and secondary actions. Buttons may play different roles for the user or be used on various surfaces, and they have to change how they look.

Interactive element used for single-step actions.

Button

Calendar dates should be focusable with keyboard and assistive technologies. Further navigation on the dates should happen with keyboard arrows or screen reader navigation and support switching the month by navigating out of a column or a row.

Keyboard navigation

Selected dates should be announced by the assistive technologies when they get focused.

State announcement

Provide short labels for the weekday names in addition to the date numbers to let users easier navigate the date selection.

Day names

Calendars should be localized for all country regions supported by the product. That includes date formats and correct ordering of the weekdays.

Internationalisation

Calendar might be used in various product areas and viewports. Make sure to support different display modes for rendering more than one month or a vertical layout.

Display modes

To help users navigate longer date ranges, the calendar should provide an easy way to switch displayed months.

Month selection

Calendar should support a single date and a selection range. Selected dates should be visually highlighted, and the range between selected dates should be visible to the users.

Selected state

Grid displaying days in one or more months and allow users to select a single date or a date range

Calendar

Cards can be used with actions usually placed at the bottom of the card, or the card itself can be tappable and represent an action.

Content composition

Multiple cards can be grouped in a single list of content sections.

Card groups

Cards are frequently used with media content. The most popular options are having a full-width area on top of the content or an area at one of the card’s sides.

Media sections

On mobile viewports, cards are usually full-width to save space for the content.

Container to group information about subjects and their related actions.

Card

Checkbox selections should be triggered with the keyboard. Using native elements for this should provide this kind of interaction automatically.

Keyboard support

Display when the checkbox gets selected and is used for the form submission.

Checked state

Use a disabled state to prevent checkbox interactions and remove its value from the submitted form values.

Use an error state for form validation when the error is related to the checkbox field. Always use a text error along with a different field color.

Error state

Checkboxes can be grouped to work with multiple values at the same time.

Checkbox group

Visually display when the checkbox has children selectable elements and only some are selected.

Indeterminate state

There should be a text label linked with the checkbox field. Clicking the label should also trigger the checkbox selection. If the label is not rendered on the page, assistive technologies should still announce it.

Label

Form field used to select one or multiple values from the list.

Checkbox

If the divider is playing a non-decorative role in the layout, its role should be announced by the assistive technologies.

Dividers should separate both horizontal and vertical lists of content.

Direction

Divider

Once dropdown content is opened, the focus ring should move inside its content area and return to the trigger element when closed.

Focus trapping

Dropdown should be accessible for keyboard and assistive technologies. Users should be able to close the dropdown using a separate close action, or once they tab outside the content area.

Dropdowns may be used for context menus, product navigation, and other purposes. Their content area should be flexible enough to support various types of content, including other components.

Dropdown should support displaying its content on hover events. The same behavior should happen for keyboard users once its trigger gets focused.

Hover trigger

Dropdown content should be displayed based on the current position of the trigger element on the screen and always stay visible to the user.

Dynamic positioning

Dropdown content should be adjusted if it doesn’t fit the screen the same way on mobile devices as on desktop.

List of contextual actions that users can trigger.

Dropdown

Icons are used as decorative elements most of the time. If an icon is meant to be interactive – that functionality should be included using buttons, links, or other interactive components.

Interactivity

Icons should support color values available in design system tokens. Additionally, it’s a good practice to support color inheritance from their parent element.

Icons should have several predefined sizes to provide a holistic experience across the product. Typography pairings may be used for these size values to ensure they align with the text sizes.

Wrapper for SVG assets to control their appearance

Icon

When the image is non-decorative, it should provide an alt text describing the picture contents.

Alt text

Depending on the screen density, you should support loading multiple image assets of different sizes and serve the relevant one to the user.

Screen density support

Display a fallback when the image URL is incorrect or undefined. That can be an empty box with a background, an icon, or a static placeholder image.

Image should be flexible in terms of supported sizes. Besides just supporting width and height – add support for aspect ratio to scale its proportions based on the parent element dynamically.

Utility for displaying images and controlling their behavior.

Links should correctly announce the button or link accessibility roles automatically resolve it based on the properties passed to it.

Links may play various roles in your product, and having a predefined color for each role should help users understand their meaning. Since the link is a text element, it should be able to automatically inherit the color defined by its parent element, the same as other text content.

Visually shows that the link is not interactive and restricts it from being pressed.

Links should be able to inherit the typography styles when used as a part of the text element.

Font inheritance

An icon can be used next to the link to communicate the purpose of the link. Icons shouldn’t be used inside a link without a text label.

When used inside a text paragraph, links should support multiline display without breaking the text flow.

Multiline display

Interactive text element used for navigation within the text paragraphs.

Link

Assistive technologies should announce lists with the correct role and number of items displayed.

List item content areas should be flexible enough to support various types of content, including other components.

Content cmposition

List items can use bulleted, numbered, and other styles and types of ordering.

Order

List

If the loading indicator is standalone – provide an accessibility label for the content area it’s loading.

The loading indicator should be synced with the system motion settings and reduce its animation speed when reduced motion settings are turned on.

Reduced motion

Loading indicators might be used inside the elements with various roles and follow their color scheme.

In some cases, the wait time can’t be determined. The loading indicator should be shown until the loading finishes or an error happens. In other cases, it’s better to indicate the time left until the loading is finished.

Loading duration

Loading indicators might provide multiple sizes, depending on the size of the areas where the loading indicator is rendered.

Animated element that communicates progress without telling how long the process will take.

Loading indicator

When the modal gets opened, the user focus should move to the first focusable element and stay trapped inside it. When the modal is closed, the focus should return to the last active element.

It should be possible to close a modal by pressing the Esc key, and all the focusable elements inside the modal container should be accessible with keyboard navigation.

Modals should use the correct accessibility role, and they should be labeled by the title and subtitle elements. If there is no visible title or subtitle, it may use an accessibility label instead.

Title and subtitle labeling

Since content in the modal may be actionable, it’s essential to have an area for action elements. This area is usually located at the bottom of the modal container.

Modals should provide a straightforward way to close, as they block content when open. This may be either a separate close button or one of the supplementary actions.

Close action

The main content area should be flexible enough to support various types of content, including other components.

Modals can be positioned in the center of the screen or displayed as sliding sheets on either side of the screen.

Provide support for changing the modal height and width based on the content you display.

Container appearing in front of the main content to provide critical information or an actionable piece of content.

Modal

Pagination should provide clear, dynamic labels for each page for assistive technologies instead of just announcing the number without context.

Full page label announcements

Pagination should announce when a selected page is focused.

Provide an option to select the number of paginated items displayed on the page.

Amount of items per page

When you don’t know the total number of available pages beforehand, use a different display mode to navigate pages individually.

Indeterminate amount of pages

Define the ranges for pages rendered around the selected page. It helps render only a limited number of pages but lets the users navigate faster than moving by 1 page at a time.

Page display ranges

Visually highlight the selected page in the list and make it non-interactive.

Selected page state

Pagination enables a selection from a range of pages

Pagination

Provide support for adding an accessibility label in case you can’t display a label in the interface.

In some cases, the wait time can’t be determined. The loading indicator should be shown until the loading finishes or an error happens. In other cases, it’s better to indicate the time left until the loading is complete.

Duration

Provide support for visually displaying a label explaining what a progress bar is responsible for.

Bar displaying progress for a task that takes a long time or consists of several steps.

Build better design systems

Design language

Foundations

Core components

Maintenance