feat: Dropdown a11y overview section

change/@fluentui-react-combobox-b89a40be-4811-4450-b226-2355943843f7.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "feat: add Accessibility section to Dropdown docs page",
+  "packageName": "@fluentui/react-combobox",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md

@@ -0,0 +1,21 @@
+<details>
+<summary>
+ Accessibility
+</summary>
+
+### Do
+
+- **Provide a label for the Dropdown.** This can be done either by using the `DropdownField` component with a `label` prop, or by using a [custom labelling technique](#TODO).
+- **Consider using Select or a Checkbox group.** For simple single-select use cases, consider using `Select` for better accessibility and mobile support. For simple multiselect use cases with less than 10 options, consider using a group of `Checkbox` components.
+- **Consider using `Dropdown` with outline or underline appearances.** When the contrast ratio against the immediate surrounding color is less than 3:1, consider using underline or outline styles which has a bottom border stroke. But please ensure the color of bottom border stroke has a sufficient contrast which is greater than 3 to 1 against the immediate surrounding color.
+- **Set `inlinePopup={true}` when possible for better VoiceOver support.** The `inlinePopup` prop will cause the listbox popup to be rendered immediately after the button in the DOM. Safari does not support `aria-owns`, so this enables iOS VoiceOver swipe navigation between the button and options.
+- **Review [known accessiblity issues](./?path=/docs/concepts-developer-accessibility-components-dropdown--page).**
+
+### Don't
+
+- **Don't nest interactive controls in Dropdown slots or children.** The `Dropdown`'s `button` slot and children of `<Option>` components will not expose nested interactive elements to screen reader users, and additional non-`Option` children in the `listbox` slot will not be keyboard accessible.
+- **Don’t place the Dropdown button on a surface which doesn’t have a sufficient contrast.** The colors adjacent to the input should have a sufficient contrast. Particularly, the color of input with filled darker and lighter styles needs to provide greater than 3 to 1 contrast ratio against the immediate surrounding color to pass accessibility requirements.
+
+Read the [Dropdown accessibility spec](./?path=/docs/concepts-developer-accessibility-components-dropdown--page) for more detailed information, as well as full descriptions of semantics and keyboard behavior.
+
+</details>

packages/react-components/react-combobox/src/stories/Dropdown/DropdownBestPractices.md

@@ -5,9 +5,12 @@
 
 ### Do
 
+- **Provide a label for the Dropdown.**
+- **Set the Option's `value` prop if the content contains JSX.** The Option value is used for keyboard accessibility to enable users to type a letter or string and jump to the matching option. The value is calculated from the children by default, but if the Option contains JSX, the `value` prop should be used to directly provide a string value.
 - **Consider using `Dropdown` with outline or underline appearances.** When the contrast ratio against the immediate surrounding color is less than 3:1, consider using underline or outline styles which has a bottom border stroke. But please ensure the color of bottom border stroke has a sufficient contrast which is greater than 3 to 1 against the immediate surrounding color.
 
 ### Don't
 
-- **Don’t place the Dropdown button on a surface which doesn’t have a sufficient contrast.** The colors adjacent to the input should have a sufficient contrast. Particularly, the color of input with filled darker and lighter styles needs to provide greater than 3 to 1 contrast ratio against the immediate surrounding color to pass accessibility requirements.
+- **Use `placeholder` for label text.** Placeholder text has lower contrast than label text, and disappears once an option is selected. If used, it should only contain temporary filler text.
+
 </details>

packages/react-components/react-combobox/src/stories/Dropdown/index.stories.tsx

@@ -3,6 +3,7 @@ import { Dropdown } from '@fluentui/react-combobox';
 
 import descriptionMd from './DropdownDescription.md';
 import bestPracticesMd from './DropdownBestPractices.md';
+import accessibilityMd from './DropdownAccessibility.md';
 
 export { Default } from './DropdownDefault.stories';
 
@@ -12,7 +13,7 @@ export default {
   parameters: {
     docs: {
       description: {
-        component: [descriptionMd, bestPracticesMd].join('\n'),
+        component: [descriptionMd, bestPracticesMd, accessibilityMd].join('\n'),
       },
     },
   },