From 71503e3d879a6584017d940400171f11f9f4da65 Mon Sep 17 00:00:00 2001 From: Erin Donehoo <105813956+edonehoo@users.noreply.github.com> Date: Wed, 27 Sep 2023 15:10:52 -0400 Subject: [PATCH] docs(usage-and-behavior): updates usage and behavior guidelines as part of content audit. (#3735) * docs(usage-and-behavior): updates usage and behavior guidelines as part of content audit. * Updates br line break tags. * Adjust page and title naming. * Spell check * Update packages/documentation-site/patternfly-docs/content/design-guidelines/usage-and-behavior/usage-and-behavior.md * Update usage-and-behavior.md --------- Co-authored-by: Margot <51165119+mmenestr@users.noreply.github.com> --- .../usage-and-behavior/usage-and-behavior.md | 174 ++++++++++-------- 1 file changed, 96 insertions(+), 78 deletions(-) diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/usage-and-behavior/usage-and-behavior.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/usage-and-behavior/usage-and-behavior.md index 257e958162..a0936eaabd 100644 --- a/packages/documentation-site/patternfly-docs/content/design-guidelines/usage-and-behavior/usage-and-behavior.md +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/usage-and-behavior/usage-and-behavior.md @@ -3,119 +3,137 @@ id: Usage and behavior section: design-foundations --- -As you design with PatternFly, you might encounter common use cases where multiple components apply. This page gives advice for which component to use in these situations and shares where to find more detailed usage guidelines. +# PatternFly component usage and behavior guidelines + +As you design with PatternFly, you might encounter common use cases where multiple components could be used. These guidelines outline which component to use in these situations and shares where to find more detailed usage guidelines. ## Displaying structured data -Structured data includes any information that is stored in a database or similar regular data structure. The most common ways of presenting structured data are to display it in either a list or a table where rows correspond to records in the database. PatternFly supports two controls for displaying this type of data: the [data list](/components/data-list) and the [table](/components/table). +Structured data includes any information that is stored in a database or similar regular data structure. Most commonly, structure data is displayed in either a list or a table, where rows correspond to records in the database. To display this type of content, we recommend using the **[data list](/components/data-list)** and the **[table](/components/table)** components. + +- Tables are built from a standard tabular structure of rows and columns. -Tables are built from a standard tabular structure of rows and columns. Data lists support any valid HTML layout inside of a row and therefore allow more formatting flexibility. +- Data lists support any valid HTML layout inside of a row, which enables more formatting flexibility. -| Use case | [Table](/components/table) | [Data list](/components/data-list) | -|------------------------ | :---: | :-------: | -|You want to display data in a grid with column headings | ✔ | ⛔ | -|Data does not easily fit into a grid or you want multiple lines of data in a row | ⛔ | ✔ | -| You want to display non-text information like images or charts | ✔ [1] | ✔ | -| All rows don’t have the same format | ⛔ | ✔ | +Your use case dictates which of these components you should use: -**[1]** Tables will support inclusion of graphical objects within a cell, but this approach is only recommended when small graphical or media objects are needed. +| **Use case** | **Recommended component** | +|----------| ---------- | +| You want to display data in a grid with column headings. | Table | +| Data does not easily fit into a grid or you want multiple lines of data in a row. | Data list | +| You want to display non-text information like images or charts. | Data list or table

**Note:** Tables support graphics within cells, but this approach is only recommended for use with small graphics. | +| All rows don’t have the same format. | Data list | ## Providing contextual help on a page -Contextual help can include any on-screen elements intended to guide the user in getting additional information to help them complete a task. Components for displaying contextual help on a page can include [tooltips](/components/tooltip), [popovers](/components/popover), and [hints](/components/hint). Tooltips display whenever the user hovers over an element. Popovers can be shown on hover or click, can contain any HTML content, and are persistent. Hints are static elements that appear inline with other content on a page. +Contextual help includes any on-screen elements intended to guide the user towards additional information that will help them complete a task. To display this type of content, we recommend using the **[tooltip](/components/tooltip)**, **[popover](/components/popover)**, and **[hint](/components/hint)** components. +- Tooltips are shown when users hover over an element. -| Use case |[Tooltip](/components/tooltip) | [Popover](/components/popover) | [Hint](/components/hint) | -|------------------------ | :---: | :-------: | :---------------: | -|You want to provide a short (no more than 1-2 lines) explanation of new or unfamiliar UI elements as a simple text string that is only shown “on-demand.”|✔|⛔ | ⛔ | -|You want to include formatted text and/or interactive elements in your message body.|⛔|✔|✔| -|You want the information to persist until the user dismisses it.|⛔|✔|✔| -|You want the information to be announced by a screen reader whenever the user tabs to an element.|✔|✔ [1]|✔| -|You want to present additional information that might not be necessary or relevant to all users.|⛔|✔|✔[2]| +- Popovers can be shown on hover or click, can contain any HTML content, and are persistent. -**[1]** By default, popovers are only triggered when the user clicks on an element and therefore will not be read by a screen reader when tabbing through an interface. If a popover is triggered on hover (optional behavior), it will behave like a tooltip and its content will be displayed whenever the keyboard user tabs to the trigger element. +- Hints are static elements that appear inline with other content on a page. -**[2]** Hint could be used to convey information to advanced users (“pro-tips,” for example). However because a hint adds static content directly to the page, consider whether it’s important for this information to be shown at all times. +Your use case dictates which of these components you should use: + +| **Use case** | **Recommended component** | +|------------------------ | -----------| +| You want to provide a short (no more than 1-2 lines) explanation of new or unfamiliar UI elements as a simple text string that is only shown “on-demand.” |Tooltip| +| You want to include formatted text and/or interactive elements in your message body. | Hint or popover | +| You want the information to persist until the user dismisses it. | Hint or popover | +|You want the information to be announced by a screen reader whenever the user tabs to an element.| Hint, popover, or tooltip

**Note:** By default, popovers are only triggered when the user clicks on an element. Therefore screen readers will not read popover text when tabbing through an interface. If a popover is triggered on hover (optional behavior), it will behave like a tooltip and its content will be announced whenever a keyboard user tabs to the trigger element. | +|You want to present additional information that might not be necessary or relevant to all users.| Hint or popover

**Note:** Hints can be used to convey information to advanced users (such as “pro-tips”). However, since a hint adds static content to a page, you should consider whether it’s important for this information to be shown at all times.| ## Progressive disclosure -Progressive disclosure is the practice of hiding information or providing it only when needed in order to simplify a user interface. PatternFly supports several components that can be used to progressively disclose information on a page. The [accordion](/components/accordion) component allows content to be placed in stackable, expandable containers so that content can be hidden from view to simplify presentation and reduce the need for scrolling. [Expandable sections](/components/expandable-section) allow designers to hide a single block of content or settings behind a show/hide link. [Expandable field groups](/components/forms/form) allow designers to group form elements into expandable containers. +Progressive disclosure is the practice of showing and hiding information as needed, in order to simplify a user interface. To progressively disclose content, we recommend using the **[accordion](/components/accordion)**, **[expandable sections](/components/expandable-section)**, and **[expandable field groups](/components/forms/form/#field-groups)**. -| Use case | [Accordion](/components/accordion) | [Expandable section](/components/expandable-section) | [Field groups](/components/forms/form)| -|---- | :----: | :----: | :----: | -|You want to group a list of actions, links, or other data into expandable groups.|✔|⛔|⛔| -|You want to hide advanced or seldomly used options within a form.|⛔|✔|✔| -|You want to give the user the ability to show or hide chunks of information on a long scrolling page.|⛔|✔|⛔ +- Accordions allow content to be placed in stackable, expandable containers so that content can be hidden from view to simplify presentation and reduce the need for scrolling. -## Inputting data on forms -Data input controls allow the user to input information into a form. There are two types of input controls for bound and unbound input. Bound input controls are constrained to only input data within a defined range. Examples of bound input controls include [sliders](/components/slider) and [number inputs](/components/number-input). Unbound controls do not enforce constraints on entry and include [text inputs](/components/forms/text-input) and [text area](/components/forms/text-area) controls. +- Expandable sections allow designers to hide a single block of content or settings behind a show/hide link. -| Use case | [Text input](/components/forms/text-input) or [text area](/components/forms/text-area) | [Number input](/components/number-input) | [Slider](/components/slider) | -|------------------------ | :----: | :----: | :----: | -|You want to enter text from the keyboard. Possible values are alpha-numeric, unconstrained, or dependent on context.|✔ [1]|⛔|⛔| -|You want to constrain the input of numeric data to a specified range.|✔ [2]|✔|✔| -|You want to optimize numeric data entry for direct manipulation by touch or using the mouse over the keyboard.|⛔|✔|✔| -|It’s useful for users to visualize where numeric input falls within the range of possible values.|⛔|⛔|✔| +- Expandable field groups allow designers to group form elements into expandable containers. -**[1]** If data will always be constrained to a single line, use a text input, otherwise use a text area component for multi-line input. +Your use case dictates which of these components you should use: -**[2]** It’s possible to use a standard text input for this use case and validate the entered value, but using either a number input or slider will be a more direct way to constrain the values that a user can input. +| **Use case** | **Recommended component** | +| ------------------------ | ----------- | +| You want to group a list of actions, links, or other data into expandable groups. | Accordion | +|You want to hide advanced or seldomly used options within a form.| Expandable section or field group | +|You want to give the user the ability to show or hide chunks of information on a long scrolling page.| Expandable section | -## Selecting between options on a form -Depending on the nature of options being presented, [checkbox](/components/forms/checkbox), [radio](/components/forms/radio), or [switch](/components/switch) components may be used. Checkboxes are used to select one or more items from a list of options. Radio buttons are used to select from a set of mutually exclusive options. Switches indicate the state of a binary setting or object — on or off, enabled or disabled. +## Inputting data within forms +Data input controls allow users to input information into a form. Input may be bound or unbound. Bound input controls only allow users to input data within a defined range, such as the **[slider](/components/slider)** and **[number input](/components/number-input)** components. Unbound controls do not enforce constraints, such as the **[text input](/components/forms/text-input)** and **[text area](/components/forms/text-area)** components. +Your use case dictates which of these components you should use: -| Use case | [Checkbox](/components/forms/checkbox) | [Radio](/components/forms/radio) | [Switch](/components/switch) | -|------------------------ | :---: | :-------: | :---------------: | -|The user wants to select one or more items from a list of items.|✔|⛔|✔ [1]| -|The user wants to select from a set of mutually exclusive options.|⛔|✔|⛔| -|The user wants to enable an option or feature.|✔ [2]|✔ [3]|✔| +| **Use case** | **Recommended component** | +|------------------------ | -----------| +|You want to enter text from the keyboard. Possible values are alpha-numeric, unconstrained, or dependent on context.| Text area or text input

**Note:** If data will always be constrained to a single line, use a text input. Use a text area component for multi-line input.| +|You want to constrain the input of numeric data to a specified range.|Number input, slider, text input, or text area

**Note:** You can use a standard text input for this use case and validate the entered value, but using a number input or slider will be a more direct way to constrain the values that a user can input. | +|You want to optimize numeric data entry for direct manipulation by touch or using the mouse over the keyboard.|Number input or slider| +|It’s useful for users to visualize where numeric input falls within the range of possible values.| Slider | +## Selecting between options on a form +There are a few components that you can use to allow users to select form options. Depending on the nature of options being presented, we recommend using the **[checkbox](/components/forms/checkbox)**, **[radio](/components/forms/radio)**, or **[switch](/components/switch)** components. -**[1]** Switches are sometimes used in place of checkboxes in this use case. The advantage of a switch is that it is more mobile friendly as it provides a larger touch target than the standard checkbox. - -**[2]** Checkboxes are often used to enable or disable (turn on or off) a feature in software. They provide a concise way to expose on/off settings while being less explicit than a switch. +- Checkboxes allow users to select one or more items from a list of options. -**[3]** You could use two radio buttons to support choosing between on/off or enabled/disabled options, however this approach uses more space and is not recommended unless it’s important to make both labeled options visible at the same time. +- Radio buttons allow users to select from a set of mutually exclusive options. -## Displaying progress -It’s important to display progress as a method of providing user feedback for operations that will take more than a few seconds. Use the [progress](/components/progress) component to provide feedback on the percentage of completion for a process or task. Use the [spinner](/components/spinner) and [skeleton](/components/skeleton) components to just indicate activity while the user is waiting for an action to complete. +- Switches indicate the state of a binary setting or object (such as on/off, enabled/disabled). -| Use case | [Progress](/components/progress) | [Spinner](/components/spinner) | [Skeleton](/components/skeleton) | -|------------------------ | :---: | :-------: | :---------------: | -| The user is waiting for a process to complete, but the time left until completion is not known.|⛔|✔|⛔| -|The user is waiting for a process to complete, but the time left until completion is known.|✔|✔ [1]|⛔| -|The user is progressing through a step-by-step task and you want to reflect where they are in the process.|✔|⛔|⛔| -|The user is waiting for a page to load.|✔ [2]|✔ [3]|✔| +Your use case dictates which of these components you should use: +| **Use case** | **Recommended component** | +|------------------------ | -----------| +|The user wants to select one or more items from a list of items. | Checkbox or switch

**Note:** Switches are sometimes used in place of checkboxes because they provide a larger touch target than a checkbox, which improves the mobile experience. | +| The user wants to select from a set of mutually exclusive options.| Radio | +|The user wants to enable an option or feature.| Checkbox, radio, or switch

**Note:** Checkboxes are often used to enable or disable software features, because they allow you to concisely display on/off settings.

**Note:** You can use 2 radio buttons to allow users to choose between options like on/off or enabled/disabled, however this approach uses more space and is only recommended when it’s important to make both labeled options visible at the same time.| -**[1]** Although a spinner could be used in this situation, using a progress component is always the preferred method when it is possible to estimate the time to completion or the percentage of the task that is done. +## Displaying progress +It’s important to display progress for action that will take more than a few seconds to complete. Use the **[progress](/components/progress)** component to show users the percentage of completion for a process or task. Use the **[spinner](/components/spinner)** and **[skeleton](/components/skeleton)** components to just simply indicate activity while the user is waiting for an action to complete. -**[2]** Progress bars are not typically used during page loading, but could be used together with skeleton loading if you want to provide the user with more information about time to completion. +Your use case dictates which of these components you should use: -**[3]** Spinners may be used to provide feedback on page loading when the shape of the data is not known. +| **Use case** | **Recommended component** | +|------------------------ | -----------| +| The user is waiting for a process to complete, but the time left until completion is not known.| Spinner | +|The user is waiting for a process to complete, but the time left until completion is known.| Progress or spinner

**Note:** A progress component is the preferred recommendation when it is possible to estimate the time to completion or the percentage of the task that is done.| +| The user is progressing through a step-by-step task and you want to reflect where they are in the process.| Progress | +|The user is waiting for a page to load.| Progress, skeleton, or spinner

**Note:** Progress bars are not typically used during page loading, but could be used with the skeleton component if you want to provide the user with more information about time to completion.

**Note:** Spinners may be used to provide feedback on page loading when the details of the data are not known. | ## Displaying object details in context -It is often necessary to display more details about an object listed in a summary view like a list or a table. This can be accomplished by drilling-down into a new page or presenting details on the same page (in context). Three approaches can be used for in-context presentation of object details. Both the [data list](/components/data-list) and [table](/components/table) components support expandable rows for displaying object details directly in the list or table. The [drawer](/components/drawer) component can also be used to create a side-by-side primary-detail view. [Popovers](/components/popover) can also be useful for displaying details about an object in a list or table. +It is often necessary to display more details about an object listed in a summary view, such as a list or a table. This can be accomplished by drilling-down into a new page or presenting contextual details on the same page. To take these approaches, we recommend using the **[data list](/components/data-list)**, **[drawer](/components/drawer)**, **[table](/components/table)**, and **[popovers](/components/popover)** components. + +- Data lists and tables support expandable rows for displaying object details directly in the list or table. -|Use case | [Data list](/components/data-list) or [table](/components/table) row expansion | [Drawer](/components/drawer)| [Popover](/components/popover) | -|------------------------ | :---: | :-------: | :---------------: | -|You want to view details of multiple objects at the same time for comparison.|✔|⛔|⛔| -|Your detailed data is best presented in a horizontal format.|✔|✔ [1]|✔| -|Your detailed data is best presented in a vertical format.|⛔|✔|✔| -|You have only a small amount of detailed data to show.|✔ [2]|✔|✔| -|You don’t want to cover other information while displaying details.|✔|✔ [3]|⛔| +- Drawers can be used to create a side-by-side primary-detail view. -**[1]** Drawers can be attached to either the left, right, or bottom edge of the parent container. To present horizontal data, use a bottom/horizontal drawer to create a top-bottom primary-detail view. +- Popovers can be used to display details about an object in a list or table. -**[2]** Row expansions and drawers can accommodate any amount of information. Showing a small amount of data within a row expansion or drawer may waste space because each presentation type will consume the full width or height of its parent container. Popovers will adjust to the size and shape of their contents. +Your use case dictates which of these components you should use: -**[3]** Both inline and overlay drawers are available. If you don’t want to cover content on a page, we recommend the [inline drawer](/components/drawer#basic-inline) variation. +| **Use case** | **Recommended component** | +|------------------------ | -----------| +|You want to view details of multiple objects at the same time for comparison.| Data list or expandable table row | +|Your detailed data is best presented in a horizontal format.| Data list, drawer, expandable table row, or popover

**Note:** Drawers can be attached to either the left, right, or bottom edge of the parent container. To present horizontal data, use a bottom/horizontal drawer to create a top-bottom primary-detail view.| +|Your detailed data is best presented in a vertical format.| Drawer or popover| +|You have only a small amount of detailed data to show.|Data list, drawer, expandable table row, or popover

**Note:** Row expansions and drawers can accommodate any amount of information. Showing a small amount of data within a row expansion or drawer may waste space because each presentation type will consume the full width or height of its parent container. Popovers will adjust to the size and shape of their contents.| +|You don’t want to cover other information while displaying details.|Data list, drawer, or expandable table row

**Note:** Both inline and overlay drawers are available. If you don’t want to cover content on a page, we recommend the [inline drawer](/components/drawer#basic-inline) variation. | ## Dropdown menus for actions and selections -PatternFly provides three types of dropdown components for selecting between items in a menu. The [select](/components/menus/select) component is used to select one or more values from a list. The [options menu](/components/menus/options-menu) is similar to a select but is more often used for selecting between optional settings. [Dropdowns](/components/menus/dropdown) are used to expose a list of possible actions. - -| Use case | [Select](/components/menus/select) | [Options menu](/components/menus/options-menu) | [Dropdown](/components/menus/dropdown) | -|------------------------ | :---: | :-------: | :---------------: | -|You want to select a value or multiple values from a list.|✔|⛔|⛔| -|You want to select filter terms from a list.|✔|⛔|⛔| -|You want to make the selected value visible when the menu is closed.|✔|⛔|⛔| -|You want to select options from one or more lists (sorting options, for example).|⛔|✔|⛔| -|You want to expose a list of commands or actions in a limited space.|⛔|⛔|✔| +To allow users to select between items in a menu, we recommend using the **[select](/components/menus/select)**, **[options](/components/menus/options-menu)**, or **[dropdown](/components/menus/dropdown)** menu components. + +- Select menus allow users to select one or more values from a list. + +- Options menus are similar to a select, but are more appropriate when users make selections from optional settings. + +- Dropdown menus allow you to expose a list of possible actions. + +Your use case dictates which of these components you should use: + +| **Use case** | **Recommended component** | +|------------------------ | -----------| +|You want to select a value or multiple values from a list.| Select | +|You want to select filter terms from a list.| Select | +|You want to make the selected value visible when the menu is closed.| Select | +|You want to select options from one or more lists (sorting options, for example).| Options menu | +|You want to expose a list of commands or actions in a limited space.| Dropdown |