diff --git a/src/pages/components/accordion/usage.mdx b/src/pages/components/accordion/usage.mdx index cfdabbb03c6..9b3fb226cfc 100755 --- a/src/pages/components/accordion/usage.mdx +++ b/src/pages/components/accordion/usage.mdx @@ -22,7 +22,6 @@ associated sections of content. Formatting Content Behaviors -Modifiers Related References Feedback @@ -47,14 +46,12 @@ associated sections of content. ## Overview The accordion component delivers large amounts of content in a small space -through progressive disclosure. The header title give the user a high level +through progressive disclosure. The header title gives the user a high level overview of the content allowing the user to decide which sections to read. Accordions can make information processing and discovering more effective. However, it does hide content from users and it's important to account for a -user not noticing or reading all of the included content. If a user is likely to -read all of the content then don't use an accordion as it adds the burden of an -extra click; instead use a full scrolling page with normal headers. +user not noticing or reading all of the included content. ### When to use @@ -64,6 +61,14 @@ extra click; instead use a full scrolling page with normal headers. - When space is at a premium and long content cannot be displayed all at once, like on a mobile interface or in a side panel. +### When not to use + +- When organizing large amounts of information that can be nested, consider + using [tree view](/components/tree-view/usage) instead. +- If a user is likely to read all of the content, then don't use an accordion as + it adds the burden of an extra click; instead use a full scrolling page with + normal headers. + ## Formatting ### Anatomy @@ -83,6 +88,35 @@ extra click; instead use a full scrolling page with normal headers. ### Alignment +#### Flush alignment + +Use flush alignment when designing within smaller spaces on a page such as side +panels or sidebars to achieve better text alignment with other content. Flush +alignment is also used to help avoid converging rule lines between components +that are close to each other on a page. + + + + +![accordion flush alignment](images/accordion-flush.png) + + + + +Flush alignment places the row title and chevron icons with 0px padding, keeping +them flush to the rule dividers. For hover and focus interactive states, the +left and right padding receives an additional 16px padding. + + + + +![accordion flush alignment spec](images/accordion-flush-spec.png) + + + + +#### Icon alignment + By default the chevron icon is placed on the `end` side of the header. This allows for the title on the `start` side to align with other type elements in the layout, which is the preferred alignment scenario. @@ -136,9 +170,9 @@ such as a side panel or tile. When placing an accordion on the 2x Grid with its default alignment, the indented title and content align to the grid columns, and the top and bottom borders hang into the gutter. However, the accordion can be modified to have a -[flush alignment](https://carbondesignsystem.com/components/accordion/usage#modifiers) -where the titles and content are instead flush aligned with the top and bottom -borders having 0px padding. +[flush alignment](/components/accordion/usage#alignment) where the titles and +content are instead flush aligned with the top and bottom borders having 0px +padding. @@ -171,6 +205,11 @@ When the accordion content is longer than the viewport the whole accordion should vertically scroll. Content should not scroll inside of an individual panel. Content should never scroll horizontally in an accordion. +### Further guidance + +For further content guidance, see Carbon's +[content guidelines](<[https://www.carbondesignsystem.com/guidelines/content/general](https://www.carbondesignsystem.com/guidelines/content/general)>). + ## Behaviors ### States @@ -236,35 +275,6 @@ Users can trigger a state change by pressing `Enter` or `Space` while the header area has focus. For additional keyboard interactions, see the [accessibility tab](/components/accordion/accessibility#keyboard-interactions). -## Modifiers - -#### Flush alignment - -Use flush alignment when designing within smaller spaces on a page such as side -panels or sidebars to achieve better text alignment with other content. Flush -alignment is also used to help avoid converging rule lines between components -that are close to each other on a page. - - - - -![accordion flush alignment](images/accordion-flush.png) - - - - -Flush alignment places the row title and chevron icons with 0px padding, keeping -them flush to the rule dividers. For hover and focus interactive states, the -left and right padding receives an additional 16px padding. - - - - -![accordion flush alignment spec](images/accordion-flush-spec.png) - - - - ## Related The following components are additional ways to organize content. Consider the @@ -272,11 +282,17 @@ type and length of content you are working with when choosing a content container. Longer form content may benefit from tabs or a content switcher while very short content might do better in a structured list. -- [Content switcher](/components/content-switcher/usage) -- [Progress indicator](/components/progress-indicator/usage) -- [Structured list](/components/structured-list/usage) -- [Tabs](/components/tabs/usage) -- [Tree view](/components/tree-view/usage) +- [Content switchers](/components/content-switcher/usage) allow users to toggle + between two or more content sections within the same space on the screen. +- [Progress indicators](/components/progress-indicator/usage) guide users + through any linear, multistep task by showing the user their completed, + current, and future steps. +- [Structured lists](/components/structured-list/usage) group content that is + similar or related, such as terms and definitions. +- [Tabs](/components/tabs/usage) organize related content by allowing the user + to navigate between groups of information that appear within the same context. +- [Tree view](/components/tree-view/usage) is a hierarchical structure that + provides nested levels of navigation. ## References diff --git a/src/pages/components/content-switcher/usage.mdx b/src/pages/components/content-switcher/usage.mdx index 1be642bc8d0..b9e5ed411bd 100755 --- a/src/pages/components/content-switcher/usage.mdx +++ b/src/pages/components/content-switcher/usage.mdx @@ -22,7 +22,7 @@ within the same space on the screen. Formatting Content Behaviors -Modifier +Modifiers Related References Feedback @@ -366,7 +366,7 @@ The content tab is clickable anywhere within the container. Text and icon content switchers with their clickable areas -## Modifier +## Modifiers ### Content switcher with icons diff --git a/src/pages/contributing/documentation.mdx b/src/pages/contributing/documentation.mdx index 519559768b9..a2eb6828292 100644 --- a/src/pages/contributing/documentation.mdx +++ b/src/pages/contributing/documentation.mdx @@ -14,6 +14,8 @@ All components and patterns require usage, style, code, and accessibility guidance on the Carbon website. Check out the markdown templates and instructions below to contribute documentation smoothly. + + @@ -33,31 +35,41 @@ templates: usage, style, code, and accessibility. Check out Carbon's handy markdown [styling cheatsheet](https://github.com/carbon-design-system/carbon-website/wiki/Markdown-cheatsheet) -for how to style content. +for how to style content. You may also use the +[Figma template](https://www.figma.com/file/XQqHxu38CiY3Vx1iHdafIa/Image-production-guidelines?type=design&node-id=2651-218&mode=design&t=UbKwOlVeoU83hyGI-0) +to draft content and images ### Usage template: for components with one variant -The usage template helps describe when to use a component and how it works. You -can see this template in use for components with only one variant: -[Accordion](/components/accordion/usage) and -[Checkbox](/components/checkbox/usage). +The usage template helps describe when to use a component and how it works. The +template below provides example content from the +[Accordion](/components/accordion/usage) usage tab, along with many tips on best +ways to compose content and images. Check out +[Content switcher](/components/content-switcher/usage) or +[Checkbox](/components/checkbox/usage) for additional single variant references. ```markdown --- -title: Component name -description: Explains what the component is in one or two sentences. +title: Accordion +description: + An accordion is a vertically stacked list of headers that reveal or hide + associated sections of content. tabs: ['Usage', 'Style', 'Code', 'Accessibility'] --- - +import A11yStatus from 'components/A11yStatus'; - + + + +An accordion is a vertically stacked list of headers that reveal or hide +associated sections of content. -Overview Live demo +Live demo Overview Formatting Content Behaviors Modifiers Related References @@ -65,47 +77,86 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +## Live demo + + + + + + + + + ## Overview - -Example: +The accordion component delivers large amounts of content in a small space +through progressive disclosure. The header title gives the user a high level +overview of the content allowing the user to decide which sections to read. -*The accordion component delivers large amounts of content in a small space through progressive disclosure. The header title give the user a high level overview of the content allowing the user to decide which sections to read.* ---> +Accordions can make information processing and discovering more effective. +However, it does hide content from users and it's important to account for a +user not noticing or reading all of the included content. -### When to use + - + + -### When not to use (optional) +### When to use - -*It is best practice not to use a dropdown if there are two or fewer options to choose from. In this case, use a radio button group instead.* ---> +- To organize related information. +- To shorten pages and reduce scrolling when content is not crucial to read in + full. +- When space is at a premium and long content cannot be displayed all at once, + like on a mobile interface or in a side panel. -## Live demo + ### When not to use + + - +- When organizing large amounts of information that can be nested, consider + using [tree view](/components/tree-view/usage) instead. +- If a user is likely to read all of the content, then don't use an accordion as + it adds the burden of an extra click; instead use a full scrolling page with + normal headers. ## Formatting ### Anatomy - +See [Notification](https://www.carbondesignsystem.com/components/notification/usage#anatomy) for an additional example.--> + + + + +![accordion anatomy](images/accordion-anatomy.png) + + + + +1. **Header**: contains the section title and is control for revealing the + panel. +2. **Icon**: indicates if the panel is open or closed. +3. **Panel**: the section of content associated with an accordion header. ### Sizing (optional) @@ -119,33 +170,121 @@ Example: ### Alignment (optional) -We have some alignment content in the Structure section of the Style tab, so consider the relationship between the two tabs and include a cross-reference if necessary. +#### Flush alignment -Example: +Use flush alignment when designing within smaller spaces on a page such as side +panels or sidebars to achieve better text alignment with other content. Flush +alignment is also used to help avoid converging rule lines between components +that are close to each other on a page. -*Inside of a modal, body copy, including titles, have a 20% margin-right. However, form inputs and other components expand the full width of a modal window.* ---> + + + +![accordion flush alignment](images/accordion-flush.png) + + + + +Flush alignment places the row title and chevron icons with 0px padding, keeping +them flush to the rule dividers. For hover and focus interactive states, the +left and right padding receives an additional 16px padding. + + + + +![accordion flush alignment spec](images/accordion-flush-spec.png) + + + + +#### Icon alignment + +By default the chevron icon is placed on the `end` side of the header. This +allows for the title on the `start` side to align with other type elements in +the layout, which is the preferred alignment scenario. + +However, in some rare scenarios, the accordion may be modified to place the icon +in `start` front of the title to function more like a tree. Most instances +should use the default `end` alignment, especially for any pure content or +documentation purposes. Icon placement in accordions should be consistent +throughout your page and should not alternate. + + + + + + +![Do use the default end icon alignment to keep accordion text aligned with other content on the page.](./images/accordion-alignment-do.png) + + + + +![Do place icons on the start side for tree like functionality.](./images/accordion-alignment-do-2.png) + + + ### Placement -You may want to include a link here to the Structure section of the Style tab. +Accordions can be placed with main page content or placed inside of a container +such as a side panel or tile. -Example: + +Tips: +- Create simplified illustrations of placement examples using the illustration library. +- Try for 1, 2, or 4 examples. If you only have 3 examples, keep the images on a 2x2 grid and leave the 4th quadrant empty.--> + + + + + +![accordion placement](images/accordion-placement-2m.png) + +![accordion placement](images/accordion-placement-2.png) + +![accordion placement](images/accordion-placement-2.png) + + + + + + + +#### Grid placement + +When placing an accordion on the 2x Grid with its default alignment, the +indented title and content align to the grid columns, and the top and bottom +borders hang into the gutter. However, the accordion can be modified to have a +[flush alignment](https://carbondesignsystem.com/components/accordion/usage#alignment) +where the titles and content are instead flush aligned with the top and bottom +borders having 0px padding. + + + + +![accordion grid placement](images/accordion-placement-1.png) + + + ## Content @@ -156,43 +295,122 @@ Identify the content elements within the component, for example, title, label, p Briefly explain any particular rules such as phrase structure, word limits, and character limits. Where there's more than one rule, use bullets to list out the multiple rules for ease of reading. If necessary, refer out to main content guidelines for more detailed information, for example, capitalization, or recommended action labels. -See [Checkbox](https://www.carbondesignsystem.com/components/checkbox/usage#content) and [Modal](https://www.carbondesignsystem.com/components/modal/usage#content) for examples. +See [Checkbox](https://www.carbondesignsystem.com/components/checkbox/usage#content) and [Modal](https://www.carbondesignsystem.com/components/modal/usage#content) for additional examples. --> -### Overflow content +#### Label - +- Content inside of a section may be split into paragraphs and include + sub-headers if needed. + +### Overflow content + + + +When the accordion content is longer than the viewport the whole accordion +should vertically scroll. Content should not scroll inside of an individual +panel. Content should never scroll horizontally in an accordion. ### Further guidance - + + +For further content guidance, see Carbon's +[content guidelines](<[https://www.carbondesignsystem.com/guidelines/content/general](https://www.carbondesignsystem.com/guidelines/content/general)>). ## Behaviors - +### States + + +The accordion component has two main states: **collapsed** and **expanded**. The +chevron icon at the end of the accordion indicates which state the accordion is +in. The chevron points down to indicate collapsed and up to indicate expanded. + +Accordions begin by default in the collapsed state with all content panels +closed. Starting in a collapsed state gives the user a high level overview of +the available information. + + + + +![accordion states](images/accordion-state-1.png) + + + + +A user can then independently expand each section of the accordion allowing for +multiple sections to be open at once. + + + + +![multiple sections expanded](images/accordion-state-2.png) + + + + +In addition to the collapsed and expanded states, accordions also have +interactive states for focus, hover, and disabled. See the +[style tab](/components/accordion/style) for more details. + + + + +![accordion interactives states](images/accordion-state-3.png) + + + + ### Interactions +#### Mouse + +Users can trigger a state change by clicking on the chevron or clicking anywhere +in the header area. + + + + +![accordion click targets](images/accordion-click-target.png) + + + + +#### Keyboard + +Users can navigate between accordion headers by pressing `Tab` or `Shift-Tab`. +Users can trigger a state change by pressing `Enter` or `Space` while the header +area has focus. For additional keyboard interactions, see the +[accessibility tab](/components/accordion/accessibility#keyboard-interactions). + ### Validation -## Modifiers +## Modifiers (optional) +### Content switcher with icons + +Use icons instead of label text to indicate alternative views of similar or +related content. Icon content switchers are often used when space is limited or +when icons can adequately describe the sections (for example, a list view versus +a card view). + + + + +![Example shows the content switcher with icons only](images/content-switcher-icon.png) + + + + + + + +![Do use consistent icon or text content tabs](images/content-switcher-usage-modifier-do.png) + + + + +![Do not mix icon and text content tabs](images/content-switcher-usage-modifier-dont.png) + + + + ## Related +The following components are additional ways to organize content. Consider the +type and length of content you are working with when choosing a content +container. Longer form content may benefit from tabs or a content switcher while +very short content might do better in a structured list. + +- [Content switchers](/components/content-switcher/usage) allow users to toggle + between two or more content sections within the same space on the screen. +- [Progress indicators](/components/progress-indicator/usage) guide users + through any linear, multistep task by showing the user their completed, + current, and future steps. +- [Structured lists](/components/structured-list/usage) group content that is + similar or related, such as terms and definitions. +- [Tabs](/components/tabs/usage) organize related content by allowing the user + to navigate between groups of information that appear within the same context. +- [Tree view](/components/tree-view/usage) is a hierarchical structure that + provides nested levels of navigation. + ## References +- Hoa Loranger, + [Accordions Are Not Always the Answer for Complex Content on Desktops](https://www.nngroup.com/articles/accordions-complex-content/) + (Nielsen Norman Group, 2014) + ## Feedback - + Help us improve this component by providing feedback, asking questions, and leaving any other comments on