diff --git a/change/@fluentui-react-combobox-b89a40be-4811-4450-b226-2355943843f7.json b/change/@fluentui-react-combobox-b89a40be-4811-4450-b226-2355943843f7.json new file mode 100644 index 00000000000000..5df7d8a04598ea --- /dev/null +++ b/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": "sarah.higley@microsoft.com", + "dependentChangeType": "none" +} diff --git a/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md b/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md new file mode 100644 index 00000000000000..04c6e0993150cc --- /dev/null +++ b/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md @@ -0,0 +1,21 @@ +
+ + Accessibility + + +### 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 labeling technique](#TODO). +- **Use Dropdown when you need JSX or styled options, otherwise use Select.** For simple single-select use cases, consider using `Select` for better accessibility and mobile support. +- **Use multi-select Dropdown when you have 10+ options, otherwise use a Checkbox group.** For simple multiselect use cases with less than 10 options, consider using a group of `Checkbox` components. +- **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 `
diff --git a/packages/react-components/react-combobox/src/stories/Dropdown/DropdownBestPractices.md b/packages/react-components/react-combobox/src/stories/Dropdown/DropdownBestPractices.md index 5b6f5e0c7416df..aa55cc93d95e6b 100644 --- a/packages/react-components/react-combobox/src/stories/Dropdown/DropdownBestPractices.md +++ b/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. + diff --git a/packages/react-components/react-combobox/src/stories/Dropdown/index.stories.tsx b/packages/react-components/react-combobox/src/stories/Dropdown/index.stories.tsx index f23b63408f70ed..44df3ae174c3b1 100644 --- a/packages/react-components/react-combobox/src/stories/Dropdown/index.stories.tsx +++ b/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'), }, }, },