diff --git a/src/pages/components/loading/usage.mdx b/src/pages/components/loading/usage.mdx index c51b1129cbf..4218b8df91c 100755 --- a/src/pages/components/loading/usage.mdx +++ b/src/pages/components/loading/usage.mdx @@ -13,11 +13,20 @@ Loading spinners are used when retrieving data or performing slow computations, Overview -Size +Live demo +Formatting Feedback +## Overview + +Loading spinners are used when retrieving data or performing slow computations. They notify to the user that their request is being processed. Although they do not provide details about what is occurring on the back-end, they reassure the user that their action is being processed. + +It is best practice to use a loading spinner whenever the wait time is anticipated to be longer than three seconds. + +## Live demo + -## Overview - -Loading spinners are used when retrieving data or performing slow computations. They notify to the user that their request is being processed. Although they do not provide details about what is occurring on the back-end, they reassure the user that their action is being processed. - -It is best practice to use a loading spinner whenever the wait time is anticipated to be longer than three seconds. - -## Size +## Formatting Loading spinners may be scaled down if the loading experience is contextual to a certain item on the page. diff --git a/src/pages/components/modal/usage.mdx b/src/pages/components/modal/usage.mdx index b5fe0177b45..dc64f66ed9a 100755 --- a/src/pages/components/modal/usage.mdx +++ b/src/pages/components/modal/usage.mdx @@ -13,6 +13,7 @@ Modals focus the user’s attention exclusively on one task or piece of informat Overview +Live demo Formatting Content Behaviors @@ -22,6 +23,38 @@ Modals focus the user’s attention exclusively on one task or piece of informat +## Overview + +Modals are a type of [dialog](/patterns/dialog-pattern) that are used to present critical information or request user input needed to complete a user’s workflow. Modals interrupt a user’s workflow by design. When active, a user is blocked from the on-page content and cannot return to their previous workflow until the modal task is completed or the user dismisses the modal. While effective when used correctly, modals should be used sparingly to limit disruption to the user. + +Modal dialogs are commonly used for short and non-frequent tasks, such as editing or management tasks. If a user needs to repeatably preform a task, consider making the task do-able from the main page. + +### When to use + +#### An immediate response is required from the user + +Use a dialog to request information that is preventing the system from continuing a user-initiated process. + +#### Notify the user of urgent information + +Use a modal dialog to notify the user of urgent information concerning their current work. Commonly used to report system errors or convey a consequence of a user’s action. + +#### Confirm a user decision + +Use a modal dialog to confirm user decisions. Clearly describe the action being confirmed and explain any potential consequences that it may cause. Both the title and the button should reflect the action that will occur. If the action is destructive or irreversible then use a transactional danger modal. + +### Types + +| Type | Usage | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| [Passive](/components/modal/usage#passive-modal) | Presents information the user needs to be aware of concerning their current workflow. Contains no actions for the user to take. | +| [Transactional](/components/modal/usage#transactional-modal) | Requires an action to be taken in order for the modal to be completed and closed. Contains a cancel and primary action buttons. | +| [Danger](/components/modal/usage#danger-modal) | A specific type of transactional modal used for destructive or irreversible actions. | +| [Acknowledgment](/components/modal/usage#acknowledgment-modal) | System requires an acknowledgement of the information from the user. Contains only a single button, commonly "OK." | +| [Progress](/components/modal/usage#progress-modal) | Requires several steps to be completed before it can be closed. Contains a cancel, previous, and next/completion buttons. | + +## Live demo + -## Overview - -Modals are a type of [dialog](/patterns/dialog-pattern) that are used to present critical information or request user input needed to complete a user’s workflow. Modals interrupt a user’s workflow by design. When active, a user is blocked from the on-page content and cannot return to their previous workflow until the modal task is completed or the user dismisses the modal. While effective when used correctly, modals should be used sparingly to limit disruption to the user. - -Modal dialogs are commonly used for short and non-frequent tasks, such as editing or management tasks. If a user needs to repeatably preform a task, consider making the task do-able from the main page. - -### When to use - -#### An immediate response is required from the user - -Use a dialog to request information that is preventing the system from continuing a user-initiated process. - -#### Notify the user of urgent information - -Use a modal dialog to notify the user of urgent information concerning their current work. Commonly used to report system errors or convey a consequence of a user’s action. - -#### Confirm a user decision - -Use a modal dialog to confirm user decisions. Clearly describe the action being confirmed and explain any potential consequences that it may cause. Both the title and the button should reflect the action that will occur. If the action is destructive or irreversible then use a transactional danger modal. - -### Types - -| Type | Usage | -| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| [Passive](/components/modal/usage#passive-modal) | Presents information the user needs to be aware of concerning their current workflow. Contains no actions for the user to take. | -| [Transactional](/components/modal/usage#transactional-modal) | Requires an action to be taken in order for the modal to be completed and closed. Contains a cancel and primary action buttons. | -| [Danger](/components/modal/usage#danger-modal) | A specific type of transactional modal used for destructive or irreversible actions. | -| [Acknowledgment](/components/modal/usage#acknowledgment-modal) | System requires an acknowledgement of the information from the user. Contains only a single button, commonly "OK." | -| [Progress](/components/modal/usage#progress-modal) | Requires several steps to be completed before it can be closed. Contains a cancel, previous, and next/completion buttons. | - ## Formatting ### Anatomy diff --git a/src/pages/components/notification/usage.mdx b/src/pages/components/notification/usage.mdx index c98a1340d0d..d54e9b446b3 100755 --- a/src/pages/components/notification/usage.mdx +++ b/src/pages/components/notification/usage.mdx @@ -13,6 +13,7 @@ Notifications are messages that communicate information to the user. The two mai Overview +Live demo Formatting Content Inline notifications @@ -23,6 +24,23 @@ Notifications are messages that communicate information to the user. The two mai +## Overview + +### When to use + +Use notifications to inform users of updates or changes to system status. Communicating with users and providing immediate feedback are important for building trust. While notifications are an effective method of communicating with users, they are disruptive and should be used sparingly. + +For more context on when to use each notification type, including modals, refer to the [notifications pattern](/patterns/notification-pattern/). Carbon currently only supports inline, toast, and modal notification types, although some product teams also support banners and notification centers. + +### Types + +| Type | Purpose | +| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Inline](#inline-notifications) | Inline notifications show up in task flows, to notify users of the status of an action. They usually appear at the top of the primary content area. | +| [Toast](#toast-notifications) | Toasts are non-modal, time-based window elements used to display short messages; they usually appear at the top of the screen and disappear after a few seconds. | + +## Live demo + -## Overview - -### When to use - -Use notifications to inform users of updates or changes to system status. Communicating with users and providing immediate feedback are important for building trust. While notifications are an effective method of communicating with users, they are disruptive and should be used sparingly. - -For more context on when to use each notification type, including modals, refer to the [notifications pattern](/patterns/notification-pattern/). Carbon currently only supports inline, toast, and modal notification types, although some product teams also support banners and notification centers. - -### Types - -| Type | Purpose | -| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Inline](#inline-notifications) | Inline notifications show up in task flows, to notify users of the status of an action. They usually appear at the top of the primary content area. | -| [Toast](#toast-notifications) | Toasts are non-modal, time-based window elements used to display short messages; they usually appear at the top of the screen and disappear after a few seconds. | - ## Formatting ### Anatomy diff --git a/src/pages/components/number-input/usage.mdx b/src/pages/components/number-input/usage.mdx index 92ff0195bc8..2811898a72c 100755 --- a/src/pages/components/number-input/usage.mdx +++ b/src/pages/components/number-input/usage.mdx @@ -13,11 +13,18 @@ The number input component is used for entering numeric values and includes cont Overview +Live demo Formatting Feedback +## Overview + +Number inputs are similar to text inputs, but contain controls used to increase or decrease an incremental value. + +## Live demo + -## Overview - -_Number inputs_ are similar to text inputs, but contain controls used to increase or decrease an incremental value. - ## Formatting - Do not use number inputs when large value changes are expected. They work best for making small, incremental changes that require only a few clicks. diff --git a/src/pages/components/overflow-menu/usage.mdx b/src/pages/components/overflow-menu/usage.mdx index 16c94130d0a..a4a46079c48 100755 --- a/src/pages/components/overflow-menu/usage.mdx +++ b/src/pages/components/overflow-menu/usage.mdx @@ -13,11 +13,18 @@ Use the overflow menu component when additional options are available to the use Overview +Live demo Formatting Feedback +## Overview + +Overflow menu is used when additional options are available to the user and there is a space constraint. + +## Live demo + -## Overview - -Overflow menu is used when additional options are available to the user and there is a space constraint. - ## Formatting #### Text diff --git a/src/pages/components/pagination/usage.mdx b/src/pages/components/pagination/usage.mdx index 9080503a455..1dbfc5c0677 100755 --- a/src/pages/components/pagination/usage.mdx +++ b/src/pages/components/pagination/usage.mdx @@ -13,11 +13,20 @@ Pagination is used for splitting up content or data into several pages, with a c Overview +Live demo Best practices Feedback +## Overview + +Generally, pagination is used if there are more than 25 items displayed in one view. + +The default number displayed will vary depending on the context. + +## Live demo + -## Overview - -Generally, pagination is used if there are more than 25 items displayed in one view. - -The default number displayed will vary depending on the context. - ## Best practices #### Identify the current page diff --git a/src/pages/components/progress-indicator/usage.mdx b/src/pages/components/progress-indicator/usage.mdx index 526fb9ee4b8..b8a141fc5b9 100755 --- a/src/pages/components/progress-indicator/usage.mdx +++ b/src/pages/components/progress-indicator/usage.mdx @@ -13,11 +13,18 @@ A progress indicator is a visual representation of a user's progress through a s Overview +Live demo Best practices Feedback +## Overview + +Use progress indicators to keep the user on track when completing a specific task. By dividing the end goal into smaller, sub-tasks, it increases the percentage of completeness as each task is completed. + +## Live demo + -## Overview - -Use progress indicators to keep the user on track when completing a specific task. By dividing the end goal into smaller, sub-tasks, it increases the percentage of completeness as each task is completed. - ## Best practices #### Logical progression diff --git a/src/pages/components/radio-button/usage.mdx b/src/pages/components/radio-button/usage.mdx index e8264e664cb..26931169a93 100755 --- a/src/pages/components/radio-button/usage.mdx +++ b/src/pages/components/radio-button/usage.mdx @@ -13,12 +13,19 @@ Use radio buttons when you have a group of mutually exclusive choices and only o Overview +Live demo Format Default selection Feedback +## Overview + +Radio buttons represent a group of mutually exclusive choices, compared to checkboxes that allow users to make one or more selections from a group. In use cases where only one selection of a group is allowed, use the radio button component instead of the checkbox. + +## Live demo + -## Overview - -Radio buttons represent a group of mutually exclusive choices, compared to checkboxes that allow users to make one or more selections from a group. In use cases where only one selection of a group is allowed, use the radio button component instead of the checkbox. - ## Format #### Headings diff --git a/src/pages/components/search/usage.mdx b/src/pages/components/search/usage.mdx index a656cb6f3ab..976816e4658 100755 --- a/src/pages/components/search/usage.mdx +++ b/src/pages/components/search/usage.mdx @@ -13,12 +13,19 @@ Search enables users to specify a word or a phrase to find relevant pieces of co Overview +Live demo Variations Formatting Feedback +## Overview + +Search offers users a way to explore a website or application using keywords. Search can be used as the primary means of discovering content, or as a filter to aid the user in finding content. + +## Live demo + -## Overview - -Search offers users a way to explore a website or application using keywords. Search can be used as the primary means of discovering content, or as a filter to aid the user in finding content. - ## Variations | Search type | Purpose | diff --git a/src/pages/components/select/usage.mdx b/src/pages/components/select/usage.mdx index f2ed9c186d7..9756c71816b 100755 --- a/src/pages/components/select/usage.mdx +++ b/src/pages/components/select/usage.mdx @@ -13,13 +13,29 @@ The select component allows users to choose one option from a list. It is used i Overview +Live demo Variations -Other guidelines +Best practices Accessibility Feedback +## Overview + +Select is a type of input that is used in forms, where a user is submitting data and chooses one option from a list. + +### Select versus Dropdown + +While the select and dropdown components look similar, they have different functions. + +- Use the select component inside a form where users are selecting from a list of options and submitting data. +- Use the dropdown component to filter or sort content on a page. + +Another important difference between the two components is the underlying code. The select component's appearance will be determined by the browser being used, while the dropdown component can be styled as needed. + +## Live demo + -## Overview - -Select is a type of input that is used in forms, where a user is submitting data and chooses one option from a list. - -### Select versus Dropdown - -While the select and dropdown components look similar, they have different functions. - -- Use the select component inside a form where users are selecting from a list of options and submitting data. -- Use the dropdown component to filter or sort content on a page. - -Another important difference between the two components is the underlying code. The select component's appearance will be determined by the browser being used, while the dropdown component can be styled as needed. - ## Variations | Select type | Purpose | @@ -129,7 +132,7 @@ Inline select is useful when you have multiple select fields within a form. Inli -## Other guidelines +## Best practices ### Labels diff --git a/src/pages/components/slider/usage.mdx b/src/pages/components/slider/usage.mdx index c8a0306d049..3ba1bc4aa62 100755 --- a/src/pages/components/slider/usage.mdx +++ b/src/pages/components/slider/usage.mdx @@ -13,12 +13,39 @@ Sliders provide a visual indication of adjustable content, where the user can in Overview +Live demo Interactions Best practices Feedback +## Overview + +The slider in its basic form should be accompanied by a label and a number input that doubles as a display for the slider's current value. + +The basic slider does **not** include discrete values, as the slider represents a percentage of 0-100. In this case it is not necessary for a user to choose a specific value, but instead generally increase or decrease an input. For example, the user increases the slider amount and the volume of the music gets louder. + +The more complex versions should be used for selecting a specific value within a value range. + + + + +![Example of volume slider](images/slider-usage-1.png) + + + + + + + +![Example of volume slider](images/slider-usage-1.png) + + + + +## Live demo + -## Overview - -The slider in its basic form should be accompanied by a label and a number input that doubles as a display for the slider's current value. The basic slider does **not** include discrete values, as the slider represents a percentage of 0-100. In this case it is not necessary for a user to choose a specific value, but instead generally increase or decrease an input. For example, the user increases the slider amount and the volume of the music gets louder. The more complex versions should be used for selecting a specific value within a value range. - - - - -![Example of volume slider](images/slider-usage-1.png) - - - - - - - -![Example of volume slider](images/slider-usage-1.png) - - - - ## Interactions Users can choose a numerical value by: diff --git a/src/pages/components/tabs/usage.mdx b/src/pages/components/tabs/usage.mdx index 28536f15841..a3ecf295a16 100755 --- a/src/pages/components/tabs/usage.mdx +++ b/src/pages/components/tabs/usage.mdx @@ -13,12 +13,27 @@ Use tabs to allow users to navigate easily between views within the same context Overview -Format +Live demo +Formatting Variations Feedback +## Overview + +Tabs are used to quickly navigate between views within the same context. + + + + +![An example of tabs being used.](images/tab-usage-1.png) + + + + +## Live demo + -## Overview - -Tabs are used to quickly navigate between views within the same context. - - - - -![An example of tabs being used.](images/tab-usage-1.png) - - - - -## Format +## Formatting #### Tab label