Merge pull request #712 from WestpacGEL/Kate-content-updates

Accessibility tab content updates

apps/site/src/content/design-system/components/accordion/accessibility/accessibility-features/content.mdoc

@@ -1,13 +1,11 @@
-- The tabset is implemented as a set of buttons, rather than tabs. This approach has shown to provide a better user experience.
+- The accordions are implemented as a set of buttons. This approach has shown to provide a better user experience.
 - An indicator outline appears around the toggle buttons when focused
-- The tabcordion shape, text and accordion toggle icons are visible in Windows High Contrast Mode
+- The accordion shape, text and accordion toggle icons are visible in Windows High Contrast Mode
 
 ### Accessibility in the HTML
 
-- `<div role="tablist">`: Indicates that the element serves as a container for a set of tabs
-- `<button aria-controls="{PANEL_ID}" aria-expanded="true|false">`: Identifies a button element that toggles a content collapse and indicates the state of a collapsible element below. The&nbsp;*aria-controls*&nbsp;attribute creates an association between toggle button and collapsible element (panel).
-- `<div id="{PANEL_ID}" aria-hidden="false|true">`: The panel must have a unique&nbsp;*id*&nbsp;value. The toggle button&nbsp;*aria-controls*&nbsp;and panel&nbsp;*id*&nbsp;attribute values must match. The panel uses the&nbsp;*aria-hidden*&nbsp;attribute to hide from assistive technologies when no longer available.
+The accordion uses the useAccordion and useAccordionItem hooks from React Aria to handle the accessibility code. Read the [full specifications](https://reactspectrum.blob.core.windows.net/reactspectrum/d77b35e970e5549f66b47a83f07423f5c93b7297/docs/react-aria/useAccordion.html) for more information.
 
 ### Keyboard support
 
-Keyboard users navigate the tabset as a set of buttons, rather than ‘tabs’. Keyboard interaction requires use of ‘tab’ and ‘enter’ (or ‘space’) keys to select, rather than arrow keys. The accordion toggles are also buttons; interaction is as expected, consistent with tabset toggles.
+Keyboard users navigate the accordions toggles as a set of buttons. Keyboard interaction requires use of ‘tab’ and ‘enter’ (or ‘space’) keys to select, rather than arrow keys.

apps/site/src/content/design-system/components/accordion/index.yaml

@@ -4,6 +4,7 @@ description: >-
   group and simplify large amounts of content such as product information.
 namedExport:
   discriminant: false
+excludeFromNavbar: false
 design:
   - title:
       name: Accordion

apps/site/src/content/design-system/components/alert/accessibility/accessibility-features/content.mdoc

@@ -1,13 +1,13 @@
-- A `<span>` element labeled with the specific Alert type represents the Alert icon
+- An `<svg>` element labelled with the specific Alert type represents the Alert icon
 - A `<button>` element labeled “Close alert” identifies the close button action
 - 'Info' Alerts can be configured with a custom icon. The custom icon must be relevant to the Alert message, sufficiently labeled and not one of the other pre-existing Alert icons.
 - he Alert shape, text and icon content is visible in Windows High Contrast Mode (WHCM). The Alert type (colour) is not visible in WHCM, however the unique Alert icon provides this information.
 
 ### Accessibility in the HTML
 
-- A `<span aria-label="{ALERT_LOOK}">`: Provides a label that describes the Alert icon
-- A `<role="img" focusable="false">`: Prevents the Alert icon SVG element from being traversed by browsers that map the SVG to the ‘group’ role and from unnecessarily receiving focus in Internet Explorer (IE)
-- A `<span aria-hidden="true">`: Prevents the close button icon from being announced; it is labeled by the parent button
+- An `<svg aria-label="{ICON_NAME}">` Provides a label that describes the Alert icon
+- A `<role="img" focusable="false">` Prevents the Alert icon SVG element from being traversed by browsers that map the SVG to the ‘group’ role and from unnecessarily receiving focus in Internet Explorer (IE)
+- A `<svg focusable=”false”>` Prevents the close button icon from being announced; it is labelled by the parent button
 
 ### Keyboard support
 

apps/site/src/content/design-system/components/breadcrumb/accessibility/accessibility-features/content.mdoc

@@ -1,17 +1,16 @@
 - The set of links is structured using an ordered list
 - A `<nav>` element labeled “Breadcrumb” identifies the structure as a breadcrumb trail and makes it a navigation landmark so that it is easy to locate
-- The links do not use ‘link’ colour or underline styling, however they are sufficiently identifiable as links by use of a link coloured (separator) icon, similar to [Link list](/design-system/wbc/components/lists?tab=design#other-lists) bullets
+- The links do not use ‘link’ colour or underline styling, however they are sufficiently identifiable as links by use of a link coloured (separator) icon, similar to [Link list](/components/list) bullets
 - The visual separator icons are hidden to prevent announcement in screen readers. The separators are part of the visual presentation that signifies the breadcrumb trail, which is already semantically represented by the `<nav>` element with its label of “Breadcrumb”.
 - The breadcrumb list is announced as expected in all screen readers including VoiceOver
 - An indicator outline appears around the links when focused
 - The breadcrumb trail and separator icons are visible in Windows High Contrast Mode
 
 ### Accessibility in the HTML
 
-- `<nav aria-label="Breadcrumb">`: Provides a label that describes the type of navigation
-- `<ol role="list">`: Links are within an ordered list to provide additional semantic meaning—crumbs are quantifiable and part of a hierarchy, each descendants of a higher-priority crumb. The list has a “list” *role* because removing standard bullet styling affects how VoiceOver announces lists (see [VoiceOver and list-style-type: none](https://unfetteredthoughts.net/2017/09/26/voiceover-and-list-style-type-none/)).
-- `<a aria-current="page">`: Applied to the last link in the set to indicate that it represents the current page
-- `<span aria-hidden="true">`: Hides the visual separator icon SVGs from assistive technologies; they are visual embellishment
+- `<nav aria-label="Breadcrumb">` Provides a label that describes the type of navigation
+- `<span aria-hidden="true">` Hides the visual separator icon SVGs from assistive technologies; they are visual embellishment
+- The breadcrumb uses the useBreadcrumbs and useBreadcrumbItem hooks from React Aria to handle the accessibility code. Read the [full specifications](https://reactspectrum.blob.core.windows.net/reactspectrum/d77b35e970e5549f66b47a83f07423f5c93b7297/docs/react-aria/useBreadcrumbs.html) for more information.
 
 ### Keyboard support
 

apps/site/src/content/design-system/components/breadcrumb/index.yaml

@@ -5,6 +5,7 @@ description: >-
   orientation.
 namedExport:
   discriminant: false
+excludeFromNavbar: false
 design:
   - title:
       name: Breadcrumbs

apps/site/src/content/design-system/components/button-group/accessibility/accessibility-features/content.mdoc

@@ -4,8 +4,7 @@
 
 ### Accessibility in the HTML
 
-- `<input type="radio" id="{OPTION_ID}" name="{NAME}">`: Each item option is defined as a (hidden) radio&nbsp;*input*&nbsp;and must have a unique&nbsp;*id*&nbsp;value. A consistent&nbsp;*name*&nbsp;attribute value is required on all inputs for toggling to operate correctly. [React component: refer to&nbsp;*name*&nbsp;prop,&nbsp;*id*&nbsp;is auto-generated]
-- `<label for="{OPTION_ID}">`: Each radio&nbsp;*input*&nbsp;is wrapped with a&nbsp;*label*&nbsp;element and uses explicit association (connected to the input using a&nbsp;*for*&nbsp;attribute) for optimal support in assistive technologies. [React component:&nbsp;*for*&nbsp;is auto-generated]
+- The button group uses the useRadioGroup and useRadio hooks from React Aria to handle the accessibility code. Read the [full specifications](https://reactspectrum.blob.core.windows.net/reactspectrum/d77b35e970e5549f66b47a83f07423f5c93b7297/docs/react-aria/useRadioGroup.html) for more information.
 
 ### Keyboard support
 

apps/site/src/content/design-system/components/button/accessibility/accessibility-features/content.mdoc

@@ -9,8 +9,8 @@
 
 - `<button>`&nbsp;/&nbsp;`<a>`: Identifies the element as a button (or link) element. Accessible name for the button is defined by the element’s text content. [React component: refer to&nbsp;*tag*&nbsp;prop]
 - `<a href="{URL}">`: Links styled to look like buttons must include an&nbsp;*href*. [React component: refer to&nbsp;*tag prop*&nbsp;and&nbsp;*href*&nbsp;attribute]
-- `<button aria-label="{BUTTON_LABEL}">`: Optionally use&nbsp;*aria-label*&nbsp;attribute to set a custom label (if different to the button text). The overall meaning of the&nbsp;*aria-label*&nbsp;must be consistent with the visual button text to ensure an optimal experience for speech recognition software users (i.e. Dragon NaturallySpeaking). [React component: refer to&nbsp;*assistiveText*&nbsp;prop]
-- `<span aria-hidden="true">`: Button icon elements have&nbsp;*aria-hidden="false"*&nbsp;to hide them from assistive technologies; they are visual embellishment. Generally the button text provides the button description, if this is not the case a custom label can be used which will be announced instead of the button text for screen reader users. [React component: refer to&nbsp;*iconBefore*,&nbsp;*iconAfter*&nbsp;and&nbsp;*assistiveText*&nbsp;props)
+- `<button aria-label="{BUTTON_LABEL}">` Optionally use aria-label attribute to set a custom label (if different to the button text). The overall meaning of the aria-label must be consistent with the visual button text to ensure an optimal experience for speech recognition software users (i.e. Dragon NaturallySpeaking)
+- `<svg aria-hidden="true">` Button icon elements have aria-hidden="true" to hide them from assistive technologies; they are visual embellishment. Generally the button text provides the button description, if this is not the case a custom label can be used which will be announced instead of the button text for screen reader users. [React component: refer to iconBefore and iconAfter props]
 
 ### Keyboard support
 

apps/site/src/content/design-system/components/checkbox-group/accessibility/accessibility-features/content.mdoc

@@ -4,10 +4,8 @@
 
 ### Accessibility in the HTML
 
-- `<input type="checkbox" id="{OPTION_ID}">`: Each item option is defined as a checkbox&nbsp;*input*&nbsp;and must have a unique&nbsp;*id*&nbsp;value. [React component:&nbsp;*id*&nbsp;is auto-generated]
-- `<label for="{OPTION_ID}">`: Each checkbox&nbsp;*input*&nbsp;has a&nbsp;*label*&nbsp;element and uses explicit association (connected to the input using a&nbsp;*for*&nbsp;attribute) for optimal support in assistive technologies. [React component:&nbsp;*for*&nbsp;is auto-generated]
-- `<button aria-expanded="true|false" aria-hidden="true|false">`: Checkbox with reveal toggle button uses&nbsp;*aria-expanded*&nbsp;attribute to indicate collapse state and&nbsp;*aria-hidden*&nbsp;to hide from assistive technologies when no longer available
-- `<div aria-hidden="true|false">`: Reveal checkbox options are wrapped in an element with&nbsp;*aria-hidden*&nbsp;attribute
+- `<button aria-expanded="true|false" >`: Checkbox with reveal toggle button uses aria-expanded attribute to indicate collapse state.
+- The checkbox uses the useCheckboxGroup and useCheckboxGroupItem hooks from React Aria to handle the accessibility code. Read the [full specifications](https://reactspectrum.blob.core.windows.net/reactspectrum/d77b35e970e5549f66b47a83f07423f5c93b7297/docs/react-aria/useCheckboxGroup.html) for more information.
 
 ### Keyboard support
 

apps/site/src/content/design-system/components/input-group/accessibility/accessibility-features/content.mdoc

@@ -1,8 +1,8 @@
 - Indicator outline appears around the input and button elements when focused
-- Text input and select elements include a visually hidden label
+- Input group includes an option to visually hide the label
 - The input group shape and text content is visible in Windows High Contrast Mode (WHCM). Button ‘look’ styling (colour) is not visible in WHCM.
 
 ### Accessibility in the HTML
 
-- `<label for="{ID}">`: Each text input or select element has a visually hidden *label* element and uses explicit association (connected to the text input or select element using a *for* attribute) for optimal support in assistive technologies. [React component: refer to *label* prop to set label text, *for* is auto-generated]
-- `<input type="text" id="{ID}">` / `<select id="{ID}">`: Text input or select elements must have a unique *id* value. [React component: *id* is auto-generated]
+- `<label htmlFor="{ID}">` Input group has the option of having a visually hidden label element and uses explicit association for optimal support in assistive technologies. [React component: refer to srOnly prop, id is auto-generated]
+- `<input type="text" id="{ID}"> / <select id="{ID}">` Text input or select elements must have a unique id value. [React component: id is auto-generated but can be overwritten using instanceId property]

apps/site/src/content/design-system/components/list/accessibility/accessibility-features/content.mdoc

@@ -3,6 +3,5 @@
 
 ### Accessibility in the HTML
 
-- `role="list"`: Lists with custom bullets have a “list” *role* because removing standard bullet styling affects how VoiceOver announced lists (see [VoiceOver and list-style-type: none](https://unfetteredthoughts.net/2017/09/26/voiceover-and-list-style-type-none/))
-- `<span aria-label="{DESCRIPTION}">`: Provides a label that describes the Icon
+- `<svg aria-label="{ICON_NAME}">`: Provides a label that describes the Icon
 - `<svg role="img" focusable="false">`: Prevents the Icon SVG element from being traversed by browsers that map the SVG to the ‘group’ role and from unnecessarily receiving focus in Internet Explorer (IE)

apps/site/src/content/design-system/components/list/index.yaml

@@ -5,6 +5,7 @@ description: >-
   or legal copy for example.
 namedExport:
   discriminant: false
+excludeFromNavbar: false
 design:
   - title:
       name: Bullet lists

apps/site/src/content/design-system/components/modal/accessibility/accessibility-features/content.mdoc

@@ -8,8 +8,6 @@
 
 ### Accessibility in the HTML
 
-- `<div aria-modal="true" aria-hidden="{true|false}">`: Tells assistive technologies that the windows underneath the current dialog are not available for interaction (inert) and&nbsp;*aria-hidden*&nbsp;ensures the modal is hidden from assistive technologies as required.&nbsp;**Note: there is no**&nbsp;***role="dialog"***&nbsp;**attribute**. This is intentional as many screen readers will announce all modal content on open if this role is used. Our approach is to simply announce the heading and let the user be in control (as mentioned above).
-- `<h1 tabindex="-1">`: Modal heading has a&nbsp;*tabindex*&nbsp;attribute, enabling the heading to receive focus (programmatically). The heading is announced on open. The&nbsp;*tabindex*&nbsp;value uses&nbsp;*-1*&nbsp;(rather than&nbsp;*0*) because we don’t need the heading focusable during normal keyboard navigation.
 - `<button aria-label="Close modal">`: Close button announced as “Close modal” in screen readers
 
 ### Keyboard support

apps/site/src/content/design-system/components/modal/index.yaml

@@ -5,6 +5,7 @@ description: >-
   user journey.
 namedExport:
   discriminant: false
+excludeFromNavbar: false
 design:
   - title:
       name: Modal sizes

apps/site/src/content/design-system/components/pagination/accessibility/accessibility-features/content.mdoc

@@ -8,7 +8,6 @@
 ### Accessibility in the HTML
 
 - `<nav aria-label="Page number">`: Provides a label that describes the type of navigation
-- `<ul role="list">`: Navigation items are within an unordered list to provide additional semantic meaning—page options are quantifiable. The list has a “list”&nbsp;*role*&nbsp;because removing standard bullet styling affects how VoiceOver announces lists (see&nbsp;[VoiceOver and list-style-type: none](https://unfetteredthoughts.net/2017/09/26/voiceover-and-list-style-type-none/)).
 - `<button aria-current="page">`&nbsp;/&nbsp;`<a aria-current="page">`: Currently selected navigation item is marked with&nbsp;*aria-current*. Depending on how routing is implemented (updating state vs linking to a new URL), an anchor (link) element may be better suited.
 - `<span role="status">`: A visually hidden&nbsp;*span*&nbsp;element with “status”&nbsp;*role*&nbsp;is updated with the current page number text to notify assistive technologies
 

apps/site/src/content/design-system/components/pagination/index.yaml

@@ -4,6 +4,7 @@ description: >-
   to multiple pages of content, typically used in long form content.
 namedExport:
   discriminant: false
+excludeFromNavbar: false
 design:
   - title:
       name: Pagination

apps/site/src/content/design-system/components/progress-bar/accessibility/accessibility-features/content.mdoc

@@ -1,8 +1,9 @@
-- A `<div>` element with “progressbar” *role* identifies an element that displays the progress status for a task that take a long time or consists of several steps. Various aria attributes provide min, max and current values.
+- A `<div>` element with “progressbar” role identifies an element that displays the progress status for a task that take a long time or consists of several steps. Various aria attributes provide min, max and current values. All of these are added through the useProgressBar hook from React Aria
 - The progress bar is configured to provide an indication of task or action completion in percentage units, announced as “x% complete”
 - Displaying the current value is optional; it can be visually hidden if required, but always provided to screen readers through aria value attributes
 - The progress bar shape and is visible in Windows High Contrast Mode (WHCM). The indicator bar is additionally rendered using a transparent CSS border to ensure visibility in WHCM.
 
 ### Accessibility in the HTML
 
-- `<div role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0" aria-valuetext="0% complete" aria-live="polite">`: Provides a progress bar with aria attributes to indicate the actual progress value. The&nbsp;*aria-live*&nbsp;attribute informs assistive technologies the region receives updates that are important for the user to receive, but not so rapid as to be annoying. [React component: refer to&nbsp;*value*&nbsp;prop]
+- The progress bar uses the useProgressBar hook from React Aria to handle the accessibility code. Read the [full specifications](https://reactspectrum.blob.core.windows.net/reactspectrum/d77b35e970e5549f66b47a83f07423f5c93b7297/docs/react-aria/useProgressBar.html) for more information.
+- An `aria-live=”polite”` property has been added on top of React Aria to inform assistive technologies the region receives updates that are important for the user to receive, but not so rapid as to be annoying.

apps/site/src/content/design-system/components/progress-bar/index.yaml

@@ -5,6 +5,7 @@ description: >-
   completion value.
 namedExport:
   discriminant: false
+excludeFromNavbar: false
 design:
   - title:
       name: Progress bar

apps/site/src/content/design-system/components/progress-rope/accessibility/accessibility-features/content.mdoc

@@ -6,7 +6,6 @@
 ### Accessibility in the HTML
 
 - `<nav role="navigation" aria-label="In this form">`: Provides a label that describes the type of navigation
-- `<ol role="list">`: Step buttons are within an ordered list to provide additional semantic meaning. The list has a “list”&nbsp;*role*&nbsp;because removing standard bullet styling affects how VoiceOver announces lists (see&nbsp;[VoiceOver and list-style-type: none](https://unfetteredthoughts.net/2017/09/26/voiceover-and-list-style-type-none/)).
 - `<button aria-current="page">`: Applied to the current step button to indicate that it represents the current page
 - `<button aria-expanded="true|false" aria-controls="{ID}">`: Identifies a button element that toggles a content collapse and indicates the state of a collapsible element below. The&nbsp;*aria-controls*&nbsp;attribute creates an association between toggle button and collapsible element.
 - `<ol role="list" id="{ID}" aria-hidden="true|false">`: The collapsible element must have a unique&nbsp;*id*&nbsp;value. The toggle button&nbsp;*aria-controls*&nbsp;and collapsible element&nbsp;*id*&nbsp;attribute values must match. The collapsible element uses the&nbsp;*aria-hidden*&nbsp;attribute to hide from assistive technologies when no longer available.