feat: DAYL-96 Update Count Badge a11y docn (#5077)

* Update count-badge docn * Implement some of Margaree's suggestions * Apply the formatting suggestions * Additional smaller changes
BrightspaceUI · Oct 28, 2024 · cda94f1 · cda94f1
1 parent cb3f8a8
commit cda94f1
Show file tree

Hide file tree

Showing 2 changed files with 41 additions and 49 deletions.
diff --git a/components/count-badge/README.md b/components/count-badge/README.md
@@ -24,30 +24,21 @@ The `d2l-count-badge` element is a web component to display a number count, depe
 </script>
 <d2l-count-badge size="small" type="notification" text="100 new notifications" number="100" has-tooltip tab-stop></d2l-count-badge>
 ```
-
-### Accessibility Properties
-| Attribute | Description |
-|---|---|
-| `text`  | REQUIRED: Only the text will be read by screen-readers (not the number), so include the number in the text. |
-| `tab-stop` | A tab stop allows screen-reader users to easily tab to the badge. Otherwise, screen-reader users will need to arrow through to the badge. |
-| `announce-changes` | Use "announce-changes" if screen-reader users should be notified that the badge has been updated, such as a new notification. The "text" property will be read as soon as the screen-reader is idle. |
-| `has-tooltip` | The tooltip will be visible on hover/tab-stop, and read out by screen-readers. |
-
 <!-- docs: start hidden content -->
 ### Properties
 
 | Property | Type | Description |
 |---|---|---|
-| `number` | Number, required | The number to display on the badge.  Must be a positive integer. |
-| `size`, default: `small` | String | The size of the badge. Valid options are `"small"` and `"large"`. |
-| `type`, default: `count` | String | The type of the badge. Valid options are `"notification"` and `"count"`. Notification badges are orange and count badges are grey. |
-| `max-digits`, default: `2` when `type="notification"`, `5` when `type="count"` | Number | Optionally specify a digit limit, after which numbers are truncated. Defaults to two for `"notification"` type and five for `"count"` type. Must be between 1-5.
-| `hide-zero`, default: `false` | Boolean | Optionally choose not to show the count badge when the number is zero. |
-| `text`, required | String | Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled. |
-| `tab-stop`, default: `false` | Boolean | Optionally choose to make the badge a tab stop. |
-| `announce-changes`, default: `false` | Boolean | Optionally choose to announce changes to the badge with an aria-live region. If the text property is changed, the text will be read by screen-readers. |
-| `has-tooltip`, default: `false` | Boolean | Optionally choose to have a tooltip below the badge. |
-| `focus-ring`, default: `false` | Boolean | Optionally force a focus ring around the badge. This property can be used to highlight the badge when the parent element is focused. |
+| `number` | Number, required | The number to display on the badge; must be a positive integer |
+| `size` | String, default: `small` | The size of the badge. Valid options are `"small"` and `"large"`. |
+| `type` | String, default: `count` | The type of the badge. Valid options are `"notification"` and `"count"`. Notification badges are orange and count badges are grey. |
+| `max-digits` | Number, default: `2` when `type="notification"`, `5` when `type="count"` | Specifies a digit limit, after which numbers are truncated. Defaults to two for `"notification"` type and five for `"count"` type. Must be between 1-5.
+| `hide-zero` | Boolean, default: `false` | Hides the count badge when `number` is zero |
+| `text` | String, required | Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled |
+| `tab-stop` | Boolean, default: `false` | Adds a tab stop to the badge, which allows screen reader and keyboard users to easily tab to the badge |
+| `announce-changes` | Boolean, default: `false` | When `true`, changes to the badge will be announced to screen reader users |
+| `has-tooltip` | Boolean, default: `false` | Adds a tooltip on the badge, which will be visible on hover/tab-stop, and read out by screen-readers |
+| `focus-ring` | Boolean, default: `false` | Forces the focus ring around the badge. This property can be used to highlight the badge when the parent element is focused. |
 <!-- docs: end hidden content -->
 
 ## Count Badge: Icon [d2l-count-badge-icon]
@@ -62,28 +53,30 @@ The `d2l-count-badge-icon` element is a web component to display a number count,
 <d2l-count-badge-icon size="small" icon="tier1:gear" type="notification" text="100 new settings applied." number="100" tab-stop has-tooltip></d2l-count-badge-icon>
 ```
 
-### Accessibility Properties
-| Attribute | Description |
-|---|---|
-| `text` | REQUIRED: Only the text will be read by screen-readers (not the number), so include the number in the text. |
-| `tab-stop` | A tab stop allows screen-reader users to easily tab to the badge. Otherwise, screen-reader users will need to arrow through to the badge. |
-| `announce-changes` | Use "announce-changes" if screen-reader users should be notified that the badge has been updated, such as a new notification. The "text" property will be read as soon as the screen-reader is idle. |
-| `has-tooltip` | The tooltip will be visible on hover/tab-stop, and read out by screen-readers. |
-
 <!-- docs: start hidden content -->
 ### Properties
 
 | Property | Type | Description |
 |--|--|--|
-| `number` | Number | Required: The number to display on the badge.  Must be a positive integer. |
-| `icon` | String | Required: [Preset icon key](../icons#preset-icons) (e.g. `tier1:gear`) |
-| `size`, default: `small` | String | The size of the badge. Valid options are `"small"` and `"large"`. |
-| `type`, default: `count` | String | The type of the badge. Valid options are `"notification"` and `"count"`. Notification badges are orange and count badges are grey. |
-| `max-digits`, default: `2` when `type="notification"`, `5` when `type="count"` | Number | Optionally specify a digit limit, after which numbers are truncated. Defaults to two for `"notification"` type and five for `"count"` type. Must be between 1-5.
-| `hide-zero`, default: `false` | Boolean | Optionally choose not to show the count badge when the number is zero. |
-| `text`  | String | REQUIRED: Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled. |
-| `tab-stop`, default: `false` | Boolean | Optionally choose to make the badge a tab stop. |
-| `announce-changes`, default: `false` | Boolean | Optionally choose to announce changes to the badge with an aria-live region. If the text property is changed, the text will be read by screen-readers. |
-| `has-tooltip`, default: `false` | Boolean | Optionally choose to have a tooltip below the badge. |
-| `focus-ring`, default: `false` | Boolean | Optionally force a focus ring around the badge. This property can be used to highlight the badge when the parent element is focused. |
+| `number` | Number, required | The number to display on the badge; must be a positive integer |
+| `icon` | String, required | [Preset icon key](../icons#preset-icons) (e.g. `tier1:gear`) |
+| `size` | String, default: `small` | The size of the badge. Valid options are `"small"` and `"large"`. |
+| `type` | String, default: `count` | The type of the badge. Valid options are `"notification"` and `"count"`. Notification badges are orange and count badges are grey. |
+| `max-digits` | Number, default: `2` when `type="notification"`, `5` when `type="count"` | Specifies a digit limit, after which numbers are truncated. Defaults to two for `"notification"` type and five for `"count"` type. Must be between 1-5.
+| `hide-zero` | Boolean, default: `false` | Hides the count badge when `number` is zero |
+| `text` | String, required | Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled |
+| `tab-stop` | Boolean, default: `false` |  Adds a tab stop to the badge, which allows screen reader and keyboard users to easily tab to the badge |
+| `announce-changes` | Boolean, default: `false` | When `true`, changes to the badge will be announced to screen reader users |
+| `has-tooltip` | Boolean, default: `false` | Adds a tooltip on the badge, which will be visible on hover/tab-stop, and read out by screen-readers |
+| `focus-ring` | Boolean, default: `false` | Forces a focus ring around the badge. This property can be used to highlight the badge when the parent element is focused. |
 <!-- docs: end hidden content -->
+
+## Accessibility
+
+Notable accessibility features:
+- `tab-stop`:
+  - While non-interactive components traditionally shouldn't be focusable, this property greatly helps screen reader users find the the count badge, and removes the need to use the arrow keys to navigate to it
+  - This isn't needed if the optional tooltip is used, as the count-badge becomes focusable in order to display the tooltip
+- `has-tooltip`:
+  - The optional tooltip makes use of the [`d2l-tooltip`](../../components/tooltip), which follows the [W3C best practices for Tooltips](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
+  - This tooltip can help provide additional context, such as by providing the exact count badge number if it were to go above the limit set in `max-digits`
diff --git a/components/count-badge/count-badge-mixin.js b/components/count-badge/count-badge-mixin.js
@@ -16,15 +16,15 @@ export const CountBadgeMixin = superclass => class extends LocalizeCoreElement(S
 	static get properties() {
 		return {
 			/**
-			 * Optionally choose to announce changes to the badge with an aria-live region. If the number property is changed, the text will be read by screenreaders. Defaults to false.
+			 * ACCESSIBILITY: When `true`, changes to the badge will be announced to screen reader users
 			 * @type {boolean}
 			 */
 			announceChanges: {
 				type: Boolean,
 				attribute: 'announce-changes'
 			},
 			/**
-			 * Optionally choose to force the focus ring around the badge. Defaults to false.
+			 * Forces the focus ring around the badge
 			 * @type {boolean}
 			 */
 			forceFocusRing: {
@@ -33,40 +33,39 @@ export const CountBadgeMixin = superclass => class extends LocalizeCoreElement(S
 				reflect: true
 			},
 			/**
-			 * Optionally add a tooltip on the badge. Defaults to false.
+			 * ACCESSIBILITY: Adds a tooltip on the badge, which will be visible on hover and keyboard interaction
 			 * @type {boolean}
 			 */
 			hasTooltip: {
 				type: Boolean,
 				attribute: 'has-tooltip'
 			},
 			/**
-			 * Optionally choose to not render the count badge when the number is zero. Defaults to false.
+			 * Hides the count badge when `number` is zero
 			 * @type {boolean}
 			 */
 			hideZero: {
 				type: Boolean,
 				attribute: 'hide-zero'
 			},
 			/**
-			 * Optionally specify a digit limit, after which numbers are truncated.
-			 * Defaults to two for "notification" type and five for "count" type.
+			 * Specifies a digit limit, after which numbers are truncated. Defaults to two for "notification" type and five for "count" type.
 			 * @type {number}
 			 */
 			maxDigits: {
 				type: Number,
 				attribute: 'max-digits'
 			},
 			/**
-			 * REQUIRED: The number to be displayed on the badge. Must be a positive integer.
+			 * REQUIRED: The number to be displayed on the badge; must be a positive integer
 			 * @type {number}
 			 */
 			number: {
 				type: Number,
 				attribute: 'number'
 			},
 			/**
-			 * The size of the badge. Defaults to "small".
+			 * The size of the badge
 			 * @type {'small'|'large'}
 			 */
 			size: {
@@ -75,22 +74,22 @@ export const CountBadgeMixin = superclass => class extends LocalizeCoreElement(S
 				attribute: 'size'
 			},
 			/**
-			 * Optionally choose to add a tab stop to the badge. Defaults to false.
+			 * ACCESSIBILITY: Adds a tab stop to the badge, which allows screen reader and keyboard users to easily tab to the badge
 			 * @type {boolean}
 			 */
 			tabStop: {
 				type: Boolean,
 				attribute: 'tab-stop'
 			},
 			/**
-			 * REQUIRED: Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled.
+			 * ACCESSIBILITY: REQUIRED: Descriptive text for the badge which will act as an accessible label and tooltip text when tooltips are enabled
 			 * @type {string}
 			 */
 			text: {
 				type: String
 			},
 			/**
-			 * The type of the badge. Defaults to "count".
+			 * The type of the badge
 			 * @type {'count'|'notification'}
 			 */
 			type: {