Introduction
Design PrinciplesAccessibility
Foundation
ColorGridIconographyIllustrationsShadowsTypography
Product Writing Guide
OverviewProduct's PersonalityBest PracticesInclusive LanguageWriting AccessiblyWriting GloballyWriting for AIGrammar RulesGlossaries
Components
ACTIONS
ButtonDropdownDropdown FlyoutToggle ButtonSegmented Controller
DISPLAY
AvatarAvatar StackContact ItemFile ListPillTokenThumbnail
INPUT
CheckboxDate SelectDropzoneFile SelectGroup SelectMenuMulti SelectNumber/Currency InputPill SelectRadio ButtonSingle SelectSliderSwitchText AreaText Editor (RTF)Text InputTiered Select
LOADING
Progress BarSpinner
MESSAGING
BannerEmpty StateToastTooltip
navigation
BreadcrumbsLinkPaginationSearchTabsTree
overlays & surfaces
CardModalPanelPopoverTearsheet
Layouts
DetailDockEmailPage TemplateRelated Items
Patterns
Content FlowFormForm Empty StateIn-Line Error ValidationOverlay UsageTitle LockupEmail Notifications
Views
Data Table
Data TableCells & RowsLocation Filter
ListLists vs TablesTile
DST Resources
ContributeDevelopmentFigma LibrariesSpotlightUser TestingFeedback

List

We use lists to display separate items that may have similar, but often varying content.  Because list items can standalone without additional context outside of the list or other items within the list, they can be reordered without changing how the information is interpreted.
Figma Component

Anatomy

List Item

Each row displays content in a consistent way, even if not all segments are filled out in every list item. Segments within a row are optional except for the header segment.

Header Segment

The header segment is required for every list item. This is where the item is defined, often by displaying the title or name of the item and any important secondary information that gives context to the title.

Do not exceed a maximum of three lines in the segment.

Content Segment

The content segment can be designed to meet your needs, but it’s important that the content is concise and scannable. If more information is needed about an item, the item name can link to a detail page or modal which can display more lengthy information. A “View” button in the action segment is also possible.
A content segment with three of the same type of content block: label/value.
A content segment with three of the same type of content block: label/value.

Content Blocks

Content blocks refer to the items within the content segment. Blocks can have varying content types and widths as long as they follow the grid. Content block can wrap as needed and the height of the list item will increase accordingly.
‍
Be sure that the content best practices are used for any type of content and that it remains consistent with the other list items. 



Do not exceed a maximum of four ‘columns’ of content blocks in the segment. This ensures that the content remains scannable.

Action Segment

If actions are needed, add a maximum of two actions before adding an overflow. Do not use a primary button in a list to maintain the hierarchy of a primary action used at the page level. If no actions are needed, this segment can be used for tertiary text like a notation or timestamp.
‍
All content in this segment is right aligned.
A segment with an action and overflow.
A segment with notation.

Types

There are two layout types to choose from. In both types, always use our grid to organize content.

Inline

In horizontal lists, segments appear horizontally accross the row. This allows for content to sit inline with each other.

Stacked

In stacked lists, the header and footer segments are inline with each other, sit above the content segment, and expand across the whole width of the list item. The content segment with content blocks appear below the header / footer row.

Row Format Examples

There are many ways to organize the content within a list row. The only requirement is that item always have a title within the header segment. Each row within a list can have varying types of content. The layouts below showcase how the segments can be used within each row.

Header + Single Content Block

Header segment with title and subtitle and content segment with a single content block 
(label and value).
Header segment with title and content segment with a single content block (value).

Header + Multiple Content Blocks

Header segment with title, subtitle and avatar. Content segment has 3 content blocks (label/value).
Header segment with title and subtitle. Content segment has 2 content blocks (label/value). Action segment has 1 secondary button.
Header segment with title, subtitle. Content segment that has many rows of content blocks 
(label/value).

List Grid

Lists use a 12 column grid with a margin and gutter of 24px.

Controls

List items can be searched, sorted and filtered using the same patterns used for tables. The patterns will be located above the list as shown in the image below.
Filters will open up a panel to the left of the list. The content within the list items will resize to fit the panel. See the filter component for more details.

Specifications

Padding