From 0e80f7fe6b68f0b7b432a11fdea4b63ef5115cd7 Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Fri, 23 Sep 2022 14:28:57 -0700 Subject: [PATCH 1/4] feat: add Accessibility section to Dropdown docs page --- .../stories/Dropdown/DropdownAccessibility.md | 21 +++++++++++++++++++ .../stories/Dropdown/DropdownBestPractices.md | 4 ++-- .../src/stories/Dropdown/index.stories.tsx | 3 ++- 3 files changed, 25 insertions(+), 3 deletions(-) create mode 100644 packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md 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..f3bdc78be05119 --- /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 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](#TODO).** + +### 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..2508f930173f86 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,9 @@ ### Do -- **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. +- **Provide a label for the Dropdown.** +- **Set the Option `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 direclty provide a string value. ### 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. 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'), }, }, }, From d1cb24eaa47f2ca9035af78748a769b23f2cf322 Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Fri, 23 Sep 2022 14:30:06 -0700 Subject: [PATCH 2/4] change file --- ...eact-combobox-b89a40be-4811-4450-b226-2355943843f7.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@fluentui-react-combobox-b89a40be-4811-4450-b226-2355943843f7.json 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" +} From cad9cc06de8acffba3f65641af35fcc6ad2ed058 Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Mon, 24 Oct 2022 16:06:03 -0700 Subject: [PATCH 3/4] add link URL, update best practices --- .../src/stories/Dropdown/DropdownAccessibility.md | 4 ++-- .../src/stories/Dropdown/DropdownBestPractices.md | 5 ++++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md b/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md index f3bdc78be05119..6f6deaeb1413a8 100644 --- a/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md +++ b/packages/react-components/react-combobox/src/stories/Dropdown/DropdownAccessibility.md @@ -9,13 +9,13 @@ - **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](#TODO).** +- **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 `