Improve API docs for buttons and improve overall doc consistency (#2117)

# Pull Request

## 🤨 Rationale

As part of #824 we want to improve the accuracy and comprehensiveness of
our storybook API documentation.

## 👩‍💻 Implementation

1. Update `button`, `toggle-button`, and `card-button` to follow new API
doc pattern. (I'll do `anchor-button` along with other anchors).
2. Add and tweak wording on shared documentation strings and utilities
3. Tweak organization of MDX headings in all stories to put Appearance
and Sizing under Styling
4. Add CONTRIBUTING guidance about referring to sections within docs (in
previous PRs we gave up on trying to link to sections and started using
bolded text instead).

## 🧪 Testing

Local storybook exploration

## ✅ Checklist

<!--- Review the list and put an x in the boxes that apply or ~~strike
through~~ around items that don't (along with an explanation). -->

- [ ] I have updated the project documentation to reflect my changes or
determined no changes are needed.

---------

Co-authored-by: Milan Raj <[email protected]>

packages/storybook/CONTRIBUTING.md

@@ -46,11 +46,15 @@ import * as componentNameStories from './component-name.stories';
 <Controls of={componentNameStories.firstStoryName} />
 <ComponentApisLink />
 
-## Appearances
+## Usage
 
-## Appearance Variants
+## Styling
 
-## Usage 
+### Appearances
+
+### Appearance Variants
+
+### Sizing
 
 ## Examples
 
@@ -79,6 +83,8 @@ Note: if linking in a story via a native or Nimble anchor component, use the fol
 <a href="./?path=/docs/some--id" target="_top">Link</a>
 ```
 
+Linking to headings within a document doesn't work very well, i.e. `./page#some-heading`; avoid using links to specific headings and instead link to the page and refer to the section using **Bold**, i.e. `See **Some Heading** on [Page](./page)`.
+
 All other Markdown formatting is supported. See any [Markdown Cheatsheet](https://www.markdownguide.org/cheat-sheet/) for more information.
 
 ### Testing 

packages/storybook/src/nimble/anchor-button/anchor-button.mdx

@@ -20,6 +20,8 @@ An anchor button is a component with the visual appearance of a button, but it n
 <Canvas of={anchorButtonStories.outlineAnchorButton} />
 <Controls of={anchorButtonStories.outlineAnchorButton} />
 
+## Styling
+
 <StylingDocs components={{ Button: anchorButtonTag }} />
 
 {/* ## Usage */}

packages/storybook/src/nimble/anchor-button/anchor-button.stories.ts

@@ -8,6 +8,7 @@ import {
     ButtonAppearanceVariant
 } from '@ni/nimble-components/dist/esm/patterns/button/types';
 import {
+    appearanceDescription,
     appearanceVariantDescription,
     contentHiddenDescription,
     endIconDescription,
@@ -56,7 +57,8 @@ const metadata: Meta<AnchorButtonArgs> = {
         },
         appearance: {
             options: Object.keys(ButtonAppearance),
-            control: { type: 'radio' }
+            control: { type: 'radio' },
+            description: appearanceDescription
         },
         appearanceVariant: {
             name: 'appearance-variant',

packages/storybook/src/nimble/anchor-tabs/anchor-tabs.mdx

@@ -14,9 +14,7 @@ tab panels hosted on the same page.
 <Canvas of={anchorTabsStories.anchorTabs} />
 <Controls of={anchorTabsStories.anchorTabs} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/anchor/anchor.mdx

@@ -10,9 +10,7 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/link/), an anchor/link widget
 <Canvas of={anchorStories.anchor} />
 <Controls of={anchorStories.anchor} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/anchored-region/anchored-region.mdx

@@ -17,9 +17,7 @@ available space, or even resize itself based on that space.
 <Canvas of={anchoredRegionStories.anchoredRegion} />
 <Controls of={anchoredRegionStories.anchoredRegion} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/banner/banner.mdx

@@ -16,9 +16,7 @@ should be spaced apart using the <code>{bannerGapSize.cssCustomProperty}</code>
 <Canvas of={bannerStories._banner} />
 <Controls of={bannerStories._banner} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/breadcrumb/breadcrumb.mdx

@@ -15,9 +15,7 @@ for information on using this component in Angular with RouterLink directives.
 <Controls of={breadcrumbStories._standardBreadcrumb} />
 <Stories of={breadcrumbStories} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/button/button.mdx

@@ -1,6 +1,7 @@
 import { Canvas, Meta, Controls, Title } from '@storybook/blocks';
 import ContentHiddenDocs from '../patterns/button/content-hidden-docs.mdx';
 import StylingDocs from '../patterns/button/styling-docs.mdx';
+import ComponentApisLink from '../../docs/component-apis-link.mdx';
 import { buttonTag } from '@ni/nimble-components/dist/esm/button';
 import { anchorButtonTag } from '@ni/nimble-components/dist/esm/anchor-button';
 import * as buttonStories from './button.stories';
@@ -15,17 +16,27 @@ action, or performing a delete operation.
 If you want a button that triggers navigation to a URL, use the <Tag name={anchorButtonTag}/> instead.
 
 <Canvas of={buttonStories.outlineButton} />
+
+## API
+
 <Controls of={buttonStories.outlineButton} />
 
+<ComponentApisLink />
+
+## Styling
+
 <StylingDocs components={{ Button: buttonTag }} />
 
-## Sizing
+### Sizing
 
 Nimble Buttons are currently always 32px tall. Designs exist for other sizes; if you need these in an application, please comment on [Configurable height for nimble controls (#610)](https://github.com/ni/nimble/issues/610).
 
-## Accessibility
+{/* ## Usage */}
+
+{/* ## Examples */}
 
-Please work with your designer and ensure you have a 4.5:1
-contrast ratio text to background.
+## Accessibility
 
 <ContentHiddenDocs buttonElement="nimble-button" />
+
+{/* ## Resources */}

packages/storybook/src/nimble/button/button.stories.ts

@@ -10,9 +10,10 @@ import {
     appearanceVariantDescription,
     contentHiddenDescription,
     endIconDescription,
-    iconDescription
+    iconDescription,
+    textContentDescription
 } from '../patterns/button/doc-strings';
-import { createUserSelectedThemeStory } from '../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory, disabledDescription } from '../../utilities/storybook';
 
 interface ButtonArgs {
     label: string;
@@ -22,6 +23,7 @@ interface ButtonArgs {
     icon: boolean;
     contentHidden: boolean;
     endIcon: boolean;
+    click: undefined;
 }
 
 const metadata: Meta<ButtonArgs> = {
@@ -36,22 +38,45 @@ const metadata: Meta<ButtonArgs> = {
         appearance: {
             options: Object.keys(ButtonAppearance),
             control: { type: 'radio' },
-            description: appearanceDescription
+            description: appearanceDescription,
+            table: { category: apiCategory.attributes }
         },
         appearanceVariant: {
             name: 'appearance-variant',
             options: Object.keys(ButtonAppearanceVariant),
             control: { type: 'radio' },
-            description: appearanceVariantDescription
+            description: appearanceVariantDescription,
+            table: { category: apiCategory.attributes }
         },
         contentHidden: {
-            description: contentHiddenDescription
+            name: 'content-hidden',
+            description: contentHiddenDescription,
+            table: { category: apiCategory.attributes }
+        },
+        disabled: {
+            description: disabledDescription({ componentName: 'button' }),
+            table: { category: apiCategory.attributes }
+        },
+        label: {
+            name: 'default',
+            description: textContentDescription({ componentName: 'button' }),
+            table: { category: apiCategory.slots }
         },
         icon: {
-            description: iconDescription
+            name: 'start',
+            description: iconDescription,
+            table: { category: apiCategory.slots }
         },
         endIcon: {
-            description: endIconDescription
+            name: 'end',
+            description: endIconDescription,
+            table: { category: apiCategory.slots }
+        },
+        click: {
+            description:
+                'Fires when the button is activated by either keyboard or mouse.',
+            table: { category: apiCategory.events },
+            control: false
         }
     },
     // prettier-ignore

packages/storybook/src/nimble/card-button/card-button.mdx

@@ -1,5 +1,6 @@
 import { Canvas, Meta, Controls, Title } from '@storybook/blocks';
 import { NimbleCardButton } from './card-button.react';
+import { anchorButtonTag } from '@ni/nimble-components/dist/esm/anchor-button';
 import { cardButtonTag } from '@ni/nimble-components/dist/esm/card-button';
 import { buttonTag } from '@ni/nimble-components/dist/esm/button';
 import * as cardButtonStories from './card-button.stories';
@@ -10,14 +11,17 @@ import * as cardButtonStories from './card-button.stories';
 The <Tag name={cardButtonTag}/> is a button that is designed to contain arbitrary content that is specified by a client
 application. The <Tag name={cardButtonTag}/> is intended to be larger and more prominent on a page than the standard <Tag name={buttonTag}/>.
 
+If you want a button that triggers navigation to a URL, use the <Tag name={anchorButtonTag}/> instead.
+
 Note: The styling for the "Color" theme is not complete.
 
 <Canvas of={cardButtonStories.cardButton} />
-<Controls of={cardButtonStories.cardButton} />
 
-{/* ## Appearances */}
+## API
+
+<Controls of={cardButtonStories.cardButton} />
 
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/card-button/card-button.stories.ts

@@ -3,11 +3,13 @@ import { withActions } from '@storybook/addon-actions/decorator';
 import type { HtmlRenderer, Meta, StoryObj } from '@storybook/html';
 import { bodyFont } from '@ni/nimble-components/dist/esm/theme-provider/design-tokens';
 import { cardButtonTag } from '@ni/nimble-components/dist/esm/card-button';
-import { createUserSelectedThemeStory } from '../../utilities/storybook';
+import { apiCategory, createUserSelectedThemeStory, disabledDescription } from '../../utilities/storybook';
 
 interface CardButtonArgs {
     disabled: boolean;
     selected: boolean;
+    content: string;
+    click: undefined;
 }
 
 const metadata: Meta<CardButtonArgs> = {
@@ -52,6 +54,28 @@ const metadata: Meta<CardButtonArgs> = {
     args: {
         disabled: false,
         selected: false
+    },
+    argTypes: {
+        disabled: {
+            description: disabledDescription({ componentName: 'card button' }),
+            table: { category: apiCategory.attributes }
+        },
+        selected: {
+            description: 'Styles the card button to indicate it is selected.',
+            table: { category: apiCategory.attributes }
+        },
+        content: {
+            name: 'default',
+            description: 'The card button allows arbitrary HTML child content in its default slot.',
+            table: { category: apiCategory.slots },
+            control: false
+        },
+        click: {
+            description:
+                'Fires when the card button is activated by either keyboard or mouse.',
+            table: { category: apiCategory.events },
+            control: false
+        }
     }
 };
 

packages/storybook/src/nimble/card/card.mdx

@@ -12,9 +12,7 @@ application. The <Tag name={cardTag} /> is intended for grouping related content
 <Canvas of={cardStories.card} />
 <Controls of={cardStories.card} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/checkbox/checkbox.mdx

@@ -10,9 +10,7 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) - The dual-state c
 <Canvas of={checkboxStories.checkbox} />
 <Controls of={checkboxStories.checkbox} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/combobox/combobox.mdx

@@ -9,9 +9,7 @@ import { listOptionTag } from '@ni/nimble-components/dist/esm/list-option/';
 <Canvas of={comboboxStories.underlineCombobox} />
 <Controls of={comboboxStories.underlineCombobox} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/dialog/dialog.mdx

@@ -11,11 +11,9 @@ By default, the first focusable control gets focus when the dialog is opened. To
 <Canvas of={dialogStories.dialog} />
 <Controls of={dialogStories.dialog} />
 
-{/* ## Appearances */}
+## Styling
 
-{/* ## Appearance Variants */}
-
-## Sizing
+### Sizing
 
 The dialog size can be customized by modyfing the width, height and max-height properties of `nimble-dialog::part(control)`.
 

packages/storybook/src/nimble/dialog/dialog.stories.ts

@@ -61,7 +61,7 @@ const content = {
 const sizeDescription = `
 Size of a nimble dialog.
 
-See the Sizing section of the Usage Docs for information on controlling the size of the dialog.
+See the **Sizing** section for information on controlling the size of the dialog.
 `;
 
 const widths = {

packages/storybook/src/nimble/drawer/drawer.mdx

@@ -9,9 +9,7 @@ Specialized dialog designed to slide in from either side of the page. Typically
 <Canvas of={drawerStories.drawer} />
 <Controls of={drawerStories.drawer} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/icon-base/icons.mdx

@@ -10,9 +10,7 @@ Nimble icons can be slotted into other components or used independently. Each ic
 <Canvas of={iconsStories.icons} />
 <Controls of={iconsStories.icons} />
 
-{/* ## Appearances */}
-
-{/* ## Appearance Variants */}
+{/* ## Styling */}
 
 {/* ## Usage */}
 

packages/storybook/src/nimble/menu-button/menu-button.mdx

@@ -19,6 +19,8 @@ often styled as a typical push button with a downward pointing arrow or triangle
 
 <ComponentApisLink />
 
+## Styling
+
 <StylingDocs components={{ Button: menuButtonTag }} />
 
 {/* ## Usage */}