From d9dda6aafb1571b08e5cc0ba3437a24a20c694f6 Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Mon, 24 Oct 2022 18:01:50 -0400 Subject: [PATCH] feat: add Dropdown a11y spec (#24917) --- ...-57716892-3a9b-4e73-b393-2585526590e5.json | 7 + .../DropdownAccessibility.stories.mdx | 326 ++++++++++++++++++ .../Dropdown/images/dropdown-click.png | Bin 0 -> 108903 bytes .../Dropdown/images/dropdown-collapsed.png | Bin 0 -> 15509 bytes .../Dropdown/images/dropdown-hover.png | Bin 0 -> 17254 bytes .../Dropdown/images/dropdown-key-select.png | Bin 0 -> 108531 bytes .../images/dropdown-multiselection1.png | Bin 0 -> 110638 bytes .../images/dropdown-multiselection2.png | Bin 0 -> 110055 bytes .../stories/Dropdown/images/dropdown-nav.png | Bin 0 -> 101333 bytes .../stories/Dropdown/images/dropdown-open.png | Bin 0 -> 110737 bytes .../Dropdown/images/dropdown-option-hover.png | Bin 0 -> 108795 bytes .../images/dropdown-selected-open.png | Bin 0 -> 106604 bytes .../Dropdown/images/dropdown-semantics.png | Bin 0 -> 112561 bytes .../Dropdown/images/dropdown-tabbing.png | Bin 0 -> 17248 bytes 14 files changed, 333 insertions(+) create mode 100644 change/@fluentui-react-combobox-57716892-3a9b-4e73-b393-2585526590e5.json create mode 100644 packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.stories.mdx create mode 100755 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-click.png create mode 100644 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-collapsed.png create mode 100755 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-hover.png create mode 100644 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-key-select.png create mode 100644 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-multiselection1.png create mode 100644 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-multiselection2.png create mode 100755 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-nav.png create mode 100755 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-open.png create mode 100755 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-option-hover.png create mode 100644 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-selected-open.png create mode 100755 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-semantics.png create mode 100755 packages/react-components/react-combobox/src/stories/Dropdown/images/dropdown-tabbing.png diff --git a/change/@fluentui-react-combobox-57716892-3a9b-4e73-b393-2585526590e5.json b/change/@fluentui-react-combobox-57716892-3a9b-4e73-b393-2585526590e5.json new file mode 100644 index 0000000000000..a59abb2604c2e --- /dev/null +++ b/change/@fluentui-react-combobox-57716892-3a9b-4e73-b393-2585526590e5.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "feat: add full Dropdown component accessibility spec", + "packageName": "@fluentui/react-combobox", + "email": "sarah.higley@microsoft.com", + "dependentChangeType": "none" +} diff --git a/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.stories.mdx b/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.stories.mdx new file mode 100644 index 0000000000000..c903d4c61667f --- /dev/null +++ b/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.stories.mdx @@ -0,0 +1,326 @@ +import { Meta } from '@storybook/addon-docs'; +import clickImg from './images/dropdown-click.png'; +import collapsedImg from './images/dropdown-collapsed.png'; +import hoverImg from './images/dropdown-hover.png'; +import keySelectImg from './images/dropdown-key-select.png'; +import multiselect1Img from './images/dropdown-multiselection1.png'; +import multiselect2Img from './images/dropdown-multiselection2.png'; +import navImg from './images/dropdown-nav.png'; +import openImg from './images/dropdown-open.png'; +import optionHoverImg from './images/dropdown-option-hover.png'; +import selectedOpenImg from './images/dropdown-selected-open.png'; +import semanticsImg from './images/dropdown-semantics.png'; +import tabbingImg from './images/dropdown-tabbing.png'; + + + +# Dropdown Accessibility Spec + +`Dropdown` is one of three form selection components that display the current selection, and allow a user to expand a popup to modify the selection. The other two are `Select` and `Combobox`. + +The semantics and behavior are roughly similar to a more complex version of the `Select` component (an HTML `` element. + +Use `Dropdown` when any of the following are required: + +- Control over styling the popup and options +- Multiple selection +- Virtualization + +Otherwise, `Select` is recommended for performance, accessibility, and native-feeling mobile support. + +#### Dropdown vs. Combobox + +`Combobox` allows text input, which enables filtering and freeform values. This is a better fit for use cases with a large number of options, or where the user may want to type a value directly without interacting with the popup. + +#### Dropdown vs. Menu + +`Select` or `Dropdown` should be used over `Menu` when creating a standalone control for selecting values. `Menu` should be used when the purpose is to allow the user to perform an immediate action on the page, or when the control is embedded within a parent `Menu`. + +Examples of appropriate `Menu` usage include: + +- Application top menus +- Context menus +- Editing menubars + +#### Multiselect Dropdown vs. Checkboxes + +Checkboxes are significantly more usable and accessible than multiselect comboboxes for smaller numbers of choices. Consider using a checkbox group over `Dropdown` if there are less than 10 options. + +### Implementing Dropdown + +#### Label + +Authors must provide label text for `Dropdown`. The recommended pattern for Fluent form controls is to use the `Label` component like this: + +```tsx + + + + + +``` + +Other options include: + +1. `aria-label="label text string"` on the `` component +2. `aria-labelledby="label-id"` on the `` component, pointing to the id of label text + +The `placeholder` prop is not a substitute for a label. It is no longer displayed when a value is selected, while labels must be persistently visible and exposed to the user. + +#### Content restrictions + +The following content types should not be used within children or slots of `Dropdown`: + +- Any interactive or focusable content, aside from `