Per-component accessibility doc updates

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"
+}

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.

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" />

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: {

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' />

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.

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).

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;

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" />

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: {

packages/nimble-components/src/patterns/button/tests/content-hidden-docs.mdx

@@ -0,0 +1,3 @@
+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.

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.
@@ -28,6 +29,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 +44,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.  

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

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.

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" />

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: {

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: {