Docs/ppdsc 2615 update usage section on all site (#558)

* docs(PPDSC-2615): docs(PPDSC-2615) update usage section in all site

site/pages/components/accordion.tsx

@@ -182,22 +182,26 @@ const AccordionComponent = (layoutProps: LayoutProps) => (
       introduction: 'Here’s how and when to use the accordion:',
       cards: [
         {
+          title: 'Do use for supporting information',
           description: 'Use accordions to provide supporting information.',
           kind: UsageKind.DO,
           media: getIllustrationComponent('components/accordion/usage/do01'),
         },
         {
+          title: 'Don’t use for important information',
           description: 'Avoid concealing crucial information in an accordion.',
           kind: UsageKind.DONT,
           media: getIllustrationComponent('components/accordion/usage/dont01'),
         },
         {
+          title: 'Do make headlines short and clear',
           description:
             'Give accordions short, meaningful headings that tell users what’s inside the panel. Group together related topics.',
           kind: UsageKind.DO,
           media: getIllustrationComponent('components/accordion/usage/do02'),
         },
         {
+          title: 'Don’t nest accordions',
           description: 'Avoid nesting accordions within themselves.',
           kind: UsageKind.DONT,
           media: getIllustrationComponent('components/accordion/usage/dont02'),

site/pages/components/audio-player.tsx

@@ -448,10 +448,10 @@ const AudioPlayerComponent = (layoutProps: LayoutProps) => (
       ],
     }}
     usage={{
-      introduction:
-        'The following guidance describes how and when to appropriately use the audio player component.',
+      introduction: 'Here’s how and when to use the audio player:',
       cards: [
         {
+          title: "Do use a flag for 'live' audio streaming",
           description: (
             <>
               Use a <Link href="/components/flag/">flag</Link> to show users
@@ -464,6 +464,7 @@ const AudioPlayerComponent = (layoutProps: LayoutProps) => (
           ),
         },
         {
+          title: 'Do adapt the component for different breakpoints',
           description: (
             <>
               For optimal user experience across breakpoints, it is recommended
@@ -478,6 +479,7 @@ const AudioPlayerComponent = (layoutProps: LayoutProps) => (
           ),
         },
         {
+          title: 'Do use the expandable volume control when space is limited',
           description:
             'Use the expandable volume control when space in an audio player is limited.',
           kind: UsageKind.DO,
@@ -486,6 +488,7 @@ const AudioPlayerComponent = (layoutProps: LayoutProps) => (
           ),
         },
         {
+          title: 'Don’t display on mobile',
           description:
             'Avoid displaying the volume control on mobile devices as users can use their native device controls to increase or decrease the volume of the audio track.',
           kind: UsageKind.DONT,

site/pages/components/banner.tsx

@@ -288,42 +288,45 @@ const BannerComponent = (layoutProps: LayoutProps) => (
       ],
     }}
     usage={{
-      introduction:
-        'The following guidance describes how and when to appropriately use a Banner component.',
+      introduction: 'Here’s how and when to use the banner:',
       cards: [
         {
+          title: 'Do use banners for essential, system-level information',
           description:
-            'Banners should be reserved only for essential system-level information, such as internet connection issues, expirations of subscriptions, payment failures or major product changes. For confirmations of actions or promotional messaging use another feedback component such as a Toast.',
+            'Examples include internet connection issues, expirations of subscriptions, payment failures or major product changes. For confirmations of actions or promotional messages, use another feedback component (e.g. toast) instead.',
           kind: UsageKind.DO,
           media: getIllustrationComponent(
             'components/banner/banner-do-1-illustration',
           ),
         },
         {
-          description:
-            'Never show multiple Banners at the same time. When multiple Banners are consecutively or simultaneously triggered, the Banner with more importance should replace an existing Banner of lesser importance until the higher priority one has been resolved.',
+          title: 'Don’t show multiple banners at the same time',
+          description: 'Banners should appear in order of importance.',
           kind: UsageKind.DONT,
           media: getIllustrationComponent(
             'components/banner/banner-dont-1-illustration',
           ),
         },
         {
+          title: 'Do add an action to help users solve the issue',
           description:
-            'Whenever possible, add an action in the Banner for a user to quickly resolve the associated Banner message.',
+            'Whenever possible, add an action in the banner so the user can quickly resolve the issue.',
           kind: UsageKind.DO,
           media: getIllustrationComponent(
             'components/banner/banner-do-2-illustration',
           ),
         },
         {
+          title: 'Don’t have more than one action in a banner',
           description:
-            'Avoid using more than one action in a Banner. (excluding the dismiss button). Having more than one action to choose from can make it difficult for users to decide what action to do next.',
+            'Having more than one action to choose from can make it difficult for users to decide what to do next. This doesn’t include the close button.',
           kind: UsageKind.DONT,
           media: getIllustrationComponent(
             'components/banner/banner-dont-2-illustration',
           ),
         },
         {
+          title: 'Do position below the navigation header',
           description:
             'Banners should be positioned at the top of a page, below the navigation header.',
           kind: UsageKind.DO,
@@ -332,37 +335,32 @@ const BannerComponent = (layoutProps: LayoutProps) => (
           ),
         },
         {
+          title: 'Don’t let banners time out',
           description:
-            'Never allow Banners to time out. They should only disappear on user interaction (either dismissing or completing a task) or when the information is no longer relevant, e.g. updating failed payment details.',
+            'Banners should only disappear on user interaction (dismissing or completing a task) or when the information is no longer relevant (e.g. updating failed payment details).',
           kind: UsageKind.DONT,
           media: getIllustrationComponent(
             'components/banner/banner-dont-3-illustration',
           ),
         },
         {
+          title: 'Do convey tone with the right intent',
           description:
-            'Use the appropriate intent to convey the tone of the Banner message. If the tone is neutral use the informative intent Banner. ',
+            'Use the appropriate intent to convey the tone of the banner message. If the tone is neutral, use the informative intent banner.',
           kind: UsageKind.DO,
           media: getIllustrationComponent(
             'components/banner/banner-do-4-illustration',
           ),
         },
         {
+          title: 'Do display again if unresolved',
           description:
-            'If a user dismisses a Banner without resolving the issue, it should be displayed again at the next possible occasion, without overwhelming the user e.g. the next time session.',
+            'If a user dismisses a banner without resolving the issue, display it again at the next possible occasion, without overwhelming the user (e.g. the next time session).',
           kind: UsageKind.DO,
           media: getIllustrationComponent(
             'components/banner/banner-dont-5-illustration',
           ),
         },
-        {
-          description:
-            "Keep a Banner's message clear and concise, describing what's happening, and what the user needs to know and do. ",
-          kind: UsageKind.DO,
-          media: getIllustrationComponent(
-            'components/banner/banner-do-6-illustration',
-          ),
-        },
       ],
     }}
     accessibility={{

site/pages/components/block.tsx

@@ -183,7 +183,7 @@ const BlockComponent = (layoutProps: LayoutProps) => (
           description:
             'Use the block as a container to easily apply spacing and style presets around other elements.',
           kind: UsageKind.DO,
-          media: getIllustrationComponent('components/block/do-01'),
+          media: getIllustrationComponent('components/block/usage/do-01'),
         },
         {
           title: 'Don’t use for equal spacing on multiple elements',
@@ -202,7 +202,7 @@ const BlockComponent = (layoutProps: LayoutProps) => (
             </>
           ),
           kind: UsageKind.DONT,
-          media: getIllustrationComponent('components/block/dont-01'),
+          media: getIllustrationComponent('components/block/usage/dont-01'),
         },
       ],
     }}

site/pages/components/button.tsx

@@ -439,36 +439,42 @@ const ButtonComponent = (layoutProps: LayoutProps) => (
       introduction: 'Here’s how and when to use the button:',
       cards: [
         {
+          title: 'Do allow a sufficient hit area',
           description:
-            'When placing two or more buttons inline, keep at least an 8px gap between them.',
+            'When placing two or more buttons inline, make sure they are a sufficient size or have spacing between them to avoid users accidentally hitting the wrong button.',
           kind: UsageKind.DO,
-          media: getIllustrationComponent('components/button/usage/do1'),
+          media: getIllustrationComponent('components/button/usage/do-01'),
         },
         {
+          title: 'Don’t use full width buttons in wide containers',
           description:
-            'Full-width buttons are generally appropriate for small devices or contained components.',
+            'Full width buttons are more appropriate for small devices or contained components.',
           kind: UsageKind.DONT,
           media: getIllustrationComponent('components/button/usage/dont1'),
         },
         {
+          title: 'Do consider button width',
           description:
             'When deciding between a fixed or full width button, consider how it will respond and react to the containers around it.',
           kind: UsageKind.DO,
           media: getIllustrationComponent('components/button/usage/do2'),
         },
         {
+          title: 'Don’t separate related buttons',
           description:
             'Place related buttons next to each other so associated actions are relative, and to reduce cognitive load.',
           kind: UsageKind.DONT,
           media: getIllustrationComponent('components/button/usage/dont2'),
         },
         {
+          title: 'Don’t stack buttons unnecessarily',
           description:
             'Avoid stacking buttons when there’s enough space to place them side by side.',
           kind: UsageKind.DONT,
           media: getIllustrationComponent('components/button/usage/dont4'),
         },
         {
+          title: 'Don’t have more than one primary button',
           description:
             'Avoid having more than one primary (high emphasis) button on a screen to help guide the user to the primary action.',
           kind: UsageKind.DONT,

site/pages/components/character-count.tsx

@@ -274,19 +274,20 @@ const CharacterCountComponent = (layoutProps: LayoutProps) => (
       ],
     }}
     usage={{
-      introduction:
-        'The following guidance describes how and when to appropriately use the character count component.',
+      introduction: 'Here’s how and when to use the character count :',
       layout: '2-span',
       cards: [
         {
+          title: 'Do display an error message when needed',
           description:
-            'If a user tries to submit a form with an exceeded character count, an error message should display prompting them to reduce the number of characters.',
+            'If a user tries to submit a form with an exceeded character count, display an error message prompting them to reduce the number of characters.',
           kind: UsageKind.DO,
           media: getIllustrationComponent(
             'components/character-count/usage/do-01',
           ),
         },
         {
+          title: 'Don’t restrict users from inputting characters',
           description: (
             <>
               Don’t restrict users from inputting characters or copying and
@@ -312,8 +313,9 @@ const CharacterCountComponent = (layoutProps: LayoutProps) => (
           ),
         },
         {
+          title: 'Do display a word count when needed',
           description:
-            'In some cases, it may be more helpful to show a word count. For example, if your question requires a longer answer, you can set data-maxwords in the component markup. E.g.//data-maxwords="100"//.',
+            'In some cases, it may be more helpful to show a word count. For example, if your question requires a longer answer, you can set data-maxwords in the component markup. E.g. //data-maxwords="100"//.',
           kind: UsageKind.DO,
           media: getIllustrationComponent(
             'components/character-count/usage/do-2',

site/pages/components/checkbox.tsx

@@ -580,64 +580,53 @@ const CheckboxComponent = (layoutProps: LayoutProps) => (
       introduction: 'Here’s how and when to use the checkbox:',
       cards: [
         {
+          title: 'Do use checkboxes for up to 7 options',
           description:
-            'When medium or large checkboxes are too visually prominent, use small checkboxes instead (e.g. in a form, to show more options at a glance).',
+            'If you have more than 7 checkboxes in a group, use a select.',
           kind: UsageKind.DO,
-          media: getIllustrationComponent('components/checkbox/usage/do-2'),
+          media: getIllustrationComponent('components/checkbox/usage/do-1'),
         },
         {
+          title: 'Do use checkboxes for selecting multiple options',
           description:
-            'Use checkboxes either for selecting multiple options from a list, or to check or uncheck a single option. If users can only select a single option, use the radio button instead.',
+            'Use checkboxes either for selecting multiple options from a list, or to check or uncheck a control. If users can only select a single option, use the radio button instead.',
           kind: UsageKind.DO,
-          media: getIllustrationComponent('components/checkbox/usage/do-3'),
+          media: getIllustrationComponent('components/checkbox/usage/do-2'),
         },
         {
+          title: 'Do give checkboxes a label',
           description:
             'Checkboxes should have an associated label to give users context.',
           kind: UsageKind.DO,
-          media: getIllustrationComponent('components/checkbox/usage/do-4'),
-        },
-        {
-          description:
-            'When grouping multiple checkboxes, put the label on the right (end) so that, when used together in forms, checkbox inputs align vertically. This makes them easier to find, especially for users of screen magnifiers.',
-          kind: UsageKind.DONT,
-          media: getIllustrationComponent('components/checkbox/usage/dont-2'),
+          media: getIllustrationComponent('components/checkbox/usage/do-3'),
         },
         {
+          title: 'Do put labels on the right of grouped checkboxes',
           description:
-            'Checkboxes should be displayed vertically, and stacked for consistent alignment, positioning and legibility across different breakpoints.',
+            'Align checkbox inputs vertically. This makes them easier to find, especially for users of screen magnifiers.',
           kind: UsageKind.DO,
-          media: getIllustrationComponent('components/checkbox/usage/do-5'),
-        },
-        {
-          description:
-            'Avoid using Checkboxes in a horizontal orientation to avoid issues with alignment and legibility when there are multiple Checkboxes grouped together.',
-          kind: UsageKind.DONT,
-          media: getIllustrationComponent('components/checkbox/usage/dont-3'),
+          media: getIllustrationComponent('components/checkbox/usage/do-4'),
         },
         {
+          title: 'Do display checkboxes vertically',
           description:
-            'Assistive text, if needed, should hint at the required user action (e.g. ‘select all that apply’).',
+            'Align checkbox inputs vertically. This makes them easier to find, especially for users of screen magnifiers.',
           kind: UsageKind.DO,
-          media: getIllustrationComponent('components/checkbox/usage/do-6'),
+          media: getIllustrationComponent('components/checkbox/usage/do-5'),
         },
         {
+          title: "Don't check options by default",
           description:
-            'Avoid default checked options as they make it more likely that users won’t realise they’ve missed a question, or submit an unintended answer.',
+            'Avoid default checked options. Users might not realise they’ve missed a question and submit an unintended answer.',
           kind: UsageKind.DONT,
-          media: getIllustrationComponent('components/checkbox/usage/dont-4'),
-        },
-        {
-          description:
-            'If the checkbox is invalid, swap assistive text with error text. Once the checkbox is valid, show the assistive text again.',
-          kind: UsageKind.DO,
-          media: getIllustrationComponent('components/checkbox/usage/do-7'),
+          media: getIllustrationComponent('components/checkbox/usage/dont-1'),
         },
         {
+          title: 'Do make error text clear and simple',
           description:
             'Error text should be clear, concise and written in complete sentences - and it should tell the user how to resolve the issue.',
           kind: UsageKind.DO,
-          media: getIllustrationComponent('components/checkbox/usage/do-8'),
+          media: getIllustrationComponent('components/checkbox/usage/do-6'),
         },
       ],
     }}

site/pages/components/divider.tsx

@@ -114,9 +114,7 @@ const DividerComponent = (layoutProps: LayoutProps) => (
             </>
           ),
           kind: UsageKind.DO,
-          media: getIllustrationComponent(
-            'components/divider/do-1-illustration',
-          ),
+          media: getIllustrationComponent('components/divider/do-01'),
         },
       ],
     }}

site/pages/components/flag.tsx

@@ -215,16 +215,17 @@ const FlagComponent = (layoutProps: LayoutProps) => (
       ],
     }}
     usage={{
-      introduction:
-        'The following guidance describes how and when to appropriately use a flag component.',
+      introduction: 'Here’s how and when to use the flag:',
       cards: [
         {
+          title: 'Do use flags to draw attention',
           description:
             'Use flags to draw attention to a new feature, piece of content, or status change that may be of particular interest to a user.',
           kind: UsageKind.DO,
           media: getIllustrationComponent('components/flag/usage/do-01'),
         },
         {
+          title: "Don't use flags for categorisation",
           description: (
             <>
               Avoid using flags for categorisation other than status. Consider
@@ -235,8 +236,9 @@ const FlagComponent = (layoutProps: LayoutProps) => (
           media: getIllustrationComponent('components/flag/usage/dont-01'),
         },
         {
+          title: "Don't make flags interactive",
           description: 'Use flags as a non-interactive status indicator.',
-          kind: UsageKind.DO,
+          kind: UsageKind.DONT,
           media: getIllustrationComponent('components/flag/usage/do-02'),
         },
       ],