diff --git a/src/data/nav-items.yaml b/src/data/nav-items.yaml index 92b15dbb03d..07998bbe353 100644 --- a/src/data/nav-items.yaml +++ b/src/data/nav-items.yaml @@ -114,6 +114,8 @@ path: /components/checkbox/usage/ - title: Code snippet path: /components/code-snippet/usage/ + - title: Contained list + path: /components/contained-list/usage/ - title: Content switcher path: /components/content-switcher/usage/ - title: Data table diff --git a/src/pages/components/contained-list/accessibility.mdx b/src/pages/components/contained-list/accessibility.mdx new file mode 100644 index 00000000000..7fc2e6635fd --- /dev/null +++ b/src/pages/components/contained-list/accessibility.mdx @@ -0,0 +1,26 @@ +--- +title: Contained list +description: + Contained lists group content that is similar or related and can contain + read-only or interactive information. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +Design annotations are needed for specific instances shown below, but for the +standard accordion component, Carbon already incorporates accessibility. + + + + + +This page is underdevelopment. Please check back later for updates. + + + + + What Carbon provides + Design recommendations + Development considerations + diff --git a/src/pages/components/contained-list/code.mdx b/src/pages/components/contained-list/code.mdx new file mode 100644 index 00000000000..a3a5baaa1a7 --- /dev/null +++ b/src/pages/components/contained-list/code.mdx @@ -0,0 +1,32 @@ +--- +title: Contained list +description: + Contained lists group content that is similar or related and can contain + read-only or interactive information. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +Preview the contained list component with the React live demo. For detailed code +usage documentation, see the Storybooks for each framework below. + + + +## Documentation + + + +**Coming soon:** The storybook code for contained list is underdevelopment and +will be available soon. + + + +## Live demo + + + +**Coming soon:** The live demo for contained list is underdevelopment and will +be available soon. + + diff --git a/src/pages/components/contained-list/images/contained-list-style-1.png b/src/pages/components/contained-list/images/contained-list-style-1.png new file mode 100644 index 00000000000..a61251e78dc Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-style-1.png differ diff --git a/src/pages/components/contained-list/images/contained-list-style-2.png b/src/pages/components/contained-list/images/contained-list-style-2.png new file mode 100644 index 00000000000..3d77a510da7 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-style-2.png differ diff --git a/src/pages/components/contained-list/images/contained-list-style-3.png b/src/pages/components/contained-list/images/contained-list-style-3.png new file mode 100644 index 00000000000..152e1c35409 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-style-3.png differ diff --git a/src/pages/components/contained-list/images/contained-list-style-4.png b/src/pages/components/contained-list/images/contained-list-style-4.png new file mode 100644 index 00000000000..0003e315a8e Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-style-4.png differ diff --git a/src/pages/components/contained-list/images/contained-list-style-5.png b/src/pages/components/contained-list/images/contained-list-style-5.png new file mode 100644 index 00000000000..8ef26fb4875 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-style-5.png differ diff --git a/src/pages/components/contained-list/images/contained-list-style-6.png b/src/pages/components/contained-list/images/contained-list-style-6.png new file mode 100644 index 00000000000..6da197716d2 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-style-6.png differ diff --git a/src/pages/components/contained-list/images/contained-list-style-7.png b/src/pages/components/contained-list/images/contained-list-style-7.png new file mode 100644 index 00000000000..8924a82050d Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-style-7.png differ diff --git a/src/pages/components/contained-list/images/contained-list-style-8.png b/src/pages/components/contained-list/images/contained-list-style-8.png new file mode 100644 index 00000000000..e5969f1dbf7 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-style-8.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-1.png b/src/pages/components/contained-list/images/contained-list-usage-1.png new file mode 100644 index 00000000000..31f748ba56b Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-1.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-10.png b/src/pages/components/contained-list/images/contained-list-usage-10.png new file mode 100644 index 00000000000..6124176d0e5 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-10.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-11.png b/src/pages/components/contained-list/images/contained-list-usage-11.png new file mode 100644 index 00000000000..e386cb77f2b Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-11.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-2.png b/src/pages/components/contained-list/images/contained-list-usage-2.png new file mode 100644 index 00000000000..65d6f482bd3 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-2.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-3.png b/src/pages/components/contained-list/images/contained-list-usage-3.png new file mode 100644 index 00000000000..a39c170b365 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-3.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-4.png b/src/pages/components/contained-list/images/contained-list-usage-4.png new file mode 100644 index 00000000000..add0d8d2b5a Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-4.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-5.png b/src/pages/components/contained-list/images/contained-list-usage-5.png new file mode 100644 index 00000000000..4cdb1b0d724 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-5.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-6.png b/src/pages/components/contained-list/images/contained-list-usage-6.png new file mode 100644 index 00000000000..d85db9017ee Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-6.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-7.png b/src/pages/components/contained-list/images/contained-list-usage-7.png new file mode 100644 index 00000000000..87c52158e98 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-7.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-8.png b/src/pages/components/contained-list/images/contained-list-usage-8.png new file mode 100644 index 00000000000..c696da10486 Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-8.png differ diff --git a/src/pages/components/contained-list/images/contained-list-usage-9.png b/src/pages/components/contained-list/images/contained-list-usage-9.png new file mode 100644 index 00000000000..9c748d1536c Binary files /dev/null and b/src/pages/components/contained-list/images/contained-list-usage-9.png differ diff --git a/src/pages/components/contained-list/style.mdx b/src/pages/components/contained-list/style.mdx new file mode 100644 index 00000000000..0e8ded20e4b --- /dev/null +++ b/src/pages/components/contained-list/style.mdx @@ -0,0 +1,153 @@ +--- +title: Contained list +description: + Contained lists group content that is similar or related and can contain + read-only or interactive information. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + +## Color + +| Element | Property | Color token | +| ---------------- | ---------------- | ------------------ | +| Title: on page | text color | `$text-primary` | +| | background-color | `$background` | +| Title: disclosed | text color | `$text-secondary` | +| | background-color | `$layer`\* | +| Item | text color | `$text-primary` | +| | background-color | transparent | +| Icon (optional) | svg | `$icon-primary` | +| Row divider | border-bottom | `$border-subtle`\* | + + + * Denotes a contextual color token that will change values based on the layer + it is placed on. + + + + + +![Enabled states for contained list variants](images/contained-list-style-1.png) + + + + +Example of enabled states for contained list variants. + +### Interactive states + +| Element | Property | Color token | +| -------- | ---------------- | ------------------ | +| Hover | background-color | `$layer-hover`\* | +| Focus | border | `$focus` | +| Active | background-color | `$layer-active`\* | +| Disabled | text color | `$text-disabled` | +| | border | `$border-disabled` | + + + * Denotes a contextual color token that will change values based on the layer + it is placed on. + + + + + +![States for contained list item rows](images/contained-list-style-2.png) + + + + +Example of states for contained list item rows. + +
+ + + + +![States for contained list inline actions](images/contained-list-style-3.png) + + + + +Example of states for contained list inline actions. + +## Typography + +All contained list text should be set in sentence case, with only the first word +in a phrase and any proper nouns capitalized. + +| Element | Font-size (px/rem) | Font-weight | Type token | +| ---------------- | ------------------ | -------------- | --------------------- | +| Title: on page | 14 / 0.875 | SemiBold / 600 | `$heading-compact-01` | +| Title: disclosed | 12 / 0.75 | Regular / 400 | `$label-01` | +| Item | 14 / 0.875 | Regular / 400 | `$body-01` | + +## Structure + +| Element | Property | px / rem | Spacing token | +| ----------------- | --------------------------- | -------- | ------------- | +| Header: on page | height | 32 / 2 | `$spacing-07` | +| | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| Header: disclosed | height | 48 / 3 | `$spacing-09` | +| | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| Item | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| Icon (optional) | height, width | 16 / 1 | — | + +
+ +![Structure and spacing measurements for the on page list variant.](images/contained-list-style-4.png) + +
+ + + Structure and spacing measurements for the on page list variant. | px / rem + + +
+ +
+ +![Structure and spacing measurements for the disclosed list variant.](images/contained-list-style-5.png) + +
+ + + Structure and spacing measurements for the disclosed list variant. | px / rem + + +
+ +
+ +![Structure and spacing measurements for height and width of row content.](images/contained-list-style-6.png) + +
+ + + Structure and spacing measurements for height and width of row content. | px / + rem + + +
+ +
+ +![Structure and spacing measurements for padding and rule alignment.](images/contained-list-style-7.png) + +
+ + + Structure and spacing measurements for padding and rule alignment. | px / rem + + +
+ +
+ +![Structure and spacing measurements for inline actions.](images/contained-list-style-8.png) + +
+ + + Structure and spacing measurements for inline actions. | px / rem + diff --git a/src/pages/components/contained-list/usage.mdx b/src/pages/components/contained-list/usage.mdx new file mode 100644 index 00000000000..8869fea0eb1 --- /dev/null +++ b/src/pages/components/contained-list/usage.mdx @@ -0,0 +1,274 @@ +--- +title: Contained list +description: + Contained lists group content that is similar or related and can contain + read-only or interactive information. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + + + +Contained lists group content that is similar or related and can contain +read-only or interactive information. + + + + + +Overview +Live demo +Formatting +Content +On page list +Disclosed list +Modifiers +Related +Feedback + + + +## Overview + +Contained lists are commonly used inside of containers like cards, sidebars, and +disclosure situations. These lists have one header column of information with +multiple list item rows. Contained lists help you organize related content +within smaller spaces within a user interface and allow you to include inline +actions and interactive elements. + + + + +![Contained list variants](images/contained-list-usage-1.png) + + + + +### When to use + +- Use on a page inside of small spaces or in disclosure situations. +- Use when including interactive elements or inline actions in a list. +- To logically group items that follow the same content structure. + +### When not to use + +- Do not use if the list content needs to be nested more than one level deep and + becomes overly complex and lengthy. For these situations, use the + [data table](https://carbondesignsystem.com/components/data-table/usage/) + component instead. +- Do not use if the list needs to contain multiple column headers, instead use + the + [structured list](https://carbondesignsystem.com/components/structured-list/usage/) + component. + +### Variants + +| Variant | Purpose | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [On page list](#on-page-list) | Use this variant when placing the list in a persistent context like the main area in the user interface, such as on a card or in a sidebar. | +| [Disclosed list](#disclosed-list) | Use this variant when the list is shown within a temporary context, for example within a popover or layer that is elevated by a drop shadow or border. | + +## Live demo + + + +**Coming soon:** The live demo for contained list is underdevelopment and will +be available soon. + + + +## Formatting + +### Anatomy + +Contained lists are made up of a list header, list title, list item rows, and +optional interactive elements. + + + + +![Contained list anatomy](images/contained-list-usage-2.png) + + + + +1. **List header:** Area to group the succeeding list items. +2. **List title:** Descriptive name for the group of list items. +3. **List item:** The content with in a list item row. +4. **Interactive element** (optional): An element that you can interact with or + treat as an inline action, such as links, icons, and toggles. + +### Sizing + +#### List header area + +The list header height is always fixed. The on page variant style list header +has a height of 48px. The disclosed variant style list header has a height of +32px. + + + + +![Contained list header height](images/contained-list-usage-3.png) + + + + +#### List item row + +List item row heights can vary based on the amount of content in each row. The +content in each row is flexible. By default, each list item row height is 48px +for one line of content. + + + + +![Contained list row height](images/contained-list-usage-4.png) + + + + +### Alignment + +Contained lists can have multiple sections and stack on top of each other. When +stacking multiple on page lists, there should be 16px padding ($spacing-05) +between each list. When stacking multiple disclosed lists, stack them to be +flush with 0px padding between each other. + + + + +![Contained list alignment](images/contained-list-usage-5.png) + + + + +### Scrolling + +Contained list header areas can be sticky and fixed in place while the list item +rows scroll underneath. This functionality is optional depending on the use +case. + + + + +![Contained list scrolling](images/contained-list-usage-6.png) + + + + +## Content + +### Main elements + +#### List title + +- A list title is a descriptive name for the group of list items. +- List titles should be short and clear, ranging from one to three words to + describe the list group. +- Use sentence-case capitalization. + +#### List item + +- List item text can vary but the structure of the content should be similar per + row in the same contained list. +- List item text can have multiple lines of concise content, but should not + contain multiple paragraphs of lengthy information. +- Use sentence-case capitalization. + +## On page list + +Use the on page list variant when placing the list on the general page of a user +interface. On page lists typically appear in smaller spaces, like in a card or +sidebars. The on page list styling has no visible background header with fixed +information. If there are scrolling capabitlies, the header will remain sticky +and have a background layer to differentiate it from the list item rows +scrolling beneath it. + +### Placement + +On page lists should span the entire width of the container they are placed +within to make the best use of space and to achieve vertical type alignment with +other text and components on the page. + + + + +![Contained list on page variant in context image](images/contained-list-usage-7.png) + + + + +## Disclosed list + +Use the disclosed list variant when placing the list within a temporary context, +like a popover or disclosure, which is typically accompanied by an enclosed +border or drop shadow. The disclosed list styling has a background layer +underneath the header. Each header has a smaller height than the on page list +styling to take up less real estate in the smaller and scrollable spaces it +usually appears in. + +### Placement + +Disclosed lists should span the entire width of the container they are placed +within to make the best use of space. + + + + +![Contained list disclosed variant in context image](images/contained-list-usage-8.png) + + + + +## Modifiers + +### Inline actions + +Contained lists can include inline actions, such as closing or dismissing row +items in the list. + + + + +![Contained list inline actions](images/contained-list-usage-9.png) + + + + +### Interactive elements + +Contained lists can have interactive elements in headers and rows, such as +links, icon buttons, and toggles. + + + + +![Contained list interactive elements](images/contained-list-usage-10.png) + + + + +### Clickable rows + +Contained lists support clickable rows as an optional feature. + + + + +![Contained list clickable rows](images/contained-list-usage-11.png) + + + + +## Related + +- [Accordion](https://carbondesignsystem.com/components/accordion/usage/) +- [Data table](https://carbondesignsystem.com/components/data-table/usage/) +- [List](https://carbondesignsystem.com/components/list/usage/) +- [Structured list](https://carbondesignsystem.com/components/structured-list/usage/) + +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).