Add usage guidance for select vs combobox vs radio (#2391)

# Pull Request

## 🤨 Rationale

I needed an example of component usage guidance for an NITech
presentation

## 👩‍💻 Implementation

Capture my understanding of when to use select, combobox, and radio in
each of their MDX files.

I moved the combobox description from storybook to mdx because it was
annoying to format large markdown strings from code.

Updated language for existing usage guidance to match new pattern.
- my secret motivation is working around a prettier bug that puts tags
near the end of a line in a new paragraph, leading to ugly docs. I
couldn't find a syntax to `prettier-ignore` in mdx files. [nor
can](prettier/prettier#12209) [other
people](https://stackoverflow.com/questions/69311134/prettier-how-to-ignore-a-single-line)

<img width="471" alt="image"
src="https://github.com/user-attachments/assets/dcfc9364-25f2-4cf1-96ee-e54b56752ad5">


## 🧪 Testing

Local storybook

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

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

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

@@ -20,9 +20,8 @@ import * as anchorButtonStories from './anchor-button.stories';
 An anchor button is a component with the visual appearance of a button, but it
 navigates like an anchor/link when pressed.
 
-If you want a button that triggers an action or event, use the
-
-<Tag name={buttonTag} /> instead.
+Consider <Tag name={buttonTag} /> if you want a button that triggers an action
+or event.
 
 <Canvas of={anchorButtonStories.outlineAnchorButton} />
 

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

@@ -13,9 +13,8 @@ Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/button/) - A button is a
 widget that enables users to trigger an action or event, such as submitting a
 form, opening a dialog, canceling an action, or performing a delete operation.
 
-If you want a button that triggers navigation to a URL, use the
-
-<Tag name={anchorButtonTag} /> instead.
+Consider <Tag name={anchorButtonTag} /> if you want a button that triggers
+navigation to a URL.
 
 <Canvas of={buttonStories.outlineButton} />
 

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

@@ -14,9 +14,8 @@ 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.
+Consider <Tag name={anchorButtonTag} /> if you want a button that triggers
+navigation to a URL.
 
 Note: The styling for the "Color" theme is not complete.
 

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

@@ -1,11 +1,21 @@
 import { Controls, Canvas, Meta, Title, Description } from '@storybook/blocks';
 import * as comboboxStories from './combobox.stories';
 import ComponentApisLink from '../../docs/component-apis-link.mdx';
+import { comboboxTag } from '../../../../nimble-components/src/combobox/';
 import { listOptionTag } from '../../../../nimble-components/src/list-option/';
+import { selectTag } from '../../../../nimble-components/src/select/';
 
 <Meta of={comboboxStories} />
 <Title of={comboboxStories} />
-<Description of={comboboxStories} />
+
+Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/), a combobox is an
+input widget that has an associated popup. The popup enables users to choose a
+value for the input from a collection. The <Tag name={comboboxTag} /> provides
+`autocomplete` options that can help a user find and select a particular value.
+
+The user can enter arbitrary values in the input area, not just those that exist
+as autocomplete options. Consider using <Tag name={selectTag} /> to limit values
+to those in the list. .
 
 <Canvas of={comboboxStories.underlineCombobox} />
 

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

@@ -89,13 +89,6 @@ const metadata: Meta<ComboboxArgs> = {
     title: 'Components/Combobox',
     decorators: [withActions<HtmlRenderer>],
     parameters: {
-        docs: {
-            description: {
-                component: `Per [W3C](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/), a combobox is an input widget that has an associated popup. The popup enables users to choose a value for the input from a collection.
-                The \`nimble-combobox\` provides 'autocomplete' options that can help a user find and select a particular value. Unlike with the \`nimble-select\` component, the \`nimble-combobox\` allows the user to enter
-                arbitrary values in the input area, not just those that exist as autocomplete options.`
-            }
-        },
         actions: {
             handles: ['change', 'input']
         },

packages/storybook/src/nimble/radio-group/radio-group.mdx

@@ -1,6 +1,7 @@
 import { Controls, Canvas, Meta, Title } from '@storybook/blocks';
 import * as radioGroupStories from './radio-group.stories';
 import ComponentApisLink from '../../docs/component-apis-link.mdx';
+import { selectTag } from '../../../../nimble-components/src/select';
 
 <Meta of={radioGroupStories} />
 <Title of={radioGroupStories} />
@@ -11,6 +12,9 @@ buttons can be checked at a time. Some implementations may initialize the set
 with all buttons in the unchecked state in order to force the user to check one
 of the buttons before moving past a certain point in the workflow.
 
+Consider using <Tag name={selectTag} /> if there are many options to select
+from.
+
 <Canvas of={radioGroupStories.radioGroup} />
 
 ## API

packages/storybook/src/nimble/select/select.mdx

@@ -4,15 +4,22 @@ import * as selectStories from './select.stories';
 import * as listOptionStories from '../list-option/list-option.stories';
 import * as listOptionGroupStories from '../list-option-group/list-option-group.stories';
 import ComponentApisLink from '../../docs/component-apis-link.mdx';
+import { comboboxTag } from '../../../../nimble-components/src/combobox';
 import { listOptionTag } from '../../../../nimble-components/src/list-option';
 import { listOptionGroupTag } from '../../../../nimble-components/src/list-option-group';
+import { radioTag } from '../../../../nimble-components/src/radio';
 
 <Meta of={selectStories} />
 <Title of={selectStories} />
 
 Select is a control for selecting amongst a set of options. Upon clicking on the
 element, the other options are visible in a dropdown.
 
+Consider using <Tag name={radioTag} /> to select from a small set of options.
+
+Consider using <Tag name={comboboxTag} /> to allow the user to enter a custom
+value.
+
 <Canvas of={selectStories.select} />
 
 ## API

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

@@ -17,9 +17,8 @@ content at a time. Each tab panel has an associated tab element, that when
 activated, displays the panel. The list of tab elements is arranged along one
 edge of the currently displayed panel, most commonly the top edge.
 
-If you want a sequence of tabs that navigate to different URLs, use the
-
-<Tag name={anchorTabsTag} /> instead.
+Consider <Tag name={anchorTabsTag} /> if you want a sequence of tabs that
+navigate to different URLs.
 
 <Canvas of={tabsStories.tabs} />