Overlay system accessibility checklists

[emplums]

Dialogs

WCAG guidelines: https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal

caption: Screenshot of the Dialog component. A dialog is a modal that sits on top of a page, with a dimmed background. It has a close button and may also contain confirmation buttons at the bottom.

WAI-ARIA Roles, States, and Properties

• The element that serves as the dialog container has a role of dialog
• The dialog container element has aria-modal set to true.
• All elements required to operate the dialog are descendants of the element that has role dialog.
• The dialog has either:
  • A value set for the aria-labelledby property that refers to a visible dialog title.
  • A label specified by aria-label.
• Optionally, the aria-describedby property is set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog. Specifying descriptive elements enables screen readers to announce the description along with the dialog title and initially focused element when the dialog opens.

Focus Management

• Modal dialogs do not provide means for moving keyboard focus outside the dialog window without closing the dialog
• When a dialog opens, focus placement depends on the nature and size of the content.
  • In all circumstances, focus moves to an element contained in the dialog.
  • Unless a condition where doing otherwise is advisable, focus is initially set on the first focusable element.
  • If content is large enough that focusing the first interactive element could cause the beginning of content to scroll out of view, it is advisable to add tabindex=-1 to a static element at the top of the dialog, such as the dialog title or first paragraph, and initially focus that element.
  • If a dialog contains the final step in a process that is not easily reversible, such as deleting data or completing a financial transaction, it may be advisable to set focus on the least destructive action, especially if undoing the action is difficult or impossible. The Alert Dialog Pattern is often employed in such circumstances.
  • If a dialog is limited to interactions that either provide additional information or continue processing, it may be advisable to set focus to the element that is likely to be most frequently used, such as an OK or Continue button.
• When a dialog closes, focus returns to the element that invoked the dialog unless either:
• The invoking element no longer exists. Then, focus is set on another element that provides logical work flow.
• The work flow design includes the following conditions that can occasionally make focusing a different element a more logical choice:
  • It is very unlikely users need to immediately re-invoke the dialog.
  • The task completed in the dialog is directly related to a subsequent step in the work flow.
    For example, a grid has an associated toolbar with a button for adding rows. the Add Rows button opens a dialog that prompts for the number of rows. After the dialog closes, focus is placed in the first cell of the first new row.
• It is strongly recommended that the tab sequence of all dialogs include a visible element with role button that closes the dialog, such as a close icon or cancel button.
• Focus is trapped inside of the dialog

Other

• Content under a modal dialog are inert, users cannot interact with content outside of an active dialog window
• Usually content behind the modal is dimmed

ActionMenu & DropdownMenu

WCAG Menu guidelines: https://www.w3.org/TR/wai-aria-practices-1.1/#menu

caption: screenshot of the DropdownMenu component, which is a menu that contains a list of items that you can select one item from. Similar to a SingleSelectPanel but for cases where there are less items to pick from

caption: Screenshot of the ActionMenu component, which is a menu that contains a list of action items such as "New file", "Copy link", "Quote reply", "Edit comment" and "Report comment". ActionMenu components can also contain separators to group actions into categories.

WAI-ARIA Roles, States, and Properties

• One of the following approaches is used to enable scripts to move focus among items in a menu as described in § 6.6 Keyboard Navigation Inside Components:
  • The menu container has tabindex set to -1 or 0 and aria-activedescendant set to the ID of the focused item.
  • Each item in the menu has tabindex set to -1
• A menu is a container of items that represent choices. The element serving as the menu has a role of either menu or menubar.
• The items contained in a menu are child elements of the containing menu and have any of the following roles:
  • menuitem
  • menuitemcheckbox
  • menuitemradio
• If activating a menuitem opens a submenu, the menuitem is known as a parent menuitem. A submenu's menu element is:
• Contained inside the same menu element as its parent menuitem.
• Is the sibling element immediately following its parent menuitem.
• A parent menuitem that opens a submenu has aria-haspopup set to either menu or true.
• A parent menuitem that opens a submenu has aria-expanded set to false when its child menu is not visible and set to true when the child menu is visible.
• When a menu item is disabled, aria-disabled is set to true.

Focus management

• When a menu opens, or when a menubar receives focus, keyboard focus is placed on the first item. All items are focusable as described in § 6.6 Keyboard Navigation Inside Components.
• Items in a menu may be divided into groups by placing an element with a role of separator between groups.
• An element with role menu either has:
  • aria-labelledby set to a value that refers to the menuitem or button that controls its display.
  • A label provided by aria-label.

Keyboard navigation

• Enter:
  • When focus is on a menuitem that has a submenu, opens the submenu and places focus on its first item.
  • Otherwise, activates the item and closes the menu.
• Space:
  • When focus is on a menuitemcheckbox, changes the state without closing the menu.
  • When focus is on a menuitemradio that is not checked, without closing the menu, checks the focused menuitemradio and unchecks any other checked menuitemradio element in the same group.
  • When focus is on a menuitem that has a submenu, opens the submenu and places focus on its first item.
  • When focus is on a menuitem that does not have a submenu, activates the menuitem and closes the menu.
• Down Arrow:
  • When focus is on a menuitem in a menubar, opens its submenu and places focus on the first item in the submenu.
  • When focus is in a menu, moves focus to the next item, optionally wrapping from the last to the first.
• Up Arrow:
  • When focus is in a menu, moves focus to the previous item, optionally wrapping from the first to the last.
  • (Optional): When focus is on a menuitem in a menubar, opens its submenu and places focus on the last item in the submenu.
• Right Arrow:
  • When focus is in a menu and on a menuitem that has a submenu, opens the submenu and places focus on its first item.
  • If the focus is inside of a submenu and that item doesn't have another submenu, it closes the submenu
  • If the focus is not in a submenu, and the item is does not have a submenu, right arrow does nothing
• Left arrow:
  • When focus is in a submenu of an item in a menu, closes the submenu and returns focus to the parent menuitem.
• Home: If arrow key wrapping is not supported, moves focus to the first item in the current menu (Note: I think we should support this even if arrow key wrapping is supported)
• End: If arrow key wrapping is not supported, moves focus to the last item in the current menu (Note: I think we should support this even if arrow key wrapping is supported)
• Escape: Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent menuitem, from which the menu was opened.
• Tab: Moves focus to the next element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers.
• Shift + Tab: Moves focus to the previous element in the tab sequence, and if the item that had focus is not in a menubar, closes its menu and all open parent menu containers.

Other

• Disabled menu items are focusable but cannot be activated.
• A separator in a menu is not focusable or interactive. (Note: This might create problems if we put group titles in separators)
• Although it is recommended that authors avoid doing so, some implementations of navigation menubars may have menuitem elements that both perform a function and open a submenu. In such implementations, enter and Space perform a navigation function, e.g., load new content, while Down Arrow, in a horizontal menubar, opens the submenu associated with that same menuitem.

SingleSelectPanel

WCAG Listbox guidelines: https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox

caption: screenshot of our SingleSelectPanel component. A SingleSelectPanel is a container that is shown when a user activates its trigger, which is usually a button. The panel contains a list of items that the user can select one of. The user can select items either by click or activating the checkbox or by clicking anywhere on the area that the item takes up, or by pressing enter or space when focused on an item. When an item is selected, a checkbox appears to the left of it. The panel also contains a search input which lets the user filter the list of items to more easily find the item they are wishing to select. Note that the SingleSelectPanel often contains many items, such as the list of users you might assign on a pull request page.

WAI-ARIA Roles, States, and Properties

• An element that contains or owns all the listbox options has role listbox.
• Each option in the listbox has role option and is a DOM descendant of the element with role listbox or is referenced by an aria-owns property on the listbox element.
• If the listbox is not part of another widget, then it has a visible label referenced by aria-labelledby on the element with role listbox.
• In a single-select listbox, the selected option has aria-selected set to true.
• If the complete set of available options is not present in the DOM due to dynamic loading as the user scrolls, their aria-setsize and aria-posinset attributes are set appropriately.

Focus management

• When a single-select listbox receives focus:
  • If none of the options are selected before the listbox receives focus, the first option receives focus. Optionally, the first option may be automatically selected.
  • If an option is selected before the listbox receives focus, focus is set on the selected option.

Keyboard navigation

• Down Arrow: Moves focus to the next option. Optionally, in a single-select listbox, selection may also move with focus.
• Up Arrow: Moves focus to the previous option. Optionally, in a single-select listbox, selection may also move with focus.
• Home: Moves focus to first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
• End: Moves focus to last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.

Other

• Type-ahead is recommended for all listboxes, especially those with more than seven options:
  • Type a character: focus moves to the next item with a name that starts with the typed character.
  • Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.
• DOM focus (the active element) is functionally distinct from the selected state. For more details, see this description of differences between focus and selection.

MultiSelectPanel

WCAG Listbox guidelines: https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox

caption: Screenshot of the MultiSelectPanel component. A MultiSelectPanel is a container that is shown when a user activates its trigger, which is usually a button. The panel contains a list of items that the user can select multiple of. Each item has a checkbox to the left of it. The user can select items either by click or activating the checkbox or by clicking anywhere on the area that the item takes up, or by pressing enter or space when focused on an item. The panel also contains a search input which lets the user filter the list of items to more easily find the item they are wishing to select. Note that the MultiSelectPanel often contains many items, such as the list of users you might assign on a pull request page.

WAI-ARIA Roles, States, and Properties

• Implements all of the items listed above in the SingleSelectPanel section
• The element with role listbox has aria-multiselectable set to true.
• All selected options have aria-selected set to true.
• All options that are not selected have aria-selected set to false.

Focus Management

• When a multi-select listbox receives focus:
  • If none of the options are selected before the listbox receives focus, focus is set on the first option and there is no automatic change in the selection state.
  • If one or more options are selected before the listbox receives focus, focus is set on the first option in the list that is selected.

Keyboard navigation

• Implements all keyboard handlers for up arrow, down arrow, home, & end keys described for the SingleSelectPanel
• Space: changes the selection state of the focused option.
• Shift + Down Arrow (Optional): Moves focus to and toggles the selected state of the next option.
• Shift + Up Arrow (Optional): Moves focus to and toggles the selected state of the previous option.
• Shift + Space (Optional): Selects contiguous items from the most recently selected item to the focused item.
• Control + Shift + Home (Optional): Selects the focused option and all options up to the first option. Optionally, moves focus to the first option.
• Control + Shift + End (Optional): Selects the focused option and all options down to the last option. Optionally, moves focus to the last option.
• Control + A (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options.

Other

• Implements all features listed in the SingleSelectPanel section above

[github-actions]

Hi! This issue has been marked as stale because it has been open with no activity for 180 days. You can comment on the issue or remove the stale label to keep it open. If you do nothing, this issue will be closed in 7 days.