Per-component accessibility doc updates (#1388)

# Pull Request ## 🤨 Rationale Resolves #1090 In [PR discussion on #1272](#1272 (comment)), we decided that the per-component accessibility notes would be better documented in Storybook (by the other component docs), instead of in accessibility.md. Resolves #1393 ## 👩‍💻 Implementation For components with accessibility notes not already documented in Storybook: - Create an mdx docs page for them, if it wasn't already present. Based on PR comments on the recent PR by Jesse, I think this is the general direction we're going for component docs. - Add a Usage Docs / Accessibility section at the bottom, and add the notes from accessibility.md. The button/spinner mdx have these sections, so again following the existing patterns. ## 🧪 Testing Manual verification in Storybook. ## ✅ Checklist - [x] I have updated the project documentation to reflect my changes or determined no changes are needed.
ni · Jul 27, 2023 · 0eaa7f3 · 0eaa7f3
1 parent 3b4aafc
commit 0eaa7f3
Show file tree

Hide file tree

Showing 17 changed files with 139 additions and 43 deletions.
diff --git a/change/@ni-nimble-components-f0feaca4-ded2-4e5c-bc9c-97420f643497.json b/change/@ni-nimble-components-f0feaca4-ded2-4e5c-bc9c-97420f643497.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Update component accessibility docs in Storybook",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}
diff --git a/packages/nimble-components/docs/accessibility.md b/packages/nimble-components/docs/accessibility.md
@@ -23,21 +23,3 @@ export const template = html<CoolNewButton>`
 
 ## Setting ARIA attributes
 When setting [ARIA attributes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes) on nimble components, avoid using id-based attributes, such as `aria-labelledby`. The id-based attributes may not behave as expected when used with Shadow DOM components, such as `nimble`.
-
-# Component-specific accessiblity notes
-
-## Buttons
-`nimble-button`, `nimble-anchor-button`, `nimble-menu-button`, `nimble-toggle-button`
-
-When using the Nimble buttons with only an icon, `contentHidden` should be set to `true` and text content should be provided within the button even though it will not be visible on the screen. The button will use the text content to configure the appropriate ARIA attributes internally to ensure the button is adequately accessible with a screen reader.
-
-## nimble-banner
-When using `nimble-banner`, the title content should always be provided for accessibility. To hide the title visually, `titleHidden` can be set to `true`.
-
-## nimble-dialog
-When using `nimble-dialog`, the title content should always be provided for accessibility. To hide the title visually, `headerHidden` can be set to `true`.
-
-## Icons
-When using an icon standalone, the `title` attribute should usually be set, to provide accessible text (which will also show as a tooltip).
-
-When using an icon as the content of a Nimble button, place the icon in the `start` slot, and follow the button guidance above.
diff --git a/packages/nimble-components/src/anchor-button/tests/anchor-button.mdx b/packages/nimble-components/src/anchor-button/tests/anchor-button.mdx
@@ -0,0 +1,24 @@
+import {
+    Controls,
+    DocsStory,
+    Meta,
+    Stories,
+    Title,
+    Description
+} from '@storybook/blocks';
+import ContentHiddenDocs from '../../patterns/button/tests/content-hidden-docs.mdx';
+import * as anchorButtonStories from './anchor-button.stories';
+
+<Meta of={anchorButtonStories} />
+
+<Title of={anchorButtonStories} />
+<Description of={anchorButtonStories} />
+
+<DocsStory of={anchorButtonStories.outlineAnchorButton} expanded={false} />
+<Controls of={anchorButtonStories.outlineAnchorButton} />
+
+# Usage Docs
+
+## Accessibility
+
+<ContentHiddenDocs buttonElement="nimble-anchor-button" />
diff --git a/packages/nimble-components/src/anchor-button/tests/anchor-button.stories.ts b/packages/nimble-components/src/anchor-button/tests/anchor-button.stories.ts
@@ -32,7 +32,6 @@ interface AnchorButtonArgs {
 
 const metadata: Meta<AnchorButtonArgs> = {
     title: 'Components/Anchor Button',
-    tags: ['autodocs'],
     parameters: {
         docs: {
             description: {

diff --git a/packages/nimble-components/src/button/tests/button.mdx b/packages/nimble-components/src/button/tests/button.mdx
@@ -1,21 +1,22 @@
 import {
-    Canvas,
+    DocsStory,
     Meta,
     Controls,
+    Primary,
     Stories,
     Title,
     Description
 } from '@storybook/blocks';
+import ContentHiddenDocs from '../../patterns/button/tests/content-hidden-docs.mdx';
 import * as buttonStories from './button.stories';
 
 <Meta of={buttonStories} />
 
 <Title of={buttonStories} />
 <Description of={buttonStories} />
 
-<Canvas of={buttonStories.outlineButton} />
+<DocsStory of={buttonStories.outlineButton} expanded={false} />
 <Controls of={buttonStories.outlineButton} />
-<Stories of={buttonStories} />
 
 # Usage Docs
 
@@ -35,3 +36,5 @@ import * as buttonStories from './button.stories';
 
     Please work with your designer and ensure you have a 4.5:1
     contrast ratio text to background.
+
+    <ContentHiddenDocs buttonElement='nimble-button' />
diff --git a/packages/nimble-components/src/checkbox/tests/checkbox.stories.ts b/packages/nimble-components/src/checkbox/tests/checkbox.stories.ts
@@ -38,6 +38,7 @@ const metadata: Meta<CheckboxArgs> = {
     argTypes: {
         indeterminate: {
             description: `Whether the checkbox is in the indeterminate (i.e. partially checked) state. Configured programmatically, not by attribute.
+
 <details>
 <summary>Usage details</summary>
 The \`indeterminate\` state is not automatically changed when the user changes the \`checked\` state. Client applications that use \`indeterminate\` state are responsible for subscribing to the \`change\` event to respond to this situation.

diff --git a/packages/nimble-components/src/icon-base/tests/icons.mdx b/packages/nimble-components/src/icon-base/tests/icons.mdx
@@ -0,0 +1,24 @@
+import {
+    Meta,
+    Controls,
+    DocsStory,
+    Title,
+    Description
+} from '@storybook/blocks';
+import * as iconsStories from './icons.stories';
+
+<Meta of={iconsStories} />
+
+<Title of={iconsStories} />
+<Description of={iconsStories} />
+
+<DocsStory of={iconsStories.icons} expanded={false} />
+<Controls of={iconsStories.icons} />
+
+# Usage Docs
+
+<br />
+
+## Accessibility
+
+When using an icon standalone, the `title` attribute should usually be set, to provide accessible text (which will also show as a tooltip).
diff --git a/packages/nimble-components/src/icon-base/tests/icons.stories.ts b/packages/nimble-components/src/icon-base/tests/icons.stories.ts
@@ -20,8 +20,7 @@ interface IconArgs {
 }
 
 const metadata: Meta<IconArgs> = {
-    title: 'Components/Icons',
-    tags: ['autodocs']
+    title: 'Components/Icons'
 };
 
 export default metadata;

diff --git a/packages/nimble-components/src/menu-button/tests/menu-button.mdx b/packages/nimble-components/src/menu-button/tests/menu-button.mdx
@@ -0,0 +1,23 @@
+import {
+    Controls,
+    DocsStory,
+    Meta,
+    Stories,
+    Title,
+    Description
+} from '@storybook/blocks';
+import ContentHiddenDocs from '../../patterns/button/tests/content-hidden-docs.mdx';
+import * as menuButtonStories from './menu-button.stories';
+
+<Meta of={menuButtonStories} />
+<Title of={menuButtonStories} />
+<Description of={menuButtonStories} />
+
+<DocsStory of={menuButtonStories.outlineButton} expanded={false} />
+<Controls of={menuButtonStories.outlineButton} />
+
+# Usage Docs
+
+## Accessibility
+
+<ContentHiddenDocs buttonElement="nimble-menu-button" />
diff --git a/packages/nimble-components/src/menu-button/tests/menu-button.stories.ts b/packages/nimble-components/src/menu-button/tests/menu-button.stories.ts
@@ -33,7 +33,6 @@ This icon will be hidden when \`contentHidden\` is set to \`true\`
 
 const metadata: Meta<MenuButtonArgs> = {
     title: 'Components/Menu Button',
-    tags: ['autodocs'],
     decorators: [withActions],
     parameters: {
         docs: {

diff --git a/packages/nimble-components/src/patterns/button/tests/content-hidden-docs.mdx b/packages/nimble-components/src/patterns/button/tests/content-hidden-docs.mdx
@@ -0,0 +1,6 @@
+When using the <code>{props.buttonElement}</code> with only an icon:
+
+-   Add the <code>{props.contentHiddenAttribute ?? 'content-hidden'}</code>
+    attribute and provide text content within the button even though it will not be visible on the screen. The button will use the text content
+    to configure the appropriate ARIA attributes internally to ensure the button is adequately accessible with a screen reader.
+-   Consider providing a tooltip to provide extra information (with the `title` attribute).
diff --git a/packages/nimble-components/src/patterns/button/tests/doc-strings.ts b/packages/nimble-components/src/patterns/button/tests/doc-strings.ts
@@ -3,6 +3,7 @@ export const appearanceDescription = `This attribute affects the appearance of t
 <details>
     <summary>Appearance Usage</summary>
     There is a hierarchy to which button appearance should be used.
+
     <ul>
         <li>For appearance \`ghost\`:
             <br/>This is the default and standard option for buttons. They create an open / airy feel, and fit comfortably in tight spaces.
@@ -13,7 +14,8 @@ export const appearanceDescription = `This attribute affects the appearance of t
         <li>For appearance \`outline\`:
             <br/>This is an alternative standard button when a ghost button is not suitable, and a more visually direct button is needed. 
             <br/>This can also create a light and airy feel. Use in combination with ghost buttons to create hierarchy. Do not use in combination with block buttons.
-        </li>                
+        </li>
+        <br/>
         <li>For appearance \`block\`:
             <br/>This standard button should be used when the most visible solution is required. 
             <br/>It can be an alternative to overly subtle button solutions when it is important to emphasize an action and the functionality of the control.
@@ -28,6 +30,7 @@ export const appearanceVariantDescription = `This attribute has no effect on but
 <details>
     <summary>Primary Button Usage</summary>
     Make a button primary to distinguish it visibly for one of the following reasons:
+
     <ul>
         <li>to indicate the action that allows the user to accomplish their most common or important goal</li>
         <li>to indicate the action that allows the user to complete their task</li>
@@ -42,6 +45,7 @@ export const iconDescription = `When including an icon, set \`slot="start"\` on
 <details>
     <summary>Icon Usage</summary>
     Icons should be consistent and only used when necessary.
+
     <ul>
         <li>Icon and text buttons: 
             <br/>Use a label plus icon to help reinforce a button's functionality, and increase the visual impact of the action.  

diff --git a/packages/nimble-components/src/spinner/tests/spinner.mdx b/packages/nimble-components/src/spinner/tests/spinner.mdx
@@ -1,5 +1,5 @@
 import {
-    Canvas,
+    DocsStory,
     Meta,
     Controls,
     Stories,
@@ -13,7 +13,7 @@ import * as spinnerStories from './spinner.stories';
 <Title of={spinnerStories} />
 <Description of={spinnerStories} />
 
-<Canvas of={spinnerStories.spinner} />
+<DocsStory of={spinnerStories.spinner} expanded={false} />
 <Controls of={spinnerStories.spinner} />
 
 # Usage Docs

diff --git a/packages/nimble-components/src/spinner/tests/spinner.stories.ts b/packages/nimble-components/src/spinner/tests/spinner.stories.ts
@@ -41,7 +41,7 @@ const metadata: Meta<SpinnerArgs> = {
     argTypes: {
         size: {
             description:
-                'Size of the spinner component.<details><summary>Usage details</summary>To customize its size, set its CSS '
+                '<p>Size of the spinner component.</p><details><summary>Usage details</summary>To customize its size, set its CSS '
                 + '<span style="font-family: monospace;">height</span> to a design token, and its width will automatically match its height. Each size will also require minimum pixel margins.<br/><ul>'
                 + `<li>For Small (16x16): ${scssPropertySetterMarkdown(
                     tokenNames.spinnerSmallHeight,
@@ -82,7 +82,7 @@ const metadata: Meta<SpinnerArgs> = {
             options: Object.keys(SpinnerAppearance),
             control: { type: 'radio' },
             description:
-                'Appearance of the spinner component.<details><summary>Usage details</summary>'
+                '<p>Appearance of the spinner component.</p><details><summary>Usage details</summary>'
                 + '<ul>'
                 + `<li>For appearance \`default\`:<br/>
                         Use in product instances.  This version helps avoid any association to status and the idea that this indicator is representing any context outside of an indeterminate wait time.

diff --git a/packages/nimble-components/src/toggle-button/tests/toggle-button.mdx b/packages/nimble-components/src/toggle-button/tests/toggle-button.mdx
@@ -0,0 +1,23 @@
+import {
+    Controls,
+    DocsStory,
+    Meta,
+    Stories,
+    Title,
+    Description
+} from '@storybook/blocks';
+import ContentHiddenDocs from '../../patterns/button/tests/content-hidden-docs.mdx';
+import * as toggleButtonStories from './toggle-button.stories';
+
+<Meta of={toggleButtonStories} />
+<Title of={toggleButtonStories} />
+<Description of={toggleButtonStories} />
+
+<DocsStory of={toggleButtonStories.outlineButton} expanded={false} />
+<Controls of={toggleButtonStories.outlineButton} />
+
+# Usage Docs
+
+## Accessibility
+
+<ContentHiddenDocs buttonElement="nimble-toggle-button" />
diff --git a/packages/nimble-components/src/toggle-button/tests/toggle-button.stories.ts b/packages/nimble-components/src/toggle-button/tests/toggle-button.stories.ts
@@ -30,7 +30,6 @@ screen reader would say something like "Mute toggle button pressed".`;
 
 const metadata: Meta<ToggleButtonArgs> = {
     title: 'Components/Toggle Button',
-    tags: ['autodocs'],
     decorators: [withActions],
     parameters: {
         docs: {

diff --git a/packages/nimble-components/src/wafer-map/tests/wafer-map.stories.ts b/packages/nimble-components/src/wafer-map/tests/wafer-map.stories.ts
@@ -140,10 +140,11 @@ const metadata: Meta<WaferMapArgs> = {
     argTypes: {
         colorScale: {
             description: `Represents the color spectrum which shows the status of the dies on the wafer.
-                <details>
-                    <summary>Usage details</summary>
-                    The \`colorScale\` element is a public property. As such, it is not available as an attribute, however it can be read or set on the corresponding \`WaferMap\` DOM element.
-                </details>
+
+<details>
+    <summary>Usage details</summary>
+    The \`colorScale\` element is a public property. As such, it is not available as an attribute, however it can be read or set on the corresponding \`WaferMap\` DOM element.
+</details>
                 `,
             options: ['set1'],
             control: {
@@ -172,10 +173,11 @@ const metadata: Meta<WaferMapArgs> = {
         },
         dies: {
             description: `Represents the input data, an array of \`WaferMapDie\`, which will be rendered by the wafer map
-                <details>
-                    <summary>Usage details</summary>
-                    The \`dies\` element is a public property. As such, it is not available as an attribute, however it can be read or set on the corresponding \`WaferMap\` DOM element.
-                </details>
+
+<details>
+    <summary>Usage details</summary>
+    The \`dies\` element is a public property. As such, it is not available as an attribute, however it can be read or set on the corresponding \`WaferMap\` DOM element.
+</details>
                 `,
             options: [
                 'fixedDies10',
@@ -208,10 +210,11 @@ const metadata: Meta<WaferMapArgs> = {
         },
         highlightedValues: {
             description: `Represents an array of die indexes that will be highlighted in the wafer map view
-                <details>
-                    <summary>Usage details</summary>
-                    The \`highlightedValues\` element is a public property. As such, it is not available as an attribute, however it can be read or set on the corresponding \`WaferMap\` DOM element.
-                </details>
+
+<details>
+    <summary>Usage details</summary>
+    The \`highlightedValues\` element is a public property. As such, it is not available as an attribute, however it can be read or set on the corresponding \`WaferMap\` DOM element.
+</details>
                 `,
             options: ['set1', 'set2', 'set3', 'set4'],
             control: {