diff --git a/src/pages/components/data-table/usage.mdx b/src/pages/components/data-table/usage.mdx index aa858d38e00..d2c33b509a2 100755 --- a/src/pages/components/data-table/usage.mdx +++ b/src/pages/components/data-table/usage.mdx @@ -52,7 +52,7 @@ table display settings, and other utilities. | Variant | Purpose | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| _Default_ | The default data table comes with a base style with only the title, header, and table elements. rows. | +| _Default_ | The default data table comes with a base style with only the title, header, and table elements rows. | | _With selection_ | Batch actions are functions that may be performed on multiple items within a table. This variant of table enables the user to select individual rows and apply an action. A batch action toolbar appears when table rows are selected. | | _With expansion_ | The expandable data table is useful for presenting large amounts of data in a small space. Rows are collapsed and can be expanded to reveal extra information. | diff --git a/src/pages/components/modal/accessibility.mdx b/src/pages/components/modal/accessibility.mdx index beed063805b..06ec6ad2a33 100644 --- a/src/pages/components/modal/accessibility.mdx +++ b/src/pages/components/modal/accessibility.mdx @@ -17,400 +17,109 @@ import { ListItem, } from '@carbon/react'; + + +Design annotations are needed for specific instances shown below, but for the +standard modal dialog component, Carbon already incorporates accessibility. + + + - How it works - Accessibility considerations - Resources - Accessibility testing + What Carbon provides + Design recommendations + Development considerations -## How it works - -The modal Carbon component is a secondary window that displays over the primary -window to allow the user to maintain the context of a particular task. When the -modal is displayed the primary window is inert, so users cannot interact with -content outside an active modal. - -The modal dialog contains the tab sequence so that `Tab` and `Shift-Tab` keys do -not move the focus outside of the modal. To support screen reader users each -modal component includes a WAI ARIA `role="dialog"` and `aria-modal="true"` so -assistive technologies understand that the windows underneath the current dialog -are not available for interaction (inert). Focus, accessible descriptions, and -labels are set based on the content of each modal. Modals that contain static -text have the `aria-describeby` property set on the element with the ARIA -`role="dialog"` to indicate which element or elements in the dialog contain -content describes the primary purpose or message of the dialog. A value is also -set for the `aria-labelledby` property that refers to a visible dialog title. - -## Accessibility considerations - -This component has been validated to meet the -[WCAG 2.0 AA](https://www.w3.org/TR/WCAG20/) and -[Section 508](http://www.section508.gov/) accessibility guidelines, however -changes made by the content owner can affect accessibility compliance. Be sure -to review and follow the guidance in this section when updating or adding new -content to this component. - -1. After the modal opens, initial focus should be set on the first focusable - element in the modal. See WAI-ARIA Authoring Practices - [Modal Dialog Example, Accessibility Features section](https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html) - for best practices on setting focus. -2. After a modal closes, focus should retain the user's point of regard and - return to the element that invoked the modal. -3. Focus must not move outside the modal until it is closed. -4. It is strongly recommended that the tab sequence of all modal dialogs include - a visible element with button role that closes the dialog, such as a close - icon or cancel button. -5. Use the Alert modal dialog for special case that interrupts user’s workflow - to communicate a brief, important message and require a user’s response. - -## Resources - -#### Helpful resources for creating customized accessible implementations - -- [W3C WAI-ARIA Authoring Practices Dialog Modal Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal) - covers the usage of ARIA names, state and roles, as well as the expected - keyboard interactions. -- [IBM Accessibility Requirements](https://www.ibm.com/able/requirements/requirements/): - - [1.4.13 Content on Hover or Focus](https://www.ibm.com/able/requirements/requirements/#1_4_13) - (WCAG Success Criteria - [1.4.13](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html)) - - [2.1.2 No Keyboard Traps](https://www.ibm.com/able/requirements/requirements/#2_1_2) - (WCAG Success Criteria - [2.1.2](https://www.w3.org/TR/UNDERSTANDING-WCAG20/keyboard-operation-trapping.html)) - - [2.4.3 Focus Order](https://www.ibm.com/able/requirements/requirements/#2_4_3) - (WCAG Success Criteria - [2.4.3](https://www.w3.org/WAI/WCAG21/Understanding/focus-order)) - -## Accessibility testing - -Accessibility issues are tracked in the -[Carbon Component GitHub repository](https://github.com/carbon-design-system/carbon/issues?q=is%3Aopen+label%3A%22type%3A+a11y+%E2%99%BF%22+label%3A%22component%3A+modal%22+). - -### Automated test +## What Carbon provides - - - - - - - Automated test environment - - Results - - - - - - - macOS Mojave version 10.14.6 with VoiceOver -
- - Chrome version 77.0.3865.90 -
- - Dynamic Assessment Plugin version 1.8.0.0 - IBM Accessibility WCAG - 2.1 Sept. 2019 Ruleset -
- Carbon React version 7.7.1 - - - DAP test -
- No violations - - - - - - +Carbon bakes keyboard operation into its components, improving the experience of +blind users and others who operate via the keyboard. Carbon incorporates many +other accessibility considerations, some of which are described below. + +### Keyboard interactions -### macOS Screen reader tests +Modal dialogs take focus on appearance, and the tab order is constrained to the +modal’s controls until the modal is closed by choosing one of the buttons with +`Enter` or `Space`, or is dismissed by pressing `Esc`. - - - - - Environment - Results - - - - - - - macOS Mojave version 10.14.6 with VoiceOver -
- - Chrome version 77.0.3865.90 -
- Carbon React version 7.7.1 - - - VoiceOver(VO) test: - - - Tab to Launch modal button. VO announces the button label. - - - Select Enter or Space key to launch the modal. VO announces the - button label, headings, and text. - - - Tab or Shift-Tab navigate through the modal buttons and - announces each label. - - - Select Control-Option-Right Arrow or Left Arrow to navigate - through the modal message. - - - Select the Esc key, Close button or Cancel button to close the - modal and return focus to the Launch modal button in the primary - window. - - - - - - - - macOS Mojave version 10.14.6 with VoiceOver -
- - Safari version 13.0.2 -
- Carbon React version 7.7.1 - - - VoiceOver(VO) test: - - - Tab to Launch modal button. VO announces the button label. - - - Select Enter or Space key to launch the modal. VO announces the - Button label. - - - Tab or Shift-Tab navigate through the modal buttons and - announces each label. - - - Select Control-Option-Right Arrow or Left Arrow to navigate - through the modal message. - - - Select the Esc key, Close button or Cancel button to close the - modal and return focus to the Launch modal button in the primary - window. - - - - - - - - + -### Windows screen reader tests +![illustration showing tab ring constrained within a modal with two buttons](images/modal-accessibility-1.png) - - - - - - Environment - Results - - - - - - - Microsoft Windows 10 -
- - Firefox version 67 -
- - JAWS version 19.1810.64 -
- Carbon React version 7.7.1 - - - JAWS test: - - - Tab to Launch modal button. JAWS announces the button label. - - - Select Enter or Space key to launch the modal. - - - Tab or Shift-Tab to navigate through the modal buttons and - announces each label. Focus does not move out of the modal when - tabbing. - - - Select Control-Option-Right Arrow or Left Arrow to navigate - through the modal message. - - - Press Close button or Cancel button to close the modal and - return focus to the Launch modal button in the primary window. - - - - - - - - Microsoft Windows 10 -
- - Chrome version 73.0.3683.103 (Official Build) (64-bit) -
- - JAWS version 19.1810.64 -
- Carbon React version 7.7.1 - - - JAWS test: - - - Tab to Launch modal button. JAWS announces the button label. - - - Select Enter or Space key to launch the modal. - - - Tab or Shift-Tab to navigate through the modal buttons and - announces each label. Focus does not move out of the modal when - tabbing. - - - Select Control-Option-Right Arrow or Left Arrow to navigate - through the modal message. - - - Press Close button or Cancel button to close the modal and - return focus to the Launch modal button in the primary window. - - - - - - - - Microsoft Windows 10 -
- - Chrome version 73.0.3683.103 (Official Build) (64-bit) -
- - NVDA Version 2018.4.1 -
- Carbon React version 7.7.1 - - - NVDA test: - - - Tab to Launch modal button. NVDA announces the button label - - - Select Enter or Space key to launch the modal. NVDA announces - the text and buttons automatically. - - - Tab or Shift-Tab to navigate through the modal buttons and - announces each label. Focus does not move out of the modal when - tabbing. - - - Select Control-Option-Right Arrow or Left Arrow to navigate - through the modal message. - - - Press Close button or Cancel button to close the modal and - return focus to the Launch modal button in the primary window. - - - - - - - - + + Keyboard navigation is constrained to the dialog. Tab cycles through the + components that take focus. + -### Android screen reader tests + + - - - - Environment - Results - - - - - - Android version 9 with Talkback -
- - Chrome Version 73.0.3683.103 (Official Build) (64-bit) -
- Carbon React version 7.7.1 - - - Talkback test: - - - Swipe left or right, or use the Alt+Arrow keys in quick nav mode - until you find the Launch modal button. - - - Double tap the button or press the Alt-Enter keys to launch the - modal. The close modal button is announces and has focus. - - - Swipe Left or Right to explore the modal. VO announces the text, - and focus on the Cancel and Save buttons. - - - Note: that navigation is not restricted to the modal only, after - the modal is open there is no way to know if there is an open - modal present, the user needs to remember it. Doubletap or press - Alt+Enter on the Close or Cancel buttons to close the modal. - - - - - - - + + +![Esc closes a modal, while Space and Enter keys activate buttons](images/modal-accessibility-2.png) + + + The dialog is resolved by the user pressing Esc or activating a button. + + + -### iOS screen reader tests +### Focus handling + +When the dialog appears, the first item that gets focus depends on the type of +dialog. Passive dialogs only contain a close button (X), so that takes focus. +For dialogs which prompt for confirmation or user decision, the primary button +takes focus (regardless of number of buttons). For destructive interactions, the +“cancel” button takes focus, not the red danger/delete button. The tab order +should proceed left and down from whichever item has focus then wrap back to the +close button (X). - - - - Environment - Results - - - - - - iOS version 13.1.3 with VoiceOver -
- - Safari version 13.1.3 -
- Carbon React version 7.7.1 - - - VoiceOver test: - - - Swipe left or right, or use the Arrow keys in quick nav mode - until you find the Launch modal button. - - - Double tap the button to launch the modal. The close modal - button is announces and has focus. - - - Swipe Left or Right to explore the modal. VO announces the text, - and focus on the Cancel and Save buttons. - - - After Double tapping on the close or cancel button, the modal - closes but focus is stuck on the selected button. Touch the - screen anywhere to move out of the focus trap. - - - - - - - + + +![initial focus in the dialog varies across four types of modals](images/modal-accessibility-3.png) + +The first item with focus varies depending on dialog type. + + + +## Design recommendations + +### Designate the input that takes focus in a transactional + +The only time the starting focus would not be on a button is where a dialog +contains input fields. For such transactional dialogs, designers should annotate +that the first input field should receive focus. Note that text links are not +considered a user input in this context. + + + + +![annotation on input says 'focus lands here when modal opens'](images/modal-accessibility-4-do.png) + + + + + +![annotation on link says 'focus lands here when modal opens'](images/modal-accessibility-4-dont.png) + + + + +## Development considerations + +Keep these considerations in mind if you are modifying Carbon or creating a +custom component. + +- Carbon assigns the container a role of "dialog" and sets `aria-modal` to + `"true"`. +- The dialog is labelled via `aria-label`, using the same string used for the + modal’s title; `aria-labelledby` could also be used to assign the title’s + string. +- See the modal pattern in the + [ARIA authoring practices](https://w3c.github.io/aria-practices/#dialog_modal) + for more considerations. diff --git a/src/pages/components/modal/images/modal-accessibility-1.png b/src/pages/components/modal/images/modal-accessibility-1.png new file mode 100644 index 00000000000..f8d06a421a8 Binary files /dev/null and b/src/pages/components/modal/images/modal-accessibility-1.png differ diff --git a/src/pages/components/modal/images/modal-accessibility-2.png b/src/pages/components/modal/images/modal-accessibility-2.png new file mode 100644 index 00000000000..7bd5ef4d8e6 Binary files /dev/null and b/src/pages/components/modal/images/modal-accessibility-2.png differ diff --git a/src/pages/components/modal/images/modal-accessibility-3.png b/src/pages/components/modal/images/modal-accessibility-3.png new file mode 100644 index 00000000000..983687e6758 Binary files /dev/null and b/src/pages/components/modal/images/modal-accessibility-3.png differ diff --git a/src/pages/components/modal/images/modal-accessibility-4-do.png b/src/pages/components/modal/images/modal-accessibility-4-do.png new file mode 100644 index 00000000000..8ca2639686c Binary files /dev/null and b/src/pages/components/modal/images/modal-accessibility-4-do.png differ diff --git a/src/pages/components/modal/images/modal-accessibility-4-dont.png b/src/pages/components/modal/images/modal-accessibility-4-dont.png new file mode 100644 index 00000000000..c3892108e08 Binary files /dev/null and b/src/pages/components/modal/images/modal-accessibility-4-dont.png differ diff --git a/src/pages/components/number-input/images/number-input-style-1-fluid.png b/src/pages/components/number-input/images/number-input-style-1-fluid.png new file mode 100644 index 00000000000..0b54e89fab8 Binary files /dev/null and b/src/pages/components/number-input/images/number-input-style-1-fluid.png differ diff --git a/src/pages/components/number-input/images/number-input-style-1.png b/src/pages/components/number-input/images/number-input-style-1.png index 38a7b7d95d6..aec4507033e 100644 Binary files a/src/pages/components/number-input/images/number-input-style-1.png and b/src/pages/components/number-input/images/number-input-style-1.png differ diff --git a/src/pages/components/number-input/images/number-input-style-1b.png b/src/pages/components/number-input/images/number-input-style-1b.png new file mode 100644 index 00000000000..4e2a81d95bf Binary files /dev/null and b/src/pages/components/number-input/images/number-input-style-1b.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-11.png b/src/pages/components/number-input/images/number-input-usage-11.png new file mode 100644 index 00000000000..e8f3f6b93c9 Binary files /dev/null and b/src/pages/components/number-input/images/number-input-usage-11.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-2-fluid.png b/src/pages/components/number-input/images/number-input-usage-2-fluid.png new file mode 100644 index 00000000000..89a58aac4f8 Binary files /dev/null and b/src/pages/components/number-input/images/number-input-usage-2-fluid.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-3-fluid.png b/src/pages/components/number-input/images/number-input-usage-3-fluid.png new file mode 100644 index 00000000000..6e97c8219c0 Binary files /dev/null and b/src/pages/components/number-input/images/number-input-usage-3-fluid.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-6-fluid.png b/src/pages/components/number-input/images/number-input-usage-6-fluid.png new file mode 100644 index 00000000000..b00b3d6ad81 Binary files /dev/null and b/src/pages/components/number-input/images/number-input-usage-6-fluid.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-6.png b/src/pages/components/number-input/images/number-input-usage-6.png index 2a19cc33964..d3b66eb2c39 100644 Binary files a/src/pages/components/number-input/images/number-input-usage-6.png and b/src/pages/components/number-input/images/number-input-usage-6.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-7-fluid.png b/src/pages/components/number-input/images/number-input-usage-7-fluid.png new file mode 100644 index 00000000000..ca81c038181 Binary files /dev/null and b/src/pages/components/number-input/images/number-input-usage-7-fluid.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-7.png b/src/pages/components/number-input/images/number-input-usage-7.png index 05b23d083b1..f98be0defe9 100644 Binary files a/src/pages/components/number-input/images/number-input-usage-7.png and b/src/pages/components/number-input/images/number-input-usage-7.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-8.png b/src/pages/components/number-input/images/number-input-usage-8.png index 5355eb046a9..a21989ad96f 100644 Binary files a/src/pages/components/number-input/images/number-input-usage-8.png and b/src/pages/components/number-input/images/number-input-usage-8.png differ diff --git a/src/pages/components/number-input/images/number-input-usage-9.png b/src/pages/components/number-input/images/number-input-usage-9.png index 1616614f254..b0614dc5b86 100644 Binary files a/src/pages/components/number-input/images/number-input-usage-9.png and b/src/pages/components/number-input/images/number-input-usage-9.png differ diff --git a/src/pages/components/number-input/style.mdx b/src/pages/components/number-input/style.mdx index 420e0a20457..8e7ab110c42 100755 --- a/src/pages/components/number-input/style.mdx +++ b/src/pages/components/number-input/style.mdx @@ -24,34 +24,62 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility'] -![Number input example](images/number-input-style-1.png) + + + + +![Fluid number input example](images/number-input-style-1.png) + + + + + +![Fixed number input example](images/number-input-style-1b.png) + + + + -Number input example. - ### Interactive states -| Element | Property | Color token | -| --------------- | ---------------- | ----------------- | -| Controls:hover | background-color | `field-hover` \* | -| Field:focus | border | `$focus` | -| Controls:focus | border | `$focus` | -| Field:invalid | border | `$support-error` | -| Error icon | svg | `$support-error` | -| Error message | text color | `$text-error` | -| Warning icon | svg | `support-warning` | -| Warning message | text color | `text-primary` | -| Label:disabled | text color | `$text-disabled` | -| Field:disabled | background-color | `$field` \* | -| | border-bottom | transparent | -| Number | text color | `$text-disabled` | +| Element | Property | Color token | +| ----------------- | --------------------- | ------------------- | +| Controls:hover | background-color | `field-hover` \* | +| Field:focus | border | `$focus` | +| Controls:focus | border | `$focus` | +| Field:invalid | border | `$support-error` | +| Error icon | svg | `$support-error` | +| Error message | text color | `$text-error` | +| Warning icon | svg | `support-warning` | +| Warning message | text color | `text-primary` | +| Label:disabled | text color | `$text-disabled` | +| Field:disabled | background-color | `$field` \* | +| | border-bottom (fixed) | transparent | +| | border-bottom (fluid) | `$border-subtle` \* | +| Number:disabled | text color | `$text-disabled` | +| Controls:disabled | svg color | `$icon-disabled` | -![Number input states example](images/number-input-style-2.png) + + + + +![Fixed number input interactive states](images/number-input-usage-6.png) + + + + + +![Fluid number input interactive states](images/number-input-usage-6-fluid.png) + + + + @@ -63,16 +91,18 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility'] Number input labels should use sentence case, with only the first word in a phrase and any proper nouns capitalized. -| Element | Font-size (px/rem) | Font-weight | Type token | -| --------------- | ------------------ | ------------- | ----------------- | -| Label | 12 / 0.75 | Regular / 400 | `$label-01` | -| Field input | 14 / 0.875 | Regular / 400 | `$code-02` | -| Error message | 12 / 0.75 | Regular / 400 | `$label-01` | -| Warning message | 12 / 0.75 | Regular / 400 | `$label-01` | -| Helper text | 12 / 0.75 | Regular / 400 | `$helper-text-01` | +| Element | Font-size (px/rem) | Font-weight | Type token | +| --------------- | ------------------ | ------------- | ------------------ | +| Label | 12 / 0.75 | Regular / 400 | `$label-01` | +| Field input | 14 / 0.875 | Regular / 400 | `$body-compact-01` | +| Error message | 12 / 0.75 | Regular / 400 | `$label-01` | +| Warning message | 12 / 0.75 | Regular / 400 | `$label-01` | +| Helper text | 12 / 0.75 | Regular / 400 | `$helper-text-01` | ## Structure +### Fixed input + The add and subtract icons can be found in the [icons](/guidelines/icons/library) library. @@ -91,11 +121,37 @@ The add and subtract icons can be found in the - Structure and spacing measurements for a number input | px / rem + Structure and spacing measurements for a fixed number input | px / rem + + +### Fluid input + +| Element | Property | px / rem | Spacing token | +| --------------------- | --------------------------- | ----------- | ------------- | +| Label | padding-bottom | 4 / 0.25 | `$spacing-02` | +| Field | height | 64 / 4 | `$spacing-10` | +| | padding-left, padding-right | 16 / 1 | `$spacing-05` | +| | padding-top, padding-bottom | 13 / 0.8125 | – | +| | border-bottom | 1px | – | +| Add or substract icon | height, width | 16 / 1 | – | +| Focus | border | 2px | – | +| Error | border | 2px | – | +| | padding-top, padding-bottom | 8 / 0.5 | `$spacing-03` | + +
+ +![Structure and spacing for number input](images/number-input-style-1-fluid.png) + +
+ + + Structure and spacing measurements for a fluid number input | px / rem ## Sizes +### Fixed input heights + The height varies for each size variant and the width varies based on content, layout, and design. diff --git a/src/pages/components/number-input/usage.mdx b/src/pages/components/number-input/usage.mdx index 43a73b723d5..479cf85c90a 100755 --- a/src/pages/components/number-input/usage.mdx +++ b/src/pages/components/number-input/usage.mdx @@ -136,7 +136,21 @@ values. -![number input anatomy](images/number-input-usage-2.png) + + + + +![Anatomy of a fixed number input](images/number-input-usage-2.png) + + + + + +![Anatomy of a fixed number input](images/number-input-usage-2-fluid.png) + + + + @@ -155,10 +169,30 @@ values. 8. **Error or Warning text**: It replaces the helper text when an error or warning state appears. +### Styling + +There are two styles of number inputs, fixed and fluid. They share the same +functionality but look visually different, influencing where to use them. + +| Style | Appearance | Use case | +| ----- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Fixed | A traditional style where the label is positioned outside and above the input field. | Use when white space is needed between input components or in productive moments where space is at a premium, and smaller components are needed. | +| Fluid | An alternative style where the label is placed inside of the input field and is stacked inline with the user input text. | Use in expressive moments, fluid forms, contained spaces, or attached to complex components, like a toolbar. | + + + + +![An example of a fixed and fluid number input](images/number-input-usage-11.png) + + + + ### Sizing -Number input has three sizes in height: **small**, **medium**, and **large**. -The width varies in size based on content, layout, and design. +#### Fixed input heights + +Number input has three sizes fixed input heights: **small**, **medium**, and +**large**. The width varies in size based on content, layout, and design. | Size | Height (px/rem) | Use case | | ----------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -169,7 +203,21 @@ The width varies in size based on content, layout, and design. -![number input sizes](images/number-input-usage-3.png) +![Fixed number input sizes](images/number-input-usage-3.png) + + + + +#### Fluid input heights + +There is only one fluid input height and it is visually larger than the fixed +heights. The input is a set height of 64px except when a warning or error +message has been added to the bottom. + + + + +![Fluid input size example](images/number-input-usage-3-fluid.png) @@ -228,7 +276,21 @@ The number input has a series of states for both field and controls elements: -![number input interactive states](images/number-input-usage-6.png) + + + + +![Fixed number input interactive states](images/number-input-usage-6.png) + + + + + +![Fluid number input interactive states](images/number-input-usage-6-fluid.png) + + + + @@ -244,7 +306,21 @@ add or subtract icon controls. -![number input mouse and keyboard interactions](images/number-input-usage-7.png) + + + + +![Fixed number input mouse and keyboard interactions](images/number-input-usage-7.png) + + + + + +![Fluid number input mouse and keyboard interactions](images/number-input-usage-7-fluid.png) + + + + diff --git a/src/pages/components/tooltip/accessibility.mdx b/src/pages/components/tooltip/accessibility.mdx index 66a35e6c215..495c3f0d36c 100644 --- a/src/pages/components/tooltip/accessibility.mdx +++ b/src/pages/components/tooltip/accessibility.mdx @@ -1,110 +1,113 @@ --- title: Tooltip description: - Tooltips provide additional information upon hover or focus. The information - should be contextual, useful, and nonessential information. + Tooltips display additional information upon hover or focus. The information + should be contextual, useful, and nonessential. tabs: ['Usage', 'Style', 'Code', 'Accessibility'] --- -import { - StructuredListWrapper, - StructuredListHead, - StructuredListBody, - StructuredListRow, - StructuredListInput, - StructuredListCell, - OrderedList, - ListItem, -} from '@carbon/react'; - -The tooltip React Carbon component has been tested against the latest -[W3C Web Content Accessibility Guidelines (WCAG) 2.1 Level A and AA success criteria](https://www.w3.org/TR/WCAG21/) -and violations have been identified as high priority issues. This document will -be updated when these accessibility issues are resolved. +Carbon’s tooltips appear accessibly on both hover and focus. Designers need only +annotate the tooltip’s text content. - Accessibility considerations - Resources - Accessibility testing + +What Carbon provides +Design recommendations +Development considerations + -## Accessibility considerations - -1. After the tooltip opens, initial focus should be set on the first focusable - element in the tooltip. See WAI-ARIA Authoring Practices - [Modal Dialog Example, Accessibility Features section](https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html) - for best practices on setting focus. Note: This does not apply to the tooltip - icon or tooltip definition components. -2. After the tooltip closes, focus should retain the user's point of regard and - return to the element that invoked it. Note: This does not apply to the - tooltip icon or tooltip definition components where focus never leaves the - element that invokes it. -3. The tooltip component's focus must not move outside the modal until it is - closed. Note: This does not apply to the tooltip icon or tooltip definition - components, as noted above, focus never leaves the element that invokes it. -4. The tooltip component has the same accessibility considerations as outlined - in the - [modal component documentation](https://pages.github.ibm.com/IBMa/Carbon_Integration/Doc/Modal-doc.html). - -## Resources - -- [W3C WAI-ARIA Authoring Practices Tooltip Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#tooltip) - covers the usage of ARIA names, state and roles, as well as the expected - keyboard interactions. -- [ARIA1: Using the aria-describedby property to provide a descriptive label for user interface controls](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA1) -- [IBM Accessibility Requirements](https://www.ibm.com/able/requirements/requirements/): - - [1.3.1 Info and Relationships](https://www.ibm.com/able/requirements/requirements/#1_3_1) - (WCAG Success Criteria - [1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)) - - [1.4.13 Content on Hover or Focus](https://www.ibm.com/able/requirements/requirements/#1_4_13) - (WCAG Success Criteria - [1.4.13](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html)) - - [3.3.2 Labels or Instructions](https://www.ibm.com/able/requirements/requirements/#3_3_2) - (WCAG Success Criteria - [3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)) - -## Accessibility testing - -Automated, manual and screen reader accessibility verification test has been -performed on the tooltip React Carbon component. -[WCAG 2.1 Level A and AA success criteria](https://www.w3.org/TR/WCAG21/) issues -have been identified and the list of open accessibility violations is available -in the Carbon Component GitHub repository. - -### Automated test +## What Carbon provides + +No annotations are needed for keyboard operation, since Carbon bakes in the +interaction. + +### Keyboard interactions + +The primary use of tooltips is to display the text labels of icon-only buttons. +Since each button is in the page’s tab order, the tooltip appears automatically +when the button receives focus. Tooltips disappear when the user moves focus +away from the button. The tips can also be dismissed by pressing `Esc`. The +tooltips themselves only contain text and are not interactive, so do not have +any other keyboard operations. + +The definition tooltip provides information about a term or text phrase. The +text that serves as the trigger has a dotted underline. When the trigger +receives focus, the definition tooltip is displayed. Like the button tooltip, +the definition can be dismissed by pressing Esc or by navigating away from the +trigger. + +Note: icon-only buttons retain their regular interaction. (They can be activated +by pointer click or by pressing Enter or Space.) A definition tooltip is unusual +in that its trigger only exists to take focus or hover, and is not otherwise +interactive (it can’t be clicked or acted upon). - - - - - - Automated test environment - - Results - - - - - - - macOS Mojave version 10.14.2 with VoiceOver -
- - Chrome version 77.0.3865.90 -
- - Dynamic Assessment Plugin (DAP) version 1.8.0.0 - IBM - Accessibility WCAG 2.1 Sept. 2019 Ruleset -
- Carbon React version 7.7.1 - - - DAP test: -
- No violations - - - - - + + +![tooltips appear on focus and disappear by pressing Esc or tabbing away from the trigger](images/tooltip-accessibility-1.png) + + + +Tooltips appear when the trigger receives focus and disappear when tabbing away +from the trigger. + + + + + + + + +![Esc dismisses a tooltip](images/tooltip-accessibility-2.png) + + + Both definition and icon-button tooltips can be dismissed by pressing Esc. + + + + + +## Design recommendations + +### Annotate the text for the tooltip + +If designers do not specify the text, tooltips are less likely to be implemented +by developers. Every icon-only button needs a tooltip, except for icons with +clearly established names or functions (such as Bold and Italics). Designers can +provide the text by using a tooltip in their designs or simply +[annotating the icon-only button](https://carbondesignsystem-2xrdev89e-carbon-design-system.vercel.app/components/button/accessibility#labeling). +For definition tooltips, see the +[Usage](https://carbondesignsystem.com/components/tooltip/usage) page for +information on the length and styling for tooltip content. + + + + +![icons have tooltips 'search' and 'switch sites'](images/tooltip-accessibility-3-do.png) + + + + + +![icon buttons in the top navigation do not have tooltips or annotations](images/tooltip-accessibility-3-dont.png) + + + + +## Development considerations + +Keep these considerations in mind if you are modifying Carbon or creating a +custom component. + +- The span containing the tooltip has a role of `tooltip` with + `aria-hidden="true"`. +- the trigger uses `aria-labelledby` to announce the tooltip text. +- See the tooltip pattern in the + [ARIA authoring practices](https://w3c.github.io/aria-practices/#tooltip) for + more considerations. diff --git a/src/pages/components/tooltip/images/tooltip-accessibility-1.png b/src/pages/components/tooltip/images/tooltip-accessibility-1.png new file mode 100644 index 00000000000..6ea0e0bb6ab Binary files /dev/null and b/src/pages/components/tooltip/images/tooltip-accessibility-1.png differ diff --git a/src/pages/components/tooltip/images/tooltip-accessibility-2.png b/src/pages/components/tooltip/images/tooltip-accessibility-2.png new file mode 100644 index 00000000000..b9564c3ffcf Binary files /dev/null and b/src/pages/components/tooltip/images/tooltip-accessibility-2.png differ diff --git a/src/pages/components/tooltip/images/tooltip-accessibility-3-do.png b/src/pages/components/tooltip/images/tooltip-accessibility-3-do.png new file mode 100644 index 00000000000..b72b1636081 Binary files /dev/null and b/src/pages/components/tooltip/images/tooltip-accessibility-3-do.png differ diff --git a/src/pages/components/tooltip/images/tooltip-accessibility-3-dont.png b/src/pages/components/tooltip/images/tooltip-accessibility-3-dont.png new file mode 100644 index 00000000000..e5713fe8211 Binary files /dev/null and b/src/pages/components/tooltip/images/tooltip-accessibility-3-dont.png differ diff --git a/src/pages/patterns/forms-pattern/index.mdx b/src/pages/patterns/forms-pattern/index.mdx index 1736744fff6..c49b3a9546a 100644 --- a/src/pages/patterns/forms-pattern/index.mdx +++ b/src/pages/patterns/forms-pattern/index.mdx @@ -259,14 +259,14 @@ file uploaders, toggles, and select lists (combo box and multiselect). Deciding what to use -| Control | Usage | Context | -| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| [Checkbox](/components/checkbox/usage) | To select or deselect one or more choices | Agree to terms and conditions, add optional items, select all that apply | -| [Radio button](/components/radio-button/usage) | To select only one option from two or more choices | Pick type, shipping method, etc. | -| [Toggle](/components/toggle/usage) | To choose one of two or more binary options | Changing user settings; On/off; Show/hide | -| [File uploader](/components/file-uploader/usage) | To upload/attach a file or multiple files to a form | Attaching SSl certificates; adding config files to support tickets | -| [Combo box](http://react.carbondesignsystem.com/?path=/story/combobox--default) | To select a single item (with type-ahead functionality from a longer list | Choosing a state, country, or language preference | -| [Multiselect](http://react.carbondesignsystem.com/?path=/story/multiselect--default) | To select multiple items from a longer list | Add a product example for MultiSelect | +| Control | Usage | Context | +| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | +| [Checkbox](/components/checkbox/usage) | To select or deselect one or more choices | Agree to terms and conditions, add optional items, select all that apply | +| [Radio button](/components/radio-button/usage) | To select only one option from two or more choices | Pick type, shipping method, etc. | +| [Toggle](/components/toggle/usage) | To choose one of two or more binary options | Changing user settings; On/off; Show/hide | +| [File uploader](/components/file-uploader/usage) | To upload/attach a file or multiple files to a form | Attaching SSl certificates; adding config files to support tickets | +| [Combo box](http://react.carbondesignsystem.com/?path=/story/combobox--default) | To select a single item with type-ahead functionality from a longer list | Choosing a state, country, or language preference | +| [Multiselect](http://react.carbondesignsystem.com/?path=/story/multiselect--default) | To select multiple items from a longer list | Add a product example for MultiSelect | #### Radio buttons: