carbon-design-system · janchild · Mar 26, 2020 · Mar 31, 2020 · Mar 31, 2020 · Mar 31, 2020
diff --git 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,
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
-<AnchorLink>Size</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
+<AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
+## 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
+
 <ComponentDemo
   components={[
     {
@@ -45,13 +54,7 @@ Loading spinners are used when retrieving data or performing slow computations,
   `}</ComponentVariant>
 </ComponentDemo>
 
-## 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
@@ -13,6 +13,7 @@ Modals focus the user’s attention exclusively on one task or piece of informat
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Behaviors</AnchorLink>
@@ -22,6 +23,38 @@ Modals focus the user’s attention exclusively on one task or piece of informat
 
 </AnchorLinks>
 
+## 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
+
 <ComponentDemo
   components={[
     {
@@ -104,36 +137,6 @@ Modals focus the user’s attention exclusively on one task or piece of informat
 `}</ComponentVariant>
 </ComponentDemo>
 
-## 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
@@ -13,6 +13,7 @@ Notifications are messages that communicate information to the user. The two mai
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Inline notifications</AnchorLink>
@@ -23,6 +24,23 @@ Notifications are messages that communicate information to the user. The two mai
 
 </AnchorLinks>
 
+## 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
+
 <ComponentDemo
   components={[
     {
@@ -87,21 +105,6 @@ Notifications are messages that communicate information to the user. The two mai
 `}</ComponentVariant>
 </ComponentDemo>
 
-## 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
@@ -13,11 +13,18 @@ The number input component is used for entering numeric values and includes cont
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
+## Overview
+
+Number inputs are similar to text inputs, but contain controls used to increase or decrease an incremental value.
+
+## Live demo
+
 <ComponentDemo
   components={[
     {
@@ -79,10 +86,6 @@ The number input component is used for entering numeric values and includes cont
     `}</ComponentVariant>
 </ComponentDemo>
 
-## 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
@@ -13,11 +13,18 @@ Use the overflow menu component when additional options are available to the use
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
+## Overview
+
+Overflow menu is used when additional options are available to the user and there is a space constraint.
+
+## Live demo
+
 <ComponentDemo
   components={[
     {
@@ -56,10 +63,6 @@ Use the overflow menu component when additional options are available to the use
   `}</ComponentVariant>
 </ComponentDemo>
 
-## 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
@@ -13,11 +13,20 @@ Pagination is used for splitting up content or data into several pages, with a c
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Best practices</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
+## 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
+
 <ComponentDemo
   components={[
     {
@@ -67,12 +76,6 @@ Pagination is used for splitting up content or data into several pages, with a c
   `}</ComponentVariant>
 </ComponentDemo>
 
-## 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
@@ -13,11 +13,18 @@ A progress indicator is a visual representation of a user's progress through a s
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Best practices</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
+## 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
+
 <ComponentDemo
   components={[
     {
@@ -84,10 +91,6 @@ A progress indicator is a visual representation of a user's progress through a s
 `}</ComponentVariant>
 </ComponentDemo>
 
-## 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
@@ -13,12 +13,19 @@ Use radio buttons when you have a group of mutually exclusive choices and only o
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Format</AnchorLink>
 <AnchorLink>Default selection</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
+## 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
+
 <ComponentDemo
   components={[
     {
@@ -71,10 +78,6 @@ Use radio buttons when you have a group of mutually exclusive choices and only o
   `}</ComponentVariant>
 </ComponentDemo>
 
-## 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
@@ -13,12 +13,19 @@ Search enables users to specify a word or a phrase to find relevant pieces of co
 <AnchorLinks>
 
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
 <AnchorLink>Variations</AnchorLink>
 <AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
+## 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
+
 <ComponentDemo
   components={[
     {
@@ -47,10 +54,6 @@ Search enables users to specify a word or a phrase to find relevant pieces of co
   `}</ComponentVariant>
 </ComponentDemo>
 
-## 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                                                                                                                                                                                                    |