diff --git a/.eslintignore b/.eslintignore index 5607b9b504..02825e8cb0 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,5 +1,5 @@ **/*.min.js common/ -examples/landmarks/js/visua11y.js -examples/js/highlight.pack.js -examples/js/skipto.js +content/patterns/landmarks/examples/js/visua11y.js +content/shared/js/highlight.pack.js +content/shared/js/skipto.js diff --git a/.eslintrc.json b/.eslintrc.json index e8e3bc1df3..7e40af6dbc 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -63,6 +63,14 @@ "strict": 0, "no-unused-vars": ["error", { "varsIgnorePattern": "SkipToConfig" }] } + }, + { + "files": [ "content/shared/js/app.js" ], + "parserOptions": { "ecmaVersion": 11 } + }, + { + "files": [ "content/shared/js/specLinks.mjs" ], + "parserOptions": { "sourceType": "module" } } ] } diff --git a/.github/workflows/coverage-report.yml b/.github/workflows/coverage-report.yml index 96847dcbfe..80f8307bc4 100644 --- a/.github/workflows/coverage-report.yml +++ b/.github/workflows/coverage-report.yml @@ -3,9 +3,9 @@ name: Regression Tests Coverage Report on: pull_request_target: paths: - - "examples/**" + - "content/**/examples/**" - "test/**" - - "!examples/landmarks/**" + - "!content/landmarks/examples/**" permissions: contents: read diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml index 02be06404a..d06e1df89b 100644 --- a/.github/workflows/examples.yml +++ b/.github/workflows/examples.yml @@ -7,13 +7,13 @@ on: paths: - "package*.json" - ".github/workflows/examples.yml" - - "examples/**" + - "content/**/examples/**" - "scripts/reference-tables.*" pull_request: paths: - "package*.json" - ".github/workflows/examples.yml" - - "examples/**" + - "content/**/examples/**" - "scripts/reference-tables.*" jobs: diff --git a/.github/workflows/link-checker.yml b/.github/workflows/link-checker.yml new file mode 100644 index 0000000000..10407a0000 --- /dev/null +++ b/.github/workflows/link-checker.yml @@ -0,0 +1,22 @@ +name: Link Checker + +on: [push, pull_request] + +jobs: + link-checker: + runs-on: ubuntu-latest + + steps: + - name: Clone repository + uses: actions/checkout@v3 + + - name: Set up Node.js + uses: actions/setup-node@v3 + with: + cache: npm + + - name: Install npm dependencies + run: npm ci + + - name: Run link checker + run: npm run link-checker diff --git a/.github/workflows/regression.yml b/.github/workflows/regression.yml index b355458637..7ea03368f5 100644 --- a/.github/workflows/regression.yml +++ b/.github/workflows/regression.yml @@ -6,9 +6,8 @@ on: - ".github/workflows/regression.yml" - "package*.json" - "test/**" - - "examples/**" - - "!examples/landmarks/**" - - "!examples/coding-template/**" + - "content/**/examples/**" + - "!content/landmarks/examples/**" push: branches-ignore: - main @@ -17,9 +16,8 @@ on: - ".github/workflows/regression.yml" - "package*.json" - "test/**" - - "examples/**" - - "!examples/landmarks/**" - - "!examples/coding-template/**" + - "content/**/examples/**" + - "!content/landmarks/examples/**" jobs: regression: diff --git a/.github/workflows/spelling.yml b/.github/workflows/spelling.yml index 7372b391df..a466c8c61a 100644 --- a/.github/workflows/spelling.yml +++ b/.github/workflows/spelling.yml @@ -9,8 +9,7 @@ on: - "!**/*.min.js" - "!**/*.pack.js" - "!**/*.paint" - - "!aria-practices-DeletedSectionsArchive.html" - - "!examples/landmarks/css/bootstrap.css" + - "!content/patterns/landmarks/examples/css/bootstrap.css" - "!common/**" - "!respec-config.js" @@ -20,8 +19,7 @@ on: - "!**/*.min.js" - "!**/*.pack.js" - "!**/*.paint" - - "!aria-practices-DeletedSectionsArchive.html" - - "!examples/landmarks/css/bootstrap.css" + - "!content/patterns/landmarks/examples/css/bootstrap.css" - "!common/**" - "!respec-config.js" diff --git a/.github/workflows/wai-trigger-deploy.yml b/.github/workflows/wai-trigger-deploy.yml index f06dee7604..ee93cd326b 100644 --- a/.github/workflows/wai-trigger-deploy.yml +++ b/.github/workflows/wai-trigger-deploy.yml @@ -7,7 +7,7 @@ on: paths: - ".github/workflows/wai-trigger-deploy.yml" - "common/**" - - "examples/**" + - "content/**/examples/**" - "img/**" - "aria-practices.html" - "index.html" diff --git a/.github/workflows/wai-trigger-pr.yml b/.github/workflows/wai-trigger-pr.yml index e0cbc5093c..ae5f28da13 100644 --- a/.github/workflows/wai-trigger-pr.yml +++ b/.github/workflows/wai-trigger-pr.yml @@ -11,11 +11,11 @@ on: - "scripts/reference-tables.*" - "**/*.js" - "test/**" - - "examples/**" + - "content/**/examples/**" - "aria-practices.html" - "index.html" - - "!examples/landmarks/**" - - "!examples/coding-template/**" + - "!content/landmarks/examples/**" + - "!coding-template/**" - "!common/**" jobs: diff --git a/.link-checker.js b/.link-checker.js new file mode 100644 index 0000000000..d3a1ff3fda --- /dev/null +++ b/.link-checker.js @@ -0,0 +1,19 @@ +module.exports = { + filesToIgnore: ['content/shared/templates/example-usage-warning.html'], + excludedLinks: { + 'content/patterns/menubar/examples/menubar-navigation.html': [ + '#ex1 [role=menuitem]', + ], + 'content/patterns/treeview/examples/treeview-navigation.html': [ + '#ex1 [role=treeitem]', + ], + 'content/patterns/carousel/examples/carousel-2-tablist.html': [ + '.carousel-image a', + ], + }, + ignoreHashesOnExternalPagesMatchingRegex: [ + // Some hash links are resolved with JS and are therefore difficult to check algorithmically + /^https:\/\/github\.com\/.*\/wiki\//, + /^https:\/\/html\.spec\.whatwg\.org\/multipage\//, + ], +}; diff --git a/aria-practices-DeletedSectionsArchive.html b/aria-practices-DeletedSectionsArchive.html deleted file mode 100644 index 77323337d0..0000000000 --- a/aria-practices-DeletedSectionsArchive.html +++ /dev/null @@ -1,3665 +0,0 @@ - - - - Content Deleted From WAI-ARIA Authoring Practices 1.1 - - - - - - - - -
-

- This document is a placeholder for sitnificatn sections of content that were removed from the ARIA Authoring Practices Guide. - It allows reviewers to more easily see what was removed, and makes it easier to restore content. -

-
- -
-

Design Patterns and Widgets

- -
-

Auto Complete

-

This section has not been updated since it was integrated from APG - version 1.0 -- an APG task force review is pending.

- -

A text box and an associated drop-down list of choices where the choices offered - are filtered based on the information typed into the box. Typically, an icon - associated with the text box triggers the display of the drop-down list of choices. - An editable auto-complete accepts text entry of choices that are not in the list. An - example of an editable auto-complete is the URL field in the browsers.

- -
-

Keyboard Interaction

-
    -
  • With focus in an empty text box, press Down Arrow, Up - Arrow, Alt + Down Arrow, or Alt + Up Arrow to - display the entire list of choices. Focus remains in the text box and no - choice is highlighted. -
      -
    • Press the Down Arrow to highlight the first choice - in the list. -
      • -
    • Press the Down Arrow and Up Arrow keys to - highlight the desired choice in the list. -
      • -
    • Note that the arrows will wrap through the text box when the - top or bottom of the list is reached. For example, pressing the down - arrow when the last choice is highlighted will move focus back to - the text box, pressing down again will move focus to the first item - in the list. Likewise, with focus in the text box and the list - displayed, pressing up arrow will move focus to the last item in the - list.
      • -
    • When a choice is highlighted using the arrow keys, the - highlighted choice is displayed in the text box.
      • -
    • Press Enter to select the highlighted choice and - close the drop-down list. This mimics the behavior of the HTML - select element. -
      • -
    -
    • -
  • With the drop-down list of choices displayed, move the mouse pointer - over an item in the list to highlight it. The text box value is not modified - when the mouse is used to highlight a choice. Clicking on the highlighted - choice will close the drop-down and update the text box with the selected - choice. This mimics the behavior of the HTML select element.
    • -
  • With focus in an empty text box, type any letter. If - any of the available choices begin with the letter typed, those choices are - displayed in a drop down. If the letter typed does not match any of the - available choices the drop-down list is not displayed. -
    • -
  • With focus in text box with an existing value type additional - letters. As the user types letters the list of choices is filtered so - that only those that begin with the typed letters are displayed. -
      -
    • Until the user presses the arrow keys to highlight a particular - choice, only the typed letters are displayed in the text box.
      • -
    • In an editable auto-complete, if no choices match the letter(s) - typed, the drop down list closes.
      • -
    • In a non-editable auto-complete, any letters that do not result - in a match from the list are ignored. The drop down list of choices - remains static until the user presses: -
        -
      • Escape to clear the text field
        • -
      • Backspace to remove some of the letters - previously typed
        • -
      • an additional letter that results in a valid list of - choices.
        • -
      -
      • -
    • Navigation through the list of choices and display of the - highlighted choice in the text box works as described above.
      - Optional: When a choice is highlighted via arrow key - navigation, the input cursor is left at the end of the typed - entry and the highlighted choice is displayed in the text box - with the characters after the input cursor selected. Typing an - additional character will remove the auto-completed portion and - append the newly typed character to the end of the previously - typed characters. The list will be filtered based on the - additional character(s) typed. -
      • -
    -
    • -
  • With focus in a text box, press Escape -
      -
    • If there is no text in the text box, pressing Escape - closes the drop-down if it is displayed. -
      • -
    • For an editable autocomplete that has text in the text box that - was both typed by the user and auto-completed by highlighting a - choice using the keyboard, the auto-completed portion of the text is - cleared and the user typed characters remain in the text box. The - drop-down list is closed. To completely clear the text box contents - the user must use the backspace key to remove the typed characters. - This is how the Google search box in the Firefox UI works. Recommend - that pressing the Escape key again completely clears - the text box rather than relying on only the backspace key. - -
      • -
    • For a non-editable auto-complete that has text in the text box - that was both typed by the user and auto-completed by highlighting a - choice using the keyboard, pressing Escape closes the - drop-down list and leaves the current choice in the text box. -
      • -
    • For an editable or non-editable auto complete with text in the - text box that was typed by the user and the mouse is highlighting a - choice in the drop down (keyboard navigation was NOT used), pressing - Escape closes the drop down and leaves the typed text - displayed in the text box. Need to consider if pressing Escape - again should clear the typed text. The user must press the Down - arrow or Alt + Down arrow or click the associated icon to - invoke the drop-down list of choices again. -
      • -
    -
    • -
  • Moving focus out of an empty auto complete field where a value is - required should either invoke an error or if a default value was initially - assigned, reset the value to the default value.
    • -
  • Moving focus out of an auto complete field that does not contain a - valid entry should either invoke an error or if a default value was - initially assigned, reset the value to the default value.
    • -
-

It is good practice to limit the number of matching items in the - drop down to a reasonable number. The reasonable number is determined by the - task at hand. A list of the 50 US States is probably reasonable, but a list - containing all of the office numbers in a building is probably not appropriate. -

-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The widget has a role of combobox. -
    • -
  • The combobox has an aria-autocomplete property set to one of 'inline', - 'list', or 'both'. -
    • -
  • For more information, see the combobox design - pattern. -
    • -
-
- -
-

Example

-

Any examples referenced here that are hosted outside www.w3.org - may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be - directly incorporated into the guide.

-

- Dojo autocomplete -

-
-
- -
-

Combo Box

-

This section has not been updated since it was integrated from APG - version 1.0 -- an APG task force review is pending.

- -

A combo box enables the user to type in a field and at the same time chose a - predefined value from a list. By using the keyboard the user can select an item from - the list. After selection she will be able to type further characters in the field. -

- -
-

Keyboard Interaction

-
    -
  • Left Arrow or Right Arrow move the caret within - the edit field.
    • -
  • Alt + Up/Down Arrow opens and closes the list.
    • -
  • Up Arrow and Down Arrow moves focus up and down - the list. As focus moves inside the dropdown list, the edit field is - updated.
    • -
  • Page Up / Page Down selects the next/previous pages item - depending on the lists size.
    • -
  • Escape closes the dropdown list, returns focus to the edit - field, and does not change the current selection.
    • -
  • Enter selects the current item on the list, updates the edit - field, highlights the selected item in the dropdown list, closes the - dropdown list, and returns focus to the input field.
    • -
  • Typing a letter (printable character) key moves focus to the - next instance of a visible node whose title begins with that printable - letter.
    • -
-

- For combo boxes that implement aria-autocomplete, see the autocomplete design pattern. -

-
- -
-

WAI-ARIA Roles, States, and Properties

-

A combobox can be implemented using either of two design patterns:

-
    -
  1. As a combination of text field, which may be editable, a displayable - list of items, and a drop button to toggle the display of that list; all - wrapped in the form of a single widget with role of combobox.
    2. -
  2. As a combobox, which behaves like a textfield and may be editable, with - a displayable list of items, and a drop button to toggle the display of that - list;
    3. -
-

Like text fields a combobox should be labeled to convey the purpose of the - widget. Keyboard focus within the widget must be managed by the widget. - Comboboxes are used extensively in graphical user interfaces and the design - pattern for the widget should be semantically correct.

-

For the first combobox design pattern:

-
    -
  • The container element that wraps the combobox has a role of combobox. -
    • -
  • The first element within the combobox is an input text - field and is responsible for managing the keyboard focus between the text - field and the list as well as displaying the list. The text field is in the - tab order. If you create a text field without using a standard HTML text - field form control then ensure that it is in the tab order. -
    • -
  • If the text field is not editable it must have aria-readonly = true. -
    • -
  • The combobox must have aria-expanded = true if the list - is displayed or aria-expanded - = false when it is not. -
    • -
  • The next element is an html <button>, or another - element with a role of button. - This element is used to toggle the display of the combobox's drop down list. -
    • -
  • The next element has a listbox - role and represents the drop down list. It manages keyboard navigation among - list items and navigating back to the text field if necessary. -
    • -
  • Each item in the listbox is an option. - Options are not in the tab order. -
    • -
  • Provide a label for the combobox by referencing the text field in the - combobox. You can use an aria-label - to associate this label with the combobox or you may use the HTML <label> - element and its for attribute to reference the text field. -
    • -
-

For the second combobox design pattern:

-
    -
  • The first element for the combobox has a role of combobox and behaves - like an input text field and is responsible for managing the keyboard focus - between the combobox and the list as well as displaying the list. The text - field is in the tab order. If you create a text field without using a - standard HTML text field form control then ensure that it is in the tab - order.
    • -
  • If the combobox is not editable it must have aria-readonly = true. -
    • -
  • The combobox must have aria-expanded = true if the list - is displayed or aria-expanded - = false when it is not. -
    • -
  • The next element is an html <button>, or another - element with a role of button. - This element is used to toggle the display of the combobox's drop down list. -
    • -
  • The next element has a listbox - role and represents the drop down list. It manages keyboard navigation among - list items and navigating back to the text field if necessary. -
    • -
  • Each item in the listbox is an option. - Options are not in the tab order. -
    • -
  • Provide a label for the combobox by referencing the text field in the - combobox. You can use an aria-label - to associate this label with the combobox or you may use the HTML <label> - element and its for attribute to reference the text field. -
    • -
-

- For each combobox pattern the button need not be in the tab order if - there is an appropriate keystroke associated with the - input - element such that when focus is on the - input - , the keystroke triggers display of the associated drop down list. In this case, - a - Tab - to focus the button is unnecessary. This is the same behavior as the - select - element. -

-
- -
-

Example

-

Any examples referenced here that are hosted outside www.w3.org - may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be - directly incorporated into the guide.

-

- First design pattern -- container element with role combobox: -

- -

- Second pattern -- text field with role combobox: -

- -
-
- -
-

Date Picker

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

- -

- The date picker widget allows the user to select a date or date ranges. - The date picker shows one month at least. All navigation that is described below depends on the application. - If no range selection is possible, the relevant keystroke interaction can be ignored. - Also navigation to the past might be optional. - Each week might be labeled with the corresponding calendar week number. -

-

- As a general rule the actual calendar portion of the date picker follows a table structure where days of the week and calendar day numbers are laid out in table cells. - This provides context so an assistive technology can render the day of the week; its corresponding numeric calendar day, and week number if necessary. - Consequently, it is best to start with an HTML table and apply WAI-ARIA semantics for a grid. - However, should the author wish to uses a div or span to represent the cells then the DOM structure for a table is duplicated with rows marked with role="row". -

-

The calendar portion can be displayed in a numbers of ways, including as a popup associated with another widget, or as a static region of a page.

- -
-

Keyboard Interaction

-

Keyboard navigation on days that are not included the currently displayed month should move to the month automatically and lead to the day in the next or previous month.

-
    -
  • - Tab - Like other widgets, the date picker widget receives focus by tabbing into it. - Once focus is received, focus is repositioned on today's date in a grid of days and weeks. - A second tab will take the user out of the date picker widget. - Focus initially is placed on today's date. -
    • -
  • - Shift + Tab - reverses the direction of the tab order. - Once in the widget, a Shift+Tab will take the user to the previous focusable element in the tab order. -
    • -
  • - Up Arrow and Down Arrow - goes to the same day of the week in the previous or next week respectively. - If the user advances past the end of the month they continue into the next or previous month as appropriate. -
    • -
  • - Left Arrow and Right Arrow - advances one day to the next, also in a continuum. - Visually focus is moved from day to day and wraps from row to row in a grid of days and weeks. -
    • -
  • Control + Page Up - Moves to the same date in the previous year.
    • -
  • Control + Page Down - Moves to the same date in the next year.
    • -
  • - Space - -
      -
    • Singleton Mode: acts as a toggle either selecting or deselecting the date.
      • -
    • - Contiguous Mode: Similar to selecting a range of text. - Space selects the first date. - Shift + Arrows add to the selection. - Pressing Space again deselects the previous selections and selects the current focused date. -
      • -
    -
    • -
  • Home - Moves to the first day of the current month.
    • -
  • End - Moves to the last day of the current month.
    • -
  • Page Up - Moves to the same date in the previous month.
    • -
  • Page Down - Moves to the same date in the next month.
    • -
  • - Enter - -
      -
    • If the calendar is a popup attached to some other widget (e.g., a text field), then Enter dismisses the popup, and the selected date(s) are shown in the associated widget.
      • -
    • If the calendar is a static region on the page, then Enter confirms the selected date(s).
      • -
    -
    • -
  • Escape - in the case of a popup date picker, closes the widget without any action.
    • -
-

Navigation into the past is optional

-

- Do not implement keyboard navigation schemes that would place more than one calendar day in the tab order at any time as this impacts the usability of keyboard navigation. - For example, using HTML anchors for the gridcells places them all in the tab order impacting the usability of keyboard navigation. -

-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • - The current month has a label representing the month and year. - It is advisable to use a role heading but is not essential. - This "label" should have a unique ID. -
    • -
  • If the author would like to ensure that a label is announced by a screen reader, as the label changes, include live region properties with the label element: aria-live="assertive" and aria-atomic="true".
    • -
  • The container for the day of week headers and numeric days of the week has a role of grid.
    • -
  • The grid has an aria-labelledby property with a value equivalent to the id of the label for the grid.
    • -
  • Each name for the day of the week has a role columnheader and is not navigable via the keyboard.
    • -
  • Each numeric day of the week has the role gridcell.
    • -
  • When a day is selected its aria-selected is set to true, otherwise it is set to false or removed.
    • -
  • Changes in aria states, identified here, as well as focus, are clearly styled to show the user where their point of regard is and what days are selected.
    • -
-

- When the date picker is active a calendar day of the week always has focus. - This can be achieved by setting the tabindex on that day as appropriate and then using script to give it focus. - Alternatively, the grid container could set aria-activedescendant to the id of the currently focused gridcell. - Keep in mind that older browsers may not support aria-activedescendant. -

-
- -
-

Example

-

- Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. -

- -
-
- -
-

Dialog (Non-Modal)

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

- -

A dialog is a small application window that sits above the application and is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response (dialog).

- -

- A non-modal dialog is one which is displayed and focusable at the same time as the application which invoked it. - Also like the modal dialog, focus via the tab and shift-tab key must be maintained within the dialog. - However, a non-modal dialog should have a keyboard mechanism to return focus to the application while leaving the dialog open. -

- -
-

Keyboard Interaction

-
    -
  • Escape cancels the dialog without taking any action.
    • -
  • Enter submits any data gathered in the dialog.
    • -
  • F6 is the recommended key to move focus between the application and an open non-model dialog.
    • -
-

Notes:

-
    -
  • The mouse user may click on either the application or the dialog to change focus between the two.
    • -
  • In a Web application the non-modal dialog is usually always displayed above the application page, rather than in a separate browser window but that is not a requirement.
    • - -
  • - Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. - Authors should ensure that Enter activates only the widget they intend. -
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties

-

See Dialog (Modal).

-
- -
-

Example

- -

- Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. -

-

Experimental dojo floating non-modal pane

-
-
- -
-

Dialog (Tooltip)

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

- -

A tooltip dialog is a modal dialog that is rendered near the invoking element and visually connected via a cartoon bubble-like protrusion. It is displayed when the mouse passes over or rests on that element.

- -
-

Keyboard Interaction:

-
    -
  • Escape The tooltip dialog is closed by pressing the escape key when focus is within the dialog, mouse clicking on a close icon, or mouse clicking outside of the dialog onto the application.
    • -
  • Tab Focus must be held within the dialog until it is cancelled or submitted. As the user presses tab to move within items in the dialog, pressing tab with focus on the last focusable item in the dialog will move focus back to the first focusable item in the dialog.
    • -
  • Shift + Tab Likewise, if the user is shift-tabbing through elements in the dialog, pressing shift-tab with focus on the first focusable item in the dialog will move focus to the last item in the dialog.
    • -
-

It is modal because focus is trapped within the dialog as the user navigates via the Tab and Shift + Tab key.

-

Unlike a true modal dialog, the user can click outside of the dialog, however in that case the tooltip dialog is immediately closed.

-

A tooltip dialog can not be moved/dragged.

-

Other than the close and move behavior, all other behaviors of a modal dialog are implemented by the tooltip dialog.

-
- -
-

WAI-ARIA Roles, States, and Properties

-

See Dialog (Modal).

-
- -
-

Example

-

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

-

Dojo nightly

-
-
- -
-

Landmark Navigation

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

- -
-

Keyboard Interaction

-
- -
-

WAI-ARIA Roles, States, and Properties

-

Provide the appropriate landmark for the role attribute. See the section describing landmark use.

-
- -
-

Example

-

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

- -
-
- -
-

Popup Help (aka Bubble Help)

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

- -

- Popup Help contains more descriptive, or actionable, help-like text and elements. - It may contain, and was designed to handle, interactive elements such as a button, link, or text field. - It is essentially a Popup Menu with un-necessary keystrokes turned off. - The key sequence for posting Popup Help was to take advantage of F1's tie to the Help paradigm (F1 calls up application Help for example). -

- -
-

Keyboard Interaction

-
    -
  • Control + F1 -
      -
    • Posts the Popup Help widget.
      • -
    • Input focus is placed on the first interactive element in the Popup Help.
      • -
    • event.stopPropagation(); and event.preventDefault(); will re-purpose the keys.
      • -
    • With the exception of Control F1 to bring up Popup Help this widget is very similar to Dialog (Modal) and/or Dialog (Non-Modal) and/or Dialog (tooltip) described elsewhere in this document.
      • -
    -
    • -
  • Esc -
      -
    • Causes no menu action and dismisses Popup Help.
      • -
    • Input focus is returned to the element, or widget the Popup Help was invoked from.
      • -
    • Pressing Enter when input focus is on the "X" glyph acts the same as pressing Esc.
      • -
    -
    • -
  • Tab -
      -
    • One of the following occurs: -
        -
      • Modal behavior -
          -
        • Moves input focus between elements in the Popup Help's tabbing order. -
            -
          • Input focus stays in the Popup Help until one of the following occurs: -
              -
            • Esc is pressed.
              • -
            • Enter is pressed when input focus is on an interactive widget/element.
              • -
            -
            • -
          -
          • -
        -
        • -
      • Non-Modal behavior -
          -
        • Moves input focus to the next tabbable element in the tabbing order if the following applies: -
            -
          • Popup Help is posted.
            • -
          • It contains no tab navigable elements in it.
            • -
          -
          • -
        -
        • -
      -
      • -
    -
    • -
  • Shift + Tab -
      -
    • As with other keyboard conventions described here, the Shift + Tab has the effect of moving the focus up rather than down and follows the same conventions as described for the modal and non-modal Tab key above.
      • -
    -
    • -
  • Enter -
      -
    • Activates the element in the Popup Help that has input focus, if applicable, then dismisses the popup. -
        -
      • Input focus should be placed on the appropriate element after the user presses the Enter key. -
          -
        • The appropriate place to move input focus to will not always be the parent element the Popup Help was invoked from.
          • -
        -
        • -
      • Nothing occurs if input focus is on an element that has no associated action.
        • -
      -
      • -
    -
    • -
  • F6 -
      -
    • In the non-modal instance, the F6 key can be used to move focus between the application and the open non-modal window. This is also the behavior described in Dialog (Non-Modal) above.
      • -
    -
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties

-

See Dialog (Modal) and/or Dialog (Non-Modal) and/or Dialog (tooltip).

-
- -
-

Example

-

Add link to example.

-
-
- -
-

Rich Text Editor

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

-

Input control that accepts free-form text as its value.

- -
-

Keyboard Interaction

- -
    -
  • The edit control is provided by the browser; it provides the keyboard support for navigating, adding, removing and selecting text, so that behavior is not defined by the rich internet application.
    • -
  • The browser should also provide a keyboard mechanism for navigating into and out of the edit control. Within most browsers the edit control is put into the tab order of the page and can be navigated into, out of, and through using the tab and shift-tab keys like any standard form control.
    • -
  • A rich text editor widget needs to provide a user interface for interacting with the browser provided edit control. Interaction between the user interface and editor is defined here assuming that a toolbar is used.
    • -
  • Tab and Shift + Tab - If not provided by the browser, the rich text editor widget provides a keyboard mechanism to move into and out of the edit control. Tab and shift-tab are the recommended keystrokes. The toolbar or other user interface component associated with the editor is placed in the tab order immediately before the editor. To set an attribute on text within the edit control the user sets focus into the edit control, moves the insertion point, selects text and presses shift-tab to move focus from the editor back to the toolbar. The user navigates through the toolbar (see toolbar behavior) to a desired attribute and invokes that attribute. When an attribute is invoked, that attribute is applied to the selected text in the editor and focus moves back into the editor at the previous insertion point with the selection intact.
    • -
  • Options: -
      -
    • Rather than using Shift + Tab to move focus from within the editor to the toolbar, another key combination could be used (Alt + Up Arrow, Control + Shift + Letter, etc.). This would eliminate the need to put the user interface control (in this example a toolbar) into the tab order immediately before the editor component. However, there are drawbacks to using a different keystroke to navigate to the user interface: -
        -
      1. It is not as "discoverable" as relying on the standard Tab/Shift + Tab behavior;
        2. -
      2. It is difficult to find key combinations which are not already captured by the browser or assistive technology.
        3. -
      3. Focus could stay within the toolbar after the user invokes an attribute. The user would then have to press an additional key to move focus back into the editor. This would allow multiple attributes to be set on the current selection without having to return back to the user interface but it would add an extra key sequence after setting just a single attribute. Requiring a keystroke to move focus back into the editor would also require modifying the toolbar behavior to intercept this keystroke and to know how to set focus back to the component (the editor) that the toolbar is associated with.
        4. -
      -
      • -
    -
    • -
- -

Optionally, if the developer wishes to provide the ability to insert a tab into the document, it is recommended one of the following methods be used.

-
    -
  • Provide indent and outdent buttons in the menu. Keyboard shortcuts to the buttons should be Control + M for indent and Control + Shift + M for outdent.
    • -
  • Provide a button in the menu to toggle the use of Tab between the two modes. If this button is used, then Control + M is recommended as a keyboard shortcut to toggle the button.
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties

-

Authors are advised to not use ARIA for rich text editors, but to rely on native HTML markup. Current rich text editors typically use an iframe element for editable content. As a result, the editable content is implicitly mapped to a document role in accessibility APIs. If using HTML5, it is recommended that authors use the designMode or contentEditable attributes.

-
- -
-

Example

-

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

- -
-
- - - - - - - -
-

Tree Grid

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

-

- A grid whose rows can be expanded and collapsed in the same manner as for a tree. - A Tree Grid is a combination of a Treeview and a Table with rows that are expandable. -

- -
-

Keyboard Interaction

-

There are two modes of keyboard interaction:

-
    -
  • Navigation Mode (Read-Only) is the default mode, and allows quick and intuitive navigation around the grid. -
      -
    • Tab -
        -
      • The initial tab enters the grid with focus on the first cell of the first row, often a header.
        • -
      • Once in the grid a second tab moves out of the grid to the next tab stop.
        • -
      • Once focus is established in the grid, a Tab into or a Shift + Tab into the grid will return to the cell which last had focus.
        • -
      -
      • -
    • Left Arrow and Right Arrow keys navigate between columns. If the next cell in the row is empty, focus should not move.
      • -
    • Up Arrow and Down Arrow The down arrow moves focus to the first column of a child row, if expanded. Otherwise focus is moved to the same column in the next row. Up arrow performs the same navigation but in reverse.
      • -
    • Control + Left and Control + Right Arrows expand or collapse rows.
      • -
    • If the cell contains an editable field, the Enter key starts edit mode and the Escape key exits edit mode.
      • -
    • Selecting Cells -
        -
      • Control + Space selects the current column.
        • -
      • Shift + Space selects the current row.
        • -
      • Control + A selects the entire grid.
        • -
      • Shift + Arrow selects contiguous cells.
        • -
      • Shift + F8 Allows additional cells to be added to a previous selection to accomplish non-contiguous selection.
        • -
      -

      See Global Recommendations for information on cut, copy and paste.

      -
      • -
    -
    • -
- -

The author may choose to indent child nodes visually. This should be done with an appropriate number of spacer cells marked as presentation in order to keep the headers aligned.

- -

If cells are used for padding or layout of the hierarchy, navigation to those presentational cells should be prevented.

- -
    -
  • Actionable Mode (Interactive) allows the interaction with other objects that might be found in the grid cells such as edit fields, links, etc. -
      -
    • F2 pressed anywhere inside the grid will enter Actionable Mode. Focus will not be moved.
      • -
    • Enter pressed while focus is on an actionable item will enter Actionable Mode. Focus will remain on the actionable item that has focus.
      • -
    • Optionally, alphanumeric keys pressed while focus is on an actionable item will enter Actionable Mode. Focus will remain on the actionable item that has focus.
      • -
    • Tab will move to the next actionable (tabbable) item in the grid and stay within the grid wrapping at the bottom. In this mode each tabbable object in each cell of the grid can be reached with the tab key. If multiple tabbable items are located inside a single grid cell, the tab will stop at each one. When the last tabbable item in a cell is reached the next tab will move to the next tabbable item in the grid, wrapping at the last tabbable item in the grid.
      • -
    • Shift + Tab moves to the previous actionable (tabbable) item in the grid and stays within the grid, wrapping at the top.
      • -
    • Escape exits Actionable mode (by which the user may enter text or perform an action to complete a operation) and returns to Navigation Mode (where the user is allowed to move focus among elements). If a widget is in the current grid cell that also uses the Escape key, then it should cancel the event propagation. A subsequent press of the Escape key will return focus to the parent widget.
      • -
    -
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties

-

- Uses the WAI-ARIA role treegrid, and requires the child element row. - By default a treegrid is considered to be editable, meaning all gridcells are editable. -

-
    -
  • To make a treegrid read-only, set aria-readonly="true" on the document element having a role="treegrid." This will make all gridcells read-only.
    • -
  • To override the read-only status on an individual gridcell, set its aria-readonly property to false.
    • -
-
- -
-

Example

-

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

-
    -
  • For a visual (not accessible) example of where padding cells have been implemented see: dojo's TreeGrid example.
    • -
  • An example where padding cells have not been used (also not accessible): Oracle's Tree Grid.
    • -
-
-
- -
-

Wizard

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

-

A sequence of dialogs or panels guiding the user through performing a task.

- -
-

Keyboard Interaction

-

A Wizard can be done in several ways. Either is valid.

-
    -
  • Method 1: Like a Toolbar
    • -
  • Method 2: Controls as Default Actions -
      -
    • Escape cancels the wizard.
      • -
    • Enter invokes the "next" action; If the last page, it invokes "finish"
      • -
    -
    • -
  • Method 3: Hot Keys -
      -
    • Control + Alt + N next, finish
      • -
    • Control + Alt + P previous
      • -
    • Escape cancel, exit without saving
      • -
    • Control + Alt + R reset current page to default settings
      • -
    • Control + Alt + S save and exit
      • -
    -
    • -
  • Method 4: Like a Dialog
    • -
-

Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. Authors should ensure that Enter activates only the widget they intend.

-
- -
-

WAI-ARIA Roles, States, and Properties

-
- -
-

Example

-

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

-

Dojo nightly

-
-
- -
- -
-

General Steps for Building an Accessible Widget with WAI-ARIA

-

This content could be useful when working on issue 73.

-

At this point you should have a basic understanding of how WAI-ARIA is used to support interoperability with assistive technologies. If you are not reusing a WAI-ARIA-enabled widget library and wish to create your own the following steps will guide you through the thought process for creating an accessible widget using WAI-ARIA.

-
    -
  1. -

    Pick the widget type (role) from the WAI-ARIA taxonomy

    -

    WAI-ARIA provides a role taxonomy ([[WAI-ARIA]], Section 3.4) constituting the most common UI component types. Choose the role type from the provided table. If your desire was to create a toolbar set the role to toolbar:

    - 
    <div role="toolbar">
    -
    2. -
  2. From the role, get the list of supported states and properties -

    Once you have chosen the role of your widget, consult the [[WAI-ARIA]] for an in-depth definition for the role to find the supported states, properties, and other attributes. For example, the toolbar role definition includes:

    -
    -
    superclass role
    -
    In the taxonomy the widget you selected inherits states and properties from this role. In the case of a toolbar you will see that a toolbar is a subclass of a group. This makes sense given that a toolbar is a collection of commonly used functions.
    -
    related concept
    -
    This is really more informative to state what other concepts are similar to this role. These may exist in different host languages outside WAI-ARIA. - The keyboard model - for the control should emulate that of the related concept control.
    -
    supported states and properties
    -
    These are unique states and properties that this widget supports and that were not inherited from its ancestors in the taxonomy. In the case of a toolbar there are no such states or properties. However, in the case of a listbox, you may choose to set the property of aria-multiselectable to true if you were to have more than one item in the listitem selected at a time. This indicates to the assistive technology that the listbox manages a collection of selectable options.
    -
    inherited states and properties
    -
    These are all the states and properties which are inherited from the roles's ancestors and which you may use.
    -
    global states and properties
    -
    These are states and properties which apply to all host language components regardless of whether a role is set or not. You may use these as well.
    -
    -

    Once you have chosen the states and properties that apply to your widget you must set those properties you will use to set their initial values. Note: You do not need to use all the states and properties available for your role. In our case we shall use:

    - 
    <div role="toolbar" id="customToolbar" tabindex="0" aria-activedescendant="button1"
-      onkeydown="return optionKeyEvent(event);"
-      onkeypress="return optionKeyEvent(event);"
-      onblur="hideFocus();"
-      onfocus="showFocus();"
-      >
-      <img src="img/btn1.gif" title="Home" alt="Home" role="button" id="button1"
-           onclick="updateText('Home was invoked');">
-      <img src="img/btn2.gif" title="Refresh" alt="Refresh" role="button" id="button2"
-           onclick="updateText('Refresh was invoked');">
-      <img src="img/btn3.gif" title="Help" alt="Help" role="button" id="button3"
-           onclick="updateText('Help was invoked');">
-</div>
-
    -

    By setting tabindex=0 on the toolbar, the toolbar will receive focus in the document order. It is necessary then to use script and the aria-activedescendant property to manage virtual focus among the buttons. The details are given in step five, below.

    -
    -

    Important: When embedding WAI-ARIA markup in (X) HTML, all WAI-ARIA states and properties must be preceded with the characters aria- with the exception of the role and tabindex attributes. Otherwise, the user agent will not map the WAI-ARIA information, resulting in it not being recognized by assistive technologies.

    -

    When embedding WAI-ARIA into other host languages, tabindex does not carry over. The WAI-ARIA tabindex extensions are specific to (X)HTML to repair deficiencies in keyboard support.

    -
    -
    3. -
  3. Establish the widget structure in the markup (parent/child) -

    Assistive technologies are very dependent on the structure of widgets as well as general document structure. Structure provides context to the user. A toolbar is a collection of common functions made available to the user. Therefore, all functions you would like in the toolbar must be contained within it. This can be determined by using the [[dom]] tree structure created by the browser when parsing the host language. By using the parent child relationship of the DOM, an assistive technology can determine all the related toolbar widgets associated with the toolbar. The toolbar widgets would be DOM children of the "toolbar" container. For our purposes we will define three image buttons for cut, copy, and paste.

    - 
    <div role="toolbar" tabindex="0" aria-activedescendant="button1">
-  <img src="buttoncut.png" alt="cut" id="button1">
-  <img src="buttoncopy.png" alt="copy" id="button2">
-  <img src="buttonpaste.png" alt="paste" id="button3">
-</div>
    -
    4. -
  4. Repeat steps 1-3 for the children of the parent -

    We now need to assign the roles and states for each of the children. However, we shall save the detailed navigation for step 5.

    - 
    <div role="toolbar" tabindex="0" aria-activedescendant="button1">
-  <img src="buttoncut.png" alt="cut" role="button" id="button1">
-  <img src="buttoncopy.png" alt="copy" role="button" id="button2">
-  <img src="buttonpaste.png" alt="paste" role="button" id="button3">
-</div>
-
    -

    The process of setting roles and states may be a recursive procedure if the children themselves have children, such as in the case of an expandable/collapsible tree widget.

    -
    5. -
  5. -

    Establish keyboard navigation of the widget and plan for how it will be navigated to within the document

    -

    It is very important that your widget be keyboard accessible. In fact, there must be a keyboard equivalent for every mouse operation. Where possible you should refer to the WAI-ARIA examples in this guide for tips on how to implement keyboard navigation for your widget. If you find that an example is not provided, you should follow standard keyboard bindings for UI components such as those used for the Java Foundation Classes for Windows 95/NT.

    -

    Commented out link to conference paper, which a) was broken, and b) we should have more canonical references than conference papers for things like this.

    -

    For our toolbar, we have chosen to have the toolbar manage the focus for its children and through the use of the aria-activedescendant property. We have also chosen to have the toolbar receive focus based on the tab order by using tabindex. In order to use aria-activedescendant, each focusable descendant must have an assigned ID.

    - 
     <head>
- <script>
-    …
-    function optionKeyEvent(event)
-      {
-      var tb = event.target;
-      var buttonid;
-
-      DOM_VK_ENTER = 13;
-      // Partial sample code for processing arrow keys
-
-      if (event.type == "keydown") {
-         if (event.altKey) {
-           return true;  // Browser should use this, the menu view doesn't need alt-modified keys
-         }
-         // XXX Implement circular keyboard navigation within the toolbar buttons
-
-         if (event.keyCode == DOM_VK_ENTER) {
-           ExecuteButtonAction(getCurrentButtonID()); // This is an author defined function
-         }
-         else if (event.keyCode == event.DOM_VK_RIGHT) {
-           // Change the active toolbar button to the one to the right (circular) by
-           var buttonid = getNextButtonID();   // This is an author defined function
-           tb.setAttribute("aria-activedescendant", buttonid);
-         }
-         else if (event.keyCode == event.DOM_VK_LEFT) {
-            // Change the active toolbar button to the one to the left (circular) by
-            var buttonid = getPrevButtonID();  // This is an author defined function
-            tb.setAttribute("aria-activedescendant", buttonid);
-         }
-         else {
-            return true;
-         }
-         return false;
-      }
-      else if (event.type == "keypress") {
-        …
-      }
-    }
-</script>
-
-<div role="toolbar" tabindex="0" aria-activedescendant="button1" id="tb1"
-  onkeydown="return optionKeyEvent(event);"
-  onkeypress="return optionKeyEvent(event);">
-  <img src="buttoncut.png" alt="cut" role="button" id="button1">
-  <img src="buttoncopy.png" alt="copy" role="button" id="button2">
-  <img src="buttonpaste.png" alt="paste" role="button" id="button3">
-</div>
    -

    The details of implementing keyboard navigation are described in Keyboard and Structural Navigation section of this document.

    -

    You must also show the visual focus for each element that has focus.

    -
    6. -
  6. -

    Apply and manage needed WAI-ARIA states in response to user input events

    -

    Similar to the processing of aria-activedescendant in Step 5, as author you must set any additional WAI-ARIA states and properties on document elements.

    -
    7. -
  7. -

    Synchronize the visual UI with accessibility states and properties for supporting user agents

    -

    Thomas comment: is confusing that the example switches from toolbar to treeitem. Maybe the best overall sample is to do a tree because it demonstrates each of the points you want to make?

    -

    You should consider binding user interface changes directly to changes in WAI-ARIA states and properties, such as through the use of CSS attribute selectors. For example, the setting of the aria-selected state may change the background of a selected treeitem in a tree. This may also be done with JavaScript.

    - 
    -.treeitem[role="treeitem"][aria-selected="true"] {color: white; background-color: #222222;}
-
-.treeitem[role="treeitem"][aria-selected="false"] {color: white; background-color: beige;}
    -

    Authors should be aware that CSS attribute selectors are not supported in some browsers, such as Internet Explorer 6. A consistent way to apply styling to reflect WAI-ARIA semantics would be to assign an element a class name based on the WAI-ARIA attribute being set using script as shown here:

    - 
    function setSelectedOption(menuItem)
-     {
-        if (menuItem.getAttribute("role") != "menuitem") {
-           return;
-        }
-        var menu = getMenu(menuItem);
-        var oldMenuItem = getSelectedOption(menu);
-
-        // Set class so that we show selection appearance
-        oldMenuItem.className="unselected";
-        menu.setAttribute("aria-activedescendant", menuItem.id);
-        menuItem.className= "selected";
-      }
    -
    8. -
  8. Showing and Hiding Sections in a Widget -

    The proper synchronization of showing and hiding sections in a widget with the WAI-ARIA display state is also critical. Some platform accessibility APIs provide events for applications to notify the assistive technology when pop-ups such as menus, alerts, and dialogs come into view or go away. Rich Internet applications can assist browsers which support these conventions by:

    -
      -
    1. -

      Creating an entire section and then insert it into the [[dom]], as a subtree of the parent element activated to show the pop-up, and then removing the section from the inserted area when the pop-up goes away.

      -

      OR

      -
      2. -
    2. -

      Using the following style sheet properties to show and hide document sections being used to represent the pop-up items, menus or dialogs:

      -
        -
      • display:block
        • -
      • display:none
        • -
      • visibility:visible
        • -
      • visibility:hidden
        • -
      -

      By monitoring these behaviors a user agent may use this information to notify assistive technology that the pop-up has occurred by generating the appropriate accessibility API event.

      -
      3. -
    -

    Some assistive technologies may use the DOM directly to determine these when pop-up occurs. In this case, the first mechanism of writing a section to the DOM would work using the DOM events as demonstrated here.

    - 
    -    // create new table row with table cell and div
-    var newTr = document.createElement('TR');
-    var newTd = document.createElement('TD');
-    var newDiv = document.createElement('DIV');
-    newTr.appendChild(newTd);
-    newTd.appendChild(newDiv);
-
-
-    //insert this new table row before the Node selected
-    var container = theNode.parentNode;
-    container.insertBefore(newTr, theNode);
-
-    //remove theNode selected
-    container.removeChild(theNode);"
    -

    However, if you are using CSS to show and hide sections of the DOM (2) it is essential that you set the corresponding WAI-ARIA aria-hidden property to indicate that the section is visible or hidden and synchronize it with your CSS styling as shown here:

    - 
    [aria-hidden=true] {visibility: hidden;}
-
-…
-
-<div role="button" aria-haspopup="true" aria-owns="mypopupmenu">
-<div role="menu" aria-hidden="true" id="mypopupmenu">…</div>
    -
    9. -
  9. Support basic accessibility, such as alternative text on images -

    When an image is used to represent information within a component, such as image buttons, you need to set the alternative text on those images. This is then mapped by the user agent to the accessible name in the platform accessibility API. Using our example:

    - 
    <div role="toolbar" tabindex="0" aria-activedescendant="button1" id="tb1"
-     onkeydown="return optionKeyEvent(event);"
-     onkeypress="return optionKeyEvent(event);">
-   <img src="buttoncut" role="button" id="button1" alt="cut">
-   <img src="buttoncopy" role="button" id="button2" alt="copy">
-   <img src="buttonpaste" role="button" id="button3" alt="paste">
-</div>
    -
    10. -
  10. Establish WAI-ARIA relationships between this widget and others -

    Once you have made the basic widget accessible you may then need to establish its relationship to other widgets. Examples of this are aria-labelledby, aria-controls, aria-describedby and aria-flowto. The details of using these relationships are described in the Relationships section of this document.

    -

    Other relationships which should be considered are more declarative and provide context to the widget within a set. For these, aria-level, aria-posinset, and aria-setsize are provided. If you structure your Document Object Model appropriately so that the user agent can determine this information from it using the DOM hierarchy directly, you do not need to set these properties. There are, however, situations in rich internet applications where all the elements in a container are not in the DOM at one time, such as when you can only render the ten of fifty items in a subtree. In this case the user agent cannot determine the number of tree items (aria-setsize) for the position in the set (aria-posinset), and potentially the tree depth (aria-level) from the DOM. In these situations you will need to provide these WAI-ARIA properties.

    -
    11. -
  11. -

    Review widget to ensure that you have not hard coded sizes

    -

    The ability for applications to respond to system font settings is a requirement. Most user agents are designed to meet this requirement. This also means your Web application running within your browser is impacted when the user agent changes the font sizes to meet the need. If you have hard coded your font size in pixels an increase in system fonts will not be reflected in your Web application. You must also not hard code the size of your widgets in pixels either. If the fonts are scalable, but the widget they are encapsulated in is not, then the text could flow outside your widget.

    -

    Follow these rules to allow your application to respond to system font settings:

    -
      -
    • Establish a base set of font sizes used in widgets based on percentage of the container element font size.
      • -
    • Use CSS width, borders, margin, padding, background, and positioning properties to specify the graphical rendering of widgets and their sub-components, use percentage units or em units to specify widths of widget components (An em is a the font unit of measure between the top and bottom of an upper case letter M.). Border widths, padding, and margins can use PX units.
      • -
    • Use scripting for run time CSS positioning of widget sub-components in relation to other sub components.
      • -
    • Make sure all widgets use consistent height and width units of measure.
      • -
    -

    -Percentages are the most reliable way to consistently specify proportional text sizes in widgets. The use of percentages and em should be used for specifying widths of a widget and the widget sub components. The use of percentages for text size and percentages and em units for widths support browser zoom capabilities to make widgets larger or smaller. - -Pixels can be used for specifying line widths, padding and margins.

    -

    Important: Most browsers today have a zoom feature which allow the user to magnify the entire Web page. Most legislation today requires that your application respond to system font and color settings and therefore you will want to consider the fact the system settings could adversely affect your Web page should you decide to hard code pixel sizes.

    -
    12. -
  12. Compensate for Background Images when in High Contrast Mode -

    Authors use background images when styling their widgets, including situations where the background image is not merely decorative, but informative. An example is a horizontal progress bar that it is filled by gradually revealing more of a background image. This is accomplished by initially setting the width of the element to zero, and then incrementing its width in accordance with the degree of progress.

    -

    High contrast mode is an operating system display modification that makes the screen easier to see for low vision users. Some operating systems (e.g., Windows), do not display background images when in high contrast mode. Consequently, the progress bar described above appears empty regardless of the progress. It is recommended that authors not use background images as the sole method to convey important information, and to compensate with alternative or additional style rules.

    -

    In the case of the progress bar example, a technique that works when in high contrast mode is to style the element with a border. Since the width of the element is updated as progress increases, its border gradually expands horizontally forming an ever wider unfilled rectangle. This provides alternative visual feedback as to the extent of the progress.

    -

    Another technique is to replace a background image with text. Consider a dialog that uses a background image for its close box. To compensate for the missing close box when in high contrast mode, a lower case 'x' is used instead. The compensation technique used depends on the context, particularly the purpose of the background image.

    -

    There are two general approaches with respect to detecting high contrast mode. They are (1) executing a script to determine if the system is in high contrast mode, or (2) providing a preference to use alternative styles. The advantage of automatic detection is that some operating systems simply apply a different color palette when in high contrast mode and do not turn off background images. In that case, authors need not compensate for missing background images. However, detection of high contrast mode by script is relatively expensive compared to a preference that users can set, and, presumably, users can see whether background images are displayed in high contrast mode on their system. It is up to individual authors to decide which method they find acceptable for their particular situation.

    -

    The following code fragment outlines how to detect high contrast mode.

    - 
    -/* Define styles for the high contrast test element */
-#hiContrastTestEl {
-    border: 1px solid;
-    border-color:red green;
-    position: absolute;
-    height: 5px;
-    top: -999px;
-    background-image: url('resources/blank.gif');
-}
-…
-// An onload event handler that inserts the high contrast test element and
-// then tests its computed styles.
-function detectHiContrast() {
-    var div = document.createElement('div');
-    div.setAttribute ('id', 'hiContrastTestEl');
-    // … append <div#hiContrastTestEl> to the <body> element …
-    var cs = window.getComputedStyle(div);
-    var bki = cs.backgroundImage;
-    var hiContrast = false;
-
-    // The CSS sets the top and right borders of the test element to red and
-    // green, respectively.  In high contrast mode either the borders are
-    // the same color, or there is no legitimate url to the background image.
-    hiContrast =    (cs.borderTopColor == cs.borderRightColor) ||
-                    (bki != null && (bki == 'none' || bki == 'url (invalid-url:)'));
-
-    if (hiContrast) {
-        // apply hi contrast styles to compensate for missing background images.
-    }
-    // … remove the test element from the document …
-}
    -
    13. -
  13. Test with User agent, Assistive Technology, and People with disabilities -

    To ensure you have set your WAI-ARIA semantics correctly, test your application with your user agent, an assistive technology, and a person with disability. Example assistive technologies are screen readers and screen magnifiers. Ensure that your user agent is designed to support WAI-ARIA and their your assistive technology is designed to support WAI-ARIA in the selected user agent.

    -

    Finding people with disabilities to do testing may be difficult but many companies employ people with disabilities, including your customers, and you should reach out to them to ask for help. Other places to look are advocacy groups like the National Federation of the Blind or your local schools for the blind, reading and learning centers, and so on. The people you reach out to may someday need to use what you produce.

    -
    14. -
-
- -
-

Providing Navigable Structure within Web Pages

-

- Matt King: Removed on July 10 per discussion in May 23, 2016 meeting. - This section is redundant given the new landmark section. - The parts that are not redundant are either out-of-date or not necessary. The possible exceptions are content covering the group and directory roles. -

-

- This section takes a broader look at the Web page. - It is intended to assist you in conveying a logical, usable, and accessible layout to an assistive technology or adaptive system designed to modify the visual layout to meet the users needs. -

-

- One of the deficiencies of (X)HTML for disabled users has been the usability of keyboard navigation. - Users dependent on a keyboard for navigation have been forced to tab everywhere in the document, as the only keyboard accessible document elements are form and anchor elements. - This has forced developers to make most everything a link to make it keyboard accessible, and to get to each link you have to tab to it. - With the advent of portals and other content aggregation means Web pages are divided into visible regions and there has been no vehicle to get to them other than perhaps to do things such as:

- -

There are number of problems with this approach:

- -

- This remainder of this section provides the author with a playbook for using WAI-ARIA to add semantically rich navigation structure in a Web page so that an assistive technology may provide an effective user experience and avoid these shortcomings. -

-
-

Steps for Defining a Logical Navigational Structure

-

- - Due to the complexity of today's web content, it is imperative that all content reside in a navigation landmark. Sight and mobility impaired users must be able to quickly access a list of landmarks for a web page, to be used as a table of contents. - This allows the user to quickly navigate to important sections of the page without "endless" TAB navigation. If this is not done, then content will be orphaned and missed by the user. In fact many of today's accessibility test tools have built-in rules to flag this issue as a compliance error. This section defines how to create these navigable regions of the page:

-
    -
  1. -

    Identify the logical structure of your page

    -

    Break up your page into perceivable block areas which contain semantically associated information called "regions". You can further break down each region into logical regions as needed. This is a common process undertaken by portal developers who break the page into perceivable regions called portlets. Think about the user wanting to navigate to these logical block areas on your Web page. Write down a description of what you believe each region to be.

    -

    Depending on your Web application you may then need to break it into sub regions depending on the complexity of your Web application. This is a recursive process. A user will look at these perceivable areas like pealing an onion. You might have an outermost collection of perceivable regions or block areas and upon entering each region you may have a collection of regions within it.

    -
    2. -
  2. -

    Implement the logical structure in markup

    -

    Implementing the block structure in markup often involves wrapping elements contained with a "region" such as a <div> or <iframe> with visible borders so that each region or block is perceivable to the user.

    -
    3. -
  3. -

    Label each region

    -

    Once you have broken up each region you need to label it. The start of each region must have a perceivable header and it should be used to label the region. For details on how to do this see section 3.4.3.1 Header Levels vs. nesting level to create a header to label each region. If you're finding it difficult to come up with a label for the region, make sure at least to use one of the standard roles defined in the following step. The drawback of not providing a label is that users will not know the purpose of the region. By definition, regions would be included in a summary of a page. If an assistive technology were to summarize it would be unable to provide information about the section without a label.

    -
    4. -
  4. -

    Assign landmark roles to each region

    -

    Now that you labeled your regions, you need to assign them semantic navigation landmarks. Landmarks are a vast improvement over the rudimentary "skip to main content" technique employed prior to WAI-ARIA. If possible it is best to use these as landmarks. Skip to main content links may impact the placement of web application elements. This may be a consideration for developers that want to try to keep their web application in a specific visible area. Consequently, layout adjustments may need to be made to support skip to main content links. Also, skip to main content links are limited in that they only address only one main content area. WAI-ARIA provides a collection of landmarks which are applied to each of the regions you identified in step 2.

    -

    The presence of common, semantic, navigation landmarks allows each site to support the same standard and allows your assistive technology to provide a consistent navigation experience - an important feature for screen readers and alternate input solutions. For users with cognitive and learning disabilities the landmark information could be used to expand and collapse these regions of your page to aid in simplifying the user experience by allowing the user to manage the amount of information processed at any one time.

    -

    WAI-ARIA landmark roles that are applied to elements having strong native semantics are not mapped consistently to the platform accessibility API. An example is the TABLE element. For this reason, it is recommended that authors apply landmarks to DIV and SPAN containers.

    -

    There are also mainstream benefits of providing navigation landmarks. Your browser may assign key sequences to move focus to these sections as they can be set on every site. Navigation to these landmarks is device independent. A personal digital assistant (PDA) could assign a device key to get to them in your document. The common landmarks in WAI-ARIA include:

    -
    -
    application
    -
    -Represents a region of the page representing a unique software unit executing a set of tasks for its users. It is an area where assistive technologies should also return browse navigation keys back over to the web application in this region. -

    If the entire web page has a role of application then it should not be treated as a navigational landmark by an assistive technology.

    -
    -
    banner
    -
    A region that contains the prime heading or internal title of a page.
    -
    complementary
    -
    Any section of the document that supports but is separable from the main content, but is meaningful on its own even when separated from it.
    -
    contentinfo
    -
    Meta information which applies to the first immediate ancestor whose role is not presentation.
    -
    form
    -
    A region of the document that represents a collection of form-associated elements, some of which can represent editable values that can be submitted to a server for processing.
    -
    main
    -
    Main content in a document.
    -
    navigation
    -
    A collection of links suitable for use when navigating the document or related documents.
    -
    search
    -
    The search tool of a Web document.
    -
    -

    To set a landmark in your page:

    - 
    <div role="navigation" title="Table of Contents"> … </div>
-<div role="main" title="Game Statistics"> … </div>
    -
    5. -
  5. For application landmarks with static prose -

    - If you have a regional landmark of type application and static descriptive text is available, then on the application landmark, include an aria-describedby reference to associate the application and the static text as shown here:

    <div role="application" aria-labelledby="calendar" aria-describedby="info">
-<h1 id="calendar">Calendar<h1>
-<p id="info">
-This calendar shows the game schedule for the Boston Red Sox.
-</p>
-<div role="grid">
-…
-</div>
    -
    6. -
  6. For landmarks unsuited to specialized region WAI-ARIA roles -

    You can create custom regional landmarks by using a generic region. While it is not essential to label these specialized regions with a header, you should provide a title to ensure that the region name is accessible to all users, just as you would the standard regional landmarks. See Header levels versus Nesting levels for directions on how to label the region.

    - 
    <div role="main"> … <div role="region" title="weather">
-
    -

    Note: the region role is generic and should only be used when a more specific role is not applicable.

    -
    7. -
  7. -

    Indicate to the assistive technology who controls the keyboard navigation

    -

    Today's screen readers for the blind have been designed to give the user a "browsing" experience meaning the screen reader consumes a number of keys to aid in the browsing experience. For example, the "up" and "down" arrow keys are used to read the next and previous line of text on your Web page. Accessible rich internet applications will use these keys in an application to navigate within "widgets" like a Tree View.

    -

    Assistive technologies must be able to identify widgets which implement WAI-ARIA and allow them use of the keyboard. However, if you have used numerous widgets to form an application you must set the role on the encompassing region to application. Should you have regions which should be browsed as documents within the application region you should mark those regions with a document role as needed. See section 3.4.2 Structural Roles used to facilitate assistive technology navigation.

    -
    8. -
-
-
-

Structural Roles that Facilitate Navigation with Assistive Technologies

- While WAI-ARIA is designed to address many disabilities, this section is best described in terms of screen reader use. In desktop applications, screen readers typically treat widgets as discrete entities, reading and interacting with each widget one at a time. The user moves the point of focus from widget to widget using tab/shift tab, mnemonics, or accelerators, keyboard commands which are usually provided by the application or the operating system. We refer to this mode of interaction as "application mode." -

When viewing Web content however, screen readers often gather information about all the widgets in an area and present them in a document-like view which the user navigates using keyboard commands provided and controlled by the screen reader. Think of this mode as a virtual environment that presents Web content in a way that makes it convenient for adaptive technology users to navigate and read. This is sometimes called browse mode, or virtual mode. We refer to this as "document browse mode."

-

Because many screen readers provide document mode navigation support using single key mnemonics on the alpha-numeric keyboard, they may provide a third mode, called "forms mode," used to interact with form controls that are encountered in document mode. Behavior in forms mode is similar to that of application mode. The key feature of forms mode is that it can be toggled with document mode to make it easy to both interact with a specific widget, and read virtualized content of which the widget is a part. Since, as described above, a screen reader's perception of an area as either a document or an application greatly influences how the user reads and interacts with it, WAI-ARIA provides content authors a way to indicate whether their pages must be viewed as applications or documents by assistive technologies.

-

To set document or application mode follow these steps:

-
    -
  1. -

    Set the Application Role

    -

    After you have divided your Web page into regions through the use of role landmarks and custom regions, you must make a decision: Is your Web page an application or not? If the majority of the content is application-like the default interaction mode should be set to application, with document regions embedded within the application if applicable. Otherwise the default interaction mode is document-like and therefore should not be overridden by the use of a global role of application. In this case the application role can be placed on discrete regions within the document if applicable.

    -

    If it is, set the role of application on the body tag as follows:

    - 
    <body role="application">
    -

    When using application, all static text must be associated with widgets, groups or panes via using the aria-labelledby and aria-describedby properties, otherwise it will not be read by the screen reader when the user navigates to the related widget or group.

    -

    Special Considerations:

    -
      -
    • If you have selected to have a role of application on the body tag, it is recommended that a widget have focus after the page is first loaded. There may be an instance when an application itself needs to receive focus, such as an application consisting solely of a scrollable editable text area.
      • -
    • If when your page loads and you should have focus on a widget this is a strong indicator that your Web page should have role of application.
      • -
    • If your page has only a few isolated widgets, like pop-up calendars located on a Web page, it is not necessary to expressly set the role of application on the body. Screen readers, based on widget roles, must be able to provide access to these widgets without recognizing the entire page as an application.
      • -
    • Also, browsers make use of a feature called the contenteditable attribute, which will be incorporated into HTML 5. Contenteditable allows an author to turn the browser section into a rich text editor, similar to a word processor. Any section which has contenteditable set to "true" is considered a widget.
      • -
    • If the body element has been given the role of application, please follow step 3. Otherwise, the Web page is considered a document, and no further action is required in this regard.
      • -
    -
    2. -
  2. Dialogs and alert dialogs - special case application roles -

    WAI-ARIA provides dialog and alertdialog roles that are to be treated as special case application roles. Like application, screen readers will leave the main job of keyboard navigation up the dialog.

    -

    When using dialog, all static text must be associated with widgets, groups or panes using the aria-labelledby and aria-describedby properties, otherwise it will not be read by the screen reader when the user navigates to the related widget or group. Unlike an application, your Web page is unlikely to start out as either of these two roles but rather the author is most likely to dynamically create dialogs or alertdialog sections within the Web page.

    -

    Unlike dialog, descriptive text of the alert does not need to be associated via a relationship, as the contents of alert dialogs will be read automatically by the screen reader when the dialog opens.

    -
    3. -
  3. Set the document role
    4. -
-
-

The default mode for a screen reader to be processing an HTML Web page is document browse mode. This is equivalent to having a role of document on the HTML <body> tag. If you have already specified a role of application on the body tag there may be times in which you tell the screen reader to switch into "document browse mode" and start stealing the necessary keys to browse a document section of your Web page. These keys are the typical keys used by WAI-ARIA widgets and to provide this level of navigation the keys must be stolen from your browser.

-

To mark areas of your page to tell the assistive technology when to switch into document browse mode, look at the regions/landmarks you have defined and determine which ones must be browsed as a document or navigated as an application. For each region which must be browsed in document browse mode, embed a div element within it with the role of document as follows:

- 
<div role="document">
-

Now, when a screen reader encounters this region, it will change its interaction model to that of document browsing mode.

-
-
-
-

Implicit Nesting and Headings

-

This section discusses the use of the heading role and nesting levels.

-
-
Header Levels Versus Nesting Levels
-

The heading role value signifies a heading for a section of the document instance. Use of the heading role indicates that a specific object serves as a header. The region of the document to which the heading pertains to should be marked with the aria-labelledby property containing the value of the id for the header. If you have a heading and there is no element containing the content that it heads, wrap the content in a <div> bearing this aria-labelledby attribute. If headings are organized into a logical outline, the aria-level property can be used to indicate the nesting level. Here is an example with and without ARIA. Note that the preferred way is using native semantics without ARIA, but the approach with ARIA is shown first to demonstrate use of the heading role:

- 
Using ARIA:
-<div role="main" aria-labelledby="page_title">
-  <p id="page_title" role="heading" aria-level="1">Top News Stories</p>
-   … main page contents here …
-</div>
-
-Using native markup:
-<div role="main" aria-labelledby="page_title">
-  <h1 id="page_title">Top News Stories</h1>
-   … main page contents here …
-</div>
-
-
-
-
Owns Repairs Nesting
-

Assistive technology briefs users on the context where they are. When they arrive at a new page, a page summary may be given. When they move into a new context, some of the labeling from elements containing the new focus or reading location may be rendered by the assistive technology, to give context to the details to be read next.

-

The syntactic structure of a page provides the default nesting of contexts. If a paragraph is nested in a <div> or table cell, it is assumed that labels for the <div> or headers for the table cell are pertinent to what is in the paragraph. On the other hand, it is not possible to always flow the logical structure one-to-one into the parse structure.

-

The aria-owns relationship is provided to annotate logical nesting where the logical child is not a syntactic descendant of the logical parent. In a Rich Internet Application, updates may be made to the document without updating the logical syntactic structure, yet elements may appear to be added to the document structure. From a DOM and accessibility hierarchy perspective aria-owns is a fallback mechanism to using the tree hierarchy provided in the DOM. An example of where aria-owns is needed is a treeitem, where children in a folder subtree are added to a visible subtree but not reflected in the actual document subtree of the folder. The aria-owns relationship can be used to associate the folder with the new "adopted" child. For more details on the use of aria-owns see section 4.2 Owning and Controlling. The aria-owns relationship is used to indicate to a user agent that a menu is an adopting parent of a sub menu. Another use for aria-owns is a hierarchical diagram where the child nodes of the diagram are not be adequately represented using the DOM structure.

-
-
-
-

Directories, Groups, and Regions

-

There are several WAI-ARIA roles used to indicate a collection of user interface objects, and each has a distinct purpose:

-
-
directory
-
Contains a static table of contents
-
group
-
Small set of related user interface objects that would not be included in a page summary or table of contents by an assistive technology
-
region
-
Section of related user interface objects that should be included in a page summary or table of contents.
-
-

The use of each is described below.

-
-
Directories and Their Applicability
-

The WAI-ARIA role, directory, allows authors to mark static table of content sections of a document. Prior to WAI-ARIA, the user would need to guess if an area of a document actually pertained to the table of contents. Authors should mark these sections within a document with a role of directory.

- 
<div role="directory">
-   <ul>
-      <li>Global Warming Causes
-          <ul>
-             <li>CO2 Buildup</li>
-             <li>Auto emissions<li>
-             <li>Factory emissions</li>
-             <li>Destruction of rainforests</li>
-          </ul>
-
-      </li>
-
-      <li>Tailoring CO2 buildup
-          <ul>
-             <li>Elimination of the incandescent light bulb</li>
-             <li>Hydrogen fuel cells</li>
-             <li>Solar energy</li>
-             <li>Wind power</li>
-          </ul>
-
-      </li>
-   </ul>
-
-</div>
-
-
-
Groups and Their Applicability
-

Authors should use a role of group to form logical collections of items with related functionality in a widget. A group should not be considered a major perceivable section on a page. A group neither has a heading nor appears in the "Table of Contents." A group may delineate a set of treeitems having the same level in the tree or it may be used to group a set of related checkboxes in a form. Other examples include:

-
    -
  • a row in a grid (a row is a specialized group representing a row in a grid);
    • -
  • a group of children in a tree widget forming a collection of siblings in a hierarchy; or
    • -
  • a group of items having the same container in a directory
    • -
-

Proper handling of a group by assistive technologies, therefore, is determined by the context in which it is provided. Group members that are outside the DOM subtree of the group need to have explicit relationships assigned for them in order to participate in the group. Groups may also be nested.

-

If an author believes that a section is significant enough in terms of the entire document instance, then the author must assign the section a role of region or one of the designated standard landmarks. The designated landmark roles are listed in the section Regions and XHTML Role landmarks.

-
-
-
Regions and Their Use
-

When defining a region for a section of a document, authors must consider using standard document landmark roles defined in the XHTML Vocabulary. This makes it possible for user agents and assistive technologies to treat roles as standard navigation landmarks. If the definition of these regions is inadequate, authors must use the WAI-ARIA region role and provide the appropriate title text.

-

For more information on the use of region see Regions and XHTML Role landmarks.

-

 

-
-
-
-

Remaining Structural Roles

- -
-
Tabular Structure-Related Roles Supporting Tabular Widgets
-

A number of structural roles support the tabular widgets, grid and treegrid. These structural roles indicate additional keyboard navigation as well as the ability to select rows and/or columns. Typically, you would apply these roles to an underlying table in the base markup as shown here:

- 
<table role="grid">
-

However, that may not work for the developer in all instances, such as when the developer has need for a <div> or <span> or when additional semantics are needed. To assist, the following roles are provided to support tabular widgets:

- -

When constructing a grid or treegrid the author must use gridcells for the actual cells:

- 
<table role="grid">
-   <tr>
-      <td role= "columnheader">Apples</td><td role= "columnheader">Oranges</td>
-   </tr>
-   <tr>
-      <td role="gridcell">Macintosh</td><td role="gridcell">Valencia</td>
-   </tr>
-</table>
-

Unlike table cells within a table, authors should ensure a grid's gridcells are focusable through the use of tabindex (in HTML), or aria-activedescendant on the grid.They may also be editable, as is shown in the above example.

-

Treegrid's may require expanding and collapsing rows which may not be performed using a <tr>. In these instances authors will use an HTML <div>. WAI-ARIA provides a role of row which may be assigned to the <div> to convey to the assistive technology that this is still a row. If you decide to not use the native HTML <table> elements and choose more flexible elements, such as <div> and <span>s, with applied WAI-ARIA roles in this section, you should structurally lay out your elements in line with what you would expect from HTML. All of your rowheaders should be in a row and your gridcells should be children of each subsequent row in the same format as HTML for <td>s and <th>s within <tr>s.

-
-
-
Marking Descriptive Sections
-

- A new feature of WAI-ARIA is the ability to associate descriptive text with a section, drawing, form element, picture, and so on using the aria-describedby property. The use case for aria-describedby is to reference the local id of the long description. The most common use case for longdesc is for the author to create a separate file to describe a picture. It is preferable to have the descriptive text in prose as well so that it is readily available to all users. This is useful for authors who do not want to create a separate document that contains the description, and for cognitively impaired users who can be confused by context changes when having to go to another page for the description. Yet, like longdesc, descriptive text is treated separately from the short name provided by the title or alt attributes in HTML. -

-

- The aria-describedby property allows for the text of hidden elements to be used for accessible descriptions. Some screen reader vendors have used non-standard attributes to provide hidden help text for form elements. In order to standardize this feature, hidden text is exposed in the description property of Accessibility API objects when referenced by aria-describedby. -

- 
<img src="foo" alt="abbreviated name" aria-describedby="prose1">
-
-<div id="prose1">
-   The prose in this div describes the image foo in detail.
-</div>
-

This is the preferred vehicle for providing long descriptions for elements in your document.

-

When the author does not desire the entire descriptive text to be located on the main page, aria-describedby can also be used to point to a link to another page.

- 
<div id="figuretitle">Figure 1-1: Entity Relationship Diagram showing EMP and DEPT</div>
-  <img src="foo" aria-labelledby="figuretitle" aria-describedby="link1">
-  <a href="descriptionLocation.html" id="link1">Description of Figure 1-1: Entity Relationship Diagram showing EMP and DEPT</a>
-</div>
-
-

It is not good practice to use the above pattern when the describing element—the <a> tag with @id='link1'—is hidden, since there is no way for a user to navigate to and activate the link. Use the technique only when the description is not hidden.

-
-
-

Miscellaneous XHTML Section Roles

-

In order to synchronize with the XHTML Role Attribute module, WAI-ARIA includes two XHTML roles which are neither landmarks nor widgets of any kind. These roles were incorporated to replace standard elements found in host languages. These roles are definition and note. If either role has a corresponding element in the host language, it is recommended that authors use the corresponding element in the host language.

-

The definition role indicates a definition statement in your document. For HTML developers implementing lists of definitions, we recommend you using the DL, DT, and DD elements rather than marking an arbitrary element with a role of definition. An arbitrary element would be appropriate for inline definitions used in conjunction with the DFN element.

-

Example of an inline definition with an explicit labelledby relationship:

- 
-<p>The doctor explained it had been a <dfn id="placebo">placebo</dfn>, <span role="definition" aria-labelledby="placebo">
-an inert preparation prescribed more for the mental relief of the patient than for its actual effect on a disorder.</span>
-</p>
-

Example of an inline definition with an implicit labelledby relationship determined by nesting:

- 
<p>The doctor explained it had been a <span role="definition">
-<dfn>placebo</dfn>, an inert preparation prescribed more for the mental relief of the patient than for its actual effect on a disorder.</span>
-</p>
-

Note: In the case where host language semantics do not allow for implicit nesting of definitions terms inside definition roles, authors should explicitly use the aria-labelledby attribute, even when the definition term is nested in the definition as shown here:

- 
<p>The doctor explained it had been a <span role="definition" aria-labelledby="placebo">
-<dfn id="placebo">placebo</dfn>, an inert preparation prescribed more for the mental relief of the patient than for its actual effect on a disorder.</span>
-</p>
-

The following is an example using a definition list:

- 
<dl>
- <dt id="anathema">anthema</dt>
- <dd role="definition" aria-labelledby="anathema">a ban or curse solemnly pronounced by ecclesiastical authority and accompanied by
-excommunication</dd>
- <dd role="definition" aria-labelledby="anathema">a vigorous denunciation : cursor</dd>
-<dt id="homily">homily</dt>
-<dd role="definition" aria-labelledby="homily">a usually short sermon</dd>
-
-<dd role="definition" aria-labelledby="homily">a lecture or discourse on or of a moral theme</dd>
-
-</dl>
-

The note role defines a parenthetic or ancillary remark to the main content of the resource. It also allows assistive technologies to skip over this section of the document unless more information is requested about the main content.

- 
<div role="main" aria-labelledby="foo">
-   <h1 id="foo">Wild fires spread across the San Diego Hills</h1>
-   Strong winds expand fires ignited by high temperatures …
-</div>
-
-<div role="note">
-   This article was last updated July 30, 2008 at 6:05PM.
-</div>
-
-
- -
-

Other Widget Authoring Practices

-

- MCK: Setting this content aside to determine whether we will remove or rewrite it. -

-

- The Common Widget Design Patterns section of this document contains best practices, such as keyboard navigation, for creating common widgets found on the Web. - This section contains miscellaneous authoring practices that you should also consider. -

- -
-

Managing Focus with Scroll

- -

Not yet edited ... considering what should be written/included. We don't want to write a javascript book.

- -

- In some browsers, a JavaScript call to scrollIntoView() on this element should suffice, but in browsers where this is unreliable, authors should explicitly set the scrollTop and scrollLeft properties of the "cell23" element and its ancestors to scroll the element into view. scrollTop and scrollLeft adjust the node positions by the amounts(pixels) needed to scroll a node into view. - Scrolling values are adjusted by the amounts(pixels) needed to scroll a node into view. - This is done by comparing the sizes of the nodes using available measurements such as scroll+offset+clientWidth/Height/Left/Top. It's important to note that you have to adjust a node so that it's viewable within - the context of its parent node. - Then you have to move up the DOM tree and make - each parent node visible. -

- -

- For example, create a custom scrollIntoView() method that is called at various times, including coincidence with the setting of the aria-activedescendant property. - The method takes a DOM node argument, say "n". Here is the high level algorithm: -

- -
    -
  1. If n is already in view, stop; otherwise, continue.
    2. -
  2. adjust n.scrollTop and n.scrollLeft such that it is in view.
    3. -
  3. adjust scrollTop and scrollLeft for the ancestor nodes of n such that that the region of the ancestors which n consumes is visible.
    4. -
- -

This is a minimum-position-change algorithm.

- -

- Understanding how the DOM scrollIntoView works across browsers is important. - Browsers (including Firefox3) force the node either to the top or the bottom of the screen (as defined by the single Boolean parameter) even if its already in view. - This is problematic when you only need to scroll horizontally to see the element. - It is also problematic when the node is partially off the bottom of the screen and the parameter is (true) which forces the node all the way to the top, and vice versa with the top going to the bottom on (false). - IE forces the node to the left of the client area (or right in right-to-left mode) even if it's horizontally in view already. -

- -

- The scrollTop and scrollLeft functions create some challenges. - scrollTop is always accurate but misleading with respect to inner (nested) scrollbars. - scrollLeft cannot be relied on in right-to-left languages because it is sometimes negative and sometimes positive especially with respect to inner (nested) scrollbars. - Different browsers handle right-to-left completely differently. -

-
- - -
-

Other Keyboard Interface Development Tips

- -

MCK: this section is a collection of keyboard related old content with a yet undecided fate.

- -
-

Miscelaneous stuff we might or might not keep

- -
    -
  • - Use focus and blur events (or event delegation) to monitor changes to the current focus - focus and blur events can now be used with every element. - Don't assume that all focus changes will come via key and mouse events, because assistive technologies such as screen readers can set the focus to any focusable element, and that needs to be handled elegantly by the JavaScript widget. - Techniques such as "event delegation" (for example, intercepting events on a list rather than on every listitem) can improve performance. -
    • - -
  • - Follow keydowns to move focus - A keydown event handler can determine the next object to receive focus and call that element's focus() method. -
    • - -
  • - Use onkeydown to trap key events, not onkeypress - Key press events do not fire for all keys and they vary across browsers. -
    • - -
  • - Use element.focus() to set focus - Do not use createEvent(), initEvent() and dispatchEvent() to send focus to an element, because these functions do not change the focus. DOM focus events are informational only, generated by the user agent after an element has acquired focus, but not used themselves to set focus. -
    • - -
  • - The use of :focus pseudo-class selectors to style the keyboard focus is not supported in many versions of Internet Explorer. Authors should use the :active pseudo-class (which older versions of IE treat like :focus) in conjunction with the :focus pseudo-class. Example: a:focus, a:active { text-decoration: underline; } - If the related CSS pseudo-classes are not appropriate or not supported in all browsers, authors can use JavaScript techniques to indicate an appropriate focus alternative, such as using focus and blur events to toggle a classname on an element. -
    • - -
  • - Always draw the focus for tabindex="-1" items and elements that receive focus programmatically when supporting versions of Internet Explorer older than 8 - Choose between changing the background color via something like this.style.backgroundColor = "gray"; or add a dotted border via this.style.border = "1px dotted invert". In the dotted border case, you will need to make sure those elements have an invisible 1px border to start with, so that the element doesn't grow when the border style is applied (borders take up space, and IE doesn't implement CSS outlines). -
    • - -
  • -

    Prevent used key events from performing browser functions - If a key such as an arrow key is used, prevent the browser from using the key to do something (such as scrolling) by using code like the following:

    - 
    <span tabindex="-1" onkeypress="return  handleKeyPress();">
    -

    - If handleKeyDown() returns false, the event will be consumed, preventing the browser from performing any action based on the keystroke. - In addition to the return value the browser must call the event methods that will prevent the default action, for IE this is setting the event property "returnValue=false", and for other browsers supporting the W3C event model this means calling the "preventDefault" method of the event object. -

    -
    • - -
  • - Use key event handlers to enable activation of the element - For every mouse event handler, a keyboard event handler is required. - For example, if you have an onclick="doSomething()" you may also need onkeydown="return event.keyCode != 13 || doSomething();" in order to allow the Enter key to activate that element. - There are user agent-specific considerations for key event handling. -
    • -
- -
- -
-

Supporting Tooltips with the Keyboard

- -

- A tooltip is a popup messages typically triggered by moving a mouse over a control or widget causing a small popup window to appear with additional information about the control. - To provide simple text tooltips, the HTML title attribute should more than suffice because the user agent will render it for tooltips. - When creating a tooltip, it is essential that the user be able to activate it using the keyboard. - When a form control or widget receives keyboard focus, the tooltip must display. - When the form control or widget loses focus, the tooltip must disappear. - Browsers do not currently support this functionality. -

- -

The following code snippet from the iCITA site shows the use of a onfocus="tooltipShow();" function to display the tooltip when focus is placed on an element.

- - 
<html lang="en-us"">
-<head>
-   <title>inline: Tooltip Example 1</title>
-   <link rel="stylesheet" href="css/tooltip1_inline.css"  type="text/css">
-   <script type="text/javascript" src="js/tooltip1_inline.js"></script>
-   <script type="text/javascript" src="../js/widgets_inline.js"></script>
-   <script type="text/javascript" src="../js/globals.js"></script>
-   <link rel="icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon">
-   <link rel="shortcut icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon">
-</head>
-   …
-
-   <body onload="initApp()">
-
-   <div id="container">
-
-   <h1>Tooltip Example 1</h1>
-     <h2>Create Account</h2>
-   <div class="text">
-   <label for="first">First Name:</label>
-
-   <input type="text"  id="first" name="first" size="20"
-          onmouseover="tooltipShow(event, this, 'tp1');"
-          onfocus="tooltipShow(event, this,  'tp1');"
-          aria-describedby="tp1"
-          aria-required="false"/>
-
-   <div id="tp1" role="tooltip" aria-hidden="true">Your first name is optional. </div>
-   </div>
-  …
-
-
-
-
-
Maintain a valid format for aria-valuenow
-

It is essential that application vendors maintain a valid format for -aria-valuenow, and aria-valuenow should -accurately represent the value of the widget.The value must be within range of aria-valuemax and aria-valuemin, where the value of aria-valuemin is less than or equal to the value of aria-valuemax, throughout the life cycle of your widget. If aria-valuemin is not less than or equal to the value of aria-valuemax, or if the aria-valuemax is indeterminate, this creates an error condition that will be handled by -the assistive technology, resulting in undesirable results. Should an alternative text - equivalent be needed to properly represent the aria-valuenow, such as a day - of the week, then you should accompany the aria-valuenow with an appropriate - aria-valuetext equivalent such as in this example:

-
-<div role="slider"
-  aria-valuenow="1"
-  aria-valuemin="1"
-  aria-valuemax="7"
-  aria-valuetext="Sunday">
-
-

-Here the values 1 through 7 represent the days of the week and - aria-valuenow of 1 is equivalent to the first day of the week or Sunday. When aria-valuetext is made available aria-valuenow should also be treated as an index which is 1 based.

-
-
- -
-

Relationships

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

-
-

Labeling and Describing

-

Marked up content or widgets will often need additional context to make clear what the meaning or purpose is. It is also reasonable that some content media types will need additional descriptions in another format to give clarity to those who are unable to consume the origin format. These additional meta-content sections are linked together by tagging them as labels or descriptions. WAI-ARIA provides the aria-labelledby and aria-describedby attributes to signal the browser to feed these relationships into the accessibility layer. This layer is then used by screen readers and other accessibility technology (AT) to gain awareness of how disparate regions are actually contextually connected to each other. With this awareness the AT can then present a meaningful navigation model for discovery and presentation of these additional content sections. The user agent itself can also choose to present these insights in a meaningful way. Generally you should always add these attributes to any widgets on your site as they are often merely a construct of HTML and JavaScript which provides no obvious insight as to what the widget's behavior or interactivity is.

-
-

Labeling

- When using one element to label another use the aria-labelledby by attribute. A label should provide the user with the essence of what the object does. For example, you could have a dialog box erected from HTML <div> and you need to associate a label for the dialog. With a WAI-ARIA role of dialog, you can indicate its widget type and define a label using an HTML header and then associate that label with the dialog using the aria-labelledby relationship. - 
-  <div role="dialog" aria-labelledby="dialogheader">
-  <h2 id="dialogheader">Choose a File</h2>
-  … Dialog contents
-  </div>
-
-

The section doing the labeling might be referenced by multiple widgets or objects as these need only reference the same id, so contextual description may not always be viable. The labelledby attribute can have multiple ids specified as a space separated list much like applying multiple classes to a single DOM object.

-

The aria-labelledby property can be used to label all visual objects, however it should be noted that (X)HTML provides a @for attribute on the label element which is used to label form controls. Use this attribute where possible and valid. Because the aria-labelledby attribute accepts multiple IDREFs, it is recommended that authors use aria-labelledby for labeling elements that require more than one label string.

-

Some elements receive their label for embedded text content, but that is the exception.

-

Often user agents will operate with images turned off for network performance reasons. In these situations, alt text is provided in the place of the image. When the host language provides alternative text capability it is recommended that authors use the alternative text to support these situations and not use separate labeling as a replacement.

-
-
-

Describing

-
-

Using aria-describedby

-

When one element describes another, use the aria-describedby attribute. An aria-describedby section provides further information about a given object or widget, which may not be intuitively obvious from the context, content or other attributes. For example, a fake window is a common widget used in Web applications and is often constructed using a div absolute positioned in a layer above other content. To simulate common window behavior look and feel there is often an X box in the corner which, when activated, dismisses the window widget. One common way to make this X box is to simply make a link whose content is an X. This doesn't give a non-visual user much to go on and belies the real purpose of the X link. To help we add more descriptive text stored elsewhere in the page like this:

- 
<button aria-label="Close" aria-describedby="descriptionClose"
-    onclick="myDialog.close();">X</button>
- and then elsewhere in the HTML - 
<div id="descriptionClose">Closing this window will discard any information entered and
-return you back to the main page</div>
- Like labelledby, describedby can accept multiple ids to point to other regions of the page using a space separated list. It is also limited to ids for defining these sets. In our contrived example we would also want a good labelledby section to fully explain what the window does and how closing will effect the task being worked on. If an object or widget lacks describedby the user agent or AT may try to extract information from the label or th tags, if present. The label and th tags have limited use in that they can only be applied to forms or tables, respectively. -
-
-

Using a tooltip as a description

-

WAI-ARIA also defines the tooltip role to which aria-describedby may reference an author defined tooltip. The assistive technology can tell from the type of object describing the document element what the purpose of that element is. For example, a screen reader could announce the tooltip without the user having to wave the mouse over the element by following the describedby relationship to a document area with a tooltip role. The aria-describedby property is also useful for describing groups.

-

Here is a code snippet showing a set of the tooltip:

- 
…
-  <div class="text">
-    <label for="first">First Name:</label>
-      <input type="text"
-          id="first"
-          name="first"
-          size="20"
-          onfocus="tooltipShow(tooltip1);"
-          onblur="tooltipHide(tooltip1);"
-          onmouseover="tooltipShow(tooltip1);"
-          onmouseout="tooltipHide(tooltip1);"
-          aria-describedby="tp1"
-      />
-  <div id="tp1" class="tooltip" role="tooltip">Your first name is optional</div>
-  </div>
-…
-
-
-

Descriptions on external pages

-

The aria-describedby property is not designed to reference descriptions on an external resource—since it is an IDREF, it must reference an element in the same DOM document. This is different from the HTML longdesc attribute, which accepts any URI. In general, the preferred pattern for WAI-ARIA applications is to include all relevant resources in the same DOM, But if you wish to reference an external resource with aria-describedby, you can reference a link that in turn references the external resource. This requires the user to follow two steps, first following the aria-describedby arc, then following the link, but does address the use case. The following example demonstrates this:

- 
<p>
-   <img
-       src="images/histogram.png"
-       alt="Histogram of Blackberry tree heights"
-       width="40%"
-       aria-describedby="longdesc1"
-   />
-</p>
-
-<p>
-    <a id="longdesc1" href="blackberry-description.html" target="_description">Data for Blackberry Histogram</a>
-</p>
-
-
-

It is not good practice to use the above pattern when the describing element—the <a> tag with @id='longdesc1'—is hidden, since there is no way for a user to navigate to and activate the link. Use the technique only when the description is not hidden.

-
-
-

Owning and Controlling

-

Two relationships expand the logical structure of a WAI-ARIA Web application. These are aria-owns and aria-controls .  The aria-owns relationship completes the parent/child relationship when it cannot be completely determined from the DOM created from the parsing of the markup. The aria-controls relationship defines a cause-and-effect relationship so that assistive technologies may navigate to content effected by and changes to the content where the user is operating.

-
-

The Owns Relationship

-

In addition to WAI-ARIA role and state information, for a document element, -an assistive technology needs to convey its context. In -the case of a treeitem, it is important to know the parent (container), - which may provide a folder depth and the number of siblings in the folder. This containment hierarchy can often be determined by -the DOM tree, as it provides parent, siblings, and children for a given -document element. That said, the DOM hierarchy is rigid and non cyclical in -that each node may only have one parent. In some situations, a child -is reused by multiple parents or a child is separated from its -siblings or parent in the DOM tree. One example is when a radio button -appears in a table but it is not a DOM child of the radiogroup, due to the -authors use of a table for formatting and the placement of the radio buttons -placing them outside the radiogroup container. To solve this problem -WAI-ARIA provides the aria-owns property.

-

-The aria-owns property is set on a document element, and its values are the -unique IDs of all the adopted children. These elements may appear anywhere -in the DOM, yet they are treated as siblings of each owning parent. This -example illustrates a radiogroup that first uses the DOM hierarchy to -convey context and then aria-owns:

-

First, consider the preferred method for using the W3C DOM to describe the relationship between - radiogroup and radio roles for HTML:

-
-<div id="radio_label">My radio label</div>
-<ul role="radiogroup" aria-labelledby="radio_label">
-<li role="radio">Item #1</li>
-<li role="radio">Item #2</li>
-<li role="radio">Item #3</li>
-</ul>
-
-

-In this example, the elements with role="radio" are child nodes of the parent role="radiogroup" element node. - -

-

-Now, consider an alternative method using the aria-owns property to describe the parent-child -role relationship between radiogroup and radio roles for HTML:

-
-<table>
-<tr>
-<td role="radiogroup" aria-owns="myradio1 myradio2 myradio3" rowspan="3" >
-My Radio Label
-</td>
-<td id="myradio1" role="radio">Item #1</td>
-</tr>
-<tr>
-<td id="myradio2" role="radio">Item #2</td>
-</tr>
-<tr>
-<td id="myradio3" role="radio">Item #3</td>
-</tr>
-</table>
-
-

-The aria-owns property should be used sparingly, since it -increases the computational load on assistive technology to provide -alternative renderings. Also, when accessing the DOM and enumerating -children of a DOM node, an AT should then enumerate the adopted children -using the aria-owns property. At that instance of walking the DOM, the -parent of the adopted children is the adopted parent and not the DOM -parent. This will avoid recursion problems.

-

-Each child, adopted or natural, should have the appropriate - aria-posinset and aria-setsize properties set consistent with their -rendering, if these cannot be determined from the DOM from a direct parsing of -the host language. Places where direct parsing does not allow the user -agent to determine - aria-posinset and aria-setsize are long lists where only -the currently visible items are loaded (via Ajax). If the children are -re-sorted then the - aria-posinset and aria-setsize values should be updated -consistent with their visual rendering. Rather than setting size only on a container, content authors should specify aria-setsize on each member of a set to avoid performance issues.  If this property is not set, the user agent must compute and set the property on supporting roles.

-

Platform accessibility API mappings must invert this relationship for - assistive technologies, so that they may determine the owning parent from a - child and couple it with aria-posinset and aria-setsize information to - provide context information to the user.

-
-
-

 Using Owns with Reusable Content

-

If you are re-using content across different, transient sections of content by restyling it to render it in association with a different object, you need to maintain the aria-owns property as well to match the current use and apparent ancestry of the reused sub-section. A good example of this is a context help menu that resides at the end of the document. When the user wishes to launch the context help menu in association with different visual elements, styling is used to render the menu in context with that object. Prior to rendering the visual submenu you should ensure the object to which you have requested help assigns its aria-owns property value to the submenu ID. When the menu closes you can remove the aria-owns property.

-
-
-

The Controls Relationship

-

In rich internet applications document elements may control the behavior on another part of Web page outside themselves. The aria-controls attribute indicates cause-and-effect relationships between document elements.

-

An example might be a group of radio buttons that "control" contents of a listbox in another part of the page. Here, you would want the radio group to assign a aria-controls relationship to the listbox which will be updating without a page reload. The user, through their assistive technology, can then navigate to the listbox by following the aria-controls relationship when a different radio is selected, to see how the contents changed in the listbox. The ability to update parts of a page without a page reload is a common practice of applications making use of Ajax. Without the aria-controls attribute, a user would be unable to effectively use these types of Web pages as assistive technologies often will not make the user aware of what is happening outside the context of the element the user is currently operating.

-

With the aria-controls attribute the user may use the assistive technology to follow the relationship to the object it is controlling. It is extremely important for an assistive technology to present changes in the document in response to user input. Therefore, an assistive technology immediately presents changes to a live region when the controlling widget is the one which has user keyboard focus. For example, if a tree view controls a help document pane, each time
- the tree item changes the new tree item and then the new help contents should also be read. In the case of a screen reader, the amount of information read in the target live region is dependent on how the live region is configured.

-

The aria-controls attribute takes one or more ids which refer to the document element. If this relationship is not implied by the host language semantics, then the controlling element must be given a controls attribute with the IDs of the other elements where the changes will show up listed in the attribute value.

-
-
-
-

Changing the Reading Flow

-

(X)HTML suffers from a number of disadvantages in keyboard navigation today. One such example is the restriction of navigation to the tabbing order. This is a common problem with presentations in office suites where the logical, perceivable, navigation order of a slide may not match the tabbing order. Sighted users may see a logical navigation process (such as visual steps in the process for assembling a lawn mower). This "flow" is not conveyed by the tab order. The user might tab from step 1 and land on step 4. Another problem is the construction of model-based authoring tools on a Web page. In a model-based authoring tool, a visual object may provide a number of paths that the user can take, such as a multiplexor, which may have output that logically flows to a number of optional electronic components in a drawing. In Web 2.0, developers are actually creating drawings like this to perform tasks such as visually model a work flow. In this scenario, the user will want to decide which object they will navigate their screen reader or alternate input device to next.

-

Although it is recommended that Tab order follow the reading flow, there may be instances where this is not possible. For these reasons, WAI-ARIA provides a relationship property, called aria-flowto. This allows the author to provide an assistive technology with alternative navigation flows through the document that best represents the author's intent and which is more logical for people with disabilities. aria-flowto establishes the recommended reading order of content, so that the an assistive may overriding the default of reading in document order to its user. aria-flowto does not change the keyboard navigation order of the browser.

-

Consider the first case of changing a basic reading flow to circumvent (X)HTML tabbing. A good example of this is a logical reading flow in a portal with landmarks. In the future, the user may wish to change the reading flow based on the order of priority with which they navigate a personalized Web application. In the following example, the navigation would follow the order of "Top News Stories", "television listings", "stock quotes", and "messages from friends" by following (X)HTML document reading order. However, the author or end user may determine that the main content is most important, followed by "stock quotes", "messages from friends", and then "TV listings." The end user can change the order if the web page or assistive technology provides an interface for such personalization.

- 
<html>
-…
-<div role="main" title="Top News Stories" id="main" aria-flowto="stock"></div>
-<div role="complementary" title="television listings" id="tv"></div>
-<div role="complementary" title="stock quotes" id="stock" aria-flowto="messages"></div>
-<div role="complementary" title="messages from friends" id="messages" aria-flowto="tv"></div>
-

The second use case is such that the Web developer may wish to circumvent the flow by branching to multiple paths in the Web page, requiring the assistive technology to present a collection of options where the user could go next. This is important for work flows or business process management applications. More of these applications are becoming Web based, and a vehicle is required to tell the user how to get through the work flow. The flowto property takes multiple idrefs, allowing the author to define each object the user could flow to. To implement this technique do the following.

- -
-
-

Popups and drop-downs

-

In order for menus, menubars, and menuitems to indicate that it opens a menu, set its aria-haspopup property to "true." The type of menu being launched (submenu, context help, etc.) is not explicitly indicated with WAI-ARIA but is based on the operational characteristics (keyboard and mouse commands).

-

Combo boxes, or drop down lists, work differently. Controls with the role combobox must contain a list of items that can be opened, usually as a drop-down. Because this is intrinsic to the functionality of a combo box, it does not need to be explicitly indicated with aria-haspopup.

- -

The following html fragment shows the use of aria-haspopup with a menubar, its menus, and submenus. All of the menuitems associated with the menubar have aria-haspopup set to 'true'. Also, the "Zoom" menuitem of the "View" menu has an aria-haspopup property as it leads to a submenu.

- - 
<div role="menubar">
-  <!--
-    File menu: File menuitem has an aria-haspopup attribute set to 'true'.
-    That popup div follows immediately below.
-  -->
-  <div role="menuitem" aria-haspopup="true" id="fileMenu">File</div>
-  <div role="menu" aria-labelledby="fileMenu">
-    <div role="menuitem">Open</div>
-    <div role="menuitem">Save</div>
-    <div role="menuitem">Save as …</div>
-    …
-  </div>
-  <!--
-    View menu:
-  -->
-  <div role="menuitem" aria-haspopup="true" id="viewMenu">View</div>
-  <div role="menu" aria-labelledby="viewMenu">
-    <div role="menuitem">Normal</div>
-    <div role="menuitem">Outline</div>
-    <!--
-      The View's Zoom menuitem has aria-haspopup='true' as it leads to a
-      submenu.
-    -->
-    <div role="menuitem" aria-haspopup="true" id="zoomSubMenu">Zoom</div>
-    <div role="menu" aria-labelledby="zoomSubMenu">
-      <div role="menuitem">50%</div>
-      <div role="menuitem">75%</div>
-      <div role="menuitem">100%</div>
-      <div role="menuitem">150%</div>
-      <div role="menuitem">200%</div>
-    </div>
-  </div>
-</div>
-
-
- -
-

Managing Dynamic Changes

-

This section has had only minor edits since it was integrated from APG version 1.0 -- a complete APG task force review is pending.

-
-

Managing Content and Presentational Changes

-

General rules for managing content and displaying information

- -

If you are refreshing areas asynchronously, then you need to designate live regions. The following sections explain how to implement live regions and when to use roles that are considered "live" sections by default, including alert, status, or log.

-
-
-

Implementing Live Regions

-

Live regions are parts of a Web page that the author expects to change. Examples of live regions include dynamically updated content (sports stats, stock information), logs where new information is being added (chat transcript logs), notification areas (status, alerts), etc.

-

Live regions enable assistive technologies, such as screen readers, to be informed of updates without losing the users' place in the content. Live region settings provide hints to assistive technologies about how to process updates. Note that the assistive technology is responsible for handling these updates and enabling users to override these hints.

-

The section on Live Region Properties and how to use them gives the details of how to apply live region properties. This process will help rich internet application (RIA) developers to set live region settings that will provide a good user experience for most assistive technology users with little configuration on their part. When applying these live region properties, it is recommended that you conduct user testing. If the AT supports scripting of the response to live regions you may wish to customize the response, such as through a screen reader script for your Web page.

-
    -
  1. -

    Identify the live regions

    -

    Live regions are any region on a page that receives dynamic updates through client-side scripting. Note the regions of your page that will be live.

    -
    2. -
  2. -

    See if any of the special case live regions meet your needs

    -

    WAI-ARIA provides a number of special case live region roles whose live region properties are pre-defined and which you may use. If one of these live region roles meet your needs just apply the specific role to the region of the Web page.

    -
    3. -
  3. -

    Decide the priority of each live region

    -

    When a live region changes, should the user be notified of the change? Notifications could include a sound for a screen reader user. (For simplicity, we will use the case of an audio notification in this discussion.) The shorter the interval between changes and the less important the information, the less likely that the user needs to hear every change. A simple example of changes that should not be heard are changes to time; a sound for every second would be very annoying.

    -

    If the user should hear the change, should the change be announced immediately, as soon as possible, or only when the user is idle? Announcing a change immediately can be disorienting for users, so that should be done sparingly. Most updates should probably only be announced when the user is idle.

    -

    After you have decided the priority for each live region, then decide the live property value:

    - -
    4. -
  4. -

    Decide how much context is needed for each update

    -

    When part of a live region changes, how much context is needed to understand the change. Does the user need to hear the entire live region or just the change by itself?

    -

    If the user needs to hear the entire live region, then mark the entire live region with aria-atomic="true".

    -
    5. -
  5. -

    Decide what types of changes are relevant for each live region

    -

    Three possible types of changes are: additions, removals, and text. Additions means new nodes are added to the DOM; removals means nodes are removed from the DOM; and text means changes are solely to the textual content. Should the user hear all types of changes or only certain types?

    -

    By default, the user will hear additions and text type changes. If you wish to explicitly define the types of changes, you need to set relevant="THE_TYPES_OF_CHANGES". If more than one type of change is relevant, the types are separated by a space. For example, to define additions and removals as relevant but not text, set relevant="additions removals".

    -
    6. -
-
-

Live Region Properties and How to Use Them

-

One of the most important concepts behind live regions is politeness. Politeness indicates how much priority a live region has. The following politeness values are available for aria-live: off, polite, and assertive.

-
-
aria-live="off"
-
This is the default. Any updates made to this region must not be announced to the user. live="off" would be a sensible setting for things that update very frequently such as GPS coordinates of a moving vehicle.
-
aria-live="polite"
-
Any updates made to this region should only be announced if the user is not currently doing anything. live="polite" should be used in most situations involving live regions that present new information to users, such as updating news headlines.
-
aria-live="assertive"
-
Any updates made to this region are important enough to be announced to the user as soon as possible, but it is not necessary to immediately interrupt the user. live="assertive" must be used if there is information that a user must know about right away, for example, warning messages in a form that does validation on the fly.
-
-

There are times to suppress AT presentation changes while a region is updating. For that you can use the aria-busy property.

-
-
aria-busy="true"
-
-

To suppress presentation of changes until a region is finished updating or until a number of rapid-fire changes are finished, set aria-busy="true" and then clear the attribute when the region is finished. While it is busy, the AT will track and collate the changes. It will finally speak the changes once the region is no longer busy.

-
-
-

When a live region is updated, the update can often be announced on its own and still make sense. For example, if a news headline is added, it would make sense to simply announce the headline. However, sometimes the entire live region must be read in order to give the user enough context to make sense of the update. For example, it would not make sense to only give the current value of a stock without saying the name of the stock. The atomic setting gives assistive technologies a hint about which of these cases an update falls into.

-
-
aria-atomic="false"
-
This is the default. It means that when there is a change in the region, that change can be presented on its own; the AT should not present the entire region. atomic="false" is generally a good idea as it presents users with only changes and does not cause them to hear repetitive information that has not changed. However, Web developers should take care that the changed information, when presented by itself, can still be understood and contextualized by the user.
-
aria-atomic="true"
-
If atomic is set to "true", it means that the region must be presented as a whole; when there is a change, the AT should present the entire region, not just the change. atomic="true" can make it harder for users to understand changes as the changed areas are not presented independently. atomic="true" can also be annoying as it can force users to listen to repetitive information that has not changed. However, atomic="true" is necessary in cases where the change, when presented by itself, cannot be understood and contextualized by the user. Note that when aria-atomic="true", the AT will attempt to speak the atomic region only once when multiple changes occur in the same region and it hasn't been spoken yet.
-
- Not all updates to a live region are relevant. For example, if the oldest headline in a list of headlines is removed and a new headline is added, the removal of the oldest headline is probably not important enough to announce to the user. However, in a chat application, when a user leaves the chat and their username is removed from the list of users, that removal may be important enough to announce. The relevant setting gives a hint about what types of changes are relevant and should be announced. Any change which is not relevant will be treated as if the region had live="off" and will not be announced. Multiple types of changes can be listed as relevant; the types are separated by a space. The default is relevant="additions text" and this is the most common use case. If the default is applicable to your application, you do not need to provide the relevant property explicitly. -
-
aria-relevant="additions"
-
Insertion of nodes to the live region should be considered relevant.
-
aria-relevant="removals"
-
Removal of nodes to the live region should be considered relevant. - Often, removals are not relevant because nodes are removed to make space for new information - e.g. a log implemented as a table where items are taken off the top. However, in the case of something like a buddy list, it is relevant if a buddy is removed. It doesn't require the screen reader to speak the removal, but it notifies the screen reader that it could be useful to do so. Use of aria-relevant="removals" or aria-relevant="all" should be used sparingly. Notification of an assistive technology when content is removed may cause an unwarranted number of changes to be notified to the user.
-
aria-relevant="text"
-
Changes to the textual content of nodes that already exist in the live region should be considered relevant. Textual content includes text equivalents, such as the alt attribute of images.
-
-

This example shows two live regions. If both regions update simultaneously, liveRegionA should be spoken first because its message has a higher priority than liveRegionB.

-
- 
<div id="liveRegionA" aria-live="assertive">
-</div>
-<div id="liveRegionB" aria-live="polite>
-</div>
-
-
-
-
-

Choosing Between Special Case Live Regions

-

You may wish to use a special live region role instead of applying live region properties. WAI-ARIA contains a number of standard roles which are by default considered "live" sections of your Web page. It is important to know when to use these and when to create a custom live region on your known. Here are some rules of thumb:

-
-

alert - You may use the alert role for a one-time notification which shows for a period of time and then goes away. It is intended to alert the user that something has happened. The assistive technology should be notified by the user agent that an alert has occurred, if your operating system supports this type of event notification. When choosing to use alert you should use the alertdialog role instead if something inside the alert is to receive focus. Both alert and alertdialog usually appear to pop-up to the user to get their attention. Unless specified otherwise an alert region has an implicit aria-live of "assertive" and aria-atomic of "true".

-

status - You may use the status role when you want to mark an area which is updated periodically and provides a general status of your Web application. Many applications provide status widgets and they are often found, visibly, at the bottom of the application and contain a variety of widgets within it to convey status. Unless specified otherwise a status region has an implicit aria-live of "polite" and aria-atomic of "true".

-

timer - You may use a timer role when you want to mark an area which indicates an amount of elapsed time from a start point, or the time remaining until an end point. The text encapsulated within the timer indicates the current time measurement, and is updated as that amount changes. However, the timer value is not necessarily machine parsable. The text contents MUST be updated at fixed intervals, except when the timer is paused or reaches an end-point. The timer role has an impicit aria-live of "off".

-

marquee- You may use a marquee role when you need to mark an area with scrolling text such as a stock ticker. The latest text of the scrolled area must be available in the DOM. A marquee behaves like a live region, with an implicit aria-live property value of "off."

-

log - You may use log if you have a live area where new information is added, like a scrolling chat log of text. Unlike other regions, implied semantics indicate the arrival of new items and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. Log has an implicit aria-live of "polite"If you have a chat text entry area you should indicate that it also controls the aria log aria like so:

- 
<div contenteditable="true" role="log" id="chatlog">
-</div>
-
-
-<label id="gettext">Send Text</label>
-<div aria-controls="chatlog"
-     role="textbox"
-     contenteditable="true"
-     aria-labelledby="gettext">
-</div
-

live region - If you have some other live area use case, WAI-ARIA allows you to mark an area using the aria-live attribute. This, accompanied by the collection of attributes which support the live property, allows you to create your own custom live area on your Web page. For more details regarding live regions refer to the live region section of this guide.

-
-

Live region roles that are applied to elements having strong native semantics are not mapped consistently to the platform accessibility API. An example is the TABLE element. It is recommended that authors apply live regions to DIV and SPAN containers. For example:

- 
<!-- Live region 'log' role used with TABLE element:  the 'log' role is not consistently mapped to platform AAPI. -->
-<!-- Do not use. -->
-<table role="log" … >
-  …
-</table>
-
-<!-- Wrap the TABLE element in a DIV with role 'log' instead: -->
-<div role="log" … >
-  <table … >
-    …
-  </table>
-</div>
-
- -
-
- -
-

Presentation Role

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

-

This section describes the presentation role, including the conditions under which it is inherited by an element's children.

-
-

Rationale

-

Authors devote a good deal of effort to the appearance of their web pages, and this is especially true in the case of scripted web applications. To this end authors employ various elements purely for visual presentation. For example, <img> elements are used for spacing and decoration; and <table>s are used to create a column based layout. Elements used strictly for presentation are semantically neutral and irrelevant in terms of accessibility. It is necessary to mark such elements as presentational so that they do not appear in the accessible tree created by the user agent. For example, a current technique used with spacer images is to provide blank alt text to indicate that the image is not meaningful. User agents will not publish any information about images with blank alt text to the platform accessibility API.

-

There are elements other than <img> and <table> that are used solely for visual presentation. Any element is a potential candidate for presentation, and, if so used, these elements also need to be marked as semantically neutral.

-

It is important to separate content and presentation. CSS 3 has introduced new table layout functionality to allow a user agent to layout content using CSS. There are many advantages to using this feature of CSS such as browser style sheet caching and improved adaptability to mobile devices with limited screen real estate. There are, however, cases where presentational markup cannot be avoided. In such instances, authors are counseled to consult WCAG 2.0 for more detailed guidance.

-

WAI-ARIA introduces the presentation role as a general device for marking elements as presentational. The presentation role overrides the element's native implicit role, and informs the user agent to not publish the element to the accessibility API. In fact, the preferred way to mark <img> elements as decorative is to use a role="presentation" attribute instead of (or in addition to) an empty alt attribute. Here is a code fragment sample:

- -
<!-- [role="presentation"] informs the user agent that the spacer images are for layout only. -->
-…
-<h2>Other Histories of Architecture</h1>
-<p>
-  <a href="www.somewhere.com">Ancient Roman Architecture</a>
-  <img src="spacer.png" role="presentation">
-  <a href="somewhere.else.com">19th Century Italian Architecture</a>
-  <img src="spacer.png" role="presentation">
-  <a href="www.elsewhere.com">Modern Buildings more than 100 Years Old</a>
-</p>
-
-<h2>Modern Building Design</h1>
-…
-
-

The resulting accessible tree is shown below. Note that none of the spacer <img> elements are present:

- -
-
-

Inheritance of Presentation by Parent Element's Children

-

In general, the presentation role is not inherited by an element's children. The exceptions are elements whose role entails that the element has required owned children. Examples include the <table> element and list role, and these exceptions are discussed further below. For all other elements, only the element marked presentational is eliminated from the accessible tree. Note, however, that its contents are published; in particular, the element's textual content is published, but any attributes of the element that may form a text-equivalent are not. For example, a header element with a presentation role would not appear in the accessible tree, but its text does. An image with a role of presentation is not exposed in the accessible tree, nor is the contents of its alt attribute. This is shown in the following code fragment:

- -
<!-- 1. [role="presentation"] negates the implicit 'heading' role semantics but does not affect the contents. -->
-
-<h1 role="presentation">Presentation role overrides Header role</h1>
-<h1>Another header</h1>
-
-<!-- 2. [role="presentation"] hides the image from the accessibility API and does not publish the alt attribute contents. -->
-
-<img role="presentation" alt="This text will not appear in the Accessibility API" src="…">
-
-
-

The first header element is absent from the accessible tree for the above example, but its text appears. The second header element is present as a heading. The img element is not exposed at all:

- -

Be aware that the markup <img role="presentation" alt="non-empty alt text"…> is in fact contradictory: Declaring a role of presentation says that the image is for layout, is decorative and meaningless, whereas the non-empty alt text implies that the image is meaningful. It is recommended that authors instead use empty alt text (alt="") where they use role="presentation".

-

Earlier it was noted that the presentation role is not generally inherited by an element's children. The exception are roles that have required owned elements. Examples include the <table> element, and the list and tree roles. A list is required to have listitem children; a tree, treeitem children. The <table> element's child components are <tbody>, <thead>, <tfoot>, <th>, <tr>, <td>, and <caption>. These component elements would not appear in the markup without the enclosing <table> root element. Thus, when a table is used for layout, it follows that all of its component elements are present in the markup for layout as well. Since annotating all the required child elements with role="presentation" is error prone and difficult to maintain, it is sufficient to mark the table root element as presentational. The presentation role propagates to all the table component elements. However, as before, the contents of the table elements do appear in the accessible tree. Here is an example:

- -
<!-- Layout table marked with [role="presentation"]. -->
-
-<table role="presentation">
-  <tbody>
-    <tr> <td>Some text</td> <td><p>Paragraph</p></td> </tr>
-    <tr> <td><a href="www.somewhere.com">Link text</a></td> <td><img src="meaningful.jpg" alt="meaningful image"></td> </tr>
-  </tbody>
-</table>
-
-

All table specific elements (table, tr, td, etc.) are eliminated from the tree by inheriting the presentation role, but other elements and textual content in the table cells are exposed:

- -

The same logic applies to other roles that have required owned children, such as a list. If the list's root element is declared presentational using role="presentation", all of its listitem elements inherit the presentation role, and none of the list item elements appear in the accessible tree. However, the contents of each list item, that is, other elements and textual content, are included in the tree.

-
-
-

Overriding Presentation

-

The presentation role is overridden in some circumstances. Recall that the presentation role informs user agents that certain elements are semantically neutral, and are irrelevant for accessibility. If, however, there is an aspect of an element that makes it meaningful, it is no longer neutral, and cannot simultaneously be presentational. The Core Accessibility API Mappings describes the cases where this occurs:

- -

These situations entail that the given element is semantically relevant and will appear in the accessible tree. Marking the element with a role="presentation" is an error, and user agents will ignore the presentation role in these cases. Authors are advised to not mark an element with a role of presentation when it has any of the above properties; rather, to use a role that reflects the element's purpose.

-
-
- -
-

Form Properties

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

-

-This section identifies authoring practices for elements used as form elements. -

-
-

Use aria-invalid and aria-required To Improve Access to Forms

-

-Until the introduction of WAI-ARIA's aria-invalid state and aria-required property, only presentational strategies have been available to Web content authors to indicate that certain form fields and controls are required or invalid. In applications, these states are only available through styling or varying markup, which is inconsistent, and therefore is inconclusive. In Web-based forms, fields required may be marked by an asterisk. Forms submitted with required data missing or improperly specified may be redisplayed with the unacceptable elements highlighted in red. The assistive technology user is poorly served by such imprecise methods, and all users confront inconsistent indicators for consistent situations. -

-

-The WAI-ARIA invalid state and required property provide: -

- -

Alert the User When Maximum Length Value Is Reached

-

When a text input field that has a maximum length value (or the host markup language's equivalent) receives focus, the value defined for -"maximum length" should be communicated to the user. When text entry reaches that maximum length (or the markup language's equivalent), an alert (expressed in accordance with user preferences and capabilities) should inform the user that the maximum length for a given field has been reached. Such an alert can be expressed programmatically or, using as an aural icon, by using a WAI-ARIA alert; the user agent may alert the user through a system beep and by triggering the operating systems' "show sounds" facility. When maximum length (or the markup language's equivalent) is reached, the user must then be able to move to another form field in a manner consistent with tab-navigation for that document.

-
-
-

Automatic Focus Changes

-

Having a user agent automatically change focus in a form in response to user input can be advantageous in situations where that change saves the user keystrokes or on-screen keyboard interaction in order to manually move the focus from one field to another. However, as with form auto-completion, this type of text input event must be firmly under user control because this may not have been the user's intention and some users with disabilities may become disoriented such as those with sight impairments. Consider these cases:

- -
-
-

Form Auto-submit

-

Use caution when using automatic submission of a form without explicit user command or -in response to a user-defined setting that permits such behavior, as -expressed by the Priority 1 UAAG 1.0 Checkpoints - 7.1, - 7.2 and - 11.1. -Unless the user has specifically chosen to set the user agent to allow auto-submission, authors are advised not to set onChange or onFocus events either to trigger submission of a form or to provide an auto-submission event upon -completion of all or all required fields of a form or input -field.

- -
- -
- -
-

Math

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

-

Editors' note: This section was added as part of disposition of comment 4, but is very incomplete. The section needs to be reordered, so that instructions on how to use the math role properly appear before considerations of legacy content and negative examples (such as the use of generic HTML to approximate a visual representation of a mathematical expression). It needs more introductory text about how to use math. The examples need better introductions, and the positive examples should preceded the negative examples, which need to be explained more fully.

-

There exists significant amounts of legacy content that uses images - and/or textual approximations to represent mathematical expressions. - Examples of this include the use of ASCII art and/or the misuse of - HTML tags -- in particular, SUB and SUP -- to achieve a visual - approximation of a mathematical expression, one which is void of - the structure needed to render mathematical expressions inherently - meaningful.

-

Use of generic HTML to approximate a visual rendering - of a mathematical expression:

-

<i>a</i><i>x</i><sup>2</sup> + <i>b</i><i>x</i> + <i>c</i> = 0

-

Accessible example of the same function, using the math role, appropriate label, and MathML rendering:

- 
<div role="math" aria-label="a times x squared plus b times x plus c equals 0">
-  <math xmlns='http://www.w3.org/1998/Math/MathML'>
-    <mrow>
-      <mrow>
-         <mrow>
-            <mi>a</mi>
-            <mo>&#x2062; <!-- invisible times --></mo>
-            <msup>
-              <mi>x</mi>
-              <mn>2</mn>
-            </msup>
-         </mrow>
-         <mo>+</mo>
-         <mrow>
-            <mi>b</mi>
-            <mo>&#x2062; <!-- invisible times --></mo>
-            <mi>x</mi>
-         </mrow>
-         <mo>+</mo>
-         <mi>c</mi>
-      </mrow>
-      <mo>=</mo>
-      <mn>0</mn>
-    </mrow>
-  </math>
-</div>
-

Similarly:

-

-<i>f</i>(<i>x</i>) - = <i>x</i><sup>2</sup> + <i>x</i> - 2 -

-

Accessible example of the same function, using the math role, appropriate label, and MathML rendering:

-

Todo: add aria-label here also

- 
<div role="math">
-  <math xmlns='http://www.w3.org/1998/Math/MathML'>
-    <mrow>
-      <mrow>
-         <mi>f</mi>
-         <mo>&#x2061;</mo>
-         <mrow>
-            <mo>(</mo>
-            <mrow>
-               <mi>x</mi>
-            </mrow>
-            <mo>)</mo>
-         </mrow>
-      </mrow>
-      <mo>=</mo>
-      <mrow>
-         <msup>
-           <mi>x</mi>
-           <mn>2</mn>
-         </msup>
-         <mo>+</mo>
-         <mi>x</mi>
-         <mo>&#x2212;</mo>
-         <mn>2</mn>
-      </mrow>
-    </mrow>
-  </math>
-</div>
-
- -
-

Drag-and-Drop Support

-

aria-grabbed and aria-dropeffect have been deprecated in ARIA 1.1 - as such this section has been removed. Advice for implementing drag and drop will be added to a future version of the Authoring Practices Guide.

- -
- -
-

Reusable Component Libraries

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

-

Rich internet applications are complex to author. To save time, it is often faster to use existing widget libraries that implement WAI-ARIA and that have already gone through:

- -

Some publicly available UI component libraries have already implemented WAI-ARIA. Authors can reuse such libraries to start developing accessible rich internet applications.

-
- -
-

Appendices

- -
-

Background on WAI-ARIA

-

This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

-

According to the SecuritySpace Technology Penetration Report, more than 55% of all Web sites today contain JavaScript, dramatically affecting the ability for persons with disabilities to access Web content. New Rich Internet Applications (RIAs) render custom widgets, modeling rich desktop components to perform UI updates without having to reload the entire page - much like a graphical user interface (GUI). Legacy GUI accessibility frameworks address these issues through a comprehensive accessibility application programming interface (API) and infrastructure to foster interoperability with assistive technologies. These APIs constitute a contract between applications and assistive technologies, such as screen readers, to enable them to access rich dynamic content with the appropriate semantics needed to produce a usable alternative. No such contract exists between modern RIAs and assistive technologies, creating an accessibility gap for persons with disabilities.

-

Unfortunately, HTML and other markup languages do not provide adequate - support for accessible dynamic content. Until now, the W3C WAI has discouraged the use of JavaScript per [[WAI-WEBCONTENT]], Checkpoint 6.1). - A - number of W3C initiatives underway address this problem using - a declarative markup approach. This primer describes a means to - bridge the interoperability problem with assistive - technologies now by incorporating the appropriate metadata into - current HTML and XHTML markup to support today's accessibility APIs. Moreover, the primer provides web developers with a conceptual understanding of WAI-ARIA as a prelude to using the [[WAI-ARIA]]. WAI-ARIA brings advanced accessibility features of the desktop to the web through the creation of cross-cutting technologies that - (X)HTML authors can incorporate in their markup. WAI-ARIA defines roles, states, and properties, where those roles reflect standard GUI elements that are recognized by accessibility Application Programming Interfaces (APIs). These metadata that describes these - GUI widgets and document structures aides assistive technology - vendors in providing accessible, usable solutions. The W3C WAI PF working group is working with User Agent manufacturers, assistive - technology vendors, and accessibility tool providers, to ensure an end-to-end working solution.

-

For an introduction to WAI-ARIA, see the Accessible Rich Internet Applications Suite (WAI-ARIA) Overview. The WAI-ARIA Primer is part of a set of resources that support the WAI-ARIA specification. The Primer provides a basic introduction to the concepts behind and reason for WAI-ARIA, and the WAI-ARIA Authoring Practices describe recommended usage patterns for Web content developers. The WAI-ARIA Suite fills gaps identified by the [[WAI-ARIA-ROADMAP]]. These documents serve as important places of clarification where topics appear to be unclear.

-
-

The Problem

-

Aspects of traditional Hypertext Markup Language (HTML) make accessible support of dynamic content difficult:

-
    -
  1. Accessibility of dynamic content relies on abstracting semantics from both content and presentational information. Extracting semantic cues from current HTML content is typically unreliable as the cues are limited to tag elements names.
    2. -
  2. While HTML allows content to be repurposed for presentational formatting, it lacks the ability to attach meaningful metadata about document structure and to convey semantic information. A common example of this is content formatted with tables rather than style sheets.
    3. -
  3. When combined with script and cascading style sheets (CSS), HTML can be repurposed to create dynamic custom components without providing a means to convey semantic information to native accessibility architectures designed to support dynamic graphical user interface (GUI) content.
    4. -
  4. Custom components built from common HTML elements often are not keyboard accessible.
    5. -
-

Authors of JavaScript-generated content do not want to limit themselves to using standard tag elements that define the actual user interface element such as tables, ordered lists, etc. Rather, they make extensive use of elements such as DIV tags in which they dynamically apply a user interface (UI) through the use of style sheets and dynamic content changes. HTML DIV tags provide no semantic information. For example, authors may define a DIV as the start of a pop-up menu or even an ordered list. However, no HTML mechanism exists to:

-
    -
  • Identify the role of the DIV as a pop-up menu
    • -
  • Alert assistive technology when these elements have focus
    • -
  • Convey accessibility property information, such as whether the pop-up menu is collapsed or expanded
    • -
  • Define what actions can be formed on the element other than through a device-dependent means through the event handler type (onmouseover, onclick, etc.)
    • -
-

In short, JavaScript needs an accessibility architecture to write to such that a solution can be mapped to the accessibility - frameworks on the native platform by the user agent.

-

The following diagram illustrates a typical document object model (DOM) node in - a Model-View-Controller architecture. Accessibility information surfaced to assistive technologies is provided only by the HTML element's tag name, with only the accessibility attributes that tag can provide.

-

shows that on the node, data, or the - "Model", which should include semantic information, is separated - from the user interface presentation, the "View." Here, the - document element is managed by the user agent based on the default - behavior of the element. The user agent's default behavior at the - document element forms the controller.

-
- Accessibility information mapped to a DOM element in the Document Object Model -
Accessibility Interoperability at a DOM Node without JavaScript
-
-

The box between the DOM node - and the assistive technology contains the contract - provided by the user agent to the assistive technology. This data - includes typical accessibility information found in the - accessibility API for many accessible platforms for GUIs - (role, state, caret, selection, text, hypertext, name - description, parent/child information, parent/child - information, and relations). For HTML and other W3C markup, the - accessibility information provided solely depends upon what the element's tag name and any accessibility attributes that map to that tag provides. For example, the accessible role of a table is table. The author provides an accessible description by assigning a title attribute.

-

In contrast, with JavaScript, user actions can trigger updates in the data and presentation, but the default accessibility information available in the element tags is no longer valid.

-
DOM Element with JavaScript controller -
Accessibility - Interoperability at a DOM Node with JavaScript
-

shows the same DOM node provided - in Figure 1.0 but with JavaScript acting as the new controller. - JavaScript overrides the default user agent behavior at the DOM - node. It manipulates the data, content, and style in response to - events caused by user interaction to produce custom widgets. In - this situation, the default accessibility information is no longer - valid and, therefore, the contract is now invalid. Figure 2.0 shows - the contract with asterisks in front of role, state, actions, - value, event changes, and relations. These asterisks represent - potential accessibility errors and gaps in the base markup. These - gaps result from the author's inability to provide the new semantic - data needed to support the contract.

-
-
-

Requirements

-

Any solution to facilitate the creation of accessible rich Internet applications (RIAs) must:

-
-
Allow for discovery of custom UI components - through the use of Semantic Web technologies
-
Web ontologies allow for storage of semantic information about - objects and how they relate to others in the ontology.
-
Support today's accessibility - architectures
-
Accessibility architecture today is centered around object - technology. Each object in an application or document exposes - its accessible properties to an assistive - technology.
-
Allow for separation of content and - presentation
-
Dynamic content authors must be able to store the accessible - meta data in the document independent of how it is rendered.
-
Allow for passive monitoring of the application - by an assistive technology
-
Assistive technology vendors should not be required to poll an - application for changes in accessibility information.
-
Leverage new W3C efforts to solve the - problem
-
This problem needs to be solved quickly. A number of - efforts are underway, such that minimal changes may be required to - bring them to the level needed.
-
Be light weight
-
The solution needs to be light-weight in order to promote adoption by Web authors.
-
Scaleable
-
The solution needs to be scalable; it must make simple things - easy while making complex things possible.
-
Internationalizable
-
Like other Web solutions, our solutions must be - internationalizable.
-
Guarantee user agent support up front
-
User agent manufacturers must be involved up front to ensure support for the solution when the specification is complete.
-
Involve assistive technology vendors up - front
-
To ensure interoperability, assistive technology vendors need to be involved from day one. - The effort must leverage support by AT vendors to ensure that a - total solution is available when the specification is complete.
-
Produce Developer Guidelines during the - process
-
This is a critical mistake made by people creating a new - accessibility model. Developers must be engaged early on so that - they can contribute feedback and start producing workable solutions - early.
-
-
-
-

Solution

-

What is clear from the problem statement is that developers of dynamic web content cannot provide the appropriate accessibility information in the markup to support the accessibility APIs on the target platform. This problem is not limited to HTML. It extends to other markup, including Scaleable Vector Graphics [SVG]. This primer addresses the problem for web content delivered to desktop browsers and introduces you to common extensions to both HTML and XHTML called [[WAI-ARIA]]. The goal is to make these standard features in HTML 5.

-
-
-

HTML Accessibility API Support Analysis

-

Using as a template for addressing the - problem and U.S. Section 508 accessibility standards, Table 1.0 illustrates gaps - in the infrastructure and identifies W3C standards that should be used to - address the problem. In the right column, table cells that are empty - or that indicate a limitation represent accessibility gaps in HTML - and XHTML.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Table 1.0 Platform Gap Analysis - for Accessible Dynamic Web Content for HTML and XHTML -
Required ComponentsWho does what today? (HTML)
Events: 
FocusChangeDOM 2, 3 events
ActivationUser Agent API
Caret ChangeUser Agent API
Value Change 
State Change 
Selection ChangeUser Agent API
MutationDOM Events
Accessible - Actions: 
Event Handler functional information to label the actions 
Access to the available event - handlers for enumerating the actions 
State Information: 
Role Information:Limited to standard HTML tag names. (Mix - Content/presentation)
Relationships: Parent/childLimited DOM (affected by style) (Mix Content/presentation)
Relationships: (Label, MemberOf - Group, - ControllerFor)Limited to HTML (Title, alt, label)
TextCore DOM from parsed HTML
Content selection:Browser-dependent (incomplete)
Font/Font Style Information:Can set but can't get final format
Description/Help:Limited to HTML 4.0 - Alt Text, title text
Accessible value:Limited to form elements
Coordinates (Bounding rectangle, etc.):User Agents. platform accessibility API
Accessible Name: 
Respond Desktop Font/Color - Changes:Partial (conflicts with CSS and JavaScript)
Device independent navigation: 
Accessibility API Mapping:Partial - User Agents
Provide focus to all active elements (important for - equivalent keyboard access on desktops)Limited to forms and anchors
-
-
- -
-

Filling the Gaps for Content Delivered to Desktop Browsers

-

This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

-

At this time,W3C WAI Protocols and - Formats working group's primary focus is on extensions to HTML 4.01 and XHTML 1.X by extending the host language to include WAI-ARIA with a migration path to HTML 5. This will require the creation of new hybrid document type definitions (DTDs) that incorporate the extensions. This work will be in the [[WAI-ARIA]] specification. WAI-ARIA will constitute - extensions to fill most of the gaps needed to support - accessibility API infrastructures and dynamic (X)HTML content. The comprehensive gap analysis of (X)HTML, used to form WAI-ARIA is found in Table 1.0 and how WAI-ARIA fills those gaps. In the future we hope to incorporate WAI-ARIA into many host languages to improve their accessibility. The critical extensions needed to make accessible dynamic Web content accessible, through rich interoperability with assistive technologies, - are summarized here:

-
-

States, and Property attributes - This is the set of attribute modifications to (X)HTML necessary to provide full keyboard focus and states and properties that may be mapped directly or indirectly to platform accessibility APIs to ensure full interoperability with assistive technologies for WAI-ARIA.

-

Role attribute - The role attribute, borrowed from the, [[ROLE-ATTRIBUTE]], allows the author to annotate host languages with machine-extractable semantic information about the purpose of an element. It is targeted for accessibility, device adaptation, server-side processing, and complex data description. WAI-ARIA uses the role attribute to provides the role information, in to an assistive technology.

-

Role document landmark values - These values, borrowed from the [[ROLE-ATTRIBUTE]] provides a standard set of role attribute values designed to define pertinent parts of a document (landmarks) for the purpose of accessibility. User agents may incorporate device equivalents, such as key mappings in the case of a desktop user agent, to navigate to these sections of a document.

-

Taxonomy of WAI-ARIA role values - The necessary core roles found in Accessibility API sets - for Windows and Linux as well as roles representative of document structure, such as banner or treegrid. Use of document - structure is necessary for assistive technologies to navigate - complex documents and to know when they have entered active areas - of a Web page such as in the case of a dynamic scripted Web - application. The taxonomy is designed to help user agents or - authoring tools determine what properties a given role supports and to assist with accessibility API mapping of these - properties. The taxonomy will is like a class hierarchy used to - convey semantics and structure and includes knowledge about each - role. At this time, that taxonomy is modeled using [[RDF-CONCEPTS]] and [[OWL-FEATURES]].

-
-

In short, WAI-ARIA will be used to fix the dynamic accessibility of scripted Web content, - in particular the use of JavaScript with (X)HTML markup. They are meant to be - cross-cutting and should apply to other markup like SVG. Less - critical for (X)HTML but helpful for accessibility - will be the descriptive extensions to XML events and the new [[XHTML Access]]. Web Content Accessibility Guidelines 2.0 calls for the WAI-ARIA properties in guideline 4.1 Maximize compatibility with current and future agents, including assistive technologies (roles, states, properties, and values) and section guideline 1.3 Create content that can be presented in different ways (for example spoken aloud, simpler layout, etc.) without losing information or structure (relationships).

-

The - next section describes how the specifications are used together as well as how they will be implemented in HTML 4.

-
-

Use of New Provisions for Keyboard Focus and Semantics to Support Platform Accessibility APIs

-

Adaptive technologies, which need to provide alternative access to - complex user interfaces authored via HTML, are often left guessing - at the semantics behind specific portions of HTML document. As an - example, an XHTML document might use a certain HTML construct, such - as a collection of DIV tags, to create navigation bars, a - site-navigation menu, and other GUI-like user interface widgets. To - fix the problem, we incorporate the role - attribute, assign the accessible state properties, and give the object - focus using the new TABINDEX feature. Addition of this information - helps authors to provide the necessary information to - enable the user agent to support the accessibility API accessed by - the adaptive technology.

-
-

Provision of the Role Attribute: "What is the Object?"

-

Each platform accessibility API has the notion of a "role" for a - GUI object. This is the case for [[JAPI]], [[MSAA]]], [[AXAPI]], and the [[ATK]], or [[UI-AUTOMATION]] (called content type in UI Automation). The WAI-ARIA specifications are based on XHTML 1.X and include the role attribute. The "role" attribute takes a qname, enabling authors to reference the role attribute from the WAI-ARIA Roles. In - the following example, we use qname to reference the menu role in the WAI-ARIA specification.

-
-

Example: Use of WAI-ARIA to incorporate - role information into XHTML 1.x

- 
-<?xml version="1.1" encoding="us-ascii"?>
-<!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml"
->
-    <body>
-        <div role="menu">
-            File
-        </div>
-    </body>
-</html>
-
-
-

WAI used RDF/OWL to model our taxonomy for WAI-ARIA. In fact, if a host language sought to use namespaces or qnames, they could do so to reference the WAI-ARIA role taxonomy. The WAI-ARIA role taxonomy could be used by authoring tool developers to ensure that states and properties assigned to a given role are accurate.

-
-
-

Provision of the Accessibility State Information: "What meaningful properties does this object have at this time?"

-

Since this is dynamic content, the state of these new repurposed - objects will change. The WAI-ARIA specification shall provide the common - accessible properties needed to support the accessible state or - property information provided by the platform accessibility API - defined previously. This specification was created based on an - analysis of the accessibility properties defined in MSAA and ATK. - The following example extends the previous approach by adding the aria-haspopup accessibility property.

-
-

Example: Use of WAI-ARIA to incorporate accessible state information into XHTML 1.x

- 
-<?xml version="1.1" encoding="us-ascii"?>
-<!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
-    http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-
-
->
-        <body>
-            <div role="menu" aria-haspopup="true">
-                File
-        </div>
-    </body>
-</html>
-
-
-

A Windows user agent may now map this property to the Microsoft - Active Accessibility state of STATE_SYSTEM_HASPOPUP. Adding or - removing this state would result in the Windows user agent sending - an EVENT_OBJECT_STATECHANGE event to the assistive technology. The - task of the JavaScript page author would be to maintain this state - attribute, which can easily be done through the use of Document - Object Model calls.

-
-
-

Provision of the Keyboard or Input Focus: "What object am I working on?"

-

Virtually all adaptive technology solutions, such as screen - readers and onscreen keyboards, must know which object currently - has focus. For example, an author might want to insert text into the - current object with focus or to announce information - about the object that has focus. With today's HTML 4.01 and XHTML 1.x, script authors can only provide focus to form - and anchor elements yet the Document Object Model Specification - allows all elements to receive events including keyboard events. - This means that HTML, by design prohibits script authors from - making all HTML elements keyboard accessible. This single problem - effects usability of Web pages where one gains access to - elements by using the Tab key on desktop browsers. This slow, - unproductive, approach makes portal navigation difficult because all active elements must be tabbed through to put focus on an - active element in the last portlet in a document. To solve this - problem in XHTML 1.x, we are incorporating a feature in Firefox and - Internet Explorer to define the tabindex for -1. This allows a script author to - give an element focus without placing it in the tab order: The - following table describes these changes that will be incorporated - into the new Accessible Adaptive Application specification.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Accessible Adaptive Application Changes to Support Use of tabindex to give Element Focus -
tabindex attributeFocusable with mouse or JavaScript via element.focus()Tab navigable
not presentFollows default behavior of element (yes for form controls, - links, etc.)Follows default behavior of element
Negative, e.g. tabindex="-1" YesNo, author must focus it with element.focus() as a - result of arrow or other key press
Zero, e.g. tabindex="0" YesIn tab order relative to element's position in document
Positive, e.g. tabindex="33" YesTabindex value directly specifies where this element is - positioned in the tab order. These elements will be positioned in - the tab order before elements that have tabindex="0" or that are - naturally included in the tab order (form elements and links)
-

The following example shows the introduction of TABINDEX to - provide focus to a DIV having the new accessibility meta data:

-
-

Example: Use of tabindex to give non-form - and anchor elements focus in XHTML 1.x

- 
-<?xml version="1.1" encoding="us-ascii"?>
-   <!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
-    http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-
-
->
-    <body>
-        <div role="menu" aria-haspopup="true" tabindex=-1>
-            File
-        </div>
-    </body>
-</html>
-
-
-
-
-

Supporting WAI-ARIA in XHTML and HTML 4.01

-

Unlike XHTML, HTML 4.01 is non-extensible in that it is not possible to extend HTML 4 through the use of namespaces. That said, members of the working group have worked with the HTML working group to agree on a vehicle that does not use namespaces, which at this time is supported by XHTML and HTML which will be supported in HTML 5 when it becomes recommendation. Firefox 3 is leading the way to implement this, and other browser manufacturers are working to support it as well. The technique allows all role values specified in WAI-ARIA (including those specified by the XHTML Role attribute module) to be specified without a namespace prefix. Additionally, WAI-ARIA states and properties shall be represented as aria- followed by the concatenated WAI-ARIA state or property.

-
-

Example: Browser supported HTML technique for the tabindex example in section 5.1.3

- 
-
-<html lang="en">
-  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  </head>
-    <body>
-        <div role="menu" aria-haspopup="true" tabindex=-1>
-            File
-        </div>
-    </body>
-</html>
-
-
-

In order to validate these extended attributes for HTML and XHTML the WAI-PF working group will investigate the creation of an enhanced schema or DTD for each host language.
-

-
-
-
-

Use of XHTML Role Landmarks to Improve Document Navigation

-

In addition to the common roles which will reside in WAI-ARIA Roles, both XHTML 2.0, and the XHTML Role attribute module ([[ROLE-ATTRIBUTE]], Section 4) defines a collection of common role, regional, landmarks that define pertinent parts of a - document for the purpose of accessibility. User agents may - incorporate device equivalents, such as key mappings in the case of - a desktop user agent, to navigate to these sections of a document - independent of the Web site. The addition of these semantics allows - the user agent to provide standardized navigation to common - document sections. This is especially important for portals to - improve the usability. These may be used as attributes in XHTML 1.x - by applying them to sections of the document as shown in this - example. Note: since these roles are a part of XHTML they do not need to be namespace qualified.

-
-

Example: Use of XHTML navigation role to define a landmark for the - navigation section in an XHTML 1.X document

- 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title>application/xhtml+xml: Navigation Roles Example 1</title>
-  <link rel="stylesheet" href="css/nav1_xhtml.css"  type="text/css" ></link>
-  <script type="text/javascript" src="../js/globals.js"></script>
-  <script type="text/javascript" src="../js/widgets_xhtml.js"></script>  <link rel="icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon" />
-  <link rel="shortcut icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon" />
-</head>
-<body onload="widgets.init()">
-.
-.
-.
-<div id="leftnav">
-<h2 class="nav" id="leftnav_label">Career Center Services</h2>
- <ul title="Career Center Services" role="navigation" aria-labelledby="leftnav_label">
-   <li><a href="http://www.uiuc.edu/">Career Home</a></li>
-   <li><a href="http://www.uiuc.edu/">Career Counseling</a></li>
-   <li><a href="http://www.uiuc.edu/">Pre-Health Advising</a></li>
-   <li><a href="http://www.uiuc.edu/">Services</a></li>
-   <li><a href="http://www.uiuc.edu/">Workshops</a></li>
-   <li><a href="http://www.uiuc.edu/">Resource Center</a></li>
-   <li><a href="http://www.uiuc.edu/">Question Board/FAQ</a></li>
- </ul>
-
-...
-
-</body>
-
-

The example above was taken from the header from the Career Center Web page at the University of Illinois at - Urbana-Champaign. Students from this university, under Jon - Gunderson's guidance created Accessibility - extensions for Mozilla/Firefox, in part, to allow a page author or - user to view a list of navigation landmarks. - This tool, shown in , lists the navigation sections on the page. Keyboard navigation of the list of navigation bars causes the - corresponding document section to be highlighted. The title for each navigation region displays in the list.

-
Table of Contents from Landmarks -
Table of Contents generated from navigation landmarks in the header
-
-

shows the accessibility - extensions for Mozilla/Firefox from the University of Illinois at - Urbana-Champaign to render the document landmarks. This picture - shows the Firefox browser rendering the University of Illinois - Career Center home page. In this example. The "List of Navigation Bars" viewer is shown, launched from the extension on the - toolbar. The viewer shows that the secondary "Career Center Services" is selected resulting - in that section of the document being highlighted in yellow. The - Navigation Bar Lists Viewer lists the following list of titles corresponding to the navigation sections:

-
    -
  • Career Counseling Resources
    • -
  • Resources by Audience
    • -
  • Career Center Services
    • -
  • Quick Links
    • -
-
-
-

WAI-ARIA Role Taxonomy - Extensible Semantic Role Model, using RDF/OWL

-

The WAI-ARIA role taxonomy was modeled using semantic web technology, in the form of [[RDF-CONCEPTS]] and the [[OWL-FEATURES]], as a vehicle to define a knowledge-based class hierarchy for roles. This model shows what states and properties are supported, by each role in the taxonomy. The role in the class hierarchy inherits properties from its ancestors and defines its own properties. Where applicable, semantic web technology is used to define related concepts within other namespaces. This information is critical in determining how to choose a role and how to interact with it. The role taxonomy uses RDF as a way for using data to describe data and provides a - W3C standards-based approach to represent this information.

-
- - Sample Semantic Map for Taxonomy -
Example, Partial RDF Map for a possible ButtonUndo role as an extended role to WAI-ARIA
-
-

shows a basic RDF mapping that - defines a set of terms and relationships defining an object. At the - center is a Widget object that defines common states and properties - for all GUI widgets. The Button object extends Widget and inherits - defined accessibility properties from the superclass Widget. It - also defines a relatedConcept property to a Link object. - The ButtonUndo role extends Button. It has a relatedConcept of an HTML input object. - ButtonUndo will introduce Dublin Core meta data such as the - description of the object. The terms relatedConcept and - requiredState are terms that will be defined as part of the - corresponding RDF schema. Each role instance will represent - standard Roles found in the platform accessibility APIs of platforms like - Windows and Gnome as well as content structure. These roles will - form the taxonomy. Although host language browser implementations may reference WAI-ARIA roles without namespaces, the RDF representation for a given role may be referenced using a - qname from a Host XML markup language. This examples shows an XHTML reference to a grid role in the RDF representation of the WAI-ARIA taxonomy:

-

<div - role="grid"> whereby grid expands to: - http://www.w3.org/2005/01/wai-rdf/GUIRoleTaxonomy#grid in the - button markup.

-

The power of this design is that it enables a web authoring tool to go back - into the corresponding RDF/OWL markup and determine what properties it - supports for Accessibility API mapping. Additional, middleware solutions can now make intelligent - transformations of Web Content by processing the semantics behind - rich browser and rich structured frameworks to adapt accessible - solutions for a broader user base. Our immediate goal is to fix the - accessibility problem with scripted Web content. Assistive - technologies will use the standard roles to determine how to render - most content.

-
-

Interoperability Example: Grid Role

-

To understand the power of this approach, consider the case of a Grid Role, analogous to a table. shows a DHTML example using - XHTML, JavaScript, and CSS to produce a GUI-like application. This - example developed in IBM shows a notebook - tab with a data grid that behaves like a traditional desktop GUI. - The user uses arrow keys to navigates the data grid and among the page tabs. - Using the Tab key, a user navigates between the notebook tab, the edit fields, buttons, and - the data grid.

-
DHTML example of GUI-like notebook tab with a data grid -
DHTML Example
-
-

Accessible role and state - meta data from the WAI-WAI-ARIA Roles, States, and Properties specification, are added as attributes to - each of the XHTML elements repurposed as GUI widgets dynamically. - The user agent, in this case Firefox, maps this information to the - platform accessibility API. shows - the Microsoft Active Accessibility rendering of the new - accessibility markup provided on the DataGrid page tab which has - focus.

-
MSAA Inspect Tool diagnostics for Notebook page tab -
Microsoft Inspect Tool rendering of the page tab - DataGrid
-
-

show a Microsoft Inspect 32 - rendering of the DataGrid Page page tab in Figure 5.0. Inspect32 - provides Microsoft Active Accessibility information; here it shows the - accessible role of "page tab" and accessible state information of - focused, focusable, and linked. There are no page tab elements in - XHTML. Here, an XHTML DIV element is repurposed by a - JavaScript controller to look like a notebook tab. It is now able - to receive focus, unlike in standard XHTML 1.X, and it does so without - requiring tabbing. With these specifications, the script - author can now add the accessibility properties to support platform - accessibility API. Accessible state properties for the DataGrid - page tab are shown as focused, focusable, and linked. Unlike a GUI - application, authors need only enable their applications once for - multiple operating system platforms.

-

Beyond scripted Web content, the working group intends to extend - the use of roles to enable other user cases. These may include:

-
    -
  • Structured Textual Markup - enhancing - structure of the markup of a document, including Data Tables , or - translating the structure of an XML document to a markup structure - that user agents are used to dealing with (e.g. myXML to XHTML) - Binding sections of a document to a common role. This allows for - different navigation techniques though a document
    • -
  • Knowledge representation of Web content - As a - secondary benefit, roles improve compatibility with Knowledge-Based - Services and the Semantic Web. By integrating accessibility and the - semantic Web, accessibility can be moved forward, paving the way - for customized accessible searches and intelligent user agents with - additional applications.
    • -
  • Adding concepts in the type of content for adaptation - to the user scenario - The more that is understood about - content, the better it can be adapted for the end user. For example: -
      -
    1. If it is known that a page hyperlink has the role of taking the - user to the site's home page, then that knowledge can be used to - create enhanced accessibility in different ways in many different - scenarios, such as icons or access keys.
      2. -
    2. If it is known that a text box is for the user email address, - then the user agent can support users filling in the form by - labeling it with an icon or symbol, automatically validating it, or - even form filling.
      3. -
    3. If it is known that a paragraph is complex, then a simple equivalent - can be shown in its place
      4. -
    4. If a word is ambiguous, then a role of a concept can be given, - providing clarity An example of this may be : <span - role="role:nonliteral" aria:hasAlternate="no">
      5. -
    -
    • -
- -
-
-
-

Accessibility Events and Event Handling

-

Interoperability between applications and assistive technologies - requires event notification for accessibility. The events will be fired via the user - agent. The accessible value and state property changes will be - generated in response to changes in the DOM attributes as defined - by the WCAG 1.0 AAA specification. User agents supporting the platform - accessibility API, will support event notification such as the state change or value change events.

-
-
-
-

Building Accessible Applications with WAI-ARIA

-

This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

-

This section provides a brief introduction to the process of making applications accessible using WAI-ARIA. The choice and usage of roles can be complex and context dependent. It is beyond the scope of this document to explain implementations for all the possible WAI-ARIA use cases. WAI-ARIA Authoring Practices provides detailed guidance on WAI-ARIA implementation methodology as well as references to sample code.

-

First steps to making an application accessible:

-
    -
  1. Each element or widget has correct and complete semantics that fully describe its behavior (using element names or roles);
    2. -
  2. The relationships between elements and groups are defined;
    3. -
  3. States, properties, and container relationships are valid for each element's behavior and are accessible via the [[dom]] and the platform accessibility API; and
    4. -
  4. Keyboard focus should be maintained for the duration of the user's interaction with the application.
    5. -
  5. All interactive components should be keyboard operable.
    6. -
-

WAI-ARIA provides authors with the means to make the different elements in a web application semantically rich. User agents use the role semantics to understand how to handle each element. Roles convey additional information that the assistive technologies need to anticipate the behavior of the elements inside the application such as how to present the corresponding WAI-ARIA states and properties to the user. The user agent will use the accessibility semantics from the host language and WAI-ARIA accessibility semantics (which may augment or override those of the host language) and present them to assistive technologies through the Document Object Model or the platform accessibility API. The user agent will create an accessible representation of each element in the web page, and will use the appropriate accessibility API to notify assistive technologies of changes to the semantics of those elements.

-

The following steps are recommended when WAI-ARIA is applied to content:

-
    -
  1. -

    Use native markup when possible.

    -

    Use the semantic elements that are defined in the host markup language. For example, with HTML or XHTML, it is better to use the native checkbox than to use a div element with role checkbox as these should already be accessible through your browser. There may also be cases where WAI-ARIA can augment an existing element in the host language. For example, a grid and gridcell elements can reuse the functionality of a table when overlaying it. WAI-ARIA roles, states, and properties are best used when the markup language does not support all the semantics required. When a role attribute is added to an element, the semantics and behavior of the element are augmented or overridden by the role behavior.

    -
    2. -
  2. -

    Apply the appropriate roles.

    -

    Set roles to make sure elements behave predictably and correctly describe the behavior of each element within the application, unless element behaviors are fully described by the native markup language. Roles for interactive elements should support all the attributes that the element could use. Once a role attribute is set it should not be changed as this may confuse the end user. This does not preclude an element being removed which has the role attribute set, but only states and properties (aria-* attributes) should be changed for a given element.

    -
    3. -
  3. -

    Preserve semantic structure.

    -

    Structural information is critical to providing context to persons with disabilities. Preserve DOM hierarchy within structural elements and widgets:

    -
      -
    • Form logical groups within user interface widgets, such as treeitem elements in a group.
      • -
    • Identify large perceivable regions and apply a landmark role to those areas. This will facilitate keyboard navigation. It will also facilitate content management by assistive technologies by providing semantics to manage how much information is rendered at a given time. The use of WAI-ARIA landmarks helps everyone, including vision-impaired users, dexterity-impaired users, and even users with cognitive or learning impairments.
      • -
    • For areas of the page that contain a group of elements that are likely to change through an Ajax application it may be specified as a live region, through the use of the aria-live attribute or it may be marked with pre-defined roles, such as log, which has assumed behavior of a live region.
      • -
    -
    4. -
  4. -

    Build relationships.

    -

    Look for relationships between elements, and mark them using the most appropriate property or attribute. For example, if a page contains both a search form and search results region, mark each container as a region and set the aria-controls attribute of the search form to reference the search results. See relationships in WAI-ARIA.

    -

    Some relationships are determined automatically from the host language, like label elements associated with input elements in HTML.

    -
    5. -
  5. -

    Set states and properties in response to events.

    -

    Once the role for an element has been set, change states and properties as appropriate during the element's life cycle, usually in response to user input events. Only use attributes supported for the chosen role or element.

    -

    User agents should notify assistive technologies of state changes. Conversely, assistive technologies' notification of property changes depends on the method by which assistive technologies communicate with the user agent. For example, the aria-multiline attribute (a property) is not something that changes frequently, whereas the aria-checked attribute (a state) changes frequently in response to user input.

    -
    6. -
  6. -

    Support full, usable keyboard navigation.

    -

    Usable keyboard navigation in a rich internet application is different from the tabbing paradigm in a static document. Rich internet applications behave more like desktop applications where the user tabs to significant widgets and uses the arrow keys to navigate within a complex widget, such as a menu or spreadsheet. The changes that WAI-ARIA introduces in keyboard navigation make this enhanced accessibility possible. Tabbing in the document should follow a logical navigation structure. Authors implementing arrow key navigation should, where possible, follow the design patterns in the WAI-ARIA Authoring Practices Guide. When using these features, it is important as always to ensure keyboard navigation is logical.

    -
    7. -
  7. -

    Synchronize the visual interface with the accessible interface.

    -

    This will allow the state of your UI to be perceivable to the user as well as assistive technologies. For example, the author should use the appropriate WAI-ARIA attribute on a form element that is visually styled to appear required (aria-required) or a gridcell that is visually styled to appear selected (aria-selected). Authors may choose to achieve visual synchronization of these interface elements by using a script or by using CSS attribute selectors.

    -
    8. -
-
-

Example: Building a Tree Widget

- Graphic of an example tree view. -

A basic tree view allows the user to select different list items and expand and collapse embedded lists. Arrow keys are used to navigate through a tree, including left/right to collapse/expand sub trees. Clicking the visible expander button with the mouse also toggles expansion. Further keyboard implementation details for tree widgets may found in the .

-

To make this feature accessible we need to:

-
    -
  • Inform assistive technologies about the role of each element;
    • -
  • Inform assistive technologies about the relationships between tree items;
    • -
  • Give a clear keyboard focus that will not confuse users with disabilities; and
    • -
  • Expose the changing states (expanded and collapsed) of the tree items.
    • -
-

Following the steps below:

-
    -
  1. -

    Look at the native markup language

    -

    Although standard list behavior is supported by the native ul and li elements in HTML, there is no element that natively supports list expansion and selection. Since there is not, we will need to use roles.

    -
    2. -
  2. -

    Finding the right roles

    -

    Since there is no native tree element in HTML, we need to add roles from the taxonomy that support the additional states and properties needed. The roles that support tree behavior are:

    -
      -
    • tree: A tree is the main container element for our tree. It is a form of a select where sub-level groups of treeitems may be collapsed and expanded.
      • -
    • treeitem: A treeitem is an option item of a tree. This is an element within a tree; sub-level groups of treeitems may be expanded or collapsed.
      • -
    • group: A group encloses a set of sub-level treeitems.
      • -
    -
    3. -
  3. -

    Look for groups and build relationships

    -

    Tree relationships can be made simply via the DOM and logical structure of the page. A tree element will be the main container encompassing all other elements in the tree. Each selectable item in the tree will be a treeitem.

    -

    When a treeitem contains an embedded list of treeitems they will be all be embedded in a group. A group should be contained inside the tree item that is the parent item.

    - 
    <h1 id="treelabel">WAI-ARIA Tree Example</h1>
-<ul role="tree" aria-labelledby="treelabel" aria-activedescendant="example_id" tabindex="0">
-  <li role="treeitem" aria-expanded="true">Animals
-    <ul role="group">
-      <li role="treeitem">Birds</li>
-      <li role="treeitem" aria-expanded="false">Cats
-        <ul role="group">
-          <li role="treeitem">Siamese</li>
-          <li role="treeitem">Tabby</li>
-        </ul>
-      </li>
-      <li role="treeitem" aria-expanded="true">Dogs
-        <ul role="group">
-          <li role="treeitem" aria-expanded="true">Small Breeds
-            <ul role="group">
-              <li role="treeitem">Chihuahua</li>
-              <li role="treeitem" id="example_id">Italian Greyhound</li>
-              <li role="treeitem">Japanese Chin</li>
-            </ul>
-          </li>
-          <li role="treeitem" aria-expanded="false">Medium Breeds
-            <ul role="group">
-              <li role="treeitem">Beagle</li>
-              <li role="treeitem">Cocker Spaniel</li>
-              <li role="treeitem">Pit Bull</li>
-            </ul>
-          </li>
-          <li role="treeitem" aria-expanded="false">Large Breeds
-            <ul role="group">
-              <li role="treeitem">Afghan</li>
-              <li role="treeitem">Great Dane</li>
-              <li role="treeitem">Mastiff</li>
-            </ul>
-          </li>
-        </ul>
-      </li>
-    </ul>
-  </li>
-  <li role="treeitem" aria-expanded="true">Minerals
-    <ul role="group">
-      <li role="treeitem">Zinc</li>
-      <li role="treeitem" aria-expanded="false">Gold
-        <ul role="group">
-          <li role="treeitem">Yellow Gold</li>
-          <li role="treeitem">White Gold</li>
-        </ul>
-      </li>
-      <li role="treeitem">Silver</li>
-    </ul>
-  </li>
-  <li role="treeitem" aria-expanded="true">Vegetables
-    <ul role="group">
-      <li role="treeitem">Carrot</li>
-      <li role="treeitem">Tomato</li>
-      <li role="treeitem">Lettuce</li>
-    </ul>
-  </li>
-</ul>
    -

    The use of aria-expanded should mirror that which is visibly expanded on screen, so authors may wish to use CSS attribute selectors to toggle visibility or style of an item based on the value of an WAI-ARIA state or property. The following example would hide the sub-level groups of a collapsed tree node.

    - 
    [aria-expanded="false"] [role="group"] { display: none; }
    -

    - - At the time of this writing, this CSS example, while technically correct, will not redraw styles properly in some browsers if the attribute's value is changed dynamically. It may be necessary to toggle a class name, or otherwise force the browser to redraw the styles properly.

    -

    Sometimes a tree structure is not explicit via the DOM and logical structure of a page. In such cases the relationships must still be made explicit using the states and properties. In the following example, the aria-owns attribute indicates that the div with id "external_treeitem" should be considered a child of the ul element with the attribute, even though it is not a child in the DOM.

    - 
    ...
-<li role="treeitem" aria-expanded="true" aria-owns="external_group">Vegetables</li>
-...
-<ul role="group" id="external_group">
-  <li role="treeitem">Carrot</li>
-  <li role="treeitem">Tomato</li>
-  <li role="treeitem">Lettuce</li>
-</ul>
-...
    -

    Sometimes trees (and other lists or grids) cannot be completed represented in the DOM due to performance limitations of the browser. For example, an application interface may only need to display 100 items out of a set of 100,000. Including all 100,000 items in the DOM could cause performance problems on both the client and server machines.

    -

    If items in a managed widget are loaded, for example, via the XMLHttpRequest object, and not present in the DOM at all times, authors should use aria-level, aria-posinset and aria-setsize, and ensure that aria-owns is not required to convey membership with the widget.

    - 
    ...
-<li role="treeitem" aria-level="1" aria-posinset="3" aria-expanded="true" aria-setsize="3">
-  Vegetables
-  <ul role="group">
-    <li role="treeitem" aria-level="2" aria-posinset="6" aria-setsize="8">Carrot</li>
-    <li role="treeitem" aria-level="2" aria-posinset="7" aria-setsize="8">Tomato</li>
-    <li role="treeitem" aria-level="2" aria-posinset="8" aria-setsize="8">Lettuce</li>
-  </ul>
-<li>
-...
    -
    4. -
  4. -

    Use states and properties in response to events

    -

    Control the behavior of the element in response to user input events such as from the keyboard and the mouse, which includes maintaining the current states and properties for that element. For example, a tree control will need to respond to click events on the expand/collapse triggers, and key events on the currently active descendant. Use device-independent events with supporting JavaScript to handle user interaction. For detailed examples of this please refer to the Design Patterns section.

    -
    5. -
-
-
-
-

Reasons for Adopting WAI-ARIA

-

This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

-

By adopting WAI-ARIA, both developers of static web sites and of dynamic Internet applications can improve the usability, accessibility, and scalability of their products. Developers of static web content can continue to follow the 1999 WCAG 1.0 standards, while improving usability and accessibility through the use of WAI-ARIA landmark roles, aria-labelledby relationships, and properties like aria-invalid and aria-required that can apply to HTML form controls. In richer, dynamic content, developers create custom widgets like calendars and spreadsheets based on technologies such as Ajax and CSS; to achieve accessibility, they need to use WCAG 2.0. Previously, when delivering rich Internet applications to users, to comply with WCAG 1.0, developers resorted to providing alternative, static content. While such measures met the WCAG 1.0 requirements, people using assistive technologies were not provided the richer user experience. When tables are used for layout, rather than CSS absolute positioning, historically, they have been problematic for assistive technologies to interpret. When the WAI-ARIA role of presentation is used on such tables, the assistive technology ignores the table structure, providing a more accessible experience without requiring major recoding.

-
-

Technical Benefits

-

Consider a rich Internet application where developers attempt to achieve keyboard accessibility using markup language. Without WAI-ARIA, results may be keyboard accessible but not highly usable; consider a user having to press Tab thirty times to put focus on a checkbox. To achieve keyboard accessibility in HTML without WAI-ARIA, developers must code active elements either as a link or as a form element. Accordingly, this means that no additional semantics are required or provided, other than that provided by the host language. In addition, WCAG 1.0 requires that content be renderable with Cascading Style Sheets turned off in the browser. This approach creates the following general usability problems:

-
    -
  • All keyboard-accessible controls must be either forms or anchors, forcing the user to tab through all focusable elements on the web page to navigate. If you need to navigate from the first link on the page to the last link on the page, that could be a very long trip and takes usability a step back.
    • -
  • Without WAI-ARIA semantics, you cannot provide contextual information to the user.
    • -
  • If you repurpose HTML elements you cannot provide the appropriate role and context information for the new widget. Lack of context is a serious usability problem. WAI-ARIA semantics results in providing contextual information to the user.
    • -
  • CSS is used for absolute positioning. If you remove that capability, usability features of widgets like pop-up menus disappear. Imagine activating the file menu and the menu showing up at the bottom of the page.
    • -
-

WAI-ARIA and WCAG 2.0 coding techniques are useful for developing content and applications that can scale across a variety of user agents, including those on mobile devices.

-

For all these reasons, adopting WAI-ARIA makes good technical as well as business sense. For a further illustration, compare how accessibility is achieved with WCAG techniques without and with WAI-ARIA, as shown in .

-
- -

Editor's Note: Figure 7, described as WAI-ARIA tree widget usability comparison, refers to a resource that has not yet been found.

-
Usability of Tree Widget Using WAI-ARIA Semantics to Implement WCAG 2.0 Guidelines Compared to WCAG 1.0 Without WAI-ARIA
-
- -

- - shows an "accessible" widget for a tree item, within a tree widget, using WCAG 1.0 without WAI-ARIA, which ,when supplied to a screen reader, may say "link folder Year." There is no information to indicate that the folder is closed (aria-expanded = "false"). There is no information to indicate its depth (aria-level="2"), position in the set and the set size at the level, all of which provides the user with context something sighted users may take for granted. The role is used to indicate that it is a treeitem which indicates that the item should behave and navigate with the keyboard like a tree item. A screen reader using the WAI-ARIA version might say "Closed Folder Year, Closed Folder one of two, Depth two, unchecked." Furthermore, the WAI-ARIA version can allow the tree items to be navigated with arrow keys and without requiring they be navigated as part of a global web page tabbing scheme. This is not what any user would expect of a tree widget. Finally, if you were told all widgets were links on the web page, consider how usable -- or not -- that would be.

-
-
-

Business Benefits

-

If, as described above, coding techniques to achieve accessibility compliance do not promote overall usability, then business strategists must ask "Why invest in accessibility?" With WAI-ARIA, businesses can invest in accessible development and reap benefits for all users, not just those with disabilities or using assistive technologies. Some benefits include:

-
    -
  • Because WAI-ARIA is being developed through the PFWG with cooperation from browser and assistive technology vendors, accessibility and interoperability with those technologies will be easier to achieve, reducing or eliminating the need for per-browser and per-screenreader coding to achieve accessibility.
    • -
  • In addition to people with disabilities, all users benefit from WAI-ARIA because it establishes a Web-standard for keyboard interaction, easing the learning curve for users moving among applications, sites, and browsers.
    • -
  • Implementing WAI-ARIA can facilitate test automation. Test engines require semantic information about user interface elements, unique names, exposure of state, specific properties in order to run automated test scripts. WAI-ARIA provides that semantic information needed for efficient test automation.
    • -
-
-
- -
- - - diff --git a/aria-practices.html b/aria-practices.html deleted file mode 100644 index 9cead1622b..0000000000 --- a/aria-practices.html +++ /dev/null @@ -1,7330 +0,0 @@ - - - - - WAI-ARIA Authoring Practices 1.2 - - - - - - - -
-

- This document provides readers with an understanding of how to use WAI-ARIA 1.2 [[WAI-ARIA]] to create accessible rich internet applications. - It describes considerations that might not be evident to most authors from the WAI-ARIA specification alone and recommends approaches to make widgets, navigation, and behaviors accessible using WAI-ARIA roles, states, and properties. - This document is directed primarily to Web application developers, but the guidance is also useful for user agent and assistive technology developers. -

-

This document is part of the WAI-ARIA suite described in the WAI-ARIA Overview.

-
- -
-

- This is an editor's draft by the - Accessible Rich Internet Applications Working Group - of the - Web Accessibility Initiative. - It supports the - [[[wai-aria-1.2]]] [[WAI-ARIA-1.2]] - specification, providing detailed advice and examples beyond what would be appropriate to a technical specification but which are important to understand the specification. -

-

This draft includes only a portion of content planned for WAI-ARIA Authoring Practices 1.2. To see plans for the complete guide, review the Authoring Practices Milestone Plan.

-

- Feedback on the information provided here is essential to the ultimate success of Rich Internet Applications that afford full access to their information and operations. - The Accessible Rich Internet Applications Working Group asks in particular: -

- -

- To comment, - file an issue in the W3C ARIA Practices GitHub repository, - or if that is not possible, send email to - public-aria-practices@w3.org - (comment archive). -

-
- -
-

Introduction

-

- The ARIA Authoring Practices Guide (APG) explains how to create accessible web experiences for users of assistive technologies and keyboard interfaces by developing web sites that properly convey accessibility semantics and implement common keyboard conventions. - It also provides guidance on some closely related topics, such as supporting operating system settings for high contrast and reduced motion. -

-

- Accessibility semantics refer to the meaning of user interface elements that need to be conveyed to assistive technology users in order for those users to understand and use the elements. - For example, people who can visually perceive a search icon button understand the element can be activated to perform a search by the way it is styled and positioned. - To make that icon accessible to a screen reader user, one of the semantics that needs to be communicated is that the element represents an interactive button. - In addition, keyboard accessibility requires the button to be focusable, and keyboard conventions call for pressing Enter or Space to activate the button when it is focused. - The APG describes how to convey accessibility semantics and implement keyboard accessibility for many common design patterns, ranging from typical buttons and popup menus to complex tree grids. - It also explains essential practices related to these patterns, such as how to convey web page structure with ARIA landmark regions and effectively utilize the many ways of encoding accessible names. -

-

- The APG is organized into two major sections: patterns and practices. - Each pattern explains how to make a common user interface element, such as a button, menu, or dialog, accessible, and provides functional example implementations of the pattern. - The practices section gives in-depth explanation of how to satisfy a variety of accessibility needs that surface when making rich internet application experiences accessible. - For instance, the practices section on providing accessible names and descriptions gives detailed descriptions of seven different naming techniques as well as a table providing guidance for naming more than 80 types of elements. -

-

- The APG assumes basic understanding of web development, especially of HTML and CSS. - It may be particularly useful to designers and engineers who are working on site design systems and component libraries. - However, it is important to understand that the APG only covers a portion of what is needed to create accessible experiences. - To understand accessibility more broadly, it is advisable to start with the WAI Accessibility Fundamentals and WAI Overview of Design and Development. -

-

- The accessibility semantics used in the APG patterns and described in APG practices are defined in the - WAI-ARIA 1.2 Specification. - That is, the ARIA specification standardizes the meaning of the attributes that describe elements and their states to assistive technologies, such as the meaning of role="button". - These attributes and other features required to make sites usable by people who rely on assistive technologies or keyboard navigation are not natively included in the languages used to create web sites, such as HTML, JavaScript, CSS, and SVG. - The W3C Web Accessibility Initiative's (WAI) Accessible Rich Internet Applications working group (ARIA WG) is addressing these deficiencies through several W3C standards efforts. - The WAI-ARIA Overview - provides additional background on WAI-ARIA, summarizes those efforts, and lists the other documents included in the WAI-ARIA suite. -

-
- -
-

Read Me First

-
-

No ARIA is better than Bad ARIA

-

- Functionally, ARIA roles, states, and properties are analogous to a CSS for assistive technologies. - For screen reader users, ARIA controls the rendering of their non-visual experience. - Incorrect ARIA misrepresents visual experiences, with potentially devastating effects on their corresponding non-visual experiences. -

-

Before using ARIA or any of the guidance in this document, please take time to understand the following two essential principles.

-

Principle 1: A role is a promise

-

This code:

- 

-        <div role="button">Place Order</div>
-
-

- Is a promise that the author of that <div> has also incorporated JavaScript that provides the keyboard interactions expected for a button. - Unlike HTML input elements, ARIA roles do not cause browsers to provide keyboard behaviors or styling. -

-

Using a role without fulfilling the promise of that role is similar to making a "Place Order" button that abandons an order and empties the shopping cart.

-

One of the objectives of this guide is to define expected behaviors for each ARIA role.

-

Principle 2: ARIA Can Both Cloak and Enhance, Creating Both Power and Danger

-

- The information assistive technologies need about the meaning and purpose of user interface elements is called accessibility semantics. - From the perspective of assistive technologies, ARIA gives authors the ability to dress up HTML and SVG elements with critical accessibility semantics that the assistive technologies would not otherwise be able to reliably derive. -

-

Some of ARIA is like a cloak; it covers up, or overrides, the original semantics or content.

- 

-        <a role="menuitem">Assistive tech users perceive this element as an item in a menu, not a link.</a>
-        <a aria-label="Assistive tech users can only perceive the contents of this aria-label, not the link text">Link Text</a>
-
-

On the other hand, some uses of ARIA are more like suspenders or belts; they add meaning that provides essential support to the original content.

- 

-        <button aria-pressed="false">Mute</button>
-
-

- This is the power of ARIA. - It enables authors to describe nearly any user interface component in ways that assistive technologies can reliably interpret, thus making components accessible to assistive technology users. -

-

- This is also the danger of ARIA. - Authors can inadvertently override accessibility semantics. -

- 
-        
-          <table role="log">
-            <!--
-              Table that assistive technology users will not perceive as a table.
-              The log role tells browser this is a log, not a table.
-            -->
-          </table>
-          <ul role="navigation">
-            <!-- This is a navigation region, not a list. -->
-            <li><a href="uri1">nav link 1</li>
-            <li><a href="uri2">nav link 2</li>
-            <!-- ERROR! Previous list items are not in a list! -->
-          </ul>
-        
-
-
-
-

Browser and Assistive Technology Support

-

- Testing assistive technology interoperability is essential before using code from this guide in production. - Because the purpose of this guide is to illustrate appropriate use of ARIA 1.2 as defined in the ARIA specification, the design patterns, reference examples, and sample code intentionally do not describe and implement coding techniques for working around problems caused by gaps in support for ARIA 1.2 in browsers and assistive technologies. - It is thus advisable to test implementations thoroughly with each browser and assistive technology combination that is relevant within a target audience. -

-

- Similarly, JavaScript and CSS in this guide is written to be compatible with the most recent version of Chrome, Firefox, and Safari at the time of writing. -Some JavaScript and CSS may not function correctly in Internet Explorer. -

-

- Except in cases where the ARIA Working Group and other contributors have overlooked an error, - examples in this guide that do not function well in a particular browser or with a specific assistive technology are demonstrating browser or assistive technology bugs. - Browser and assistive technology developers can thus utilize code in this guide to help assess the quality of their support for ARIA 1.2. -

-
-
-

Mobile and Touch Support

-

- Currently, this guide does not indicate which examples are compatible with mobile browsers or touch interfaces. - While some of the examples include specific features that enhance mobile and touch support, some ARIA features are not supported in any mobile browser. - In addition, there is not yet a standardized approach for providing touch interactions that work across mobile browsers. -

-

More guidance about touch and mobile support is planned for future releases of the guide.

-
-
- -
-

Design Patterns and Widgets

-

This section demonstrates how to make common rich internet application patterns and widgets accessible by applying WAI-ARIA roles, states, and properties and implementing keyboard support.

-
-

Accordion (Sections With Show/Hide Functionality)

-

- An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content. - The headings function as controls that enable users to reveal or hide their associated sections of content. - Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page. -

-

Terms for understanding accordions include:

-
-
Accordion Header:
-
Label for or thumbnail representing a section of content that also serves as a control for showing, and in some implementations, hiding the section of content.
-
Accordion Panel:
-
Section of content associated with an accordion header.
-
-

- In some accordions, there are additional elements that are always visible adjacent to the accordion header. - For instance, a menubutton may accompany each accordion header to provide access to actions that apply to that section. - And, in some cases, a snippet of the hidden content may also be visually persistent. -

-
-

Example

-

Accordion Example: demonstrates a form divided into three sections using an accordion to show one section at a time.

-
-
-

Keyboard Interaction

-
    -
  • - Enter or Space: -
      -
    • - When focus is on the accordion header for a collapsed panel, expands the associated panel. - If the implementation allows only one panel to be expanded, and if another panel is expanded, collapses that panel. -
      • -
    • - When focus is on the accordion header for an expanded panel, collapses the panel if the implementation supports collapsing. - Some implementations require one panel to be expanded at all times and allow only one panel to be expanded; so, they do not support a collapse function. -
      • -
    -
    • -
  • Tab: Moves focus to the next focusable element; all focusable elements in the accordion are included in the page Tab sequence.
    • -
  • Shift + Tab: Moves focus to the previous focusable element; all focusable elements in the accordion are included in the page Tab sequence.
    • -
  • - Down Arrow (Optional): If focus is on an accordion header, moves focus to the next accordion header. - If focus is on the last accordion header, either does nothing or moves focus to the first accordion header. -
    • -
  • - Up Arrow (Optional): If focus is on an accordion header, moves focus to the previous accordion header. - If focus is on the first accordion header, either does nothing or moves focus to the last accordion header. -
    • -
  • - Home (Optional): When focus is on an accordion header, moves focus to the first accordion header. -
    • -
  • - End (Optional): When focus is on an accordion header, moves focus to the last accordion header. -
    • -
-
-
-

WAI-ARIA Roles, States, and Properties:

-
    -
  • - The title of each accordion header is contained in an element with role button. -
    • -
  • - Each accordion header button is wrapped in an element with role heading that has a value set for aria-level that is appropriate for the information architecture of the page. -
      -
    • If the native host language has an element with an implicit heading and aria-level, such as an HTML heading tag, a native host language element may be used.
      • -
    • - The button element is the only element inside the heading element. - That is, if there are other visually persistent elements, they are not included inside the heading element. -
      • -
    -
    • -
  • - If the accordion panel associated with an accordion header is visible, the header button element has aria-expanded set to true. - If the panel is not visible, aria-expanded is set to false. -
    • -
  • - The accordion header button element has aria-controls set to the ID of the element containing the accordion panel content. -
    • -
  • - If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true. -
    • -
  • - Optionally, each element that serves as a container for panel content has role - region and - aria-labelledby - with a value that refers to the button that controls display of the panel. -
      -
    • - Avoid using the region role in circumstances that create landmark region proliferation, - e.g., in an accordion that contains more than approximately 6 panels that can be expanded at the same time. -
      • -
    • - Role region is especially helpful to the perception of structure by screen reader users when panels contain heading elements or a nested accordion. -
      • -
    -
    • -
-
-
- -
-

Alert

-

- An alert is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. - Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound. - It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before page load completes. -

-

- Because alerts are intended to provide important and potentially time-sensitive information without interfering with the user's ability to continue working, - it is crucial they do not affect keyboard focus. - The alert dialog is designed for situations where interrupting work flow is necessary. -

-

- It is also important to avoid designing alerts that disappear automatically. - An alert that disappears too quickly can lead to failure to meet - WCAG 2.0 success criterion 2.2.3. - Another critical design consideration is the frequency of interruption caused by alerts. - Frequent interruptions inhibit usability for people with visual and cognitive disabilities, which makes meeting the requirements of - WCAG 2.0 success criterion 2.2.4 - more difficult. -

- -
-

Example

-

Alert Example

-
- -
-

Keyboard Interaction

-

Not applicable.

-
- -
-

WAI-ARIA Roles, States, and Properties

-

The widget has a role of alert.

-
-
- -
-

Alert and Message Dialogs

-

- An alert dialog is a modal dialog that interrupts the user's workflow to communicate an important message and acquire a response. - Examples include action confirmation prompts and error message confirmations. - The alertdialog role - enables assistive technologies and browsers to distinguish alert dialogs from other dialogs - so they have the option of giving alert dialogs special treatment, such as playing a system alert sound. -

- -
-

Example

-

Alert Dialog Example: A confirmation prompt that demonstrates an alert dialog.

-
- -
-

Keyboard Interaction

-

See the keyboard interaction section for the modal dialog pattern.

-
-
-

WAI-ARIA Roles, States, and Properties

-
    -
  • - The element that contains all elements of the dialog, including the alert - message and any dialog buttons, has role - alertdialog. -
    • -
  • - The element with role alertdialog has either: -
      -
    • - A value for - aria-labelledby - that refers to the element containing the title of the dialog if the - dialog has a visible label. -
      • -
    • - A value for - aria-label - if the dialog does not have a visible label. -
      • -
    -
    • -
  • - The element with role alertdialog has a value set for - aria-describedby - that refers to the element containing the alert message. -
    • -
-
-
- - - -
-

Button

-

- A button is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation. - A common convention for informing users that a button launches a dialog is to append "…" (ellipsis) to the button label, e.g., "Save as…". -

-

In addition to the ordinary button widget, WAI-ARIA supports 2 other types of buttons:

- -

- The types of actions performed by buttons are distinctly different from the function of a link (see link pattern). - It is important that both the appearance and role of a widget match the function it provides. - Nevertheless, elements occasionally have the visual style of a link but perform the action of a button. - In such cases, giving the element role button helps assistive technology users understand the function of the element. - However, a better solution is to adjust the visual design so it matches the function and ARIA role. -

- -
-

Examples

-
    -
  • Button Examples: Examples of clickable HTML div and span elements made into accessible command and toggle buttons.
    • -
  • Button Examples (IDL): Examples of clickable HTML div and span elements made into accessible command and toggle buttons. This example uses the IDL Interface.
    • -
-
- -
-

Keyboard Interaction

-

When the button has focus:

-
    -
  • - Space: Activates the button. -
    • -
  • - Enter: Activates the button. -
    • -
  • - Following button activation, focus is set depending on the type of action the button - performs. For example: -
      -
    • - If activating the button opens a dialog, the focus moves inside the dialog. (see - dialog pattern) -
      • -
    • If activating the button closes a dialog, focus typically returns to the - button that opened the dialog unless the function performed in the dialog context - logically leads to a different element. For example, activating a cancel button in a - dialog returns focus to the button that opened the dialog. However, if - the dialog were confirming the action of deleting the page from which it was - opened, the focus would logically move to a new context.
      • -
    • If activating the button does not dismiss the current context, then focus - typically remains on the button after activation, e.g., an Apply or - Recalculate button.
      • -
    • If the button action indicates a context change, such as move to next step in - a wizard or add another search criteria, then it is often appropriate to move focus to - the starting point for that action.
      • -
    • - If the button is activated with a shortcut key, the focus usually remains in - the context from which the shortcut key was activated. For example, if Alt - + U were assigned to an "Up" button that moves the currently focused - item in a list one position higher in the list, pressing Alt + U when the - focus is in the list would not move the focus from the list. -
      • -
    -
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The button has role of button.
    • -
  • - The button has an accessible label. - By default, the accessible name is computed from any text content inside the button element. - However, it can also be provided with aria-labelledby or aria-label. -
    • -
  • If a description of the button's function is present, the button element has aria-describedby set to the ID of the element containing the description.
    • -
  • When the action associated with a button is unavailable, the button has aria-disabled set to true.
    • -
  • - If the button is a toggle button, it has an aria-pressed state. - When the button is toggled on, the value of this state is true, and when toggled off, the state is false. -
    • -
-
-
- - - -
-

Checkbox

-

WAI-ARIA supports two types of checkbox widgets:

-
    -
  1. Dual-state: The most common type of checkbox, it allows the user to toggle between two choices -- checked and not checked.
    2. -
  2. Tri-state: This type of checkbox supports an additional third state known as partially checked.
    3. -
-

- One common use of a tri-state checkbox can be found in software installers where a single tri-state checkbox is used to represent and control the state of an entire group of install options. - And, each option in the group can be individually turned on or off with a dual state checkbox. -

- -

The user can use the tri-state checkbox to change all options in the group with a single action:

- - -
-

Examples

-
    -
  • - Checkbox (Two-State) Example: Demonstrates a simple 2-state checkbox. -
    • -
  • - Checkbox (Mixed-State) Example: - Demonstrates a checkbox that uses the mixed value for aria-checked to reflect and control checked states within a group of two-state HTML checkboxes contained in an HTML fieldset. -
    • -
-
- -
-

Keyboard Interaction

-

When the checkbox has focus, pressing the Space key changes the state of the checkbox.

-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The checkbox has role checkbox.
    • -
  • - The checkbox has an accessible label provided by one of the following: -
      -
    • Visible text content contained within the element with role checkbox.
      • -
    • A visible label referenced by the value of aria-labelledby set on the element with role checkbox.
      • -
    • aria-label set on the element with role checkbox.
      • -
    -
    • -
  • When checked, the checkbox element has state aria-checked set to true.
    • -
  • When not checked, it has state aria-checked set to false.
    • -
  • When partially checked, it has state aria-checked set to mixed.
    • -
  • If a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role group that has the property aria-labelledby set to the ID of the element containing the label.
    • -
  • If the presentation includes additional descriptive static text relevant to a checkbox or checkbox group, the checkbox or checkbox group has the property aria-describedby set to the ID of the element containing the description.
    • -
-
-
- -
-

Combobox

-

- A combobox is an input widget with an associated popup that enables users to select a value for the combobox from a collection of possible values. - In some implementations, the popup presents allowed values, while in other implementations, the popup presents suggested values, and users may either select one of the suggestions or type a value. - The popup may be a listbox, - grid, - tree, or - dialog. - Many implementations also include a third optional element -- a graphical Open button adjacent to the combobox, which indicates availability of the popup. - Activating the Open button displays the popup if suggestions are available. -

-

- The combobox pattern supports several optional behaviors. - The one that most shapes interaction is text input. - Some comboboxes allow users to type and edit text in the combobox and others do not. - If a combobox does not support text input, it is referred to as select-only, meaning the only way users can set a value is by selecting a value in the popup. - For example, in some browsers, an HTML select element with size="1" is presented to assistive technologies as a combobox. - Alternatively, if a combobox supports text input, it is referred to as editable. - An editable combobox may either allow users to input any arbitrary value, or it may restrict its value to a discrete set of allowed values, in which case typing input serves to filter suggestions presented in the popup. -

-

The popup is hidden by default, i.e., the default state is collapsed. The conditions that trigger expansion -- display of the popup --are specific to each implementation. Some possible conditions that trigger expansion include:

- -

Combobox widgets are useful for acquiring user input in either of two scenarios:

-
    -
  1. - The value must be one of a predefined set of allowed values, e.g., a location field must contain a valid location name. - Note that the listbox and menu button patterns are also useful in this scenario; differences between combobox and alternative patterns are described below. -
    2. -
  2. - An arbitrary value is allowed, but it is advantageous to suggest possible values to users. - For example, a search field may suggest similar or previous searches to save the user time. -
    3. -
-

- The nature of possible values presented by a popup and the way they are presented is called the autocomplete behavior. - Comboboxes can have one of four forms of autocomplete: -

-
    -
  1. - No autocomplete: The combobox is editable, and when the popup is triggered, the suggested values it contains are the same regardless of the characters typed in the combobox. - For example, the popup suggests a set of recently entered values, and the suggestions do not change as the user types. -
    2. -
  2. - List autocomplete with manual selection: When the popup is triggered, it presents suggested values. If the combobox is editable, the suggested values complete or logically correspond to the characters typed in the combobox. - The character string the user has typed will become the value of the combobox unless the user selects a value in the popup. -
    3. -
  3. - List autocomplete with automatic selection: The combobox is editable, and when the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the combobox, - and the first suggestion is automatically highlighted as selected. - The automatically selected suggestion becomes the value of the combobox when the combobox loses focus unless the user chooses a different suggestion or changes the character string in the combobox. -
    4. -
  4. - List with inline autocomplete: This is the same as list with automatic selection with one additional feature. - The portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the combobox. - The inline completion string is visually highlighted and has a selected state. -
    5. -
-

- If a combobox is editable and has any form of list autocomplete, the popup may appear and disappear as the user types. - For example, if the user types a two character string that triggers five suggestions to be displayed but then types a third character that forms a string that does not have any matching suggestions, - the popup may close and, if present, the inline completion string disappears. -

-

- Two other widgets that are also visually compact and enable users to make a single choice from a set of discrete choices are listbox and menu button. - One feature that distinguishes combobox from both listbox and menu button is that the user's choice can be presented as a value in an editable field, which gives users the ability to select some or all of the value for copying to the clipboard. - Comboboxes and menu buttons can be implemented so users can explore the set of allowed choices without losing a previously made choice. - That is, users can navigate the set of available choices in a combobox popup or menu and then press escape, which closes the popup or menu without changing previous input. - In contrast, navigating among options in a single-select listbox immediately changes its value, and Escape does not provide an undo mechanism. - Comboboxes and listboxes can be marked as required with aria-required="true", and they have an accessible name that is distinct from their value. - Thus, when assistive technology users focus either a combobox or listbox in its default state, they can perceive both a name and value for the widget. - However, a menu button cannot be marked required, and while it has an accessible name, it does not have a value so is not suitable for conveying the user's choice in its collapsed state. -

- -
-

Examples

- -
- -
-

Keyboard Interaction

-
    -
  • Tab: The combobox is in the page Tab sequence.
    • -
  • Note: The popup indicator icon or button (if present), the popup, and the popup descendants are excluded from the page Tab sequence.
    • -
-
Combobox Keyboard Interaction
-

When focus is in the combobox:

-
    -
  • Down Arrow: If the popup is available, moves focus into the popup: -
      -
    • If the autocomplete behavior automatically selected a suggestion before Down Arrow was pressed, focus is placed on the suggestion following the automatically selected suggestion.
      • -
    • Otherwise, places focus on the first focusable element in the popup.
      • -
    -
    • -
  • Up Arrow (Optional): If the popup is available, places focus on the last focusable element in the popup.
    • -
  • Escape: Dismisses the popup if it is visible. Optionally, if the popup is hidden before Escape is pressed, clears the combobox.
    • -
  • - Enter: If the combobox is editable and an autocomplete suggestion is selected in the popup, accepts the suggestion either by placing the input cursor at the end of the accepted value in the combobox or by performing a default action on the value. - For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the combobox so the user can add another recipient. -
    • -
  • Printable Characters: -
      -
    • If the combobox is editable, type characters in the combobox. Note that some implementations may regard certain characters as invalid and prevent their input.
      • -
    • If the combobox is not editable, optionally moves focus to a value that starts with the typed characters.
      • -
    -
    • -
  • If the combobox is editable, it supports standard single line text editing keys appropriate for the device platform (see note below).
    • -
  • Alt + Down Arrow (Optional): If the popup is available but not displayed, displays the popup without moving focus.
    • -
  • Alt + Up Arrow (Optional): If the popup is displayed: -
      -
    • If the popup contains focus, returns focus to the combobox.
      • -
    • Closes the popup.
      • -
    -
    • -
-
-

Standard single line text editing keys appropriate for the device platform:

-
    -
  1. include keys for input, cursor movement, selection, and text manipulation.
    2. -
  2. Standard key assignments for editing functions depend on the device operating system.
    3. -
  3. The most robust approach for providing text editing functions is to rely on browsers, which supply them for HTML inputs with type text and for elements with the contenteditable HTML attribute.
    4. -
  4. IMPORTANT: Ensure JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.
    5. -
-
-
Listbox Popup Keyboard Interaction
-

When focus is in a listbox popup:

-
    -
  • Enter: Accepts the focused option in the listbox by closing the popup, placing the accepted value in the combobox, and if the combobox is editable, placing the input cursor at the end of the value.
    • -
  • Escape: Closes the popup and returns focus to the combobox. Optionally, if the combobox is editable, clears the contents of the combobox.
    • -
  • Down Arrow: Moves focus to and selects the next option. If focus is on the last option, either returns focus to the combobox or does nothing.
    • -
  • Up Arrow: Moves focus to and selects the previous option. If focus is on the first option, either returns focus to the combobox or does nothing.
    • -
  • - Right Arrow: If the combobox is editable, returns focus to the combobox without closing the popup and moves the input cursor one character to the right. - If the input cursor is on the right-most character, the cursor does not move. -
    • -
  • - Left Arrow: If the combobox is editable, returns focus to the combobox without closing the popup and moves the input cursor one character to the left. - If the input cursor is on the left-most character, the cursor does not move. -
    • -
  • Home (Optional): Either moves focus to and selects the first option or, if the combobox is editable, returns focus to the combobox and places the cursor on the first character.
    • -
  • End (Optional): Either moves focus to the last option or, if the combobox is editable, returns focus to the combobox and places the cursor after the last character.
    • -
  • Any printable character: -
      -
    • If the combobox is editable, returns the focus to the combobox without closing the popup and types the character.
      • -
    • Otherwise, moves focus to the next option with a name that starts with the characters typed.
      • -
    -
    • -
  • Backspace (Optional): If the combobox is editable, returns focus to the combobox and deletes the character prior to the cursor.
    • -
  • Delete (Optional): If the combobox is editable, returns focus to the combobox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.
    • -
-
    -
  1. DOM Focus is maintained on the combobox and the assistive technology focus is moved within the listbox using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.
    2. -
  2. Selection follows focus in the listbox; the listbox allows only one suggested value to be selected at a time for the combobox value.
    3. -
-
Grid Popup Keyboard Interaction
-

- In a grid popup, each suggested value may be represented by either a single cell or an entire row. - See notes below for how this aspect of grid design effects the keyboard interaction design and the way that selection moves in response to focus movements. -

-
    -
  • Enter: Accepts the currently selected suggested value by closing the popup, placing the selected value in the combobox, and if the combobox is editable, placing the input cursor at the end of the value.
    • -
  • Escape: Closes the popup and returns focus to the combobox. Optionally, if the combobox is editable, clears the contents of the combobox.
    • -
  • - Right Arrow: Moves focus one cell to the right. - Optionally, if focus is on the right-most cell in the row, focus may move to the first cell in the following row. - If focus is on the last cell in the grid, either does nothing or returns focus to the combobox. -
    • -
  • - Left Arrow: Moves focus one cell to the left. - Optionally, if focus is on the left-most cell in the row, focus may move to the last cell in the previous row. - If focus is on the first cell in the grid, either does nothing or returns focus to the combobox. -
    • -
  • - Down Arrow: Moves focus one cell down. - If focus is in the last row of the grid, either does nothing or returns focus to the combobox. -
    • -
  • - Up Arrow: Moves focus one cell up. - If focus is in the first row of the grid, either does nothing or returns focus to the combobox. -
    • -
  • - Page Down (Optional): Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. - If focus is in the last row of the grid, focus does not move. -
    • -
  • - Page Up (Optional): Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. - If focus is in the first row of the grid, focus does not move. -
    • -
  • Home (Optional): Either: -
      -
    • Moves focus to the first cell in the row that contains focus. Or, if the grid has fewer than three cells per row or multiple suggested values per row, focus may move to the first cell in the grid.
      • -
    • If the combobox is editable, returns focus to the combobox and places the cursor on the first character.
      • -
    -
    • -
  • End (Optional): Either: -
      -
    • Moves focus to the last cell in the row that contains focus. Or, if the grid has fewer than three cells per row or multiple suggested values per row, focus may move to the last cell in the grid.
      • -
    • If the combobox is editable, returns focus to the combobox and places the cursor after the last character.
      • -
    -
    • -
  • Control + Home (optional): moves focus to the first row.
    • -
  • Control + End (Optional): moves focus to the last row.
    • -
  • Any printable character: If the combobox is editable, returns the focus to the combobox without closing the popup and types the character.
    • -
  • Backspace (Optional): If the combobox is editable, returns focus to the combobox and deletes the character prior to the cursor.
    • -
  • Delete (Optional): If the combobox is editable, returns focus to the combobox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.
    • -
-
    -
  1. DOM Focus is maintained on the combobox and the assistive technology focus is moved within the grid using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.
    2. -
  2. The grid allows only one suggested value to be selected at a time for the combobox value.
    3. -
  3. In a grid popup, each suggested value may be represented by either a single cell or an entire row. This aspect of design effects focus and selection movement: -
      -
    1. If every cell contains a different suggested value: -
        -
      • Selection follows focus so that the cell containing focus is selected.
        • -
      • Horizontal arrow key navigation typically wraps from one row to another.
        • -
      • Vertical arrow key navigation typically wraps from one column to another.
        • -
      -
      2. -
    2. If all cells in a row contain information about the same suggested value: -
        -
      • Either the row containing focus is selected or a cell containing a suggested value is selected when any cell in the same row contains focus.
        • -
      • Horizontal key navigation may wrap from one row to another.
        • -
      • Vertical arrow key navigation does not wrap from one column to another.
        • -
      -
      3. -
    -
    4. -
-
Tree Popup Keyboard Interaction
-

- In some implementations of tree popups, some or all parent nodes may serve as suggestion category labels so may not be selectable values. - See notes below for how this aspect of the design effects the way selection moves in response to focus movements. -

-

When focus is in a vertically oriented tree popup:

-
    -
  • Enter: Accepts the currently selected suggested value by closing the popup, placing the selected value in the combobox, and if the combobox is editable, placing the input cursor at the end of the value.
    • -
  • Escape: Closes the popup and returns focus to the combobox. Optionally, clears the contents of the combobox.
    • -
  • Right arrow: -
      -
    • When focus is on a closed node, opens the node; focus and selection do not move.
      • -
    • When focus is on a open node, moves focus to the first child node and selects it if it is selectable.
      • -
    • When focus is on an end node, does nothing.
      • -
    -
    • -
  • Left arrow: -
      -
    • When focus is on an open node, closes the node.
      • -
    • When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node and selects it if it is selectable.
      • -
    • When focus is on a root node that is also either an end node or a closed node, does nothing.
      • -
    -
    • -
  • Down Arrow: Moves focus to the next node that is focusable without opening or closing a node and selects it if it is selectable.
    • -
  • Up Arrow: Moves focus to the previous node that is focusable without opening or closing a node and selects it if it is selectable.
    • -
  • Home: Moves focus to the first focusable node in the tree without opening or closing a node and selects it if it is selectable.
    • -
  • End: Moves focus to the last focusable node in the tree without opening or closing a node and selects it if it is selectable.
    • -
  • Any printable character: -
      -
    • If the combobox is editable, returns the focus to the combobox without closing the popup and types the character.
      • -
    • Otherwise, moves focus to the next suggested value with a name that starts with the characters typed.
      • -
    -
    • -
-
    -
  1. DOM Focus is maintained on the combobox and the assistive technology focus is moved within the tree using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.
    2. -
  2. The tree allows only one suggested value to be selected at a time for the combobox value.
    3. -
  3. - In a tree popup, some or all parent nodes may not be selectable values; they may serve as category labels for suggested values. - If focus moves to a node that is not a selectable value, either: -
      -
    • The previously selected node, if any, remains selected until focus moves to a node that is selectable.
      • -
    • There is no selected value.
      • -
    • In either case, focus is visually distinct from selection so users can readily see if a value is selected or not.
      • -
    -
    4. -
  4. If nodes in the tree are arranged horizontally (aria-orientation is set to horizontal): -
      -
    1. Down Arrow performs as Right Arrow is described above, and vice versa.
      2. -
    2. Up Arrow performs as Left Arrow is described above, and vice versa.
      3. -
    -
    5. -
-
Dialog Popup Keyboard Interaction
-

When focus is in a dialog popup:

-
    -
  • There are two ways to close the popup and return focus to the combobox: -
      -
    1. Perform an action in the dialog, such as activate a button, that specifies a value for the combobox.
      2. -
    2. - Cancel out of the dialog, e.g., press Escape or activate the cancel button in the dialog. - Canceling either returns focus to the text box without changing the combobox value or returns focus to the combobox and clears the combobox. -
      3. -
    -
    • -
  • The dialog implements the keyboard interaction defined in the modal dialog pattern.
    • -
-

- Unlike other combobox popups, dialogs do not support aria-activedescendant so DOM focus moves into the dialog from the combobox. -

-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element that serves as an input and displays the combobox value has role combobox.
    • -
  • - The combobox element has aria-controls set to a value that refers to the element that serves as the popup. - Note that aria-controls only needs to be set when the popup is visible. However, it is valid to reference an element that is not visible. -
    • -
  • The popup is an element that has role listbox, tree, grid, or dialog.
    • -
  • - If the popup has a role other than listbox, the element with role combobox has aria-haspopup set to a value that corresponds to the popup type. - That is, aria-haspopup is set to grid, tree, or dialog. - Note that elements with role combobox have an implicit aria-haspopup value of listbox. -
    • -
  • - When the combobox popup is not visible, the element with role combobox has aria-expanded set to false. - When the popup element is visible, aria-expanded is set to true. - Note that elements with role combobox have a default value for aria-expanded of false. -
    • -
  • When a combobox receives focus, DOM focus is placed on the combobox element.
    • -
  • When a descendant of a listbox, grid, or tree popup is focused, DOM focus remains on the combobox and the combobox has aria-activedescendant set to a value that refers to the focused element within the popup.
    • -
  • For a combobox that controls a listbox, grid, or tree popup, when a suggested value is visually indicated as the currently selected value, the option, gridcell, row, or treeitem containing that value has aria-selected set to true.
    • -
  • - If the combobox has a visible label and the combobox element is an HTML element that can be labelled using the HTML label element (e.g., the input element), it is labeled using the label element. - Otherwise, if it has a visible label, the combobox element has aria-labelledby set to a value that refers to the labelling element. - Otherwise, the combobox element has a label provided by aria-label. -
    • -
  • The combobox element has aria-autocomplete set to a value that corresponds to its autocomplete behavior: -
      -
    • none: When the popup is displayed, the suggested values it contains are the same regardless of the characters typed in the combobox.
      • -
    • list: When the popup is triggered, it presents suggested values. If the combobox is editable, the values complete or logically correspond to the characters typed in the combobox.
      • -
    • - both: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the combobox. - In addition, the portion of the selected suggestion that has not been typed by the user, known as the completion string, appears inline after the input cursor in the combobox. - The inline completion string is visually highlighted and has a selected state. -
      • -
    -
    • -
-
-
    -
  1. - In ARIA 1.0, the combobox referenced its popup with aria-owns instead of aria-controls. - While user agents might support comboboxes with aria-owns for backwards compatibility with legacy content, it is strongly recommended that authors use aria-controls. -
    2. -
  2. When referring to the roles, states, and properties documentation for the below list of patterns used for popups, keep in mind that a combobox is a single-select widget where selection follows focus in the popup.
    3. -
  3. The roles, states, and properties for popup elements are defined in their respective design patterns: - -
    4. -
-
-
-
- -
-

Dialog (Modal)

-

- A dialog is a window overlaid on either the primary window or another dialog window. - Windows under a modal dialog are inert. - That is, users cannot interact with content outside an active dialog window. - Inert content outside an active dialog is typically visually obscured or dimmed so it is difficult to discern, - and in some implementations, attempts to interact with the inert content cause the dialog to close. -

-

- Like non-modal dialogs, modal dialogs contain their tab sequence. - That is, Tab and Shift + Tab do not move focus outside the dialog. - However, unlike most non-modal dialogs, modal dialogs do not provide means for moving keyboard focus outside the dialog window without closing the dialog. -

-

- The alertdialog role is a special-case dialog role - designed specifically for dialogs that divert users' attention to a brief, important message. - Its usage is described in the alert dialog design pattern. -

- -
-

Examples

- -
- -
-

Keyboard Interaction

-

In the following description, the term tabbable element refers to any element with a tabindex value of zero or greater. Note that values greater than 0 are strongly discouraged.

-
    -
  • When a dialog opens, focus moves to an element inside the dialog. See notes below regarding initial focus placement.
    • -
  • Tab: -
      -
    • Moves focus to the next tabbable element inside the dialog.
      • -
    • If focus is on the last tabbable element inside the dialog, moves focus to the first tabbable element inside the dialog.
      • -
    -
    • -
  • Shift + Tab: -
      -
    • Moves focus to the previous tabbable element inside the dialog.
      • -
    • If focus is on the first tabbable element inside the dialog, moves focus to the last tabbable element inside the dialog.
      • -
    -
    • -
  • Escape: Closes the dialog.
    • -
-
    -
  1. When a dialog opens, focus moves to an element contained in the dialog. Generally, focus is initially set on the first focusable element. However, the most appropriate focus placement will depend on the nature and size of the content. Examples include: -
      -
    • - If the dialog content includes semantic structures, such as lists, tables, or multiple paragraphs, that need to be perceived in order to easily understand the content, i.e., if the content would be difficult to understand when announced as a single unbroken string, then it is advisable to add tabindex="-1" to a static element at the start of the content and initially focus that element. - This makes it easier for assistive technology users to read the content by navigating the semantic structures. - Additionally, it is advisable to omit applying aria-describedby to the dialog container in this scenario. -
      • -
    • 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. -
      • -
    -
    2. -
  2. - 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: -
        -
      1. It is very unlikely users need to immediately re-invoke the dialog.
        2. -
      2. The task completed in the dialog is directly related to a subsequent step in the work flow.
        3. -
      - 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. -
      • -
    -
    3. -
  3. 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.
    4. -
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element that serves as the dialog container has a role of dialog.
    • -
  • All elements required to operate the dialog are descendants of the element that has role dialog.
    • -
  • The dialog container element has aria-modal set to true.
    • -
  • 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, which is typically helpful only when the descriptive content is simple and can easily be understood without structural information. - It is advisable to omit specifying aria-describedby if the dialog content includes semantic structures, such as lists, tables, or multiple paragraphs, that need to be perceived in order to easily understand the content, i.e., if the content would be difficult to understand when announced as a single unbroken string. -
    • -
-
    -
  • - Because marking a dialog modal by setting - aria-modal - to true can prevent users of some assistive technologies from perceiving content outside the dialog, - users of those technologies will experience severe negative ramifications if a dialog is marked modal but does not behave as a modal for other users. - So, mark a dialog modal only when both: -
      -
    1. Application code prevents all users from interacting in any way with content outside of it.
      2. -
    2. Visual styling obscures the content outside of it.
      3. -
    -
    • -
  • - The aria-modal property introduced by ARIA 1.1 replaces - aria-hidden - for informing assistive technologies that content outside a dialog is inert. - However, in legacy dialog implementations where aria-hidden is used to make content outside a dialog inert for assistive technology users, it is important that: -
      -
    1. aria-hidden is set to true on each element containing a portion of the inert layer.
      2. -
    2. The dialog element is not a descendant of any element that has aria-hidden set to true.
      3. -
    -
    • -
-
-
- -
-

Disclosure (Show/Hide)

-

- A disclosure is a widget that enables content to be either collapsed (hidden) or expanded (visible). - It has two elements: a disclosure button and a section of content whose visibility is controlled by the button. - When the controlled content is hidden, the button is often styled as a typical push button with a right-pointing arrow or triangle to hint that activating the button will display additional content. - When the content is visible, the arrow or triangle typically points down. -

- -
-

Examples

- -
- -
-

Keyboard Interaction

-

When the disclosure control has focus:

-
    -
  • Enter: activates the disclosure control and toggles the visibility of the disclosure content.
    • -
  • Space: activates the disclosure control and toggles the visibility of the disclosure content.
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element that shows and hides the content has role button.
    • -
  • - When the content is visible, the element with role button has - aria-expanded - set to true. - When the content area is hidden, it is set to false. -
    • -
  • - Optionally, the element with role button has a value specified for - aria-controls - that refers to the element that contains all the content that is shown or hidden. -
    • -
- -
-
- -
-

Feed

-

- A feed is a section of a page that automatically loads new sections of content as the user scrolls. - The sections of content in a feed are presented in article elements. - So, a feed can be thought of as a dynamic list of articles that often appears to scroll infinitely. -

-

- The feature that most distinguishes feed from other ARIA patterns that support loading data as users scroll, e.g., a grid, is that a feed is a structure, not a widget. - Consequently, assistive technologies with a reading mode, such as screen readers, default to reading mode when interacting with feed content. - However, unlike most other WAI-ARIA structures, a feed establishes an interoperability contract between the web page and assistive technologies. - The contract governs scroll interactions so that assistive technology users can read articles, jump forward and backward by article, and reliably trigger new articles to load while in reading mode. -

-

- For example, a product page on a shopping site may have a related products section that displays five products at a time. - As the user scrolls, more products are requested and loaded into the DOM. - While a static design might include a next button for loading five more products, a dynamic implementation that automatically loads more data as the user scrolls simplifies the user experience and reduces the inertia associated with viewing more than the first five product suggestions. - But, unfortunately when web pages load content dynamically based on scroll events, it can cause usability and interoperability difficulties for users of assistive technologies. -

-

- The feed pattern enables reliable assistive technology reading mode interaction by establishing the following interoperability agreement between the web page and assistive technologies: -

-
    -
  1. In the context of a feed, the web page code is responsible for: -
      -
    • - Appropriate visual scrolling of the content based on which article contains DOM focus. -
      • -
    • Loading or removing feed articles based on which article contains DOM focus.
      • -
    -
    2. -
  2. In the context of a feed, assistive technologies with a reading mode are responsible for: -
      -
    • Indicating which article contains the reading cursor by ensuring the article element or one of its descendants has DOM focus.
      • -
    • providing reading mode keys that move DOM focus to the next and previous articles.
      • -
    • Providing reading mode keys for moving the reading cursor and DOM focus past the end and before the start of the feed.
      • -
    -
    3. -
-

- Thus, implementing the feed pattern allows a screen reader to reliably read and trigger the loading of feed content while staying in its reading mode. -

-

- Another feature of the feed pattern is its ability to facilitate skim reading for assistive technology users. - Web page authors may provide both an accessible name and description for each article. - By identifying the elements inside of an article that provide the title and the primary content, assistive technologies can provide functions that enable users to jump from article to article and efficiently discern which articles may be worthy of more attention. -

- -
-

Example

-

- Example Implementation of Feed Pattern -

-
- -
-

Keyboard Interaction

-

- The feed pattern is not based on a desktop GUI widget so the feed role is not associated with any well-established keyboard conventions. - Supporting the following, or a similar, interface is recommended. -

-

When focus is inside the feed:

-
    -
  • Page Down: Move focus to next article.
    • -
  • Page Up: Move focus to previous article.
    • -
  • Control + End: Move focus to the first focusable element after the feed.
    • -
  • Control + Home: Move focus to the first focusable element before the feed.
    • -
-
    -
  1. Due to the lack of convention, providing easily discoverable keyboard interface documentation is especially important.
    2. -
  2. - In some cases, a feed may contain a nested feed. - For example, an article in a social media feed may contain a feed of comments on that article. - To navigate the nested feed, users first move focus inside the nested feed. - Options for supporting nested feed navigation include: -
      -
    • - Users move focus into the nested feed from the content of the containing article with Tab. - This may be slow if the article contains a significant number of links, buttons, or other widgets. -
      • -
    • Provide a key for moving focus from the elements in the containing article to the first item in the nested feed, e.g., Alt + Page Down.
      • -
    • To continue reading the outer feed, Control + End moves focus to the next article in the outer feed.
      • -
    -
    3. -
  3. In the rare circumstance that a feed article contains a widget that uses the above suggested keys, the feed navigation key will operate the contained widget, and the user needs to move focus to an element that does not utilize the feed navigation keys in order to navigate the feed.
    4. -
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element that contains the set of feed articles has role feed.
    • -
  • - If the feed has a visible label, the feed element has aria-labelledby referring to the element containing the title. - Otherwise, the feed element has a label specified with aria-label. -
    • -
  • - Each unit of content in a feed is contained in an element with role article. - All content inside the feed is contained in an article element. -
    • -
  • - Each article element has - aria-labelledby - referring to elements inside the article that can serve as a distinguishing label. -
    • -
  • - It is optional but strongly recommended for each article element to have - aria-describedby - referring to one or more elements inside the article that serve as the primary content of the article. -
    • -
  • - Each article element has - aria-posinset - set to a value that represents its position in the feed. -
    • -
  • - Each article element has - aria-setsize - set to a value that represents either the total number of articles that have been loaded or the total number in the feed, - depending on which value is deemed more helpful to users. - If the total number in the feed is undetermined, it can be represented by a aria-setsize value of -1. -
    • -
  • - When article elements are being added to or removed from the feed container, - and if the operation requires multiple DOM operations, - the feed element has - aria-busy - set to true during the update operation. - Note that it is extremely important that aria-busy is set to false when the operation is complete or the changes may not become visible to some assistive technology users. -
    • -
-
-
- -
-

Grids : Interactive Tabular Data and Layout Containers

- -

- A grid widget is a container that enables users to navigate the information or interactive elements it contains using directional navigation keys, such as arrow keys, Home, and End. - As a generic container widget that offers flexible keyboard navigation, it can serve a wide variety of needs. - It can be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application. - While the words "row" and "column" are used in the names of WAI-ARIA attributes and by assistive technologies when describing and presenting the logical structure of elements with the grid role, using the grid role on an element does not necessarily imply that its visual presentation is tabular. -

- -

When presenting content that is tabular, consider the following factors when choosing between implementing this grid pattern or the table pattern.

- - - -

- Uses of the grid pattern broadly fall into two categories: presenting tabular information (data grids) and grouping other widgets (layout grids). - Even though both data grids and layout grids employ the same ARIA roles, states, and properties, differences in their content and purpose surface factors that are important to consider in keyboard interaction design. - To address these factors, the following two sections describe separate keyboard interaction patterns for data and layout grids. -

- -
-

Examples

-
    -
  • Layout Grid Examples: Three example implementations of grids that are used to lay out widgets, including a collection of navigation links, a message recipients list, and a set of search results.
    • -
  • Data Grid Examples: Three example implementations of grid that include features relevant to presenting tabular information, such as content editing, sort, and column hiding.
    • -
  • Advanced Data Grid Example: Example of a grid with behaviors and features similar to a typical spreadsheet, including cell and row selection.
    • -
-
- -
-

Data Grids For Presenting Tabular Information

-

- A grid can be used to present tabular information that has column titles, row titles, or both. - The grid pattern is particularly useful if the tabular information is editable or interactive. - For example, when data elements are links to more information, rather than presenting them in a static table and including the links in the tab sequence, implementing the grid pattern provides users with intuitive and efficient keyboard navigation of the grid contents as well as a shorter tab sequence for the page. - A grid may also offer functions, such as cell content editing, selection, cut, copy, and paste. -

-

- In a grid, every cell contains a focusable element or is itself focusable, regardless of whether the cell content is editable or interactive. - There is one exception: if column or row header cells do not provide functions, such as sort or filter, they do not need to be focusable. - One reason it is important for all cells to be able to receive or contain keyboard focus is that screen readers will typically be in their application reading mode, rather than their document reading mode, when users are interacting with the grid. - While in application mode, a screen reader user hears only focusable elements and content that labels focusable elements. - So, screen reader users may unknowingly overlook elements contained in a grid that are either not focusable or not used to label a column or row. -

-
-
Keyboard Interaction For Data Grids
-

- The following keys provide grid navigation by moving focus among cells of the grid. - Implementations of grid make these key commands available when an element in the grid has received focus, e.g., after a user has moved focus to the grid with Tab. -

-
    -
  • - Right Arrow: Moves focus one cell to the right. - If focus is on the right-most cell in the row, focus does not move. -
    • -
  • Left Arrow: Moves focus one cell to the left. If focus is on the left-most cell in the row, focus does not move.
    • -
  • Down Arrow: Moves focus one cell down. If focus is on the bottom cell in the column, focus does not move.
    • -
  • Up Arrow: Moves focus one cell Up. If focus is on the top cell in the column, focus does not move.
    • -
  • Page Down: Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row of the grid, focus does not move.
    • -
  • Page Up: Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row of the grid, focus does not move.
    • -
  • Home: moves focus to the first cell in the row that contains focus.
    • -
  • End: moves focus to the last cell in the row that contains focus.
    • -
  • Control + Home: moves focus to the first cell in the first row.
    • -
  • Control + End: moves focus to the last cell in the last row.
    • -
-
    -
  • - When the above grid navigation keys move focus, whether the focus is set on an element inside the cell or the grid cell depends on cell content. - See Whether to Focus on a Cell or an Element Inside It. -
    • -
  • - While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell. - If this functionality is needed, see Editing and Navigating Inside a Cell. -
    • -
  • If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as control + End, may move focus to the last row in the DOM rather than the last available row in the back-end data.
    • -
-

If a grid supports selection of cells, rows, or columns, the following keys are commonly used for these functions.

-
    -
  • Control + Space: selects the column that contains the focus.
    • -
  • Shift + Space: Selects the row that contains the focus. If the grid includes a column with checkboxes for selecting rows, this key can serve as a shortcut for checking the box when focus is not on the checkbox.
    • -
  • Control + A: Selects all cells.
    • -
  • Shift + Right Arrow: Extends selection one cell to the right.
    • -
  • Shift + Left Arrow: Extends selection one cell to the left.
    • -
  • Shift + Down Arrow: Extends selection one cell down.
    • -
  • Shift + Up Arrow: Extends selection one cell Up.
    • -
-

See for cut, copy, and paste key assignments.

-
-
- -
-

Layout Grids for Grouping Widgets

- -

- The grid pattern can be used to group a set of interactive elements, such as links, buttons, or checkboxes. - Since only one element in the entire grid is included in the tab sequence, grouping with a grid can dramatically reduce the number of tab stops on a page. - This is especially valuable if scrolling through a list of elements dynamically loads more of those elements from a large data set, such as in a continuous list of suggested products on a shopping site. - If elements in a list like this were in the tab sequence, keyboard users are effectively trapped in the list. - If any elements in the group also have associated elements that appear on hover, the grid pattern is also useful for providing keyboard access to those contextual elements of the user interface. -

- -

- Unlike grids used to present data, A grid used for layout does not necessarily have header cells for labelling rows or columns and might contain only a single row or a single column. - Even if it has multiple rows and columns, it may present a single, logically homogenous set of elements. - For example, a list of recipients for a message may be a grid where each cell contains a link that represents a recipient. - The grid may initially have a single row but then wrap into multiple rows as recipients are added. - In such circumstances, grid navigation keys may also wrap so the user can read the list from beginning to end by pressing either Right Arrow or Down Arrow. - While This type of focus movement wrapping can be very helpful in a layout grid, it would be disorienting if used in a data grid, especially for users of assistive technologies. -

- -

Because arrow keys are used to move focus inside of a grid, a grid is both easier to build and use if the components it contains do not require the arrow keys to operate. If a cell contains an element like a listbox, then an extra key command to focus and activate the listbox is needed as well as a command for restoring the grid navigation functionality. Approaches to supporting this need are described in the section on Editing and Navigating Inside a Cell.

- -
-
Keyboard Interaction For Layout Grids
-

- The following keys provide grid navigation by moving focus among cells of the grid. - Implementations of grid make these key commands available when an element in the grid has received focus, e.g., after a user has moved focus to the grid with Tab. -

-
    -
  • - Right Arrow: Moves focus one cell to the right. - Optionally, if focus is on the right-most cell in the row, focus may move to the first cell in the following row. - If focus is on the last cell in the grid, focus does not move. -
    • -
  • - Left Arrow: Moves focus one cell to the left. - Optionally, if focus is on the left-most cell in the row, focus may move to the last cell in the previous row. - If focus is on the first cell in the grid, focus does not move. -
    • -
  • - Down Arrow: Moves focus one cell down. - Optionally, if focus is on the bottom cell in the column, focus may move to the top cell in the following column. - If focus is on the last cell in the grid, focus does not move. -
    • -
  • - Up Arrow: Moves focus one cell up. - Optionally, if focus is on the top cell in the column, focus may move to the bottom cell in the previous column. - If focus is on the first cell in the grid, focus does not move. -
    • -
  • - Page Down (Optional): Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. - If focus is in the last row of the grid, focus does not move. -
    • -
  • - Page Up (Optional): Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. - If focus is in the first row of the grid, focus does not move. -
    • -
  • - Home: moves focus to the first cell in the row that contains focus. - Optionally, if the grid has a single column or fewer than three cells per row, focus may instead move to the first cell in the grid. -
    • -
  • - End: moves focus to the last cell in the row that contains focus. - Optionally, if the grid has a single column or fewer than three cells per row, focus may instead move to the last cell in the grid. -
    • -
  • Control + Home (optional): moves focus to the first cell in the first row.
    • -
  • Control + End (Optional): moves focus to the last cell in the last row.
    • -
-
    -
  • - When the above grid navigation keys move focus, whether the focus is set on an element inside the cell or the grid cell depends on cell content. - See Whether to Focus on a Cell or an Element Inside It. -
    • -
  • - While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell. - If this functionality is needed, see Editing and Navigating Inside a Cell. -
    • -
  • If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as control + End, may move focus to the last row in the DOM rather than the last available row in the back-end data.
    • -
- -

It would be unusual for a layout grid to provide functions that require cell selection. If it did, though, the following keys are commonly used for these functions.

- -
    -
  • Control + Space: selects the column that contains the focus.
    • -
  • - Shift + Space: Selects the row that contains the focus. - If the grid includes a column with checkboxes for selecting rows, this key can serve as a shortcut for checking the box when focus is not on the checkbox. -
    • -
  • Control + A: Selects all cells.
    • -
  • Shift + Right Arrow: Extends selection one cell to the right.
    • -
  • Shift + Left Arrow: Extends selection one cell to the left.
    • -
  • Shift + Down Arrow: Extends selection one cell down.
    • -
  • Shift + Up Arrow: Extends selection one cell Up.
    • -
-

See for cut, copy, and paste key assignments.

-
-
- -
-

Keyboard Interaction - Setting Focus and Navigating Inside Cells

-

This section describes two important aspects of keyboard interaction design shared by both data and layout grid patterns:

- -
    -
  1. Choosing whether a cell or an element inside a cell receives focus in response to grid navigation key events.
    2. -
  2. Enabling grid navigation keys to be used to interact with elements inside of a cell.
    3. -
- -
-
Whether to Focus on a Cell Or an Element Inside It
- -

- For assistive technology users, the quality of experience when navigating a grid heavily depends on both what a cell contains and on where keyboard focus is set. - For example, if a cell contains a button and a grid navigation key places focus on the cell instead of the button, screen readers announce the button label but do not tell users a button is present. -

- -

There are two optimal cell design and focus behavior combinations:

- -
    -
  1. - A cell contains one widget whose operation does not require arrow keys and grid navigation keys set focus on that widget. - Examples of such widgets include link, button, menubutton, toggle button, radio button (not radio group), switch, and checkbox. -
    2. -
  2. A cell contains text or a single graphic and grid navigation keys set focus on the cell.
    3. -
- -

- While any combination of widgets, text, and graphics may be included in a single cell, grids that do not follow one of these two cell design and focus movement patterns add complexity for authors or users or both. - The reference implementations included in the example section below demonstrate some strategies for making other cell designs as accessible as possible, but the most widely accessible experiences are likely to come by applying the above two patterns. -

-
- -
-
Editing and Navigating Inside a Cell
- -

- While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to perform actions like operate a combobox or move an editing caret inside of a cell. The user may need keys that are used for grid navigation to operate - elements inside a cell if a cell contains: -

- -
    -
  1. Editable content.
    2. -
  2. Multiple widgets.
    3. -
  3. A widget that utilizes arrow keys in its interaction model, such as a radio group or slider.
    4. -
- -

Following are common keyboard conventions for disabling and restoring grid navigation functions.

- -
    -
  • - Enter: Disables grid navigation and: -
      -
    • If the cell contains editable content, places focus in an input field, such as a textbox. If the input is a single-line text field, a subsequent press of Enter may either restore grid navigation - functions or move focus to an input field in a neighboring cell.
      • -
    • If the cell contains one or more widgets, places focus on the first widget.
      • -
    -
    • - -
  • - F2: -
      -
    • If the cell contains editable content, places focus in an input field, such as a textbox. A subsequent press of F2 restores grid navigation functions.
      • -
    • If the cell contains one or more widgets, places focus on the first widget. A subsequent press of F2 restores grid navigation functions.
      • -
    -
    • - -
  • Alphanumeric keys: If the cell contains editable content, places focus in an input field, such as a textbox.
    • -
- -

When grid navigation is disabled, conventional changes to navigation behaviors include:

- -
    -
  • Escape: restores grid navigation. If content was being edited, it may also undo edits.
    • -
  • - Right Arrow or Down Arrow: If the cell contains multiple widgets, moves focus to the next widget inside the cell, optionally wrapping to the first widget if focus is on the last widget. - Otherwise, passes the key event to the focused widget. -
    • -
  • - Left Arrow or Up Arrow: If the cell contains multiple widgets, moves focus to the previous widget inside the cell, optionally wrapping to the first widget if focus is on the last widget. - Otherwise, passes the key event to the focused widget. -
    • -
  • - Tab: moves focus to the next widget in the grid. - Optionally, the focus movement may wrap inside a single cell or within the grid itself. -
    • -
  • - Shift + Tab: moves focus to the previous widget in the grid. - Optionally, the focus movement may wrap inside a single cell or within the grid itself. -
    • -
-
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The grid container has role grid.
    • -
  • Each row container has role row and is either a DOM descendant of or owned by the grid element or an element with role rowgroup.
    • -
  • Each cell is either a DOM descendant of or owned by a row element and has one of the following roles: -
      -
    • columnheader if the cell contains a title or header information for the column.
      • -
    • rowheader if the cell contains title or header information for the row.
      • -
    • gridcell if the cell does not contain column or row header information.
      • -
    -
    • -
  • - If there is an element in the user interface that serves as a label for the grid, aria-labelledby is set on the grid element with a value that refers to the labelling element. - Otherwise, a label is specified for the grid element using aria-label. -
    • -
  • If the grid has a caption or description, aria-describedby is set on the grid element with a value referring to the element containing the description.
    • -
  • If the grid provides sort functions, aria-sort is set to an appropriate value on the header cell element for the sorted column or row as described in the section on grid and table properties.
    • -
  • - If the grid supports selection, when a cell or row is selected, the selected element has aria-selected set true. - If the grid supports column selection and a column is selected, all cells in the column have aria-selected set to true. -
    • -
  • - If the grid provides content editing functionality and contains cells that may have edit capabilities disabled in certain conditions, aria-readonly may be set true on cells where editing is disabled. - If edit functions are disabled for all cells, aria-readonly may be set true on the grid element. - Grids that do not provide editing functions do not include the aria-readonly attribute on any of their elements. -
    • -
  • - If there are conditions where some rows or columns are hidden or not present in the DOM, e.g., data is dynamically loaded when scrolling or the grid provides functions for hiding rows or columns, the following properties are applied as described in the section on grid and table properties. - -
    • -
  • If the grid includes cells that span multiple rows or multiple columns, and if the grid role is NOT applied to an HTML table element, then aria-rowspan or aria-colspan is applied as described in grid and table properties.
    • -
- -
    -
  • - If the element with the grid role is an HTML table element, then it is not necessary to use ARIA roles for rows and cells because the HTML elements have implied ARIA semantics. - For example, an HTML <TR> has an implied ARIA role of row. - A grid built from an HTML table that includes cells that span multiple rows or columns must use HTML rowspan and colspan and must not use aria-rowspan or aria-colspan. -
    • -
  • - If rows or cells are included in a grid via aria-owns, - they will be presented to assistive technologies after the DOM descendants of the grid element unless the DOM descendants are also included in the aria-owns attribute. -
    • -
-
-
- - - -
-

Listbox

-

- A listbox widget presents a list of options and allows a user to select one or more of them. - A listbox that allows a single option to be chosen is a single-select listbox; one that allows multiple options to be selected is a multi-select listbox. -

-

- When screen readers present a listbox, they may render the name, state, and position of each option in the list. - The name of an option is a string calculated by the browser, typically from the content of the option element. - As a flat string, the name does not contain any semantic information. - Thus, if an option contains a semantic element, such as a heading, screen reader users will not have access to the semantics. - In addition, the interaction model conveyed by the listbox role to assistive technologies does not support interacting with elements inside of an option. - Because of these traits of the listbox widget, it does not provide an accessible way to present a list of interactive elements, such as links, buttons, or checkboxes. - To present a list of interactive elements, see the grid pattern. -

-

- Avoiding very long option names facilitates understandability and perceivability for screen reader users. - The entire name of an option is spoken as a single unit of speech when the option is read. - When too much information is spoken as the result of a single key press, it is difficult to understand. - Long names inhibit perception by increasing the impact of interrupted speech because users typically have to re-read the entire option. - And, if the user does not understand what is spoken, reading the name by character, word, or phrase may be a difficult operation for many screen reader users in the context of a listbox widget. -

-

- Sets of options where each option name starts with the same word or phrase can also significantly degrade usability for keyboard and screen reader users. - Scrolling through the list to find a specific option becomes inordinately time consuming for a screen reader user who must listen to that word or phrase repeated before hearing what is unique about each option. - For example, if a listbox for choosing a city were to contain options where each city name were preceded by a country name, and if many cities were listed for each country, a screen reader user would have to listen to the country name before hearing each city name. - In such a scenario, it would be better to have 2 list boxes, one for country and one for city. -

- -
-

Examples

- -
- -
-

Keyboard Interaction

-

For a vertically oriented listbox:

-
    -
  • 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.
      • -
    -
    • -
  • 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.
      • -
    -
    • -
  • 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 (Optional): 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 (Optional): 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.
    • -
  • 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.
      • -
    -
    • -
  • Multiple Selection: - Authors may implement either of two interaction models to support multiple selection: - a recommended model that does not require the user to hold a modifier key, such as Shift or Control, while navigating the list - or an alternative model that does require modifier keys to be held while navigating in order to avoid losing selection states. -
      -
    • Recommended selection model -- holding modifier keys is not necessary: -
        -
      • 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.
        • -
      -
      • -
    • Alternative selection model -- moving focus without holding a Shift or Control modifier unselects all selected options except the focused option: -
        -
      • Shift + Down Arrow: Moves focus to and toggles the selection state of the next option.
        • -
      • Shift + Up Arrow: Moves focus to and toggles the selection state of the previous option.
        • -
      • Control + Down Arrow: Moves focus to the next option without changing its selection state.
        • -
      • Control + Up Arrow: Moves focus to the previous option without changing its selection state.
        • -
      • Control + Space Changes the selection state of the focused 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.
        • -
      -
      • -
    -
    • -
-
    -
  1. DOM focus (the active element) is functionally distinct from the selected state. For more details, see this description of differences between focus and selection.
    2. -
  2. - The listbox role supports the aria-activedescendant property, - which provides an alternative to moving DOM focus among option elements when implementing keyboard navigation. - For details, see Managing Focus in Composites Using aria-activedescendant. -
    3. -
  3. - In a single-select listbox, moving focus may optionally unselect the previously selected option and select the newly focused option. - This model of selection is known as "selection follows focus". - Having selection follow focus can be very helpful in some circumstances and can severely degrade accessibility in others. - For additional guidance, see Deciding When to Make Selection Automatically Follow Focus. -
    4. -
  4. If selecting or unselecting all options is an important function, implementing separate controls for these actions, such as buttons for "Select All" and "Unselect All", significantly improves accessibility.
    5. -
  5. - If the options in a listbox are arranged horizontally: -
      -
    1. Down Arrow performs as Right Arrow is described above, and vice versa.
      2. -
    2. Up Arrow performs as Left Arrow is described above, and vice versa.
      3. -
    -
    6. -
-
- -
-

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 contained in or owned by either: -
      -
    • The element with role listbox.
      • -
    • An element with role group that is contained in or owned by the element with role listbox.
      • -
    -
    • -
  • - Options contained in a group are referred to as grouped options and form what is called an option group. - If a listbox contains grouped options, then: -
      -
    • All option groups contain at least one option.
      • -
    • Each option group has an accessible name provided via aria-label or aria-labelledby.
      • -
    -
    • -
  • If the element with role listbox is not part of another widget, such as a combobox, then it has either a visible label referenced by aria-labelledby or a value specified for aria-label.
    • -
  • - If the listbox supports selection of more than one option, the element with role listbox has aria-multiselectable set to true. - Otherwise, aria-multiselectable is either set to false or the default value of false is implied. -
    • -
  • - The selection state of each selectable option is indicated with either aria-selected or aria-checked: -
      -
    • - If the selection state is indicated with aria-selected, then aria-checked is not specified for any options. - Alternatively, if the selection state is indicated with aria-checked, then aria-selected is not specified for any options. - See notes below regarding considerations for which property to use and for details of the unusual conditions that might allow for both properties in the same listbox. -
      • -
    • - If any options are selected, each selected option has either aria-selected or aria-checked set to true. - No more than one option is selected at a time if the element with role listbox does not have aria-multiselectable set to true. -
      • -
    • - All options that are selectable but not selected have either aria-selected or aria-checked set to false. -
      • -
    • - Note that except in listboxes where selection follows focus, the selected state is distinct from focus. - For more details, see this description of differences between focus and selection and Deciding When to Make Selection Automatically Follow Focus. -
      • -
    -
    • -
  • 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.
    • -
  • - If options are arranged horizontally, the element with role listbox has aria-orientation set to horizontal. - The default value of aria-orientation for listbox is vertical. -
    • -
-
    -
  1. Some factors to consider when choosing whether to indicate selection with aria-selected or aria-checked are: -
      -
    • - Some design systems use aria-selected for single-select widgets and aria-checked for multi-select widgets. - In the absence of factors that would make an alternative convention more appropriate, this is a recommended convention. -
      • -
    • - The language of instructions and the appearance of the interface might suggest one attribute is more appropriate than the other. - For instance, do instructions say to select items? Or, is the visual indicator of selection a check mark? -
      • -
    • It is important to adopt a consistent convention for selection models across a site or app.
      • -
    -
    2. -
  2. - Conditions that would permit a listbox to include both aria-selected and aria-checked are extremely rare. - It is strongly recommended to avoid designing a listbox widget that would have the need for more than one type of state. - If both states were to be used within a listbox, all the following conditions need to be satisfied: -
      -
    • The meaning and purpose of aria-selected is different from the meaning and purpose of aria-checked in the user interface.
      • -
    • The user interface makes the meaning and purpose of each state apparent.
      • -
    • The user interface provides a separate method for controlling each state.
      • -
    -
    3. -
  3. - If aria-owns is set on the listbox element to include elements that are not DOM children of the container, - those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. - Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order. -
    4. -
-
-
- - - - - -
-

Meter

-

- A meter is a graphical display of a numeric value that varies within a defined range. - For example, a meter could be used to depict a device's current battery percentage or a car's fuel level. -

- - -
-

Example

-

Meter Example

-
- -
-

Keyboard Interaction

-

Not applicable.

-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element serving as the meter has a role of meter.
    • -
  • The meter has aria-valuenow set to a decimal value between aria-valuemin and aria-valuemax representing the current value of the meter.
    • -
  • The meter has aria-valuemin set to a decimal value less than aria-valuemax.
    • -
  • The meter has aria-valuemax set to a decimal value greater than aria-valuemin.
    • -
  • - Assistive technologies often present aria-valuenow as a percentage. - If conveying the value of the meter only in terms of a percentage would not be user friendly, the aria-valuetext property is set to a string that makes the meter value understandable. - For example, a battery meter value might be conveyed as aria-valuetext="50% (6 hours) remaining". -
    • -
  • If the meter has a visible label, it is referenced by aria-labelledby on the element with role meter. Otherwise, the element with role meter has a label provided by aria-label.
    • -
-
-
- -
-

Radio Group

-

- A radio group is a set of checkable buttons, known as radio buttons, where no more than one of - the buttons can be checked at a time. - Some implementations may initialize the set with all buttons in the unchecked state in order to - force the user to check one of the buttons before moving past a certain point in the workflow. -

- -
-

Examples

- -
- -
-

Keyboard Interaction

-
-
For Radio Groups Not Contained in a Toolbar
-

- This section describes the keyboard interaction implemented for most radio groups. - For the special case of a radio group nested inside a toolbar, use the keyboard interaction described in the following section. -

-
    -
  • - Tab and Shift + Tab: - Move focus into and out of the radio group. - When focus moves into a radio group : -
      -
    • If a radio button is checked, focus is set on the checked button.
      • -
    • If none of the radio buttons are checked, focus is set on the first radio - button in the group.
      • -
    -
    • -
  • Space: checks the focused radio button if it is not already checked.
    • -
  • - Right Arrow and Down Arrow: move focus to the next radio button in - the group, uncheck the previously focused button, and check the newly focused button. If - focus is on the last button, focus moves to the first button. -
    • -
  • - Left Arrow and Up Arrow: move focus to the previous radio button - in the group, uncheck the previously focused button, and check the newly focused button. - If focus is on the first button, focus moves to the last button. -
    • -
-

- The initial focus behavior described above differs slightly from the behavior - provided by some browsers for native HTML radio groups. In some browsers, if none of the - radio buttons are selected, moving focus into the radio group with Shift+Tab will place focus on the last radio button - instead of the first radio button. -

-
-
-
For Radio Group Contained in a Toolbar
-

- Because arrow keys are used to navigate among elements of a toolbar and the Tab key moves focus in and out of a toolbar, when a radio group is nested inside a toolbar, the keyboard interaction of the radio group is slightly different from that of a radio group that is not inside of a toolbar. - For instance, users need to be able to navigate among all toolbar elements, including the radio buttons, without changing which radio button is checked. - So, when navigating through a radio group in a toolbar with arrow keys, the button that is checked does not change. - The keyboard interaction of a radio group nested in a toolbar is as follows. -

-
    -
  • Space: If the focused radio button is not checked, unchecks the currently checked radio button and checks the focused radio button. Otherwise, does nothing.
    • -
  • Enter (optional): If the focused radio button is not checked, unchecks the currently checked radio button and checks the focused radio button. Otherwise, does nothing.
    • -
  • Right Arrow: -
      -
    • When focus is on a radio button and that radio button is not the last radio button in the radio group, moves focus to the next radio button.
      • -
    • When focus is on the last radio button in the radio group and that radio button is not the last element in the toolbar, moves focus to the next element in the toolbar.
      • -
    • When focus is on the last radio button in the radio group and that radio button is also the last element in the toolbar, moves focus to the first element in the toolbar.
      • -
    -
    • -
  • Left Arrow: -
      -
    • When focus is on a radio button and that radio button is not the first radio button in the radio group, moves focus to the previous radio button.
      • -
    • When focus is on the first radio button in the radio group and that radio button is not the first element in the toolbar, moves focus to the previous element in the toolbar.
      • -
    • When focus is on the first radio button in the radio group and that radio button is also the first element in the toolbar, moves focus to the last element in the toolbar.
      • -
    -
    • -
  • - Down Arrow (optional): Moves focus to the next radio button in the radio group. - If focus is on the last radio button in the radio group, moves focus to the first radio button in the group. -
    • -
  • - Up Arrow (optional): Moves focus to the previous radio button in the radio group. - If focus is on the first radio button in the radio group, moves focus to the last radio button in the group. -
    • -
-

- Radio buttons in a toolbar are frequently styled in a manner that appears more like toggle buttons. - For an example, See the Simple Editor Toolbar Example -

-
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • - The radio buttons are contained in or owned by an element with role - radiogroup. -
    • -
  • - Each radio button element has role - radio. -
    • -
  • - If a radio button is checked, the radio element has - aria-checked - set to true. If it is not checked, it has - aria-checked - set to false. -
    • -
  • - Each radio element is labelled by its content, has a visible label - referenced by - aria-labelledby, - or has a label specified with - aria-label. -
    • -
  • - The radiogroup element has a visible label referenced by - aria-labelledby - or has a label specified with - aria-label. -
    • -
  • - If elements providing additional information about either the radio group or each radio - button are present, those elements are referenced by the radiogroup element - or radio elements with the - aria-describedby - property. -
    • -
-
-
- -
-

Slider

-

- A slider is an input where the user selects a value from within a given range. - Sliders typically have a slider thumb that can be moved along a bar or track to change the value of the slider. -

-

- Some users of touch-based assistive technologies may experience difficulty utilizing widgets that implement this slider pattern because the gestures their assistive technology provides for operating sliders may not yet generate the necessary output. - To change the slider value, touch-based assistive technologies need to respond to user gestures for increasing and decreasing the value by synthesizing key events. - This is a new convention that may not be fully implemented by some assistive technologies. - Authors should fully test slider widgets using assistive technologies on devices where touch is a primary input mechanism before considering incorporation into production systems. -

-
-

Examples

-
    -
  • Color Viewer Slider Example: Basic horizontal sliders that illustrate setting numeric values for a color picker.
    • -
  • Vertical Temperature Slider Example: Demonstrates using aria-orientation to specify vertical orientation and aria-valuetext to communicate unit of measure for a temperature input.
    • -
  • Rating Slider Example: Horizontal slider that demonstrates using aria-valuetext to communicate current and maximum value of a rating input for a five star rating scale.
    • -
  • Media Seek Slider Example: Horizontal slider that demonstrates using aria-valuetext to communicate current and maximum values of time in media to make the values easy to understand for assistive technology users by converting the total number of seconds to minutes and seconds.
    • -
-
- -
-

Keyboard Interaction

-
    -
  • Right Arrow: Increase the value of the slider by one step.
    • -
  • Up Arrow: Increase the value of the slider by one step.
    • -
  • Left Arrow: Decrease the value of the slider by one step.
    • -
  • Down Arrow: Decrease the value of the slider by one step.
    • -
  • Home: Set the slider to the first allowed value in its range.
    • -
  • End: Set the slider to the last allowed value in its range.
    • -
  • Page Up (Optional): Increase the slider value by an amount larger than the step change made by Up Arrow.
    • -
  • Page Down (Optional): Decrease the slider value by an amount larger than the step change made by Down Arrow.
    • -
-
    -
  1. Focus is placed on the slider (the visual object that the mouse user would move, also known as the thumb.
    2. -
  2. In some circumstances, reversing the direction of the value change for the keys specified above, e.g., having Up Arrow decrease the value, could create a more intuitive experience.
    3. -
-
-
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element serving as the focusable slider control has role slider.
    • -
  • The slider element has the aria-valuenow property set to a decimal value representing the current value of the slider.
    • -
  • The slider element has the aria-valuemin property set to a decimal value representing the minimum allowed value of the slider.
    • -
  • The slider element has the aria-valuemax property set to a decimal value representing the maximum allowed value of the slider.
    • -
  • - If the value of aria-valuenow is not user-friendly, e.g., the day of the week is represented by a number, the - aria-valuetext - property is set to a string that makes the slider value understandable, e.g., "Monday". -
    • -
  • - If the slider has a visible label, it is referenced by - aria-labelledby on the slider element. - Otherwise, the slider element has a label provided by - aria-label. -
    • -
  • - If the slider is vertically oriented, it has aria-orientation set to vertical. - The default value of aria-orientation for a slider is horizontal. -
    • -
-
-
- -
-

Slider (Multi-Thumb)

-

- A multi-thumb slider is a slider - with two or more thumbs that each set a value in a group of related values. - For example, in a product search, a two-thumb slider could be used to enable users to set the minimum and maximum price limits for the search. - In many two-thumb sliders, the thumbs are not allowed to pass one another, such as when the slider sets the minimum and maximum values for a range. - For example, in a price range selector, the maximum value of the thumb that sets the lower end of the range is limited by the current value of the thumb that sets the upper end of the range. - Conversely, the minimum value of the upper end thumb is limited by the current value of the lower end thumb. - However, in some multi-thumb sliders, each thumb sets a value that does not depend on the other thumb values. -

-

- Some users of touch-based assistive technologies may experience difficulty utilizing widgets that implement this slider pattern because the gestures their assistive technology provides for operating sliders may not yet generate the necessary output. - To change the slider value, touch-based assistive technologies need to respond to user gestures for increasing and decreasing the value by synthesizing key events. - This is a new convention that may not be fully implemented by some assistive technologies. - Authors should fully test slider widgets using assistive technologies on devices where touch is a primary input mechanism before considering incorporation into production systems. -

- -
-

Example

-

Multi-Thumb Slider Examples: Demonstrates a two-thumb slider for picking a price range for a hotel reservation.

-
- -
-

Keyboard Interaction

-
    -
  • Each thumb is in the page tab sequence and has the same keyboard interaction as a single-thumb slider.
    • -
  • - The tab order remains constant regardless of thumb value and visual position within the slider. - For example, if the value of a thumb changes such that it moves past one of the other thumbs, the tab order does not change. -
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • Each element serving as a focusable slider thumb has role slider.
    • -
  • Each slider element has the aria-valuenow property set to a decimal value representing the current value of the slider.
    • -
  • Each slider element has the aria-valuemin property set to a decimal value representing the minimum allowed value of the slider.
    • -
  • Each slider element has the aria-valuemax property set to a decimal value representing the maximum allowed value of the slider.
    • -
  • When the range (e.g. minimum and/or maximum value) of another slider is dependent on the current value of a slider, the values of aria-valuemin or aria-valuemax of the dependent sliders are updated when the value changes.
    • -
  • - If a value of aria-valuenow is not user-friendly, e.g., the day of the week is represented by a number, the - aria-valuetext - property is set to a string that makes the slider value understandable, e.g., "Monday". -
    • -
  • - If a slider has a visible label, it is referenced by - aria-labelledby on the slider element. - Otherwise, the slider element has a label provided by - aria-label. -
    • -
  • - If a slider is vertically oriented, it has aria-orientation set to vertical. - The default value of aria-orientation for a slider is horizontal. -
    • -
-
-
- -
-

Spinbutton

-

- A spinbutton is an input widget that restricts its value to a set or range of discrete values. - For example, in a widget that enables users to set an alarm, a spinbutton could allow users to select a number from 0 to 59 for the minute of an hour. -

-

- Spinbuttons often have three components, including a text field that displays the current value, an increase button, and a decrease button. - The text field is usually the only focusable component because the increase and decrease functions are keyboard accessible via arrow keys. - Typically, the text field also allows users to directly edit the value. -

-

- If the range is large, a spinbutton may support changing the value in both small and large steps. - For instance, in the alarm example, the user may be able to move by 1 minute with Up Arrow and Down Arrow and by 10 minutes with Page Up and Page Down. -

- -
-

Example

-

Date Picker Spin Button Example: Illustrates a date picker made from three spin buttons for day, month, and year.

-
- -
-

Keyboard Interaction

-
    -
  • Up Arrow: Increases the value.
    • -
  • Down Arrow: Decreases the value.
    • -
  • Home: If the spinbutton has a minimum value, sets the value to its minimum.
    • -
  • End: If the spinbutton has a maximum value, sets the value to its maximum.
    • -
  • Page Up (Optional): Increases the value by a larger step than Up Arrow.
    • -
  • Page Down (Optional): Decreases the value by a larger step than Down Arrow.
    • -
  • If the spinbutton text field allows directly editing the value, the following keys are supported: -
      -
    • Standard single line text editing keys appropriate for the device platform (see note below).
      • -
    • - Printable Characters: Type characters in the textbox. Note that many implementations allow only certain characters as part of the value and prevent input of any other characters. - For example, an hour-and-minute spinner would allow only integer values from 0 to 59, the colon ':', and the letters 'AM' and 'PM'. - Any other character input does not change the contents of the text field nor the value of the spinbutton. -
      • -
    -
    • -
-
    -
  1. Focus remains on the text field during operation.
    2. -
  2. Standard single line text editing keys appropriate for the device platform: -
      -
    1. include keys for input, cursor movement, selection, and text manipulation.
      2. -
    2. Standard key assignments for editing functions depend on the device operating system.
      3. -
    3. The most robust approach for providing text editing functions is to rely on browsers, which supply them for HTML inputs with type text and for elements with the contenteditable HTML attribute.
      4. -
    4. IMPORTANT: Be sure that JavaScript does not interfere with browser-provided text editing functions by capturing key events for the keys used to perform them.
      5. -
    -
    3. -
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • - The focusable element serving as the spinbutton has role spinbutton. - This is typically an element that supports text input. -
    • -
  • The spinbutton element has the aria-valuenow property set to a decimal value representing the current value of the spinbutton.
    • -
  • The spinbutton element has the aria-valuemin property set to a decimal value representing the minimum allowed value of the spinbutton if it has a known minimum value.
    • -
  • The spinbutton element has the aria-valuemax property set to a decimal value representing the maximum allowed value of the spinbutton if it has a known maximum value.
    • -
  • - If the value of aria-valuenow is not user-friendly, e.g., the day of the week is represented by a number, the - aria-valuetext - property is set on the spinbutton element to a string that makes the spinbutton value understandable, e.g., "Monday". -
    • -
  • - If the spinbutton has a visible label, it is referenced by - aria-labelledby on the spinbutton element. - Otherwise, the spinbutton element has a label provided by - aria-label. -
    • -
  • - The spinbutton element has - aria-invalid set to true - if the value is outside the allowed range. - Note that most implementations prevent input of invalid values, but in some scenarios, blocking all invalid input may not be practical. -
    • -
-
-
- -
-

Switch

-

- A switch is an input widget that allows users to choose one of two values: on or off. - Switches are similar to checkboxes and toggle buttons, which can also serve as binary inputs. - One difference, however, is that switches can only be used for binary input while checkboxes and toggle buttons allow implementations the option of supporting a third middle state. - Checkboxes can be checked or not checked and can optionally also allow for a partially checked state. - Toggle buttons can be pressed or not pressed and can optionally allow for a partially pressed state. -

-

- Since switch, checkbox, and toggle button all offer binary input, they are often functionally interchangeable. - Choose the role that best matches both the visual design and semantics of the user interface. - For instance, there are some circumstances where the semantics of on or off would be easier for assistive technology users to understand than the semantics of checked or unchecked, and vice versa. - Consider a widget for turning lights on or off. - In this case, screen reader output of Lights switch on is more user friendly than Lights checkbox checked. - However, if the same input were in a group of inputs labeled Which of the following must be included in your pre-takeoff procedures?, Lights checkbox checked would make more sense. -

-

- Important: it is critical the label on a switch does not change when its state changes. -

- -
-

Examples

- -
- -
-

Keyboard Interaction

-
    -
  • Space: When focus is on the switch, changes the state of the switch.
    • -
  • Enter (Optional): When focus is on the switch, changes the state of the switch.
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The switch has role switch.
    • -
  • - The switch has an accessible label provided by one of the following: -
      -
    • Visible text content contained within the element with role switch.
      • -
    • A visible label referenced by the value of aria-labelledby set on the element with role switch.
      • -
    • aria-label set on the element with role switch.
      • -
    -
    • -
  • When on, the switch element has state aria-checked set to true.
    • -
  • When off, the switch element has state aria-checked set to false.
    • -
  • If the switch element is an HTML input[type="checkbox"], it uses the HTML checked attribute instead of the aria-checked property.
    • -
  • If a set of switches is presented as a logical group with a visible label, either: -
      -
    • The switches are included in an element with role group that has the property aria-labelledby set to the ID of the element containing the group label.
      • -
    • The set is contained in an HTML fieldset and the label for the set is contained in an HTML legend element.
      • -
    -
    • -
  • If the presentation includes additional descriptive static text relevant to a switch or switch group, the switch or switch group has the property aria-describedby set to the ID of the element containing the description.
    • -
-
-
- -
-

Table

-

- Like an HTML table element, a WAI-ARIA table is a static tabular structure containing one or more rows that each contain one or more cells; it is not an interactive widget. - Thus, its cells are not focusable or selectable. - The grid pattern is used to make an interactive widget that has a tabular structure. -

-

- However, tables are often used to present a combination of information and interactive widgets. - Since a table is not a widget, each widget contained in a table is a separate stop in the page tab sequence. - If the number of widgets is large, replacing the table with a grid can dramatically reduce the length of the page tab sequence because a grid is a composite widget that can contain other widgets. -

-

- As with other WAI-ARIA roles that have a native host language equivalent, - authors are strongly encouraged to use a native HTML table element whenever possible. - This is especially important with role table because it is a new feature of WAI-ARIA 1.1. - It is thus advisable to test implementations thoroughly with each browser and assistive technology combination that could be used by the target audience. -

-
-

Examples

-
    -
  • Table Example: ARIA table made using HTML div and span elements.
    • -
  • Sortable Table Example: Basic HTML table that illustrates implementation of aria-sort in the headers of sortable columns.
    • -
-
-
-

Keyboard Interaction

-

Not applicable.

-
-
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The table container has role table.
    • -
  • Each row container has role row and is either a DOM descendant of or owned by the table element or an element with role rowgroup.
    • -
  • Each cell is either a DOM descendant of or owned by a row element and has one of the following roles: -
      -
    • columnheader if the cell contains a title or header information for the column.
      • -
    • rowheader if the cell contains title or header information for the row.
      • -
    • cell if the cell does not contain column or row header information.
      • -
    -
    • -
  • - If there is an element in the user interface that serves as a label for the table, aria-labelledby is set on the table element with a value that refers to the labelling element. - Otherwise, a label is specified for the table element using aria-label. -
    • -
  • If the table has a caption or description, aria-describedby is set on the table element with a value referring to the element containing the description.
    • -
  • If the table contains sortable columns or rows, aria-sort is set to an appropriate value on the header cell element for the sorted column or row as described in the section on grid and table properties.
    • -
  • - If there are conditions where some rows or columns are hidden or not present in the DOM, e.g., there are widgets on the page for hiding rows or columns, the following properties are applied as described in the section on grid and table properties. - -
    • -
  • If the table includes cells that span multiple rows or multiple columns, then aria-rowspan or aria-colspan is applied as described in grid and table properties.
    • -
-

- If rows or cells are included in a table via aria-owns, - they will be presented to assistive technologies after the DOM descendants of the table element unless the DOM descendants are also included in the aria-owns attribute. -

-
-
- -
-

Tabs

-

- Tabs are a set of layered sections of content, known as tab panels, that display one panel of content at a time. - Each tab panel has an associated tab element, that when activated, displays the panel. - The list of tab elements is arranged along one edge of the currently displayed panel, most commonly the top edge. -

-

Terms used to describe this design pattern include:

-
-
Tabs or Tabbed Interface
-
A set of tab elements and their associated tab panels.
-
Tab List
-
A set of tab elements contained in a tablist element.
-
tab
-
An element in the tab list that serves as a label for one of the tab panels and can be activated to display that panel.
-
tabpanel
-
The element that contains the content associated with a tab.
-
-

- When a tabbed interface is initialized, one tab panel is displayed and its associated tab is styled to indicate that it is active. - When the user activates one of the other tab elements, the previously displayed tab panel is hidden, the tab panel associated with the activated tab becomes visible, and the tab is considered "active". -

- -
-

Examples

- -
- -
-

Keyboard Interaction

-

For the tab list:

-
    -
  • - Tab: -
      -
    • When focus moves into the tab list, places focus on the active tab element.
      • -
    • When the tab list contains the focus, moves focus to the next element in the page tab sequence outside the tablist, which is the tabpanel unless the first element containing meaningful content inside the tabpanel is focusable.
      • -
    -
    • -
  • When focus is on a tab element in a horizontal tab list: -
      -
    • - Left Arrow: moves focus to the previous tab. - If focus is on the first tab, moves focus to the last tab. - Optionally, activates the newly focused tab (See note below). -
      • -
    • - Right Arrow: Moves focus to the next tab. - If focus is on the last tab element, moves focus to the first tab. - Optionally, activates the newly focused tab (See note below). -
      • -
    -
    • -
  • When focus is on a tab in a tablist with either horizontal or vertical orientation: -
      -
    • Space or Enter: Activates the tab if it was not activated automatically on focus.
      • -
    • Home (Optional): Moves focus to the first tab. Optionally, activates the newly focused tab (See note below).
      • -
    • End (Optional): Moves focus to the last tab. Optionally, activates the newly focused tab (See note below).
      • -
    • Shift + F10: If the tab has an associated popup menu, opens the menu.
      • -
    • - Delete (Optional): If deletion is allowed, deletes (closes) the current tab element and its associated tab panel, - sets focus on the tab following the tab that was closed, and optionally activates the newly focused tab. If there is not a tab that followed the tab that was deleted, - e.g., the deleted tab was the right-most tab in a left-to-right horizontal tab list, - sets focus on and optionally activates the tab that preceded the deleted tab. - If the application allows all tabs to be deleted, and the user deletes the last remaining tab in the tab list, - the application moves focus to another element that provides a logical work flow. - As an alternative to Delete, or in addition to supporting Delete, the delete function is available in a context menu. -
      • -
    -
    • -
-
    -
  1. - It is recommended that tabs activate automatically when they receive focus as long as their associated tab panels are displayed without noticeable latency. - This typically requires tab panel content to be preloaded. - Otherwise, automatic activation slows focus movement, which significantly hampers users' ability to navigate efficiently across the tab list. - For additional guidance, see . -
    2. -
  2. - When a tab list has its aria-orientation set to vertical: -
      -
    1. Down Arrow performs as Right Arrow is described above.
      2. -
    2. Up Arrow performs as Left Arrow is described above.
      3. -
    -
    3. -
  3. If the tab list is horizontal, it does not listen for Down Arrow or Up Arrow so those keys can provide their normal browser scrolling functions even when focus is inside the tab list.
    4. -
  4. When the tabpanel does not contain any focusable elements or the first element with content is not focusable, the tabpanel should set tabindex="0" to include it in the tab sequence of the page.
    5. -
-
-
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element that serves as the container for the set of tabs has role tablist.
    • -
  • Each element that serves as a tab has role tab and is contained within the element with role tablist.
    • -
  • Each element that contains the content panel for a tab has role tabpanel.
    • -
  • - If the tab list has a visible label, the element with role tablist has aria-labelledby set to a value that refers to the labelling element. - Otherwise, the tablist element has a label provided by aria-label. -
    • -
  • Each element with role tab has the property aria-controls referring to its associated tabpanel element.
    • -
  • The active tab element has the state aria-selected set to true and all other tab elements have it set to false.
    • -
  • Each element with role tabpanel has the property aria-labelledby referring to its associated tab element.
    • -
  • If a tab element has a popup menu, it has the property aria-haspopup set to either menu or true.
    • -
  • - If the tablist element is vertically oriented, it has the property aria-orientation set to vertical. - The default value of aria-orientation for a tablist element is horizontal. -
    • -
-
-
- -
-

Toolbar

-

A toolbar is a container for grouping a set of controls, such as buttons, menubuttons, or checkboxes.

-

- When a set of controls is visually presented as a group, the toolbar role can be used to communicate the presence and purpose of the grouping to screen reader users. - Grouping controls into toolbars can also be an effective way of reducing the number of tab stops in the keyboard interface. -

-

To optimize the benefit of toolbar widgets:

- -
-

Example

-

- Toolbar Example: - A toolbar that uses roving tabindex to manage focus and contains several types of controls, including toggle buttons, radio buttons, a menu button, a spin button, a checkbox, and a link. -

-
-
-

Keyboard Interaction

-
    -
  • Tab and Shift + Tab: Move focus into and out of the toolbar. When focus moves into a toolbar: -
      -
    • If focus is moving into the toolbar for the first time, focus is set on the first control that is not disabled.
      • -
    • If the toolbar has previously contained focus, focus is optionally set on the control that last had focus. Otherwise, it is set on the first control that is not disabled.
      • -
    -
    • -
  • For a horizontal toolbar (the default): -
      -
    • Left Arrow: Moves focus to the previous control. Optionally, focus movement may wrap from the first element to the last element.
      • -
    • Right Arrow: Moves focus to the next control. Optionally, focus movement may wrap from the last element to the first element.
      • -
    -
    • -
  • Home (Optional): Moves focus to first element.
    • -
  • End (Optional): Moves focus to last element.
    • -
-
    -
  1. If the items in a toolbar are arranged vertically: -
      -
    1. Down Arrow performs as Right Arrow is described above.
      2. -
    2. Up Arrow performs as Left Arrow is described above.
      3. -
    -
    2. -
  2. - Typically, disabled elements are not focusable when navigating with a keyboard. - However, in circumstances where discoverability of a function is crucial, it may be helpful if disabled controls are focusable so screen reader users are more likely to be aware of their presence. - For additional guidance, see . -
    3. -
  3. In applications where quick access to a toolbar is important, such as accessing an editor's toolbar from its text area, a documented shortcut key for moving focus from the relevant context to its corresponding toolbar is recommended.
    4. -
-
-
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element that serves as the toolbar container has role toolbar.
    • -
  • - If the toolbar has a visible label, it is referenced by - aria-labelledby on the toolbar element. - Otherwise, the toolbar element has a label provided by - aria-label. -
    • -
  • If the controls are arranged vertically, the toolbar element has aria-orientation set to vertical. The default orientation is horizontal.
    • -
-
-
- -
-

Tooltip Widget

-

- NOTE: This design pattern is work in progress; it does not yet have task force consensus. - Progress and discussions are captured in - issue 128. -

-

- A tooltip is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. - It typically appears after a small delay and disappears when Escape is pressed or on mouse out. -

-

- Tooltip widgets do not receive focus. - A hover that contains focusable elements can be made using a non-modal dialog. -

-
-

Example

-

- Work to develop a tooltip example is tracked by - issue 127. -

-
-
-

Keyboard Interaction

-

Escape: Dismisses the Tooltip.

-
    -
  1. Focus stays on the triggering element while the tooltip is displayed.
    2. -
  2. - If the tooltip is invoked when the trigger element receives focus, then it is dismissed when it no longer has focus (onBlur). - If the tooltip is invoked with mouseIn, then it is dismissed with on mouseOut. -
    3. -
-
-
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element that serves as the tooltip container has role tooltip.
    • -
  • The element that triggers the tooltip references the tooltip element with aria-describedby.
    • -
-
-
- -
-

Tree View

-

- A tree view widget presents a hierarchical list. - Any item in the hierarchy may have child items, and items that have children may be expanded or collapsed to show or hide the children. - For example, in a file system navigator that uses a tree view to display folders and files, - an item representing a folder can be expanded to reveal the contents of the folder, which may be files, folders, or both. -

-

Terms for understanding tree views include:

-
-
Node
-
An item in a tree.
-
Root Node
-
Node at the base of the tree; it may have one or more child nodes but does not have a parent node.
-
Child Node
-
Node that has a parent; any node that is not a root node is a child node.
-
End Node
-
Node that does not have any child nodes; an end node may be either a root node or a child node.
-
Parent Node
-
Node with one or more child nodes. It can be open (expanded) or closed (collapsed).
-
Open Node
-
Parent node that is expanded so its child nodes are visible.
-
Closed Node
-
Parent node that is collapsed so the child nodes are not visible.
-
-

- When using a keyboard to navigate a tree, a visual keyboard indicator informs the user which node is focused. - If the tree allows the user to choose just one item for an action, then it is known as a single-select tree. - In some implementations of single-select tree, the focused item also has a selected state; this is known as selection follows focus. - However, in multi-select trees, which enable the user to select more than one item for an action, the selected state is always independent of the focus. - For example, in a typical file system navigator, the user can move focus to select any number of files for an action, such as copy or move. - It is important that the visual design distinguish between items that are selected and the item that has focus. - For more details, see this description of differences between focus and selection - and Deciding When to Make Selection Automatically Follow Focus. -

- -
-

Examples

- -
- -
-

Keyboard Interaction

-

For a vertically oriented tree:

-
    -
  • When a single-select tree receives focus: -
      -
    • If none of the nodes are selected before the tree receives focus, focus is set on the first node.
      • -
    • If a node is selected before the tree receives focus, focus is set on the selected node.
      • -
    -
    • -
  • When a multi-select tree receives focus: -
      -
    • If none of the nodes are selected before the tree receives focus, focus is set on the first node.
      • -
    • If one or more nodes are selected before the tree receives focus, focus is set on the first selected node.
      • -
    -
    • -
  • Right arrow: -
      -
    • When focus is on a closed node, opens the node; focus does not move.
      • -
    • When focus is on a open node, moves focus to the first child node.
      • -
    • When focus is on an end node, does nothing.
      • -
    -
    • -
  • Left arrow: -
      -
    • When focus is on an open node, closes the node.
      • -
    • When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node.
      • -
    • When focus is on a root node that is also either an end node or a closed node, does nothing.
      • -
    -
    • -
  • Down Arrow: Moves focus to the next node that is focusable without opening or closing a node.
    • -
  • Up Arrow: Moves focus to the previous node that is focusable without opening or closing a node.
    • -
  • Home: Moves focus to the first node in the tree without opening or closing a node.
    • -
  • End: Moves focus to the last node in the tree that is focusable without opening a node.
    • -
  • Enter: activates a node, i.e., performs its default action. For parent nodes, one possible default action is to open or close the node. In single-select trees where selection does not follow focus (see note below), the default action is typically to select the focused node.
    • -
  • Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes: -
      -
    • Type a character: focus moves to the next node with a name that starts with the typed character.
      • -
    • Type multiple characters in rapid succession: focus moves to the next node with a name that starts with the string of characters typed.
      • -
    -
    • -
  • * (Optional): Expands all siblings that are at the same level as the current node.
    • -
  • Selection in multi-select trees: - Authors may implement either of two interaction models to support multiple selection: a recommended model that does not require the user to hold a modifier key, such as Shift or Control, while navigating the list - or an alternative model that does require modifier keys to be held while navigating in order to avoid losing selection states. -
      -
    • Recommended selection model -- holding a modifier key while moving focus is not necessary: -
        -
      • Space: Toggles the selection state of the focused node.
        • -
      • Shift + Down Arrow (Optional): Moves focus to and toggles the selection state of the next node.
        • -
      • Shift + Up Arrow (Optional): Moves focus to and toggles the selection state of the previous node.
        • -
      • Shift + Space (Optional): Selects contiguous nodes from the most recently selected node to the current node.
        • -
      • Control + Shift + Home (Optional): Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node.
        • -
      • Control + Shift + End (Optional): Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node.
        • -
      • Control + A (Optional): Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes.
        • -
      -
      • -
    • Alternative selection model -- Moving focus without holding the Shift or Control modifier unselects all selected nodes except for the focused node: -
        -
      • Shift + Down Arrow: Moves focus to and toggles the selection state of the next node.
        • -
      • Shift + Up Arrow: Moves focus to and toggles the selection state of the previous node.
        • -
      • Control + Down Arrow: Without changing the selection state, moves focus to the next node.
        • -
      • Control + Up Arrow: Without changing the selection state, moves focus to the previous node.
        • -
      • Control + Space: Toggles the selection state of the focused node.
        • -
      • Shift + Space (Optional): Selects contiguous nodes from the most recently selected node to the current node.
        • -
      • Control + Shift + Home (Optional): Selects the node with focus and all nodes up to the first node. Optionally, moves focus to the first node.
        • -
      • Control + Shift + End (Optional): Selects the node with focus and all nodes down to the last node. Optionally, moves focus to the last node.
        • -
      • Control + A (Optional): Selects all nodes in the tree. Optionally, if all nodes are selected, it can also unselect all nodes.
        • -
      -
      • -
    -
    • -
-
    -
  1. DOM focus (the active element) is functionally distinct from the selected state. For more details, see this description of differences between focus and selection.
    2. -
  2. - The tree role supports the aria-activedescendant property, - which provides an alternative to moving DOM focus among treeitem elements when implementing keyboard navigation. - For details, see Managing Focus in Composites Using aria-activedescendant. -
    3. -
  3. - In a single-select tree, moving focus may optionally unselect the previously selected node and select the newly focused node. - This model of selection is known as "selection follows focus". - Having selection follow focus can be very helpful in some circumstances and can severely degrade accessibility in others. - For additional guidance, see Deciding When to Make Selection Automatically Follow Focus. -
    4. -
  4. If selecting or unselecting all nodes is an important function, implementing separate controls for these actions, such as buttons for "Select All" and "Unselect All", significantly improves accessibility.
    5. -
  5. - If the nodes in a tree are arranged horizontally: -
      -
    1. Down Arrow performs as Right Arrow is described above, and vice versa.
      2. -
    2. Up Arrow performs as Left Arrow is described above, and vice versa.
      3. -
    -
    6. -
-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • All tree nodes are contained in or owned by an element with role tree.
    • -
  • Each element serving as a tree node has role treeitem.
    • -
  • Each root node is contained in the element with role tree or referenced by an aria-owns property set on the tree element.
    • -
  • Each parent node contains or owns an element with role group.
    • -
  • Each child node is contained in or owned by an element with role group that is contained in or owned by the node that serves as the parent of that child.
    • -
  • - Each element with role treeitem that serves as a parent node has aria-expanded - set to false when the node is in a closed state and set to true when the node is in an open state. - End nodes do not have the aria-expanded attribute because, if they were to have it, they would be incorrectly described to assistive technologies as parent nodes. -
    • -
  • - If the tree supports selection of more than one node, the element with role tree has aria-multiselectable set to true. - Otherwise, aria-multiselectable is either set to false or the default value of false is implied. -
    • -
  • - The selection state of each selectable node is indicated with either aria-selected or aria-checked: -
      -
    • - If the selection state is indicated with aria-selected, then aria-checked is not specified for any nodes. - Alternatively, if the selection state is indicated with aria-checked, then aria-selected is not specified for any nodes. - See notes below regarding considerations for which property to use and for details of the unusual conditions that might allow for both properties in the same tree. -
      • -
    • - If any nodes are selected, each selected node has either aria-selected or aria-checked set to true. - No more than one node is selected at a time if the element with role tree does not have aria-multiselectable set to true. -
      • -
    • - All nodes that are selectable but not selected have either aria-selected or aria-checked set to false. -
      • -
    • - If the tree contains nodes that are not selectable, neither aria-selected nor aria-checked is present on those nodes. -
      • -
    • - Note that except in trees where selection follows focus, the selected state is distinct from focus. - For more details, see this description of differences between focus and selection and Deciding When to Make Selection Automatically Follow Focus. -
      • -
    -
    • -
  • The element with role tree has either a visible label referenced by aria-labelledby or a value specified for aria-label.
    • -
  • If the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree, each node has aria-level, aria-setsize, and aria-posinset specified.
    • -
  • - If the tree element is horizontally oriented, it has aria-orientation - set to horizontal. - The default value of aria-orientation for a tree is vertical. -
    • -
-
    -
  1. Some factors to consider when choosing whether to indicate selection with aria-selected or aria-checked are: -
      -
    • - Some design systems use aria-selected for single-select widgets and aria-checked for multi-select widgets. - In the absence of factors that would make an alternative convention more appropriate, this is a recommended convention. -
      • -
    • - The language of instructions and the appearance of the interface might suggest one attribute is more appropriate than the other. - For instance, do instructions say to select items? Or, is the visual indicator of selection a check mark? -
      • -
    • It is important to adopt a consistent convention for selection models across a site or app.
      • -
    -
    2. -
  2. - Conditions that would permit a tree to include both aria-selected and aria-checked are extremely rare. - It is strongly recommended to avoid designing a tree widget that would have the need for more than one type of state. - If both states were to be used within a tree, all the following conditions need to be satisfied: -
      -
    • The meaning and purpose of aria-selected is different from the meaning and purpose of aria-checked in the user interface.
      • -
    • The user interface makes the meaning and purpose of each state apparent.
      • -
    • The user interface provides a separate method for controlling each state.
      • -
    -
    3. -
  3. - If aria-owns is set on the tree container to include elements that are not DOM children of the container, - those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. - Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order. -
    4. -
-
-
- -
-

Treegrid

-

- A treegrid widget presents a hierarchical data grid consisting of tabular information that is editable or interactive. - Any row in the hierarchy may have child rows, and rows with children may be expanded or collapsed to show or hide the children. - For example, in a treegrid used to display messages and message responses for a e-mail discussion list, messages with responses would be in rows that can be expanded to reveal the response messages. -

-

- In a treegrid both rows and cells are focusable. Every row and cell contains a focusable element or is itself focusable, regardless of whether individual cell content is editable or interactive. - There is one exception: if column header cells do not provide functions, such as sort or filter, they do not need to be focusable. - One reason it is important for all cells to be able to receive or contain keyboard focus is that screen readers will typically be in their application reading mode, rather than their document reading mode, when users are interacting with the grid. - While in application mode, a screen reader user hears only focusable elements and content that labels focusable elements. - So, screen reader users may unknowingly overlook elements contained in a treegrid that are either not focusable or not used to label a column or row. -

-

- When using a keyboard to navigate a treegrid, a visual keyboard indicator informs the user which row or cell is focused. - If the treegrid allows the user to choose just one item for an action, then it is known as a single-select treegrid, and the item with focus also has a selected state. - However, in multi-select treegrids, which enable the user to select more than one row or cell for an action, the selected state is independent of the focus. - For example, in a hierarchical e-mail discussion grid, the user can move focus to select any number of rows for an action, such as delete or move. - It is important that the visual design distinguish between items that are selected and the item that has focus. - For more details, see this description of differences between focus and selection. -

- -
-

Examples

-
    -
  • - E-mail Inbox treegrid Example: A treegrid for navigating an e-mail inbox that demonstrates three keyboard navigation models -- rows first, cells first, and cells only. -
    • -
-
- -
-

Keyboard Interaction

-

- The following keys provide treegrid navigation by moving focus among rows and cells of the grid. - Implementations of treegrid make these key commands available when an element in the grid has received focus, e.g., after a user has moved focus to the grid with Tab. - Moving focus into the grid may result in the first cell or the first row being focused. - Whether focus goes to a cell or the row depends on author preferences and whether row focus is supported, since some treegrids may not provide focus to rows. -

-
    -
  • Enter: If cell-only focus is enabled and focus is on the first cell with the aria-expanded property, opens or closes the child rows.,Otherwise, performs the default action for the cell.
    • -
  • Tab: If the row containing focus contains focusable elements (e.g., inputs, buttons, links, etc.), moves focus to the next input in the row. If focus is on the last focusable element in the row, moves focus out of the treegrid widget to the next focusable element.
    • -
  • - Right Arrow: -
      -
    • If focus is on a collapsed row, expands the row.
      • -
    • If focus is on an expanded row or is on a row that does not have child rows, moves focus to the first cell in the row.
      • -
    • If focus is on the right-most cell in a row, focus does not move.
      • -
    • If focus is on any other cell, moves focus one cell to the right.
      • -
    -
    • -
  • Left Arrow: -
      -
    • If focus is on an expanded row, collapses the row.
      • -
    • If focus is on a collapsed row or on a row that does not have child rows, focus does not move.
      • -
    • If focus is on the first cell in a row and row focus is supported, moves focus to the row.
      • -
    • If focus is on the first cell in a row and row focus is not supported, focus does not move.
      • -
    • If focus is on any other cell, moves focus one cell to the left.
      • -
    -
    • -
  • - Down Arrow: -
      -
    • If focus is on a row, moves focus one row down. If focus is on the last row, focus does not move.
      • -
    • If focus is on a cell, moves focus one cell down. If focus is on the bottom cell in the column, focus does not move.
      • -
    -
    • -
  • - Up Arrow: -
      -
    • If focus is on a row, moves focus one row up. If focus is on the first row, focus does not move.
      • -
    • If focus is on a cell, moves focus one cell up. If focus is on the top cell in the column, focus does not move.
      • -
    -
    • -
  • - Page Down: -
      -
    • If focus is on a row, moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row, focus does not move.
      • -
    • If focus is on a cell, moves focus down an author-determined number of cells, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. If focus is in the last row, focus does not move.
      • -
    -
    • -
  • - Page Up: -
      -
    • If focus is on a row, moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row, focus does not move.
      • -
    • If focus is on a cell, moves focus up an author-determined number of cells, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. If focus is in the first row, focus does not move.
      • -
    -
    • -
  • - Home: -
      -
    • If focus is on a row, moves focus to the first row. If focus is in the first row, focus does not move.
      • -
    • If focus is on a cell, moves focus to the first cell in the row. If focus is in the first cell of the row, focus does not move.
      • -
    -
    • -
  • - End: -
      -
    • If focus is on a row, moves focus to the last row. If focus is in the last row, focus does not move.
      • -
    • If focus is on a cell, moves focus to the last cell in the row. If focus is in the last cell of the row, focus does not move.
      • -
    -
    • -
  • - Control + Home: -
      -
    • If focus is on a row, moves focus to the first row. If focus is in the first row, focus does not move.
      • -
    • If focus is on a cell, moves focus to the first cell in the column. If focus is in the first row, focus does not move.
      • -
    -
    • -
  • - Control + End: -
      -
    • If focus is on a row, moves focus to the last row. If focus is in the last row, focus does not move.
      • -
    • If focus is on a cell, moves focus to the last cell in the column. If focus is in the last row, focus does not move.
      • -
    -
    • -
-
    -
  • - When the above treegrid navigation keys move focus, whether the focus is set on an element inside the cell or on the cell depends on cell content. - See Whether to Focus on a Cell or an Element Inside It. -
    • -
  • - While navigation keys, such as arrow keys, are moving focus from cell to cell, they are not available to do something like operate a combobox or move an editing caret inside of a cell. - If this functionality is needed, see Editing and Navigating Inside a Cell. -
    • -
  • If navigation functions can dynamically add more rows or columns to the DOM, key events that move focus to the beginning or end of the grid, such as control + End, may move focus to the last row in the DOM rather than the last available row in the back-end data.
    • -
-

If a treegrid supports selection of cells, rows, or columns, the following keys are commonly used for these functions.

-
    -
  • - Control + Space: -
      -
    • If focus is on a row, selects all cells.
      • -
    • If focus is on a cell, selects the column that contains the focus.
      • -
    -
    • -
  • - Shift + Space: -
      -
    • If focus is on a row, selects the row.
      • -
    • If focus is on a cell, selects the row that contains the focus. If the treegrid includes a column with checkboxes for selecting rows, this key can serve as a shortcut for checking the box when focus is not on the checkbox.
      • -
    -
    • -
  • Control + A: Selects all cells.
    • -
  • - Shift + Right Arrow: -
      -
    • If focus is on a row, does not change selection.
      • -
    • if focus is on a cell, extends selection one cell to the right.
      • -
    -
    • -
  • - Shift + Left Arrow: -
      -
    • If focus is on a row, does not change selection.
      • -
    • if focus is on a cell, extends selection one cell to the left.
      • -
    -
    • -
  • - Shift + Down Arrow: -
      -
    • If focus is on a row, extends selection to all the cells in the next row.
      • -
    • If focus is on a cell, extends selection one cell down.
      • -
    -
    • -
  • - Shift + Up Arrow: -
      -
    • If focus is on a row, extends selection to all the cells in the previous row.
      • -
    • If focus is on a cell, extends selection one cell up.
      • -
    -
    • -
-

See for cut, copy, and paste key assignments.

-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The treegrid container has role treegrid.
    • -
  • Each row container has role row and is either a DOM descendant of or owned by the treegrid element or an element with role rowgroup.
    • -
  • Each cell is either a DOM descendant of or owned by a row element and has one of the following roles: -
      -
    • columnheader if the cell contains a title or header information for the column.
      • -
    • rowheader if the cell contains title or header information for the row.
      • -
    • gridcell if the cell does not contain column or row header information.
      • -
    -
    • -
  • - A row that can be expanded or collapsed to show or hide a set of child rows is a parent row. - Each parent row has the aria-expanded state set on either the row element or on a cell contained in therow. - The aria-expanded state is set to false when the child rows are not displayed and set to true when the child rows are displayed. - Rows that do not control display of child rows do not have the aria-expanded attribute because, if they were to have it, they would be incorrectly described to assistive technologies as parent rows. -
    • -
  • If the treegrid supports selection of more than one row or cell, it is a multi-select treegrid and the element with role treegrid has aria-multiselectable set to true. Otherwise, it is a single-select treegrid, and aria-multiselectable is either set to false or the default value of false is implied.
    • -
  • If the treegrid is a single-select treegrid, aria-selected is set to true on the selected row or cell, and it is not present on any other row or cell in the treegrid.
    • -
  • if the treegrid is a multi-select treegrid: -
      -
    • All selected rows or cells have aria-selected set to true.
      • -
    • All rows and cells that are not selected have aria-selected set to false.
      • -
    -
    • -
  • - If there is an element in the user interface that serves as a label for the treegrid, aria-labelledby is set on the grid element with a value that refers to the labelling element. - Otherwise, a label is specified for the grid element using aria-label. -
    • -
  • If the treegrid has a caption or description, aria-describedby is set on the grid element with a value referring to the element containing the description.
    • -
  • If the treegrid provides sort functions, aria-sort is set to an appropriate value on the header cell element for the sorted column or row as described in the section on grid and table properties.
    • -
  • - If the treegrid provides content editing functionality and contains cells that may have edit capabilities disabled in certain conditions, aria-readonly is set to true on cells where editing is disabled. - If edit functions are disabled for all cells, instead of setting aria-readonly to true on every cell, aria-readonly may be set to true on the treegrid element. - Treegrids that do not provide cell content editing functions do not include the aria-readonly attribute on any of their elements. -
    • -
  • - If there are conditions where some rows or columns are hidden or not present in the DOM, e.g., data is dynamically loaded when scrolling or the grid provides functions for hiding rows or columns, the following properties are applied as described in the section on grid and table properties. - -
    • -
  • If the treegrid includes cells that span multiple rows or multiple columns, and if the treegrid role is NOT applied to an HTML table element, then aria-rowspan or aria-colspan is applied as described in grid and table properties.
    • -
-
    -
  • - A treegrid built from an HTML table that includes cells that span multiple rows or columns must use HTML rowspan and colspan and must not use aria-rowspan or aria-colspan. -
    • -
  • - If rows or cells are included in a treegrid via aria-owns, - they will be presented to assistive technologies after the DOM descendants of the treegrid element unless the DOM descendants are also included in the aria-owns attribute. -
    • -
-
-
- -
-

Window Splitter

-

- NOTE: ARIA 1.1 introduced changes to the separator role so it behaves as a widget when focusable. - While this pattern has been revised to match the ARIA 1.1 specification, the task force will not complete its review until a functional example that matches the ARIA 1.1 specification is complete. - Progress on this pattern is tracked by - issue 129. -

-

- A window splitter is a moveable separator between two sections, or panes, of a window that enables users to change the relative size of the panes. - A Window Splitter can be either variable or fixed. - A fixed splitter toggles between two positions whereas a variable splitter can be adjusted to any position within an allowed range. -

-

- A window splitter has a value that represents the size of one of the panes, which, in this pattern, is called the primary pane. - When the splitter has its minimum value, the primary pane has its smallest size and the secondary pane has its largest size. - The splitter also has an accessible name that matches the name of the primary pane. -

-

- For example, consider a book reading application with a primary pane for the table of contents and a secondary pane that displays content from a section of the book. - The two panes are divided by a vertical splitter labelled "Table of Contents". - When the table of contents pane has its maximum size, the splitter has a value of 100, - and when the table of contents is completely collapsed, the splitter has a value of 0. -

-

- Note that the term "primary pane" does not describe the importance or purpose of content inside the pane. -

-
-

Example

-

- Work to develop an example window splitter widget is tracked by - issue 130. -

-
-
-

Keyboard Interaction

-
    -
  • Left Arrow: Moves a vertical splitter to the left.
    • -
  • Right Arrow: Moves a vertical splitter to the right.
    • -
  • Up Arrow: Moves a horizontal splitter up.
    • -
  • Down Arrow: Moves a horizontal splitter down.
    • -
  • Enter: If the primary pane is not collapsed, collapses the pane. If the pane is collapsed, restores the splitter to its previous position.
    • -
  • Home (Optional): Moves splitter to the position that gives the primary pane its smallest allowed size. This may completely collapse the primary pane.
    • -
  • End (Optional): Moves splitter to the position that gives the primary pane its largest allowed size. This may completely collapse the secondary pane.
    • -
  • F6 (Optional): Cycle through window panes.
    • -
-

A fixed size splitter omits implementation of the arrow keys.

-
-
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The element that serves as the focusable splitter has role separator.
    • -
  • The separator element has the aria-valuenow property set to a decimal value representing the current position of the separator.
    • -
  • The separator element has the aria-valuemin property set to a decimal value that represents the position where the primary pane has its minimum size. This is typically 0.
    • -
  • The separator element has the aria-valuemax property set to a decimal value that represents the position where the primary pane has its maximum size. This is typically 100.
    • -
  • - If the primary pane has a visible label, it is referenced by - aria-labelledby on the separator element. - Otherwise, the separator element has a label provided by - aria-label. -
    • -
  • The separator element has aria-controls referring to the primary pane.
    • -
-
-
-
- -
-

Landmark Regions

-

- ARIA landmark roles provide a powerful way to identify the organization and structure of a web page. - By classifying and labelling sections of a page, they enable structural information that is conveyed visually through layout to be represented programmatically. - Screen readers exploit landmark roles to provide keyboard navigation to important sections of a page. - Landmark regions can also be used as targets for "skip links" and by browser extensions to enhanced keyboard navigation. -

-

- This section explains how HTML sectioning elements and ARIA landmark roles - are used to make it easy for assistive technology users to understand the meaning of the layout of a page. -

-
-

HTML Sectioning Elements

-

- Several HTML sectioning elements automatically create ARIA landmark regions. - So, in order to provide assistive technology users with a logical view of a page, - it is important to understand the effects of using HTML sectioning elements. - [[HTML-ARIA]] contains more information on HTML element role mapping. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Default landmark roles for HTML sectioning elements
HTML ElementDefault Landmark Role
asidecomplementary
footercontentinfo when in context of the body element
headerbanner when in context of the body element
mainmain
navnavigation
sectionregion when it has an accessible name using aria-labelledby or aria-label
-
-
-

General Principles of Landmark Design

-

- Including all perceivable content on a page in one of its landmark regions - and giving each landmark region a semantically meaningful role - is one of the most effective ways of ensuring assistive technology users will not overlook information that is relevant to their needs. -

-

Step 1: Identify the logical structure

- - - -

Step 2: Assign landmark roles to each area

- - - -

Step 3: Label areas

- - -
- -
-

Landmark Roles

- -
-

Banner

- -

- A banner landmark identifies site-oriented content at the beginning of each page within a website. Site-oriented content typically includes things such as the logo or identity - of the site sponsor, and site-specific search tool. A banner usually appears at the top of the page and typically spans the full width. -

- -
    -
  • Each page may have one banner landmark.
    • - -
  • The banner landmark should be a top-level landmark.
    • - -
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have - one banner landmark.
    • - -
  • If a page includes more than one banner landmark, each should have a unique label (see Step 3 above).
    • -
- -
-
HTML Techniques
-
    -
  • The HTML header element defines a banner landmark when its context is the body element.
    • - -
  • - The HTML header element is not considered a banner landmark when it is descendant of any of following elements (see HTML Accessibility Mappings [[HTML-AAM]]): -
      -
    • article
      • -
    • aside
      • -
    • main
      • -
    • nav
      • -
    • section
      • -
    -
    • -
- -
ARIA Techniques
- -

If the HTML header element technique is not being used, a role="banner" attribute should be used to define a banner landmark.

-
- -
-
Examples
- -

Banner Landmark Example

-
- -
- -
-

Complementary

- -

A complementary landmark is a supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful - when separated from the main content.

- -
    -
  • complementary landmarks should be top level landmarks (e.g. not contained within any other landmarks).
    • - -
  • If the complementary content is not related to the main content, a more general role should be assigned (e.g. region).
    • - -
  • If a page includes more than one complementary landmark, each should have a unique label (see Step 3 above).
    • -
- -
-
HTML Technique
- -

Use the HTML aside element to define a complementary landmark.

- -
ARIA Technique
- -

If the HTML aside element technique is not being used, use a role="complementary" attribute to define a complementary landmark.

-
- -
-
Examples
- -

Complementary Landmark Example

-
-
- -
-

Contentinfo

- -

A contentinfo landmark is a way to identify common information at the bottom of each page within a website, typically called the "footer" of the page, including information - such as copyrights and links to privacy and accessibility statements.

- -
    -
  • Each page may have one contentinfo landmark.
    • - -
  • The contentinfo landmark should be a top-level landmark.
    • - -
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have - one contentinfo landmark.
    • - -
  • If a page includes more than one contentinfo landmark, each should have a unique label (see Step 3 above).
    • -
- -
- -
HTML Techniques
- -
    -
  • The HTML footer element defines a contentinfo landmark when its context is the body element.
    • - -
  • - The HTML footer element is not considered a contentinfo landmark when it is descendant of any of following elements (see HTML Accessibility Mappings [[HTML-AAM]]): -
      -
    • article
      • -
    • aside
      • -
    • main
      • -
    • nav
      • -
    • section
      • -
    -
    • -
- -
ARIA Technique
- -

If the HTML footer element technique is not being used, a role="contentinfo" attribute should be used to define a contentinfo landmark.

-
- -
-
Examples
-

Contentinfo Landmark Example

-
-
- -
-

Form

- -

A form landmark identifies a region that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. main - or search).

- -
    -
  • Use the search landmark instead of the form landmark when the form is used for search functionality.
    • - -
  • A form landmark should have a label to help users understand the purpose of the form.
    • - -
  • A label for the form landmark should be visible to all users (e.g. an h1-h6 element).
    • - -
  • If a page includes more than one form landmark, each should have a unique label (see Step 3 above).
    • - -
  • - Whenever possible, controls contained in a form landmark in an HTML document should use native host semantics: -
      -
    • button
      • - -
    • input
      • - -
    • select
      • - -
    • textarea
      • -
    -
    • -
- -
-
HTML Techniques
- -

The HTML form element defines a form landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).

- -
ARIA Technique
- -

Use the role="form" to identify a region of the page; do not use it to identify every form field.

-
- -
-
Examples
- -

Form Landmark Example

-
-
- -
-

Main

- -

A main landmark identifies the primary content of the page.

- -
    -
  • Each page should have one main landmark.
    • - -
  • The main landmark should be a top-level landmark.
    • - -
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have - one main landmark.
    • - -
  • If a page includes more than one main landmark, each should have a unique label (see Step 3 above).
    • -
- -
-
HTML Technique
- -

Use the HTML main element to define a main landmark.

- -
ARIA Technique
- -

If the HTML main element technique is not being used, use a role="main" attribute to define a main landmark.

-
- -
-
Examples
- -

Main Landmark Example

-
-
- -
-

Navigation

- -

Navigation landmarks provide a way to identify groups (e.g. lists) of links that are intended to be used for website or page content navigation.

- -
    -
  • If a page includes more than one navigation landmark, each should have a unique label (see Step 3 above).
    • - -
  • If a navigation landmark has an identical set of links as another navigation landmark on the page, use the same label for each navigation landmark.
    • -
- -
-
HTML Technique
- -

Use the HTML nav element to define a navigation landmark.

- -
ARIA Technique
- -

If the HTML nav element technique is not being used, use a role="navigation" attribute to define a navigation landmark.

- -
- -
-
Examples
- -

Navigation Landmark Example

-
-
- -
-

Region

- -

A region landmark is a perceivable section of the page containing content that is sufficiently important for users to be able to navigate to the section.

- -
    -
  • A region landmark must have a label.
    • - -
  • If a page includes more than one region landmark, each should have a unique label (see Step 3 above).
    • - -
  • The region landmark can be used identify content that named landmarks do not appropriately describe.
    • -
- -
-
HTML Technique
- -

The HTML section element defines a region landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).

- -
ARIA Technique
- -

If the HTML section element technique is not being used, use a role="region" attribute to define a region landmark.

-
- -
-
Examples
- -

Region Landmark Example

-
-
- - -
-
- -
-

Providing Accessible Names and Descriptions

-

- Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most important responsibilities authors have when developing accessible web experiences. - While doing so is straightforward for most elements, technical mistakes that can completely block users of assistive technologies are easy to make and unfortunately common. - To help authors effectively provide accessible names and descriptions, this section explains their purpose, when authors need to provide them, how browsers assemble them, and rules for coding and composing them. - It also guides authors in the use of the following naming and describing techniques and WAI-ARIA properties: -

- - -
-

What ARE Accessible Names and Descriptions?

-

- An accessible name is a short string, typically 1 to 3 words, that authors associate with an element to provide users of assistive technologies with a label for the element. - For example, an input field might have an accessible name of "User ID" or a button might be named "Submit". -

-

An accessible name serves two primary purposes for users of assistive technologies, such as screen readers:

-
    -
  1. Convey the purpose or intent of the element.
    2. -
  2. Distinguish the element from other elements on the page.
    3. -
-

- Both the WAI-ARIA specification and WCAG require all focusable, interactive elements to have an accessible name. - In addition dialogs and some structural containers, such as tables and regions, are required to have a name. - Many other elements can be named, but whether a name will enhance the accessible experience is determined by various characteristics of the surrounding context. - Finally, there are some elements where providing an accessible name is technically possible but not advisable. - The Accessible Name Guidance by Role section lists naming requirements and guidelines for every ARIA role. -

-

- An accessible description is also an author-provided string that is rendered by assistive technologies. - Authors supply a description when there is a need to associate additional information with an element, such as instructions or format requirements for an input field. -

-

- Assistive technologies present names differently from descriptions. - For instance, screen readers typically announce the name and role of an element first, e.g., a button named Mute Conversationcould be spoken as Mute Conversation button. - If an element has a state, it could be announced either before or after the name and role; after name and role is the typical default. - For example, a switch button named Mute Conversation in the off state could be announced as Mute Conversation switch button off. - Because descriptions are optional strings that are usually significantly longer than names, they are presented last, sometimes after a slight delay. - For example, Mute Conversation Switch button off, Silences alerts and notifications about activity in this conversation. - To reduce verbosity, some screen readers do not announce descriptions by default but instead inform users of their presence so that users can press a key that will announce the description. -

-
- -
-

How Are Name and Description Strings Derived?

-

- Because there are several elements and attributes for specifying text to include in an accessible name or description string, and because authors can combine them in a practically endless number of ways, browsers implement fairly complex algorithms for assembling the strings. -The sections on accessible name calculation and accessible description calculation explain the algorithms and how they implement precedence. -However, most authors do not need such detailed understanding of the algorithms since nearly all circumstances where a name or description is useful are supported by the coding patterns described in the naming techniques and describing techniques sections. -

-
- -
-

Cardinal Rules of Naming

- -
-

Rule 1: Heed Warnings and Test Thoroughly

-

- Several of the naming techniques below include notes that warn against specific coding patterns that are either prohibited by the ARIA specification or fall into gray space that is not yet fully specified. - Some of these prohibited or ambiguous patterns may appear logical and even yield desired names in some browsers. - However, it is unlikely they will provide consistent results across browsers, especially over time as work to improve the consistency of name calculation across browsers progresses. -

-

- In addition to heeding the warnings provided in the naming techniques, it is difficult to over emphasize the importance of testing to ensure that names browsers calculate match expectations. -

-
- -
-

Rule 2: Prefer Visible Text

-

- When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. - When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names will not be updated when the user interface design or content are changed. -

-

- If an interactive element, such as an input field or button, does not have a visually persistent text label, consider adjusting the design to include one. - In addition to serving as a more robust source for an accessible name, visible text labels enhance accessibility for many people with disabilities who do not use assistive technologies that present invisible accessible names. - In most circumstances, visible text labels also make the user interface easier to understand for all users. -

-
- -
-

Rule 3: Prefer Native Techniques

-

- In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element for form elements and caption element for tables. - While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences. - Several of the naming techniques highlight specific accessibility advantages of using HTML features instead of ARIA attributes. -

-
- -
-

Rule 4: Avoid Browser Fallback

-

- When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fallback methods for generating a name. - For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names. - Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective. -

-
- -
-

Rule 5: Compose Brief, Useful Names

-

- Similar to how visually crowded screens and ambiguous icons reduce usability, excessively long, insufficiently distinct, or unclear accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. - In other words, for a web experience to be accessible, its accessible names must be effective. - The section on Composing Effective and User-friendly Accessible Names provides guidance for balancing brevity and clarity. -

-
-
- -
-

Naming Techniques

- -
-

Naming with Child Content

-

- Certain elements get their name from the content they contain. - For example, the following link is named "Home". -

- - 
<a href="/">Home</a>
- -

- When assistive technologies render an element that gets its accessible name from its content, such as a link or button, the accessible name is the only content the user can perceive for that element. - This is in contrast to other elements, such as text fields or tables, where the accessible name is a label that is presented in addition to the value or content of the element. - For instance, the accessible name of a table can be derived from a caption element, and assistive technologies render both the caption and all other content contained inside the table. -

-

Elements having one of the following roles are, by default, named by a string calculated from their descendant content:

-
    -
  • button
    • -
  • cell
    • -
  • checkbox
    • -
  • columnheader
    • -
  • gridcell
    • -
  • heading
    • -
  • link
    • -
  • menuitem (content contained in a child menu element is excluded.)
    • -
  • menuitemcheckbox
    • -
  • menuitemradio
    • -
  • option
    • -
  • radio
    • -
  • row
    • -
  • rowheader
    • -
  • switch
    • -
  • tab
    • -
  • tooltip
    • -
  • treeitem (content included in a child group element is excluded.)
    • -
-

- When calculating a name from content for an element, user agents recursively walk through each of its descendant elements, calculate a name string for each descendant, and concatenate the resulting strings. - In two special cases, certain descendants are ignored: group descendants of treeitem elements and menu descendants of menuitem elements are omitted from the calculation. - For example, in the following tree, the name of the first tree item is Fruits; Apples, Bananas, and Oranges are omitted. -

- 
<ul role="tree">
-  <li role="treeitem">Fruits
-    <ul role="group">
-      <li role="treeitem">Apples</li>
-      <li role="treeitem">Bananas</li>
-      <li role="treeitem">Oranges</li>
-    </ul>
-  </li>
-</ul>
-

- If an element with one of the above roles that supports naming from child content is named by using aria-label or aria-labelledby, content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby. - It is strongly recommended to avoid using either of these attributes to override content of one of the above elements except in rare circumstances where hiding content from assistive technology users is beneficial. - In addition, in situations where visible content is hidden from assistive technology users by use of one of these attributes, thorough testing with assistive technologies is particularly important. -

-
- -
-

Naming with a String Attribute Via aria-label

-

- The aria-label property enables authors to name an element with a string that is not visually rendered. - For example, the name of the following button is "Close". -

- 
<button type="button" aria-label="Close">X</button>
-

- The aria-label property is useful when there is no visible text content that will serve as an appropriate accessible name. -

-

- The aria-label property affects assistive technology users in one of two different ways, depending on the role of the element to which it is applied. - When applied to an element with one of the roles that supports naming from child content, aria-label hides descendant content from assistive technology users and replaces it with the value of aria-label. - However, when applied to nearly any other type of element, assistive technologies will render both the value of aria-label and the content of the element. - For example, the name of the following navigation region is "Product". -

- 
<nav aria-label="Product">
-  <!-- list of navigation links to product pages -->
-</nav>
-

- When encountering this navigation region, a screen reader user will hear the name and role of the element, e.g., "Product navigation region", and then be able to read through the links contained in the region. -

-
    -
  1. - If aria-label is applied to an element with one of the roles that supports naming from child content, content contained in the element and its descendants is hidden from assistive technology users. - It is strongly recommended to avoid using aria-label to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial. -
    2. -
  2. There are certain types of elements, such as paragraphs and list items, that should not be named with aria-label. They are identified in the table in the Accessible Name Guidance by Role section.
    3. -
  3. Because the value of aria-label is not rendered visually, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
    4. -
  4. When a user interface is translated into multiple languages, ensure that aria-label values are translated.
    5. -
-
- -
-

Naming with Referenced Content Via aria-labelledby

-

- The aria-labelledby property enables authors to reference other elements on the page to define an accessible name. - For example, the following switch is named by the text content of a previous sibling element. -

- 
<span id="night-mode-label">Night mode</span>
-<span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
-

- Note that while using aria-labelledby is similar in this situation to using an HTML label element with the for attribute, one significant difference is that browsers do not automatically make clicking on the labeling element activate the labeled element; that is an author responsibility. - However, HTML label cannot be used to label a span element. - Fortunately, an HTML input with type="checkbox" allows the ARIA switch role, so when feasible, using the following approach creates a more robust solution. -

- 
<label for="night-mode">Night mode</label>
-<input type="checkbox" role="switch" id="night-mode">
-

The aria-labelledby property is useful in a wide variety of situations because:

-
    -

  • It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, including aria-label.

    • -

  • It can concatenate content from multiple elements into a single name string.

    • -
  • -

    It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with the HTML hidden attribute, CSS display: none, or CSS visibility: hidden in the calculated name string.

    -
    • -

  • It incorporates the value of input elements, i.e., if it references a textbox, the value of the textbox is included in the calculated name string.

    • -
-

An example of referencing a hidden element with aria-labelledby could be a label for a night switch control:

- 
<span id="night-mode-label" hidden>Night mode</span>
-<input type="checkbox" role="switch" aria-labelledby="night-mode-label">
- -

- In some cases, the most effective name for an element is its own content combined with the content of another element. - Because aria-labelledby has highest precedence in name calculation, in those situations, it is possible to use aria-labelledby to reference both the element itself and the other element. - In the following example, the "Read more..." link is named by the element itself and the article’s heading, resulting in a name for the link of "Read more... 7 ways you can help save the bees". -

- 
<h2 id="bees-heading">7 ways you can help save the bees</h2>
-<p>Bees are disappearing rapidly. Here are seven things you can do to help.</p>
-<p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
-

- When multiple elements are referenced by aria-labelledby, text content from each referenced element is concatenated in the order specified in the aria-labelledby value. - If an element is referenced more than one time, only the first reference is processed. - When concatenating content from multiple elements, browsers trim leading and trailing white space and separate content from each element with a single space. -

- 
<button id="download-button" aria-labelledby="download-button download-details">Download</button>
-<span id="download-details">PDF, 2.4 MB</span>
-

In the above example, the accessible name of the button will be "Download PDF, 2.4 MB", with a space between "Download" and "PDF", and not "DownloadPDF, 2.4 MB".

-
    -
  1. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
    2. -
  2. If an element is referenced by aria-labelledby more than one time during a name calculation, the second and any subsequent references will be ignored.
    3. -
  3. There are certain types of elements, such as paragraphs and list items, that should not be named with aria-labelledby. They are identified in the table in the Accessible Name Guidance by Role section.
    4. -
  4. - If aria-labelledby is applied to an element with one of the roles that supports naming from child content, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby. - It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial. -
    5. -
  5. Because calculating the name of an element with aria-labelledby can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
    6. -
-
- -
-

Naming Form Controls with the Label Element

-

- The HTML label element enables authors to identify content that serves as a label and associate it with a form control. - When a label element is associated with a form control, browsers calculate an accessible name for the form control from the label content. -

-

- For example, text displayed adjacent to a checkbox may be visually associated with the checkbox, so it is understood as the checkbox label by users who can perceive that visual association. - However, unless the text is programmatically associated with the checkbox, assistive technology users will experience a checkbox without a label. - Wrapping the checkbox and the labeling text in a label element as follows gives the checkbox an accessible name. -

- 
<label>
-  <input type="checkbox" name="subscribe">
-  subscribe to our newsletter
-</label>
-

- A form control can also be associated with a label by using the for attribute on the label element. - This allows the label and the form control to be siblings or have different parents in the DOM, but requires adding an id attribute to the form control, which can be error-prone. - When possible, use the above encapsulation technique for association instead of the following for attribute technique. -

- 
<input type="checkbox" name="subscribe" id="subscribe_checkbox">
-<label for="subscribe_checkbox">subscribe to our newsletter</label>
-

- Using the label element is an effective technique for satisfying Rule 2: Prefer Visible Text. - It also satisfies Rule 3: Prefer Native Techniques. - Native HTML labels offer an important usability and accessibility advantage over ARIA labeling techniques: browsers automatically make clicking the label equivalent to clicking the form control. - This increases the hit area of the form control. -

-
- -
-

Naming Fieldsets with the Legend Element

-

- The HTML fieldset element can be used to group form controls, and the legend element can be used to give the group a name. - For example, a group of radio buttons can be grouped together in a fieldset, where the legend element labels the group for the radio buttons. -

- 
<fieldset>
-  <legend>Select your starter class</legend>
-  <label><input type="radio" name="starter-class" value="green">Green</label>
-  <label><input type="radio" name="starter-class" value="red">Red</label>
-  <label><input type="radio" name="starter-class" value="blue">Blue</label>
-</fieldset>
-

- This grouping technique is particularly useful for presenting multiple choice questions. - It enables authors to associate a question with a group of answers. - If a question is not programmatically associated with its answer options, assistive technology users may access the answers without being aware of the question. -

-

- Similar benefits can be gained from grouping and naming other types of related form fields using fieldset and legend. -

- 
<fieldset>
-  <legend>Shipping address</legend>
-  <p><label>Full name <input name="name" required></label></p>
-  <p><label>Address line 1 <input name="address-1" required></label></p>
-  <p><label>Address line 2 <input name="address-2"></label></p>
-  ...
-</fieldset>
-<fieldset>
-  <legend>Billing address</legend>
-  ...
-</fieldset>
-

Using the legend element to name a fieldset element satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.

-
- -
-

Naming Tables and Figures with Captions

-

- The accessible name for HTML table and figure elements can be derived from a child caption or figcaption element, respectively. - Tables and figures often have a caption to explain what they are about, how to read them, and sometimes giving them numbers used to refer to them in surrounding prose. - Captions can help all users better understand content, but are especially helpful to users of assistive technologies. -

-

- In HTML, the table element marks up a data table, and can be provided with a caption using the caption element. - If the table element does not have aria-label or aria-labelledby, then the caption will be used as the accessible name. - For example, the accessible name of the following table is Special opening hours. -

- 
<table>
- <caption>Special opening hours</caption>
- <tr><td>30 May</td><td>Closed</td></tr>
- <tr><td>6 June</td><td>11:00-16:00</td></tr>
-</table>
-

The following example gives the table a number (Table 1) so it can be referenced.

- 
<table>
- <caption>Table 1. Traditional dietary intake of Okinawans and other Japanese circa 1950</caption>
- <thead>
-  <tr>
-   <th></th>
-   <th>Okinawa, 1949</th>
-   <th>Japan, 1950</th>
-  </tr>
- <tbody>
-  <tr>
-   <th>Total calories</th>
-   <td>1785</td>
-   <td>2068</td>
-
-  [...]
-
-</table>
-

Note: Above table content is from Caloric restriction, the traditional Okinawan diet, and healthy aging: the diet of the world's longest-lived people and its potential impact on morbidity and life span.

-

- If a table is named using aria-label or aria-labelledby, then a caption element, if present, will become an accessible description. - For an example, see Describing Tables and Figures with Captions. -

-

- Similarly, an HTML figure element can be given a caption using the figcaption element. - The caption can appear before or after the figure, but it is more common for figures to have the caption after. -

- 
<figure>
- <img alt="Painting of a person walking in a desert." src="Hole_JesusalDesierto.jpg">
- <figcaption>Jesus entering the desert as imagined by William Hole, 1908</figcaption>
-</figure>
-

- Like with table elements, if a figure is not named using aria-label or aria-labelledby, the content of the figcaption element will be used as the accessible name. - However unlike table elements, if the figcaption element is not used for the name, it does not become an accessible description unless it is referenced by aria-describedby. - Nevertheless, assistive technologies will render the content of a figcaption regardless of whether it is used as a name, description, or neither. -

-

Using the caption element to name a table element, or a figcaption element to name a figure element, satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.

-
- -
-

Fallback Names Derived from Titles and Placeholders

-

- When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), browsers calculate an accessible name from other attributes as a fallback mechanism. - Because the attributes used in fallback name calculation are not intended for naming, they typically yield low quality accessible names that are not effective. -So, As advised by Rule 4: Avoid Browser Fallback, prefer the explicit labeling techniques described above over fallback techniques described in this section. -

- -

- Any HTML element can have a title attribute specified. - The title attribute may be used as the element's fallback accessible name. - The title attribute is commonly presented visually as a tooltip when the user hovers over the element with a pointing device, which is not particularly discoverable, and is also not accessible to visual users without a pointing device. -

- -

For example, a fieldset element without a legend element child, but with a title attribute, gets its accessible name from the title attribute.

- - 
<fieldset title="Select your starter class">
-  <label><input type="radio" name="starter-class" value="green">Green</label>
-  <label><input type="radio" name="starter-class" value="red">Red</label>
-  <label><input type="radio" name="starter-class" value="blue">Blue</label>
-</fieldset>
- -

- For the HTML input and textarea elements, the placeholder attribute is used as a fallback labeling mechanism if nothing else (including the title attribute) results in a label. - It is better to use a label element, since it does not disappear visually when the user focuses the form control. -

- - 
<!-- Using a <label> is recommended -->
-<label>Search <input type=search name=q></label>
-
-<!-- A placeholder is used as fallback -->
-<input type=search name=q placeholder="Search">
-
-
- -
-

Composing Effective and User-friendly Accessible Names

-

- For assistive technology users, especially screen reader users, the quality of accessible names is one of the most significant contributors to usability. - Names that do not provide enough information reduce users' effectiveness while names that are too long reduce efficiency. - And, names that are difficult to understand reduce effectiveness, efficiency, and enjoyment. -

-

The following guidelines provide a starting point for crafting user friendly names.

- -
- -
-

Accessible Name Guidance by Role

-

- Certain elements always require a name, others may usually or sometimes require a name, and still others should never be named. - The table below lists all ARIA roles and provides the following information for each : -

-
-
Necessity of Naming
-
- Indicates how necessary it is for authors to add a naming attribute or element to supplement or override the content of an element with the specified role. - This column may include one of the following values: -
    -
  • - Required Only If Content Insufficient: An element with this role is named by its descendant content. - If aria-label or aria-labelledby is applied, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby. - Avoid hiding descendant content except in the rare circumstances where doing so benefits assistive technology users. -
    • -
  • Required: The ARIA specification requires authors to provide a name; a missing name causes accessibility validators to report an error.
    • -
  • Recommended: Providing a name is strongly recommended.
    • -
  • Discretionary: Naming is either optional or, in the circumstances described in the guidance column, is discouraged.
    • -
  • Do Not Name: Naming is strongly discouraged even if it is technically permitted; often assistive technologies do not render a name even if provided.
    • -
  • Prohibited: The ARIA specification does not permit the element to be named; If a name is specified, accessibility validators will report an error.
    • -
-
-
Guidance:
-
- Provides information to help determine if providing a name is beneficial, and if so, describes any recommended techniques. -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
roleNecessity of NamingGuidance
alertDiscretionary - Some screen readers announce the name of an alert before announcing the content of the alert. - Thus, aria-label provides a method for prefacing the visible content of an alert with text that is not displayed as part of the alert. - Using aria-label is functionally equivalent to providing off-screen text in the contents of the alert, except off-screen text would be announced by screen readers that do not support aria-label on alert elements. -
alertdialogRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
applicationRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
articleRecommended -
    -
  • Recommended to distinguish articles from one another; helps users when navigating among articles.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
-
bannerDiscretionary -
    -
  • Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
    • -
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
  • See the Banner Landmark section.
    • -
-
blockquoteDiscretionary - If a visible label is present, associating it with the blockquote by using aria-labelledby could benefit some assistive technology users. -
buttonRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
-
captionProhibited
cellRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • Note that a name is not required; assistive technologies expect an empty cell in a table to be represented by an empty name.
    • -
  • Note that associated row or column headers do not name a cell; the name of a cell in a table is its content. Headers are complementary information.
    • -
-
checkboxRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
    • -
  • If based on HTML type="checkbox", use a label element.
    • -
  • Otherwise, reference visible content via aria-labelledby.
    • -
-
codeProhibited
columnheaderRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • If the columnheader role is implied from an HTML th, the HTML abbr attribute can be used to specify an abbreviated version of the name that is only announced when screen readers are reading an associated cell within the table, grid, or treegrid.
    • -
-
comboboxRequired -
    -
  • If the combobox role is applied to an HTML select or input element, can be named with an HTML label element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
-
complementaryRecommended -
    -
  • Naming is necessary when two complementary landmark regions are present on the same page.
    • -
  • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Complementary Landmark section.
    • -
-
contentinfoDiscretionary -
    -
  • Necessary in the uncommon circumstance where two contentinfo landmark regions are present on the same page. It is otherwise optional.
    • -
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
-
definitionRecommendedReference the term being defined with role="term", using aria-labelledby.
deletionProhibited
dialogRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
directoryDiscretionary -
    -
  • Naming can help users understand the purpose of the directory.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
-
documentDiscretionary - Elements with the document role are contained within an element with the application role, which is required to have a name. - Typically, the name of the application element will provide sufficient context and identity for the document element. - Because the application element is used only to create unusual, custom widgets, careful assessment is necessary to determine whether or not adding an accessible name is beneficial. -
emphasisProhibited
feedRecommended -
    -
  • Helps screen reader users understand the context and purpose of the feed.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Feed Design Pattern.
    • -
-
figureRecommended -
    -
  • For HTML, use the figure and figcaption elements. The figcaption will serve as the accessible name for the figure. See the Naming Tables and Figures with Captions section.
    • -
  • When not using HTML, or when retrofitting legacy HTML, use the aria-labelledby on the figure, pointing to the figure's caption.
    • -
  • If there is no visible caption, aria-label can be used.
    • -
-
formRecommended -
    -
  • Helps screen reader users understand the context and purpose of the form landmark.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Form Landmark section.
    • -
-
genericProhibited
gridRequired -
    -
  • If the grid is applied to an HTML table element, then the accessible name can be derived from the table's caption element.
    • -
  • Otherwise, use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
-
gridcellRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • Note that a name is not required; assistive technologies expect an empty cell in a grid to be represented by an empty name.
    • -
  • Note that associated row or column headers do not name a gridcell; the name of a cell in a grid is its content. Headers are complementary information.
    • -
-
groupDiscretionary -
    -
  • When using the HTML fieldset element, the accessible name can be derived from the legend element.
    • -
  • When using the HTML details element, do not provide an accessible name for this element. The user interacts with the summary element, and that can derive its accessible name from its contents.
    • -
  • When using the HTML optgroup element, use the label attribute.
    • -
  • Otherwise, use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
-
headingRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
-
insertionProhibited
imgRequiredFor the HTML img element, use the alt attribute. For other elements with the img role, use aria-labelledby or aria-label.
linkRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
-
listDiscretionary -
    -
  • Potentially beneficial for users of screen readers that support both list names and navigation among lists on a page.
    • -
  • Potentially a source of distracting or undesirable screen reader verbosity, especially if nested within a named container, such as a navigation region.
    • -
  • Can be named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
-
listboxRequired -
    -
  • If the listbox role is applied to an HTML select element (with the multiple attribute or a size attribute having a value greater than 1), can be named with an HTML label element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
  • See the Listbox Design Pattern.
    • -
-
listitemDo Not NameNaming is not supported by assistive technologies; it is necessary to include relevant content within the list item.
logDiscretionary - Some screen readers announce the name of a log element before announcing the content of the log element. - Thus, aria-label provides a method for prefacing the visible content of a log element with text that is not displayed as part of the log element. - Using aria-label is functionally equivalent to providing off-screen text in the contents of the log element, except off-screen text would be announced by screen readers that do not support aria-label on log elements. -
mainDiscretionary -
    -
  • Potentially helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event.
    • -
  • Can be named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
  • See the Main Landmark section.
    • -
-
marqueeDiscretionaryUse aria-labelledby if a visible label is present, otherwise use aria-label.
mathRecommended -
    -
  • If the math element has only presentational children and the accessible name is intended to convey the mathematical expression, use aria-label to provide a string that represents the expression.
    • -
  • If the math element contains navigable content that conveys the mathematical expression and a visible label for the expression is present, use aria-labelledby.
    • -
  • Otherwise, use aaria-label to name the expression, e.g., aria-label="Pythagorean Theorem".
    • -
-
menuRecommended -
    -
  • Use aria-labelledby to refer to the menuitem or button that controls this element's display.
    • -
  • Otherwise, use aria-label.
    • -
  • See the Menu or Menu bar Design Pattern.
    • -
-
menubarRecommended -
    -
  • - Helps screen reader users understand the context and purpose of menuitem elements in a menubar. - Naming a menubar is comparable to naming a menu button. - The name of a button that opens a menu conveys the purpose of the menu it opens. - Since a menubar element is displayed persistently, a name on the menubar can serve that same purpose. -
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Menu or Menu bar Design Pattern.
    • -
-
menuitemRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • Note: content contained within a child menu is automatically excluded from the accessible name calculation.
    • -
  • See the Menu or Menu bar Design Pattern.
    • -
-
menuitemcheckboxRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • See the Menu or Menu bar Design Pattern.
    • -
-
menuitemradioRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • See the Menu or Menu bar Design Pattern.
    • -
-
meterRequired -
    -
  • If based on an HTML meter element, can be named with an HTML label element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
-
navigationRecommended -
    -
  • Helps screen reader users understand the context and purpose of the navigation landmark.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Navigation Landmark section.
    • -
-
noneProhibitedAn element with role="none" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label.
noteDiscretionary -
    -
  • Naming is optional, but can help screen reader users understand the context and purpose of the note.
    • -
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
-
optionRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • See the Combobox Design Pattern.
    • -
-
paragraphProhibited
presentationProhibitedAn element with role="presentation" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label.
progressbarRequired -
    -
  • If the progressbar role is applied to an HTML progress element, can be named with an HTML label element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
-
radioRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
    • -
  • If based on HTML type="checkbox", use a label element.
    • -
  • Otherwise, reference visible content via aria-labelledby.
    • -
-
radiogroupRequired -
    -
  • Recommended to help assistive technology users understand the purpose of the group of radio buttons.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Radio Group Design Pattern.
    • -
-
regionRequired -
    -
  • Helps screen reader users understand the context and purpose of the landmark.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Region Landmark section.
    • -
-
row - Required Only If Content Insufficient - AND descendant of a treegrid - AND the row is focusable - - When row elements are focusable in a treegrid, screen readers announce the entire contents of a row when navigating by row. - This is typically the most appropriate behavior. - However, in some circumstances, it could be beneficial to change the order in which cells are announced or exclude announcement of certain cells by using aria-labelledby to specify which cells to announce. -
rowgroupDo Not NameNaming is not supported by assistive technologies.
rowheaderRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • If the rowheader role is implied from an HTML th, the HTML abbr attribute can be used to specify an abbreviated version of the name that is only announced when screen readers are reading an associated cell within the table, grid, or treegrid.
    • -
-
scrollbarDiscretionary -
    -
  • Naming is optional, but can potentially help screen reader users understand the purpose of the scrollbar. The purpose is also conveyed using the aria-controls attribute, which is required for scrollbar.
    • -
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
-
searchRecommended -
    -
  • Helps screen reader users understand the context and purpose of the search landmark.
    • -
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
  • See the Search Landmark section.
    • -
-
searchboxRequired -
    -
  • If the searchbox role is applied to an HTML input element, can be named with an HTML label element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
-
separatorDiscretionary -
    -
  • Recommended if there is more than one focusable separator element on the page.
    • -
  • Can help assistive technology users understand the purpose of the separator.
    • -
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
-
sliderRequired -
    -
  • If the slider role is applied to an HTML input element, can be named with an HTML label element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
  • See the Slider Design Pattern and the Slider (Multi-Thumb) Design Pattern.
    • -
-
spinbuttonRequired -
    -
  • If the textbox role is applied to an HTML input element, can be named with an HTML label element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
  • See the Spinbutton Design Pattern.
    • -
-
statusDiscretionary - Some screen readers announce the name of a status element before announcing the content of the status element. - Thus, aria-label provides a method for prefacing the visible content of a status element with text that is not displayed as part of the status element. - Using aria-label is functionally equivalent to providing off-screen text in the contents of the status element, except off-screen text would be announced by screen readers that do not support aria-label on status elements. -
strongProhibited
subscriptProhibited
superscriptProhibited
switchRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
    • -
  • If based on HTML type="checkbox", use a label element.
    • -
  • Otherwise, reference visible content via aria-labelledby.
    • -
-
tabRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
-
tableRequired -
    -
  • If using HTML table element, use the caption element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
  • See the Table Design Pattern.
    • -
-
tablistRecommended -
    -
  • Helps screen reader users understand the context and purpose of the tablist.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Carousel Design Pattern and Tabs Design Pattern.
    • -
-
tabpanelRequired - -
termDo Not NameSince a term is usually the name for the role="definition" element, it could be confusing if the term itself also has a name.
textboxRequired -
    -
  • If the textbox role is applied to an HTML input or textarea element, can be named with an HTML label element.
    • -
  • Otherwise use aria-labelledby if a visible label is present.
    • -
  • Use aria-label if a visible label is not present.
    • -
-
timeDo Not NameNaming is not supported by assistive technologies.
timerDiscretionary - Some screen readers announce the name of a timer element before announcing the content of the timer element. - Thus, aria-label provides a method for prefacing the visible content of a timer element with text that is not displayed as part of the timer element. - Using aria-label is functionally equivalent to providing off-screen text in the contents of the timer element, except off-screen text would be announced by screen readers that do not support aria-label on timer elements. -
toolbarRecommended -
    -
  • If there is more than one toolbar element on the page, naming is required.
    • -
  • Helps assistive technology users to understand the purpose of the toolbar, even when there is only one toolbar on the page.
    • -
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Toolbar Pattern.
    • -
-
tooltipRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
-
treeRequired - -
treegridRequired -
    -
  • If the treegrid is applied to an HTML table element, then the accessible name can be derived from the table's caption element.
    • -
  • Otherwise, use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Treegrid Design Pattern.
    • -
-
treeitemRequired Only If Content Insufficient -
    -
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
    • -
  • Ideally named by visible, descendant content.
    • -
  • Note: content contained within a child group is automatically excluded from the accessible name calculation.
    • -
  • See the Tree View Design Pattern.
    • -
-
-
- -
-

Accessible name calculation

-

- User agents construct an accessible name string for an element by walking through a list of potential naming methods and using the first that generates a name. - The algorithm they follow is defined in the accessible name specification. - It is roughly like the following: -

-
    -

  1. The aria-labelledby property is used if present.

    2. -

  2. If the name is still empty, the aria-label property is used if present.

    3. -
  3. -

    If the name is still empty, then host-language-specific attributes or elements are used if present. For HTML, these are, depending on the element:

    -
    -
    input whose type attribute is in the Button, Submit Button, or Reset Button state
    -
    The value attribute.
    - -
    input whose type attribute is in the Image Button state
    -
    img
    -
    area
    -
    The alt attribute.
    - -
    fieldset
    -
    The first child legend element.
    - -
    Other form elements
    -
    The associated label element(s).
    - -
    figure
    -
    The first child figcaption element.
    - -
    table
    -
    The first child caption element.
    -
    -
    4. -

  4. If the name is still empty, then for elements with a role that supports naming from child content, the content of the element is used.

    5. -
  5. -

    Finally, if the name is still empty, then other fallback host-language-specific attributes or elements are used if present. For HTML, these are, depending on the element:

    -
    -
    input whose type attribute is in the Text, Password, Search, Telephone, or URL states
    -
    textarea
    -
    The title attribute. Otherwise, the placeholder attribute.
    - -
    input whose type attribute is in the Submit Button state
    -
    A localized string of the word "submit".
    - -
    input whose type attribute is in the Reset Button state
    -
    A localized string of the word "reset".
    - -
    input whose type attribute is in the Image Button state
    -
    The title attribute. Otherwise, a localized string of the phrase "Submit Query".
    - -
    summary
    -
    The word "Details".
    - -
    Other elements
    -
    The title attribute.
    -
    -
    6. -
-

- The final step is a fallback mechanism. Generally when labeling an element, use one of the non-fallback mechanisms. -

-

- When calculating a name from content, the user agent walks through all descendant nodes except in the cases of treeitem and menuitem as described below. - And, when following references in an aria-labelledby attribute, it similarly walks the tree of each referenced element. - Thus, the naming algorithm is recursive. - The following two sections explain non-recursive and recursive examples of how the algorithm works. -

-

- When calculating a name from content for the treeitem role, descendant content of child group elements are not included. - For example, in the following tree, the name of the first tree item is Fruits; Apples, Bananas, and Oranges are automatically omitted. -

- 
<ul role="tree">
-  <li role="treeitem">Fruits
-    <ul role="group">
-      <li role="treeitem">Apples</li>
-      <li role="treeitem">Bananas</li>
-      <li role="treeitem">Oranges</li>
-    </ul>
-  </li>
-</ul>
-

- Similarly, when calculating a name from content for the menuitem role, descendant content of child menu elements are not included. - So, the name of the first parent menuitem in the following menu is Fruits. -

- 
<ul role="menu">
-  <li role="menuitem">Fruits
-    <ul role="menu">
-      <li role="menuitem">Apples</li>
-      <li role="menuitem">Bananas</li>
-      <li role="menuitem">Oranges</li>
-    </ul>
-  </li>
-</ul>
- -
-

Examples of non-recursive accessible name calculation

-

Consider an input element that has no associated label element and only a name attribute and so does not have an accessible name (do not do this):

- 
<input name="code">
-

If there is a placeholder attribute, then it serves as a naming fallback mechanism (avoid doing this):

- - 
<input name="code"
-       placeholder="One-time code">
- -

If there is also a title attribute, then it is used as the accessible name instead of placeholder, but it is still a fallback (avoid doing this):

- - 
<input name="code"
-       placeholder="123456"
-       title="One-time code">
- -

If there is also a label element (recommended), then that is used as the accessible name, and the title attribute is instead used as the accessible description:

- - 
<label>One-time code
- <input name="code"
-        placeholder="123456"
-        title="Get your code from the app.">
-</label>
- -

If there is also an aria-label attribute (not recommended unless it adds clarity for assistive technology users), then that becomes the accessible name, overriding the label element:

- - 
<label>Code
- <input name="code"
-        aria-label="One-time code"
-        placeholder="123456"
-        title="Get your code from the app.">
-</label>
- -

If there is also an aria-labelledby attribute, that wins over the other elements and attributes (the aria-label attribute ought to be removed if it is not used):

- - 
<p>Please fill in your <span id="code-label">one-time code</span> to log in.</p>
-<p>
- <label>Code
-  <input name="code"
-         aria-labelledby="code-label"
-         aria-label="This is ignored"
-         placeholder="123456"
-         title="Get your code from the app.">
- </label>
-</p>
-
- -
-

Examples of recursive accessible name calculation

-

The accessible name calculation algorithm will be invoked recursively when necessary. An aria-labelledby reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

- -

In this example, the label for the button is computed by recursing into each child node, resulting in Move to trash.

- - 
<button>Move to <img src="bin.svg" alt="trash"></button>
- -

When following an aria-labelledby reference, the algorithm avoids following the same reference twice to avoid infinite loops.

- -

In this example, the label for the button is computed by first following the aria-labelledby reference to the parent element, and then computing the label for that element from the child nodes, first visiting the button element again but ignoring the aria-labelledby reference and instead using the aria-label, and then visiting the next child (the text node). The resulting label is Remove meeting: Daily status report.

- - 
<div id="meeting-1">
-  <button aria-labelledby="meeting-1" aria-label="Remove meeting:">X</button>
-  Daily status report
-</div>
-
-
- -
-

Describing Techniques

-
-

Describing by referencing content with aria-describedby

-

- The aria-describedby property works similarly to the aria-labelledby property. - For example, a button could be described by a sibling paragraph. -

- - 
<button aria-describedby="trash-desc">Move to trash</button>
-...
-<p id="trash-desc">Items in the trash will be permanently removed after 30 days.</p>
- -

Descriptions are reduced to text strings. For example, if the description contains an HTML img element, a text equivalent of the image is computed.

- - 
<button aria-describedby="trash-desc">Move to <img src="bin.svg" alt="trash"></button>
-...
-<p id="trash-desc">Items in <img src="bin.svg" alt="the trash"> will be permanently removed after 30 days.</p>
- -

- As with aria-labelledby, it is possible to reference an element using aria-describedby even if that element is hidden. - For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. - The description could also be referenced from the text field directly with aria-describedby. - In the following example, the accessible description for the input element is Your username is the name that you use to log in to this service. -

- - 
<label for="username">Username</label>
-<input id="username" name="username" aria-describedby="username-desc">
-<button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
-<p id="username-desc" hidden>
-  Your username is the name that you use to log in to this service.
-</p>
-
- -
-

Describing Tables and Figures with Captions

-

- In HTML, if the table is named using aria-label or aria-labelledby, a child caption element becomes an accessible description. - For example, a preceding heading might serve as an appropriate accessible name, and the caption element might contain a longer description. - In such a situation, aria-labelledby could be used on the table to set the accessible name to the heading content and the caption would become the accessible description. -

- 
<h2 id="events-heading">Upcoming events</h2>
-<table aria-labelledby="events-heading">
- <caption>
-  Calendar of upcoming events, weeks 27 through 31, with each week starting with
-  Monday. The first column is the week number.
- </caption>
- <tr><th>Week</th><th>Monday</th><th>Tuesday</th><th>Wednesday</th><th>Thursday</th><th>Friday</th><th>Saturday</th><th>Sunday</th></tr>
- <tr><td>27</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
- <tr><td>28</td><td></td><td></td><td></td><td></td><td></td><td></td><td><a href="/events/9856">Crown Princess's birthday</a></td></tr>
- <tr><td>29</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
- <tr><td>30</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
- <tr><td>31</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
-</table>
-

The HTML figure element can get its accessible name from its figcaption element, but it will not be used as the accessible description, even if it was not used as the accessible name. If the figcaption element is appropriate as an accessible description, and the accessible name is set using aria-labelledby or aria-label, then the figcaption can be explicitly set as the accessible description using the aria-describedby attribute.

- 
<h2 id="neutron">Neutron</h2>
-<figure aria-labelledby="neutron" aria-describedby="neutron-caption">
- <img src="neutron.svg" alt="Within the neutron are three quarks (blue 'u',
- red 'd', green 'd') that are interconnected.">
- <figcaption id="neutron-caption">
-  The quark content of the neutron. The color assignment of individual quarks is
-  arbitrary, but all three colors must be present. Forces between quarks are
-  mediated by gluons.
- </figcaption>
-</figure>
-
- -
-

Descriptions Derived from Titles

-

If an accessible description was not provided using the aria-describedby attribute or one of the primary host-language-specific attributes or elements (e.g., the caption element for table), then, for HTML, if the element has a title attribute, that is used as the accessible description.

-

A visible description together with aria-describedby is generally recommended. If a description that is not visible is desired, then the title attribute can be used, for any HTML element that can have an accessible description.

-

Note that the title attribute might not be accessible to some users, in particular sighted users not using a screen reader and not using a pointing device that supports hover (e.g., a mouse).

-

For example, an input element with input constrained using the pattern attribute can use the title attribute to describe what the expected input is.

- 
<label> Part number:
- <input pattern="[0-9][A-Z]{3}" name="part"
-        title="A part number is a digit followed by three uppercase letters."/>
-</label>
-

The title attribute in this case can be shown to the user as a tooltip when the user hovers or focuses the control, but also as part of the error message when the user agent validates the form, if the input element's value doesn't match the pattern.

-

As another example, a link can use the title attribute to describe the link in more detail.

- 
<a href="http://twitter.com/W3C"
-   title="Follow W3C on Twitter">
-   <img src="/2008/site/images/Twitter_bird_logo_2012.svg"
-        alt="Twitter" class="social-icon" height="40" />
-</a>
-
-
- -
-

Accessible description calculation

-

- Like the accessible name calculation, the accessible description calculation produces a text string. -

-

- The accessible description calculation algorithm is the same as the accessible name calculation algorithm except for a few branch points that depend on whether a name or description is being calculated. - In particular, when accumulating text for an accessible description, the algorithm uses aria-describedby instead of aria-labelledby. -

-

- User agents construct an accessible description string for an element by walking through a list of potential description methods and using the first that generates a description. - The algorithm they follow is defined in the accessible name specification. - It is roughly like the following: -

-
    -

  1. The aria-describedby property is used if present.

    2. -
  2. -

    If the description is still empty, then host-language-specific attributes or elements are used if present, if it wasn't already used as the accessible name. For HTML, these are, depending on the element:

    -
    -
    input whose type attribute is in the Button, Submit Button, or Reset Button state
    -
    The value attribute.
    - -
    summary
    -
    The element's subtree.
    - -
    table
    -
    The first child caption element.
    -
    -
    3. -
  3. -

    Finally, if the description is still empty, then other host-language-specific attributes or elements are used if present, if it wasn't already used for the accessible name. For HTML, this is the title attribute.

    -
    4. -
-
-
- -
-

Developing a Keyboard Interface

-

- Unlike native HTML form elements, browsers do not provide keyboard support for graphical user interface (GUI) components that are made accessible with ARIA; authors have to provide the keyboard support in their code. - This section describes the principles and methods for making the functionality of a web page that includes ARIA widgets, such as menus and grids, as well as interactive components, such as toolbars and dialogs, operable with a keyboard. - Along with the basics of focus management, this section offers guidance toward the objective of providing experiences to people who rely on a keyboard that are as efficient and enjoyable as the experiences available to others. -

-

This section covers:

-
    -
  1. Understanding fundamental principles of focus movement conventions used in ARIA design patterns.
    2. -
  2. Maintaining visible focus, predictable focus movement, and distinguishing between keyboard focus and the selected state.
    3. -
  3. Managing movement of keyboard focus between components, e.g., how the focus moves when the Tab and Shift+Tab keys are pressed.
    4. -
  4. Managing movement of keyboard focus inside components that contain multiple focusable elements, e.g., two different methods for programmatically exposing focus inside widgets like radio groups, menus, listboxes, trees, and grids.
    5. -
  5. Determining when to make disabled interactive elements focusable.
    6. -
  6. Assigning and revealing keyboard shortcuts, including guidance on how to avoid problematic conflicts with keyboard commands of assistive technologies, browsers, and operating systems.
    7. -
-
-

Fundamental Keyboard Navigation Conventions

- -

- ARIA roles, states, and properties model accessibility behaviors and features shared among GUI components of popular desktop GUIs, including Microsoft Windows, macOS, and GNOME. - Similarly, ARIA design patterns borrow user expectations and keyboard conventions from those platforms, consistently incorporating common conventions with the aim of facilitating easy learning and efficient operation of keyboard interfaces across the web. -

- -

- For a web page to be accessible, all interactive elements must be operable via the keyboard. - In addition, consistent application of the common GUI keyboard interface conventions described in the ARIA design patterns is important, especially for assistive technology users. - Consider, for example, a screen reader user operating a tree. - Just as familiar visual styling helps users discover how to expand a tree branch with a mouse, ARIA attributes give the tree the sound and feel of a tree in a desktop application. - So, screen reader users will commonly expect that pressing the right arrow key will expand a collapsed node. - Because the screen reader knows the element is a tree, it also has the ability to instruct a novice user how to operate it. - Similarly, voice recognition software can implement commands for expanding and collapsing branches because it recognizes the element as a tree and can execute appropriate keyboard commands. - All this is only possible if the tree implements the GUI keyboard conventions as described in the ARIA tree pattern. -

- -

- A primary keyboard navigation convention common across all platforms is that the tab and shift+tab keys move focus from one UI component to another while other keys, primarily the arrow keys, move focus inside of components that include multiple focusable elements. - The path that the focus follows when pressing the tab key is known as the tab sequence or tab ring. -

- -

- Common examples of UI components that contain multiple focusable elements are radio groups, tablists, menus, and grids. - A radio group, for example, contains multiple radio buttons, each of which is focusable. - However, only one of the radio buttons is included in the tab sequence. - After pressing the Tab key moves focus to a radio button in the group, pressing arrow keys moves focus among the radio buttons in the group, and pressing the Tab key moves focus out of the radio group to the next element in the tab sequence. -

- -

- The ARIA specification refers to a discrete UI component that contains multiple - focusable elements as a composite - widget. The process of controlling focus movement inside a composite is called - managing focus. Following are some ARIA design patterns with example implementations - that demonstrate focus management: -

- - -
- -
-

Discernible and Predictable Keyboard Focus

-

Work to complete this section is tracked by issue 217.

-

- When operating with a keyboard, two essentials of a good experience are the abilities to easily discern the location of the keyboard focus and to discover where focus landed after a navigation key has been pressed. - The following factors affect to what extent a web page affords users these capabilities. -

- -
    -
  1. Visibility of the focus indicator: Users need to be able to easily distinguish the keyboard focus indicator from other features of the visual design. Just as a mouse user may move the mouse to help find the mouse pointer, a keyboard user may press a navigation key to watch for movement. If visual changes in response to focus movement are subtle, many users will lose track of focus and be unable to operate. Authors are advised to rely on the default focus indicators provided by browsers. If overriding the default, consider: -
      -
    • something about ... Colors and gradients can disappear in high contrast modes.
      • -
    • Users need to be able to easily distinguish between focus and selection as described in , especially when a component that contains selected elements does not contain the focus.
      • -
    • ... other considerations to be added ...
      • -
    -
    2. - -
  2. Persistence of focus: It is essential that there is always a component within the user interface that is active (document.activeElement is not null or is not the body element) and that the active element has a visual focus indicator. Authors need to manage events that effect the currently active element so focus remains visible and moves logically. For example, if the user closes a dialog or performs a destructive operation like deleting an item from a list, the active element may be hidden or removed from the DOM. If such events are not managed to set focus on the button that triggered the dialog or on the list item following the deleted item, browsers move focus to the body element, effectively causing a loss of focus within the user interface.
    3. - -
  3. - Predictability of movement: Usability of a keyboard interface is heavily influenced by how readily users can guess where focus will land after a navigation key is pressed. - Some possible approaches to optimizing predictability include: - -
      -
    • - Move focus in a pattern that matches the reading order of the page's language. In left to right languages, for example, create a tab sequence that moves focus left to right and then top to bottom. -
      • - -
    • - Incorporate all elements of a section of the page in the tab sequence before moving focus to another section. For instance, in a page - with multiple columns that has content in a left side bar, center region, and right side bar, build a tab sequence that covers all elements in the left sidebar before focus moves to the first focusable element in the center column. -
      • - -
    • - When the distance between two consecutive elements in the tab sequence is significant, avoid movement that would be perceived as backward. - For example, on a page with a left to right language, a jump from the last element in the bottom right of the main content to the top element in a left-hand sidebar is likely to be less predictable and more difficult to follow, especially for users with a narrow field of view. -
      • - -
    • - Follow consistent patterns across a site. - The keyboard experience is more predictable when similar pages have similar focus movement patterns. -
      • - -
    • Do not set initial focus when the page loads except in cases where: -
        -
      • The page offers a single, primary function that nearly all users employ immediately after page load.
        • -
      • Any given user is likely to use the page often.
        • -
      -
      • -
    -
    4. -
-
- -
-

Focus VS Selection and the Perception of Dual Focus

- -

- Occasionally, it may appear as if two elements on the page have focus at the same time. - For example, in a multi-select list box, when an option is selected it may be greyed. - Yet, the focus indicator can still be moved to other options, which may also be selected. - Similarly, when a user activates a tab in a tablist, the selected state is set on the tab and its visual appearance changes. - However, the user can still navigate, moving the focus indicator elsewhere on the page while the tab retains its selected appearance and state. -

- -

- Focus and selection are quite different. - From the keyboard user's perspective, focus is a pointer, like a mouse pointer; it tracks the path of navigation. - There is only one point of focus at any time and all operations take place at the point of focus. - On the other hand, selection is an operation that can be performed in some widgets, such as list boxes, trees, and tablists. - If a widget supports only single selection, then only one item can be selected and very often the selected state will simply follow the focus when focus is moved inside of the widget. - That is, in some widgets, moving focus may also perform the select operation. - However, if the widget supports multiple selection, then more than one item can be in a selected state, and keys for moving focus do not perform selection. - Some multi-select widgets do support key commands that both move focus and change selection, but those keys are different from the normal navigation keys. - Finally, when focus leaves a widget that includes a selected element, the selected state persists. -

- -

- From the developer's perspective, the difference is simple -- the focused element is the active element (document.activeElement). - Selected elements are elements that have aria-selected="true". -

- -

With respect to focus and the selected state, the most important considerations for designers and developers are:

- - -
- -
-

Deciding When to Make Selection Automatically Follow Focus

-

in composite widgets where only one element may be selected, such as a tablist or single-select listbox, moving the focus may also cause the focused element to become the selected element. This is called having selection follow focus. Having selection follow focus is often beneficial to users, but in some circumstances, it is extremely detrimental to accessibility.

-

- For example, in a tablist, the selected state is used to indicate which panel is displayed. - So, when selection follows focus in a tablist, moving focus from one tab to another automatically changes which panel is displayed. - If the content of panels is present in the DOM, then displaying a new panel is nearly instantaneous. - A keyboard user who wishes to display the fourth of six tabs can do so with 3 quick presses of the right arrow. - And, a screen reader user who perceives the labels on tabs by navigating through them may efficiently read through the complete list without any latency. -

-

However, if displaying a new panel causes a network request and possibly a page refresh, the effect of having selection automatically focus can be devastating to the experience for keyboard and screen reader users. In this case, displaying the fourth tab or reading through the list becomes a tedious and time-consuming task as the user experiences significant latency with each movement of focus. Further, if displaying a new tab refreshes the page, then the user not only has to wait for the new page to load but also return focus to the tab list.

-

- When selection does not follow focus, the user changes which element is selected by pressing the Enter or Space key. -

-
- -
-

Keyboard Navigation Between Components (The Tab Sequence)

- -

As explained in section , all interactive UI components need to be reachable via the keyboard. This is best achieved by either including them in the tab sequence or by making them accessible from a component that is in the tab sequence, e.g., as part of a composite component. This section addresses building and managing the tab sequence, and subsequent sections cover making focusable elements that are contained within components keyboard accessible.

- -

- The [[HTML]] tabindex and [[SVG2]] tabindex attributes can be used to add and remove elements from the tab sequence. - The value of tabindex can also influence the order of the tab sequence, although authors are strongly advised not to use tabindex for that purpose. -

- -

- In HTML, the default tab sequence of a web page includes only links and HTML form elements, except In macOS, where it includes only form elements. - macOS system preferences include a keyboard setting that enables the tab key to move focus to all focusable elements. -

- -

- The default order of elements in the tab sequence is the order of elements in the DOM. - The DOM order also determines screen reader reading order. - It is important to keep the keyboard tab sequence and the screen reader reading order aligned, logical, and predictable as described in . - The most robust method of manipulating the order of the tab sequence while also maintaining alignment with the reading order that is currently available in all browsers is rearranging elements in the DOM. -

- -

The values of the tabindex attribute have the following effects.

- -
-
tabindex is not present or does not have a valid value
-
- The element has its default focus behavior. - In HTML, only form controls and anchors with an HREF attribute are included in the tab sequence. -
-
tabindex="0"
-
The element is included in the tab sequence based on its position in the DOM.
-
tabindex="-1"
-
The element is not included in the tab sequence but is focusable with element.focus().
-
tabindex="X" where X is an integer in the range 1 <= X <= 32767
-
- Authors are strongly advised NOT to use these values. - The element is placed in the tab sequence based on the value of tabindex. - Elements with a tabindex value of 0 and elements that are focusable by default will be in the sequence after elements with a tabindex value of 1 or greater. -
-
-
- -
-

Keyboard Navigation Inside Components

- -

- As described in section , the tab sequence should include only one focusable element of a composite UI component. - Once a composite contains focus, keys other than Tab and Shift + Tab enable the user to move focus among its focusable elements. - Authors are free to choose which keys move focus inside of a composite, but they are strongly advised to use the same key bindings as similar components in common GUI operating systems as demonstrated in . -

- -

The convention for where focus lands in a composite when it receives focus as a result of a Tab key event depends on the type of composite. It is typically one of the following.

- - - -

- The following sections explain two strategies for managing focus inside composite elements: creating a roving tabindex and using the aria-activedescendant property. -

- -
-

Managing Focus Within Components Using a Roving tabindex

- -

- When using roving tabindex to manage focus in a composite UI component, the element that is to be included in the tab sequence has tabindex of "0" and all other focusable elements contained in the composite have tabindex of "-1". - The algorithm for the roving tabindex strategy is as follows. -

- -
    -
  • When the component container is loaded or created, set tabindex="0" on the element that will initially be included in the tab sequence and set tabindex="-1" on all other focusable elements it contains.
    • -
  • - When the component contains focus and the user presses a navigation key that moves focus within the component, such as an arrow key: - -
      -
    • set tabindex="-1" on the element that has tabindex="0".
      • -
    • Set tabindex="0" on the element that will become focused as a result of the key event.
      • -
    • Set focus, element.focus(), on the element that has tabindex="0".
      • -
    -
    • - -
  • - If the design calls for a specific element to be focused the next time the user moves focus into the composite with Tab or Shift+Tab, check if that target element has tabindex="0" when the composite loses focus. - If it does not, set tabindex="0" on the target element and set tabindex="-1" on the element that previously had tabindex="0". -
    • -
- -

- One benefit of using roving tabindex rather than aria-activedescendant to manage focus is that the user agent will scroll the newly focused element into view. -

-
- -
-

Managing Focus in Composites Using aria-activedescendant

- -

- If a component container has an ARIA role that supports the aria-activedescendant property, it is not necessary to manipulate the tabindex attribute and move DOM focus among focusable elements within the container. - Instead, only the container element needs to be included in the tab sequence. When the container has DOM focus, the value of aria-activedescendant on the container tells assistive technologies which element is active within the widget. - Assistive technologies will consider the element referred to as active to be the focused element even though DOM focus is on the element that has the aria-activedescendant property. - And, when the value of aria-activedescendant is changed, assistive technologies will receive focus change events equivalent to those received when DOM focus actually moves. -

- -

The steps for using the aria-activedescendant method of managing focus are as follows.

- -
    -
  • When the container element that has a role that supports aria-activedescendant is loaded or created, ensure that: -
      -
    • The container element is included in the tab sequence as described in or is a focusable element of a composite that implements a roving tabindex.
      • -
    • - It has aria-activedescendant="IDREF" where IDREF is the ID of the element within the container that should be identified as active when the widget receives focus. - The referenced element needs to meet the DOM relationship requirements described below. -
      • -
    -
    • -
  • When the container element receives DOM focus, draw a visual focus indicator on the active element and ensure the active element is scrolled into view.
    • -
  • When the composite widget contains focus and the user presses a navigation key that moves focus within the widget, such as an arrow key: -
      -
    • Change the value of aria-activedescendant on the container to refer to the element that should be reported to assistive technologies as active.
      • -
    • Move the visual focus indicator and, if necessary, scrolled the active element into view.
      • -
    -
    • -
  • - If the design calls for a specific element to be focused the next time a user moves focus into the composite with Tab or Shift+Tab, check if aria-activedescendant is referring to that target element when the container loses focus. - If it is not, set aria-activedescendant to refer to the target element. -
    • -
- -

- The specification for aria-activedescendant places important restrictions on the DOM relationship between the focused element that has the aria-activedescendant attribute and the element referenced as active by the value of the attribute. - One of the following three conditions must be met. -

-
    -
  1. The element referenced as active is a DOM descendant of the focused referencing element.
    2. -
  2. The focused referencing element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
    3. -
  3. The focused referencing element has role of combobox, textbox, or searchbox and has aria-controls property referring to an element with a role that supports aria-activedescendant and either: -
      -
    1. The element referenced as active is a descendant of the controlled element.
      2. -
    2. The controlled element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
      3. -
    -
    4. -
-
-
-
-

Focusability of disabled controls

-

- By default, disabled HTML input elements are removed from the tab sequence. - In most contexts, the normal expectation is that disabled interactive elements are not focusable. - However, there are some contexts where it is common for disabled elements to be focusable, especially inside of composite widgets. - For example, as demonstrated in the pattern, disabled items are focusable when navigating through a menu with the arrow keys. -

- -

- Removing focusability from disabled elements can offer users both advantages and disadvantages. - Allowing keyboard users to skip disabled elements usually reduces the number of key presses required to complete a task. - However, preventing focus from moving to disabled elements can hide their presence from screen reader users who "see" by moving the focus. -

- -

- Authors are encouraged to adopt a consistent set of conventions for the focusability of disabled elements. - The examples in this guide adopt the following conventions, which both reflect common practice and attempt to balance competing concerns. -

- -
    -
  1. For elements that are in the tab sequence when enabled, remove them from the tab sequence when disabled.
    2. - -
  2. - For the following composite widget elements, keep them focusable when disabled: - - -
    3. - -
  3. - For elements contained in a toolbar, make them focusable if discoverability is a concern. Here are two examples to aid with this judgment. - -
      -
    1. - A toolbar with buttons for moving, removing, and adding items in a list includes buttons for "Up", "Down", "Add", and "Remove". - The "Up" button is disabled and its focusability is removed when the first item in the list is selected. - Given the presence of the "Down" button, discoverability of the "Up" button is not a concern. -
      2. - -
    2. - A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard. - It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar. -
      3. -
    -
    4. -
- -

One design technique for mitigating the impact of including disabled elements in the path of keyboard focus is employing appropriate keyboard shortcuts as described in .

-
-
-

Key Assignment Conventions for Common Functions

-

- The following key assignments can be used in any context where their conventionally associated functions are appropriate. - While the assignments associated with Windows and Linux platforms can be implemented and used in browsers running in macOS, - replacing them with macOS assignments in browsers running on a macOS device can make the keyboard interface more discoverable and intuitive for those users. - In some cases, it may also help avoid system or browser keyboard conflicts. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FunctionWindows/Linux KeymacOS Key
open context menuShift + F10
Copy to clipboardControl + CCommand + C
Paste from clipboardControl + VCommand + V
Cut to clipboardControl + XCommand + X
undo last actionControl + ZCommand + Z
Redo actionControl + YCommand + Shift + Z
-
-
-

Keyboard Shortcuts

-

- When effectively designed, keyboard shortcuts that focus an element, activate a widget, or both can dramatically enhance usability of frequently used features of a page or site. - This section addresses some of the keyboard shortcut design and implementation factors that most impact their effectiveness, including: -

-
    -
  1. Understanding how keyboard shortcuts augment a keyboard interface and whether to make a particular shortcut move focus, perform a function, or both.
    2. -
  2. Making key assignments and avoiding assignment conflicts with assistive technologies, browsers, and operating systems.
    3. -
  3. Exposing and documenting key assignments.
    4. -
-
-

Designing the Scope and Behavior of Keyboard Shortcuts

- -

This section explains the following factors when determining which elements and features to assign keyboard shortcuts and what behavior to give each shortcut:

- -
    -
  1. Ensuring discovery through navigation; keyboard shortcuts enhance, not replace, standard keyboard access.
    2. - -
  2. - Effectively choosing from among the following behaviors: - -
      -
    1. Navigation: Moving focus to an element.
      2. -
    2. Activation: Performing an operation associated with an element that does not have focus and might not be visible.
      3. -
    3. Navigation and activation: Both moving focus to an element and activating it.
      4. -
    -
    3. - -
  3. Balancing efficiency and cognitive load: lack of a shortcut can reduce efficiency while too many shortcuts can increase cognitive load and clutter the experience.
    4. -
- -
-
Ensure Basic Access Via Navigation
- -

- Before assigning keyboard shortcuts, it is essential to ensure the features and functions to which shortcuts may be assigned are keyboard accessible without a keyboard shortcut. - In other words, all elements that could be targets for keyboard shortcuts need to be focusable via the keyboard using the methods described in: -

- -
    -
    • -
    • -
- -

- Do not use keyboard shortcuts as a substitute for access via navigation. - This is essential to full keyboard access because: -

- -
    -
  1. The primary means of making functions and their shortcuts discoverable is by making the target elements focusable and revealing key assignments on the element itself.
    2. -
  2. If people who rely on the keyboard have to read documentation to learn which keys are required to use an interface, the interface may technically meet some accessibility standards but in practice is only accessible to the small subset of them who have the knowledge that such documentation exists, have the extra time available, and the ability to retain the necessary information.
    3. -
  3. Not all devices that depend on keyboard interfaces can support keyboard shortcuts.
    4. -
-
- -
-
Choose Appropriate Shortcut Behavior
- -

The following conventions may help identify the most advantageous behavior for a keyboard shortcut.

- -
    -
  • - Move focus when the primary objective is to make navigation more efficient, e.g., reduce the number of times the user must press Tab or the arrow keys. - This behavior is commonly expected when assigning a shortcut to a text box, toolbar, or composite, such as a listbox, tree, grid, or menubar. - This behavior is also useful for moving focus to a section of a page, such as the main content or a complementary landmark section. -
    • - -
  • Activate an element without moving focus when the target context of the function is the context that contains the focus. This behavior is most common for command buttons and for functions associated with elements that are not visible, such as a "Save" option that is accessible via a menu. For example, if the focus is on an option in a listbox and a toolbar contains buttons for moving and removing options, it is most beneficial to keep focus in the listbox when the user presses a key shortcut for one of the buttons in the toolbar. This behavior can be particularly important for screen reader users because it provides confirmation of the action performed and makes performing multiple commands more efficient. For instance, when a screen reader user presses the shortcut for the "Up" button, the user will be able to hear the new position of the option in the list since it still has the focus. Similarly, when the user presses the shortcut for deleting an option, the user can - hear the next option in the list and immediately decide whether to press the delete shortcut again.
    • - -
  • - Move focus and activate when the target of the shortcut has a single function and the context of that function is the same as the target. - This behavior is typical when a shortcut is assigned to a button that opens a menu or dialog, to a checkbox, or to a navigation link or button. -
    • -
-
- -
-
Choose Where to Add Shortcuts
-

Work to draft content for this section is tracked in issue 219.

-

The first goal when designing a keyboard interface is simple, efficient, and intuitive operation with only basic keyboard navigation support. If basic operation of a keyboard interface is inefficient, attempting to compensate for fundamental design issues, such as suboptimal layout or command structure, by implementing keyboard shortcuts will not likely reduce user frustration. The practical implication of this is that, in most well-designed user interfaces, the percentage of functionality that needs to be accessible via a keyboard shortcut in order to create optimal usability is not very high. In many simple user interfaces, keyboard shortcuts can be entirely superfluous. And, in user interfaces with too many keyboard shortcuts, the excess shortcuts create cognitive load that make the most useful ones more difficult to remember.

-

Consider the following when deciding where to assign keyboard shortcuts:

- -
    -
  1. To be written.
    2. -
-
-
-
-

Assigning Keyboard Shortcuts

-

When choosing the keys to assign to a shortcut, there are many factors to consider.

-
    -
  • Making the shortcut easy to learn and remember by using a mnemonic (e.g., Control + S for "Save") or following a logical or spacial pattern.
    • -
  • Localizing the interface, including for differences in which keys are available and how they behave and for language considerations that could impact mnemonics.
    • -
  • Avoiding and managing conflicts with key assignments used by an assistive technology, the browser, or the operating system.
    • -
-

- Methods for designing a key shortcut scheme that supports learning and memory is beyond the scope of this guide. - Unless the key shortcut scheme is extensive, it is likely sufficient to mimic concepts that are familiar from common desktop software, such as browsers. - Similarly, while localization is important, describing how to address it is left to other resources that specialize in that topic. -

-

- The remainder of this section provides guidance balancing requirements and concerns related to key assignment conflicts. - It is typically ideal if key assignments do not conflict with keys that are assigned to functions in the user's operating system, browser, or assistive technology. - Conflicts can block efficient access to functions that are essential to the user, and a perfect storm of conflicts can trap a user. - At the same time, there are some circumstances where intentional conflicts are useful. - And, given the vast array of operating system, browser, and assistive technology keys, it is almost impossible to be certain conflicts do not exist. - So it is also important to employ strategies that mitigate the impact of conflicts whether they are intentional or unknown. -

-

- In the following sections, meta key refers to the Windows key on Windows-compatible keyboards and the Command key on MacOS-compatible keyboards. -

-
-
Operating System Key Conflicts
- -

It is essential to avoid conflicts with keys that perform system level functions, such as application and window management and display and sound control. In general, this can be achieved by refraining from the following types of assignments.

- -
    -
  1. Any modifier keys + any of Tab, Enter, Space, or Escape.
    2. - -
  2. Meta key + any other single key (there are exceptions, but they can be risky as these keys can change across versions of operating systems).
    3. - -
  3. Alt + a function key.
    4. -
- -

- In addition, there are some important application level features that most applications, including browsers, generally support. - These include: -

- -
    -
  1. Zoom
    2. -
  2. Copy/Paste
    3. -
  3. ... to be continued ...
    4. -
-
- -
-
Assistive Technology Key Conflicts
- -

- Even though assistive technologies have collectively taken thousands of key assignments, avoiding conflicts is relatively easy. - This is because assistive technologies have had to develop key assignment schemes that avoid conflicts with both operating systems and applications. - They do this by hijacking specific keys as modifiers that uniquely define their key commands. - For example, many assistive technologies use the Caps Lock key as a modifier. -

- -

Deflect assistive technology key conflicts by steering clear of the following types of assignments.

- -
    -
  1. Caps Lock + any other combination of keys.
    2. -
  2. Insert + any combination of other keys.
    3. -
  3. Scroll Lock + any combination of other keys.
    4. -
  4. macOS only: Control+Option + any combination of other keys.
    5. -
-
- -
-
Browser Key Conflicts
- -

While there is considerable similarity among browser keyboard schemes, the patterns within the schemes are less homogenous. Consequently, it is more difficult to avoid conflicts with browser key assignments. While the impact of conflicts is sometimes mitigated by the availability of two paths to nearly every function -- keyboard accessible menus and keyboard shortcuts, avoiding conflicts with shortcuts to heavily used functions is nonetheless important. Pay special attention to avoiding conflicts with shortcuts to:

- -
    -
  1. Address or location bar
    2. -
  2. Notification bar
    3. -
  3. Page refresh
    4. -
  4. Bookmark and history functions
    5. -
  5. Find functions
    6. -
-
-
-
Intentional Key Conflicts
- -

- While avoiding key conflicts is usually desirable, there are circumstances where intentionally conflicting with a browser function is acceptable or even desirable. - This can occur when the following combination of conditions arises: -

- -
    -
  • A web application has a frequently used function that is similar to a browser function.
    • -
  • Users will often want to execute the web application function.
    • -
  • Users will rarely execute the browser function.
    • -
  • There is an efficient, alternative path to the browser function.
    • -
- -

For example, consider a save function that is available when the focus is in an editor. Most browsers use ... to be continued ...

-
-
-
-
- -
-

Grid and Table Properties

-

- To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the - grid pattern or table pattern, - assistive technologies need to be able to determine: -

- -

- Browsers automatically populate their accessibility tree with the number of rows and columns in a grid or table based on the rendered DOM. - However, there are many situations where the DOM does not contain the whole grid or table, such as when the data set is too large to fully render. - Additionally, some of this information, like skipped columns or rows and how data is sorted, cannot be derived from the DOM structure. -

-

The below sections explain how to use the following properties that ARIA provides for grid and table accessibility.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Grid and Table Property Definitions
PropertyDefinition
aria-colcountDefines the total number of columns in a table, grid, or treegrid.
aria-rowcountDefines the total number of rows in a table, grid, or treegrid.
aria-colindex -
    -
  • Defines a cell's position with respect to the total number of columns within a table, grid, or treegrid.
    • -
  • Note: Numbering starts with 1, not 0.
    • -
-
aria-rowindex -
    -
  • Defines a cell's position with respect to the total number of rows within a table, grid, or treegrid.
    • -
  • Note: Numbering starts with 1, not 0.
    • -
-
aria-colspanDefines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.
aria-rowspanDefines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.
aria-sortIndicates if items in a row or column are sorted in ascending or descending order.
-
-

Using aria-rowcount and aria-rowindex

-

- When the number of rows represented by the DOM structure is not the total number of rows available for a table, grid, or treegrid, - the aria-rowcount property is used to communicate the total number of rows available, - and it is accompanied by the aria-rowindex property to identify the row indices of the rows that are present in the DOM. -

-

- The aria-rowcount is specified on the element with the table, grid, or treegrid role. - Its value is an integer equal to the total number of rows available, including header rows. - If the total number of rows is unknown, a value of -1 may be specified. - Using a value of -1 indicates that more rows are available to include in the DOM without specifying the size of the available supply. -

-

- When aria-rowcount is used on a table, grid, or treegrid, - a value for aria-rowindex property is specified on each of its descendant rows, including any header rows. - The value of aria-rowindex is an integer that is: -

-
    -
  1. Greater than or equal to 1.
    2. -
  2. Greater than the value of aria-rowindex on any previous rows.
    3. -
  3. Set to the index of the first row in the span if cells span multiple rows.
    4. -
  4. Less than or equal to the total number of rows.
    5. -
-

- WARNING! Missing or inconsistent values of aria-rowindex could have devastating effects on assistive technology behavior. - For example, specifying an invalid value for aria-rowindex or setting it on some but not all rows in a table, could cause screen reader table reading functions to skip rows or simply stop functioning. -

-

- The following code demonstrates the use of aria-rowcount and aria-rowindex properties on a table containing a hypothetical class list. -

- 
-        
-          <!--
-            aria-rowcount tells assistive technologies the actual size of the grid
-            is 463 rows even though only 4 rows are present in the markup.
-          -->
-          <table role="grid" aria-rowcount="463">
-            aria-label="Student roster for history 101"
-            <thead>
-              <tr aria-rowindex="1">
-                <th>Last Name</th>
-                <th>First Name</th>
-                <th>E-mail</th>
-                <th>Major</th>
-                <th>Minor</th>
-                <th>Standing</th>
-              </tr>
-            </thead>
-            <tbody>
-                <!--
-                  aria-rowindex tells assistive technologies that this
-                  row is row 51 in the grid of 463 rows.
-                -->
-              <tr aria-rowindex="51">
-                <td>Henderson</td>
-                <td>Alan</td>
-                <td>ahederson56@myuniveristy.edu</td>
-                <td>Business</td>
-                <td>Spanish</td>
-                <td>Junior</td>
-              </tr>
-                <!--
-                  aria-rowindex tells assistive technologies that this
-                  row is row 52 in the grid of 463 rows.
-                -->
-              <tr aria-rowindex="52">
-                <td>Henderson</td>
-                <td>Alice</td>
-                <td>ahederson345@myuniveristy.edu</td>
-                <td>Engineering</td>
-                <td>none</td>
-                <td>Sophomore</td>
-              </tr>
-                <!--
-                  aria-rowindex tells assistive technologies that this
-                  row is row 53 in the grid of 463 rows.
-                -->
-              <tr aria-rowindex="53">
-                <td>Henderson</td>
-                <td>Andrew</td>
-                <td>ahederson75@myuniveristy.edu</td>
-                <td>General Studies</td>
-                <td>none</td>
-                <td>Freshman</td>
-              </tr>
-            </tbody>
-          </table>
-        
-
-
-
-

Using aria-colcount and aria-colindex

-

- When the number of columns represented by the DOM structure is not the total number of columns available for a table, grid, or treegrid, - the aria-colcount property is used to communicate the total number of columns available, - and it is accompanied by the aria-colindex property to identify the column indices of the columns that are present in the DOM. -

-

- The aria-colcount is specified on the element with the table, grid, or treegrid role. - Its value is an integer equal to the total number of columns available. - If the total number of columns is unknown, a value of -1 may be specified. - Using a value of -1 indicates that more columns are available to include in the DOM without specifying the size of the available supply. -

-

- When aria-colcount is used on a table, grid, or treegrid, - a value for aria-colindex property is either specified on each of its descendant rows or on every cell in each descendant row, depending on whether the columns are contiguous as described below. - The value of aria-colindex is an integer that is: -

-
    -
  1. Greater than or equal to 1.
    2. -
  2. When set on a cell, greater than the value set on any previous cell within the same row.
    3. -
  3. Set to the index of the first column in the span if a cell spans multiple columns.
    4. -
  4. Less than or equal to the total number of columns.
    5. -
-

- WARNING! Missing or inconsistent values of aria-colindex could have devastating effects on assistive technology behavior. - For example, specifying an invalid value for aria-colindex or setting it on some but not all cells in a row, could cause screen reader table reading functions to skip cells or simply stop functioning. -

-
-

Using aria-colindex When Column Indices Are Contiguous

-

- When all the cells in a row have column index numbers that are consecutive integers, - aria-colindex can be set on the row element with a value equal to the index number of the first column in the set. - Browsers will then compute a column number for each cell in the row. -

-

- The following code shows a grid with 16 columns, of which columns 2 through 5 are displayed to the user. - Because the set of columns is contiguous, aria-colindex can be placed on each row. -

- 
-        
-<div role="grid" aria-colcount="16">
-  <div role="rowgroup">
-    <div role="row" aria-colindex="2">
-      <span role="columnheader">First Name</span>
-      <span role="columnheader">Last Name</span>
-      <span role="columnheader">Company</span>
-      <span role="columnheader">Address</span>
-    </div>
-  </div>
-  <div role="rowgroup">
-    <div role="row" aria-colindex="2">
-      <span role="gridcell">Fred</span>
-      <span role="gridcell">Jackson</span>
-      <span role="gridcell">Acme, Inc.</span>
-      <span role="gridcell">123 Broad St.</span>
-    </div>
-    <div role="row" aria-colindex="2">
-      <span role="gridcell">Sara</span>
-      <span role="gridcell">James</span>
-      <span role="gridcell">Acme, Inc.</span>
-      <span role="gridcell">123 Broad St.</span>
-    </div>
-   …
-  </div>
-</div>
-
-
-
-
-

Using aria-colindex When Column Indices Are Not Contiguous

-

- When the cells in a row have column index numbers that are not consecutive integers, aria-colindex needs to be set on each cell in the row. - The following example shows a grid for an online grade book where the first two columns contain a student name and subsequent columns contain scores. - In this example, the first two columns with the student name are shown, but the score columns have been scrolled to show columns 10 through 13. - Columns 3 through 9 are not visible so are not in the DOM. -

- 
-          
-            <table role="grid" aria-rowcount="463" aria-colcount="13">
-              aria-label="Student grades for history 101"
-              <!--
-                aria-rowcount and aria-colcount tell assistive technologies
-                the actual size of the grid is 463 rows by 13 columns,
-                which is not the number rows and columns found in the markup.
-              -->
-              <thead>
-                <tr aria-rowindex="1">
-                  <!--
-                    aria-colindex tells assistive technologies that the
-                    following columns represent columns 1 and 2 of the total data set.
-                  -->
-                  <th aria-colindex="1">Last Name</th>
-                  <th aria-colindex="2">First Name</th>
-                  <!--
-                    aria-colindex tells users of assistive technologies that the
-                    following columns represent columns 10, 11, 12, and 13 of
-                    the overall data set of grades.
-                  -->
-                  <th aria-colindex="10">Homework 4</th>
-                  <th aria-colindex="11">Quiz 2</th>
-                  <th aria-colindex="12">Homework 5</th>
-                  <th aria-colindex="13">Homework 6</th>
-                </tr>
-              </thead>
-              <tbody>
-                <tr aria-rowindex="50">
-                  <!--
-                    every cell needs to define the aria-colindex attribute
-                  -->
-                  <td aria-colindex="1">Henderson</td>
-                  <td aria-colindex="2">Alan</td>
-                  <td aria-colindex="10">8</td>
-                  <td aria-colindex="11">25</td>
-                  <td aria-colindex="12">9</td>
-                  <td aria-colindex="13">9</td>
-                </tr>
-                <tr aria-rowindex="51">
-                  <td aria-colindex="1">Henderson</td>
-                  <td aria-colindex="2">Alice</td>
-                  <td aria-colindex="10">10</td>
-                  <td aria-colindex="11">27</td>
-                  <td aria-colindex="12">10</td>
-                  <td aria-colindex="13">8</td>
-                </tr>
-                <tr aria-rowindex="52">
-                  <td aria-colindex="1">Henderson</td>
-                  <td aria-colindex="2">Andrew</td>
-                  <td aria-colindex="10">9</td>
-                  <td aria-colindex="11">0</td>
-                  <td aria-colindex="12">29</td>
-                  <td aria-colindex="13">8</td>
-                </tr>
-              </tbody>
-            </table>
-          
-
-
-
-
-

Defining cell spans using aria-colspan and aria-rowspan

-

- For tables, grids, and treegrids created using elements other than HTML table elements, - row and column spans are defined with the aria-rowspan and aria-colspan properties. -

-

The value of aria-colspan is an integer that is:

-
    -
  1. Greater than or equal to 1.
    2. -
  2. less than the value that would cause the cell to overlap the next cell in the same row.
    3. -
-

The value of aria-rowspan is an integer that is:

-
    -
  1. Greater than or equal to 0.
    2. -
  2. 0 means the cell spans all the remaining rows in its row group.
    3. -
  3. less than the value that would cause the cell to overlap the next cell in the same column.
    4. -
-

- The following example grid has a two row header. - The first two columns have headers that span both rows of the header. - The subsequent 6 columns are grouped into 3 pairs with headers in the first row that each span two columns. -

- 
-        
-          <div role="grid" aria-rowcount="463">
-            aria-label="Student grades for history 101"
-            <div role="rowgroup">
-              <div role="row" aria-rowindex="1">
-                  <!--
-                    aria-rowspan and aria-colspan provide
-                    assistive technologies with the correct data cell header information
-                    when header cells span more than one row or column.
-                  -->
-                  <span role="columnheader" aria-rowspan="2">Last Name</span>
-                  <span role="columnheader" aria-rowspan="2">First Name</span>
-                  <span role="columnheader" aria-colspan="2">Test 1</span>
-                  <span role="columnheader" aria-colspan="2">Test 2</span>
-                  <span role="columnheader" aria-colspan="2">Final</span>
-              </div>
-              <div role="row" aria-rowindex="2">
-                  <span role="columnheader">Score</span>
-                  <span role="columnheader">Grade</span>
-                  <span role="columnheader">Score</span>
-                  <span role="columnheader">Grade</span>
-                  <span role="columnheader">Total</span>
-                  <span role="columnheader">Grade</span>
-              </div>
-            </div>
-            <div role="rowgroup">
-              <div role="row" aria-rowindex="50">
-                <span role="cell">Henderson</span>
-                <span role="cell">Alan</span>
-                <span role="cell">89</span>
-                <span role="cell">B+</span>
-                <span role="cell">72</span>
-                <span role="cell">C</span>
-                <span role="cell">161</span>
-                <span role="cell">B-</span>
-              </div>
-              <div role="row" aria-rowindex="51">
-                <span role="cell">Henderson</span>
-                <span role="cell">Alice</span>
-                <span role="cell">94</span>
-                <span role="cell">A</span>
-                <span role="cell">86</span>
-                <span role="cell">B</span>
-                <span role="cell">180</span>
-                <span role="cell">A-</span>
-              </div>
-              <div role="row" aria-rowindex="52">
-                <span role="cell">Henderson</span>
-                <span role="cell">Andrew</span>
-                <span role="cell">82</span>
-                <span role="cell">B-</span>
-                <span role="cell">95</span>
-                <span role="cell">A</span>
-                <span role="cell">177</span>
-                <span role="cell">B+</span>
-              </div>
-            </div>
-          </div>
-        
-
-

- Note: When using HTML table elements, - use the native semantics of the th and td elements to define row and column spans - by using the rowspan and colspan attributes. -

-
-
-

Indicating sort order with aria-sort

-

- When rows or columns are sorted, the aria-sort property can be applied to a column or row header to indicate the sorting method. - The following table describes allowed values for aria-sort. -

- - - - - - - - - - - - - - - - - - - - - - - - - - -
- Description of values for aria-sort -
ValueDescription
ascendingData are sorted in ascending order.
descendingData are sorted in descending order.
otherData are sorted by an algorithm other than ascending or descending.
noneDefault (no sort applied).
-

- It is important to note that ARIA does not provide a way to indicate levels of sort for data sets that have multiple sort keys. - Thus, there is limited value to applying aria-sort with a value other than none to more than one column or row. -

-

The following example grid uses aria-sort to indicate the rows are sorted from the highest "Quiz 2" score to the lowest "Quiz 2" score.

- 
-        
-          <table role="grid" aria-rowcount="463" aria-colcount="13"
-            aria-label="Student grades for history 101">
-            <thead>
-              <tr aria-colindex="10" aria-rowindex="1">
-                <th>Homework 4</th>
-                <!--
-                  aria-sort indicates the column with the heading
-                  "Quiz 2" has been used to sort the rows of the grid.
-                -->
-                <th aria-sort="descending">Quiz 2</th>
-                <th>Homework 5</th>
-                <th>Homework 6</th>
-              </tr>
-            </thead>
-            <tbody>
-              <tr aria-colindex="10" aria-rowindex="50">
-                <td>8</td>
-                <td>30</td>
-                <td>9</td>
-                <td>9</td>
-              </tr>
-              <tr aria-colindex="10"  aria-rowindex="51">
-                <td>10</td>
-                <td>29</td>
-                <td>10</td>
-                <td>8</td>
-              </tr>
-              <tr aria-colindex="10"  aria-rowindex="52">
-                <td>9</td>
-                <td>9</td>
-                <td>27</td>
-                <td>6</td>
-              </tr>
-              <tr aria-colindex="10"  aria-rowindex="53">
-                <td>9</td>
-                <td>10</td>
-                <td>26</td>
-                <td>8</td>
-              </tr>
-              <tr aria-colindex="10"  aria-rowindex="54">
-                <td>9</td>
-                <td>7</td>
-                <td>24</td>
-                <td>6</td>
-              </tr>
-            </tbody>
-          </table>
-        
-
- - -
- -
- - - -
-

Intentionally Hiding Semantics with the presentation Role

-

- While ARIA is primarily used to express semantics, there are some situations where hiding an - element’s semantics from assistive technologies is helpful. This is done with the - presentation - role, which declares that an element is being used only for presentation and therefore does - not have any accessibility semantics. The ARIA 1.1 specification also includes role - none, - which serves as a synonym for presentation. -

-

- For example, consider a tabs widget built using an HTML ul element. -

- 
-    <ul role="tablist">
-      <li role="presentation">
-        <a role="tab" href="#">Tab 1</a>
-      </li>
-      <li role="presentation">
-        <a role="tab" href="#">Tab 2</a>
-      </li>
-      <li role="presentation">
-        <a role="tab" href="#">Tab 3</a>
-      </li>
-    </ul>
-
-

- Because the list is declared to be a tablist, the list items are not in a list context. It - could confuse users if an assistive technology were to render those list items. Applying role - presentation to the li elements tells browsers to leave those - elements out of their accessibility tree. Assistive technologies will thus be unaware of the - list item elements and see the tab elements as immediate children of the tablist. -

-

- Three common uses of role presentation are: -

-
    -
  1. Hiding a decorative image; it is equivalent to giving the image null alt text.
    2. -
  2. Suppressing table semantics of tables used for layout in circumstances where the table semantics do not convey meaningful relationships.
    3. -
  3. Eliminating semantics of intervening orphan elements in the structure of a composite - widget, such as a tablist, menu, or tree as demonstrated in the example above.
    4. -
-
-

- Effects of Role presentation -

-

- When role="presentation" is specified on an element, if a - condition that requires a browser to ignore the presentation role - does not exist, it has the following three effects. -

-
    -
  1. The element’s implied ARIA role and any ARIA states and properties associated with - that role are hidden from assistive technologies.
    2. -
  2. - Text contained by the element, i.e., inner text, as well as inner text of all its - descendant elements remains visible to assistive technologies except, of course, when the - text is explicitly hidden, e.g., styled with display: none or has aria-hidden="true". -
    3. -
  3. - The roles, states, and properties of each descendant element remain visible to assistive - technologies unless the descendant requires the context of the presentational - element. For example: -
      -
    • If presentation is applied to a ul or ol element, each child li element inherits the presentation role because ARIA requires the listitem elements to have the parent list element. So, the li elements are not exposed to assistive technologies, but elements contained inside of those li elements, including nested lists, are visible to assistive technologies.
      • -
    • - Similarly, if presentation is applied to a table element, - the descendant caption, thead, tbody, tfoot, - tr, th, and td - elements inherit role presentation and are thus not exposed to assistive technologies. - But, elements inside of the th and td elements, including nested tables, are exposed to assistive technologies. -
      • -
    -
    4. -
-
-
-

- Conditions That Cause Role presentation to be Ignored -

-

- Browsers ignore role="presentation", and it therefore has no effect, if either of the following are true about the element to which it is applied:

- -
-
-

- Example Demonstrating Effects of the presentation Role -

-

This code:

- 
-        <ul role="presentation">
-          <li>Date of birth:</li>
-          <li>January 1, 3456</li>
-        </ul>
-
-

when parsed by a browser, is equivalent to the following from the perspective of a screen reader or other assistive technology that relies on the browser's accessibility tree: -

- 
-        <div>Date of birth:</div>
-          <div>January 1, 3456</div>
-
-
-
- -
-

Roles That Automatically Hide Semantics by Making Their Descendants Presentational

-

- There are some types of user interface components that, when represented in a platform - accessibility API, can only contain text. For example, accessibility APIs do not have a way of - representing semantic elements contained in a button. To deal with this limitation, WAI-ARIA - requires browsers to automatically apply role presentation to all descendant - elements of any element with a role that cannot support semantic children. -

-

The roles that require all children to be presentational are:

- -

For instance, consider the following tab element, which contains a heading.

- 
-      <li role="tab"><h3>Title of My Tab</h3></li>
-
-

- Because WAI-ARIA requires descendants of tab to be presentational, - the following code is equivalent. -

- 
-      <li role="tab"><h3 role="presentation">Title of My Tab</h3></li>
-
-

- And, from the perspective of anyone using a technology that relies on an accessibility API, such as a screen reader, - the heading does not exist since the previous code is equivalent to the following. -

- 
-      <li role="tab">Title of My Tab</li>
-
-

- See the - - section about role presentation - - for a detailed explanation of what it does. -

-
- -
-

Structural Roles

-

- ARIA provides a set of roles that convey the accessibility semantics of structures on a page. - These roles express the meaning that is conveyed by the layout and appearance of elements that organize and structure content, such as headings, lists, and tables. -

-

- some host languages, such as HTML, include elements that express the same semantics as an ARIA role. - For instance, the HTML <p> element is mapped to accessibility APIs in exactly the same way as <div role="paragraph">. - The ARIA and HTML specifications refer to this mapping of HTML elements to ARIA attributes as implied semantics, i.e., the implied ARIA role of the HTML <p> element is paragraph. -

-

- When developing HTML, it is important to use native HTML elements where ever possible. - Do not use an ARIA role or property if it is possible to use an HTML element that has equivalent semantics. - Circumstances where it is appropriate to use ARIA attributes instead of equivalent HTML are: -

-
    -
  1. When the HTML element cannot be styled in a way that meets visual design requirements.
    2. -
  2. When testing reveals that browsers or assistive technologies provide better support for the ARIA equivalent.
    3. -
  3. When remediating or retrofitting legacy content and altering the underlying DOM to use the HTML would be cost prohibitive.
    4. -
  4. When building a web component to compose a custom element and the element being extended does not convey the appropriate or sufficient accessibility semantics.
    5. -
-

The following table lists all structural roles defined in ARIA 1.2.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ARIA structural roles
ARIA RoleHTML Equivalent
applicationNo equivalent element
articlearticle
blockquoteblockquote
captioncaption
celltd
codecode
columnheaderth
definitiondd
deletiondel
directoryNo equivalent element
documentNo equivalent element
emphasisem
feedNo equivalent element
figurefigure
genericdiv, span
groupNo equivalent element
heading with aria-level="N" where N is 1, 2, 3, 4, 5, or 6h1, h2, h3, h4, h5, h6
insertionins
imgimg
listul, ol
listitemli
mathNo equivalent element
noneNo equivalent element
noteNo equivalent element
presentationNo equivalent element
paragraphp
rowtr
rowgrouptbody, thead, tfoot
rowheaderth
separator (when not focusable)hr
strongstrong
subscriptsub
superscriptsup
tabletable
termdfn
timetime
toolbarNo equivalent element
tooltipNo equivalent element
-
- -
-

Indexes

- -
- -
-

Change History

- -

- APG 1.1 supported ARIA 1.1, and this version, APG 1.2, includes changes to support version 1.2 of the ARIA specification. - It also includes nearly 200 significant updates to improve the quality and breadth of content. - A detailed log of all changes is available on the wiki of the w3c/aria-practices GitHub repository. - Highlights of major changes to support ARIA 1.2 as well as some of the improvements include the following. -

- -

Comprehensive lists of closed issues included in APG 1.2 release 1 are tracked in the following GitHub milestones.

- - -
- -
-

Acknowledgements

-
-

Honorary Editor

-

- This version of the ARIA Authoring Practices Guide is dedicated to the memory of Carolyn MacLeod whose contributions are visible throughout the entire guide. - She was dedicated to all aspects of the work of the APG Task Force from writing code and suggesting editorial revisions to testing examples with assistive technologies. -

- -
-
-

Major Contributors to Version 1.1

-

- While WAI-ARIA Authoring Practices 1.1 is the work of the entire Authoring Practices Task Force and also benefits from many people throughout the open source community who both contribute significant work and provide valuable feedback, - special thanks goes to the following people who provided distinctly large portions of the content and code in version 1.1. -

- -
-
-

Participants active in the ARIA Authoring Practices Task Force

- -
-
-

Other commenters and contributors to Version 1.1

- -
- -
- -
- - diff --git a/examples/coding-template/Depricated-MultipleImplementationExample-Template.html b/content-templates/Depricated-MultipleImplementationExample-Template.html similarity index 100% rename from examples/coding-template/Depricated-MultipleImplementationExample-Template.html rename to content-templates/Depricated-MultipleImplementationExample-Template.html diff --git a/content-templates/Example-Template.html b/content-templates/Example-Template.html new file mode 100644 index 0000000000..4a6231b8e7 --- /dev/null +++ b/content-templates/Example-Template.html @@ -0,0 +1,225 @@ + + + + + + + + + EXAMPLE_NAME Example + + + + + + + + + + + + + + + + + +
+ +

EXAMPLE_NAME Example

+ +
+

About This Example

+

+ + Replace this paragraph with an overview of the example that is something like the following. The below example section demonstrates a simple checkbox that implements the + design pattern for checkbox. + This example uses ... summarize salient techniques ) +

+

Similar examples include:

+ +
+ +
+
+

Example

+
+ + +
+ +

This is the place where the reader will experience the functioning example.

+
    +
  • The HTML in this section along with the javascript and CSS it uses demonstrate the design pattern.
    • +
  • When developing an example implementation for this guide, please follow the APG example coding guidelines.
    • + + + +
+
+ +
+ +
+

Accessibility Features

+

Optional section: If appropriate, please replace this content with a list of any special or noteworthy accessibility features demonstrated in this implementation, such as:

+
    +
  1. What distinguishes this example from related examples.
    2. +
  2. Keyboard shortcuts, live regions, unusual event handling, or other ancillary best practices that are employed.
    3. +
  3. Do not include information that would be repeated in the following keyboard and attribute sections.
    4. +
  4. Delete this section if not needed.
    5. +
+
+ +
+

Keyboard Support

+ + + + + + + + + + + + + + + + + + +
KeyFunction
KeyName + Description of key function. + +
KeyName +
    +
  • If condition 1, performs function 1.
    • +
  • If condition 2, performs function 2.
    • +
  • Only use a list if multiple statements are needed.
    • +
+
+
+ +
+

Role, Property, State, and Tabindex Attributes

+ + + + + + + + + + + + + + + + + + + + + + + + +
RoleAttributeElementUsage
RoleNameHTML_ELEMENTDescribe usage/purpose, e.g., indicates the focusable element that serves as the ...
+ + + AttributeName=AttributeValue + HTML_ELEMENT +
    +
  • explanation of usage, purpose, benefit, and/or guidance relevant to this implementation.
    • +
  • If making multiple statements, use list for brevity and clarity
    • +
  • Do not make a single item list.
    • +
+
+
+ +
+

Javascript and CSS Source Code

+ + +
+ +
+

HTML Source Code

+ +
+ + +
+
+ + diff --git a/examples/coding-template/css/example_name.css b/content-templates/css/example_name.css similarity index 100% rename from examples/coding-template/css/example_name.css rename to content-templates/css/example_name.css diff --git a/examples/coding-template/js/example_name.js b/content-templates/js/example_name.js similarity index 100% rename from examples/coding-template/js/example_name.js rename to content-templates/js/example_name.js diff --git a/content/about/about.html b/content/about/about.html new file mode 100644 index 0000000000..1c9e5cb61c --- /dev/null +++ b/content/about/about.html @@ -0,0 +1,299 @@ + + + + + + About + + + + + + + + + +
+

About

+ +
+

Introduction

+

+ The ARIA Authoring Practices Guide (APG) explains how to create accessible web experiences for users of assistive technologies and keyboard interfaces by developing web sites that properly convey accessibility semantics and implement common keyboard conventions. + It also provides guidance on some closely related topics, such as supporting operating system settings for high contrast and reduced motion. +

+

+ Accessibility semantics refer to the meaning of user interface elements that need to be conveyed to assistive technology users in order for those users to understand and use the elements. + For example, people who can visually perceive a search icon button understand the element can be activated to perform a search by the way it is styled and positioned. + To make that icon accessible to a screen reader user, one of the semantics that needs to be communicated is that the element represents an interactive button. + In addition, keyboard accessibility requires the button to be focusable, and keyboard conventions call for pressing Enter or Space to activate the button when it is focused. + The APG describes how to convey accessibility semantics and implement keyboard accessibility for many common design patterns, ranging from typical buttons and popup menus to complex tree grids. + It also explains essential practices related to these patterns, such as how to convey web page structure with ARIA landmark regions and effectively utilize the many ways of encoding accessible names. +

+

+ The APG is organized into two major sections: patterns and practices. + Each pattern explains how to make a common user interface element, such as a button, menu, or dialog, accessible, and provides functional example implementations of the pattern. + The practices section gives in-depth explanation of how to satisfy a variety of accessibility needs that surface when making rich internet application experiences accessible. + For instance, the practices section on providing accessible names and descriptions gives detailed descriptions of seven different naming techniques as well as a table providing guidance for naming more than 80 types of elements. +

+

+ The APG assumes basic understanding of web development, especially of HTML and CSS. + It may be particularly useful to designers and engineers who are working on site design systems and component libraries. + However, it is important to understand that the APG only covers a portion of what is needed to create accessible experiences. + To understand accessibility more broadly, it is advisable to start with the WAI Accessibility Fundamentals and WAI Overview of Design and Development. +

+

+ The accessibility semantics used in the APG patterns and described in APG practices are defined in the + WAI-ARIA 1.2 Specification. + That is, the ARIA specification standardizes the meaning of the attributes that describe elements and their states to assistive technologies, such as the meaning of role="button". + These attributes and other features required to make sites usable by people who rely on assistive technologies or keyboard navigation are not natively included in the languages used to create web sites, such as HTML, JavaScript, CSS, and SVG. + The W3C Web Accessibility Initiative's (WAI) Accessible Rich Internet Applications working group (ARIA WG) is addressing these deficiencies through several W3C standards efforts. + The WAI-ARIA Overview + provides additional background on WAI-ARIA, summarizes those efforts, and lists the other documents included in the WAI-ARIA suite. +

+
+ +
+

Change History

+ +

+ APG 1.1 supported ARIA 1.1, and this version, APG 1.2, includes changes to support version 1.2 of the ARIA specification. + It also includes nearly 200 significant updates to improve the quality and breadth of content. + A detailed log of all changes is available on the wiki of the w3c/aria-practices GitHub repository. + Highlights of major changes to support ARIA 1.2 as well as some of the improvements include the following. +

+ +

Comprehensive lists of closed issues included in APG 1.2 release 1 are tracked in the following GitHub milestones.

+ +
+ +
+

Acknowledgements

+

Editors

+
+
Current editors:
+
+ + (Facebook) +
+
+ + (University of Illinois) +
+
+ + (Adobe) +
+
+ Zoë Bijl (Invited Expert) +
+
+ Michael Cooper + (W3C) +
+
Former editors:
+
+ Joseph Scheuhammer (Inclusive Design + Research Centre, OCAD University) - Until + +
+
+ Lisa Pappas (SAS) - Until + +
+
+ Rich Schwerdtfeger (IBM Corporation) - Until + +
+
+ +
+

Honorary Editor

+

+ This version of the ARIA Authoring Practices Guide is dedicated to the memory of Carolyn MacLeod whose contributions are visible throughout the entire guide. + She was dedicated to all aspects of the work of the APG Task Force from writing code and suggesting editorial revisions to testing examples with assistive technologies. +

+
    +
  • Carolyn MacLeod (IBM Canada)
    • +
+
+
+

Major Contributors to Version 1.1

+

+ While WAI-ARIA Authoring Practices 1.1 is the work of + the entire Authoring Practices Task Force and also benefits from many people throughout the open source + community who both contribute significant work and provide valuable feedback, special thanks goes to the + following people who provided distinctly large portions of the content and code in version 1.1. +

+
    +
  • Jon Gunderson and Nicholas Hoyt of the Division of Disability Resources and Education Services at the + University of Illinois Urbana/Champaign and the students Max Foltz, Sulaiman Sanaullah, Mark McCarthy, and + Jinyuan Zhou for their contributions to the development of many of the design pattern examples.
    • +
  • Valerie Young of Bocoup and her sponsor, Facebook, for development of the example test framework and + regressions tests for more than 50 examples.
    • +
  • Simon Pieters of Bocoup and his sponsor, Facebook, for authoring of significant guidance sections, + including comprehensive treatment of the topic of accessible names and descriptions.
    • +
+
+
+

Participants active in the ARIA Authoring Practices Task Force

+
    +
  • Ann Abbott (Invited Expert)
    • +
  • Shirisha Balusani (Microsoft Corporation)
    • +
  • Dorothy Bass (Wells Fargo Bank N.A.)
    • +
  • Curt Bellew (Oracle)
    • +
  • Zoë Bijl (Invited Expert)
    • +
  • + Michael Cooper (W3C) +
    • +
  • Bryan Garaventa (Level Access)
    • +
  • Jon Gunderson (University of Illinois at Urbana-Champaign)
    • +
  • Jesse Hausler(Salesforce)
    • +
  • Sarah Higley (Microsoft Corporation)
    • +
  • Hans Hillen (The Paciello Group, LLC)
    • +
  • Matt King (Facebook)
    • +
  • Jaeun Ku (University of Illinois at Urbana-Champaign)
    • +
  • Aaron Leventhal (Google)
    • +
  • Carolyn MacLeod (IBM Corporation)
    • +
  • Mark McCarthy (University of Illinois at Urbana-Champaign)
    • +
  • James Nurthen (Adobe)
    • +
  • Scott O'Hara (The Paciello Group, LLC)
    • +
  • Simon Pieters (Bocoup)
    • +
  • Scott Vinkle (Shopify)
    • +
  • Evan Yamanishi (W. W. Norton)
    • +
  • Valerie Young (Bocoup)
    • +
+
+
+

Other commenters and contributors to Version 1.1

+
    +
  • Vyacheslav Aristov
    • +
  • J. Renée Beach
    • +
  • Kasper Christensen
    • +
  • Gerard K. Cohen
    • +
  • Anne-Gaelle Colom
    • +
  • Kevin Coughlin
    • +
  • Cameron Cundiff
    • +
  • Manish Dahamiwal
    • +
  • Gilmore Davidson
    • +
  • Boris Dušek
    • +
  • Michael Fairchild
    • +
  • Jeremy Felt
    • +
  • Rob Fentress
    • +
  • Geppy
    • +
  • Tatiana Iskandar
    • +
  • Patrick Lauke
    • +
  • Marek Lewandowski
    • +
  • Dan Matthew
    • +
  • Shane McCarron
    • +
  • Victor Meyer
    • +
  • Jonathan Neal
    • +
  • Philipp Rudloff
    • +
  • Joseph Scheuhammer
    • +
  • Nick Schonning
    • +
  • thomascorthals
    • +
  • Christopher Tryens
    • +
+
+
+ +
+

References

+
+

Informative references

+
+
[HTML]
+
+ + HTML Standard + + . Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living + Standard. URL: + https://html.spec.whatwg.org/multipage/ +
+
[HTML-AAM]
+
+ + HTML Accessibility API Mappings 1.0 + + . Steve Faulkner; Scott O'Hara. W3C. 26 October 2022. W3C Working Draft. URL: + https://www.w3.org/TR/html-aam-1.0/ +
+
[HTML-ARIA]
+
+ + ARIA in HTML + + . Steve Faulkner; Scott O'Hara; Patrick Lauke. W3C. 27 September 2022. W3C Recommendation. URL: + https://www.w3.org/TR/html-aria/ +
+
[SVG2]
+
+ + Scalable Vector Graphics (SVG) 2 + + . Amelia Bellamy-Royds; Bogdan Brinza; Chris Lilley; Dirk Schulze; David Storey; Eric Willigers. W3C. 4 + October 2018. W3C Candidate Recommendation. URL: + https://www.w3.org/TR/SVG2/ +
+
[WAI-ARIA]
+
+ + Accessible Rich Internet Applications (WAI-ARIA) 1.1 + + . Joanmarie Diggs; Shane McCarron; Michael Cooper; Richard Schwerdtfeger; James Craig. W3C. 14 December 2017. + W3C Recommendation. URL: + https://www.w3.org/TR/wai-aria-1.1/ +
+
[WAI-ARIA-1.2]
+
+ + Accessible Rich Internet Applications (WAI-ARIA) 1.2 + + . Joanmarie Diggs; James Nurthen; Michael Cooper. W3C. 8 December 2021. W3C Candidate Recommendation. URL: + https://www.w3.org/TR/wai-aria-1.2/ +
+
+
+
+ +
+ + diff --git a/content/about/coverage-and-quality/coverage-and-quality-report.html b/content/about/coverage-and-quality/coverage-and-quality-report.html new file mode 100644 index 0000000000..6679f54b4a --- /dev/null +++ b/content/about/coverage-and-quality/coverage-and-quality-report.html @@ -0,0 +1,2887 @@ + + + + + Coverage and Quality Reports + + + + + + + + +
+

Coverage and Quality Reports

+
+

About These Reports

+

+ The APG Task Force uses the reports on this page to help plan content improvements. + The reports provide data about the scope and quality of content in the APG. + The data delineates: +

+ +

+ The data in the reports are generated by a script + that is run by a GitHub action workflow + when the main branch of the aria-practices repository is updated. + The script will indicate that an ARIA attribute has guidance in a pattern or practice if any of the following conditions are met: +

+ +

+ If either of the data attributes is specified on a heading, the content of that heading will not be processed. + In the generated report, the suffix "(D)" indicates a reference came from a data attribute, otherwise the reference came from the text content of a heading. +

+

+ The following files and reports are generated: +

+ +
+ +
+

CSV Formatted Reports of Role, Property, and State Coverage

+ +
+ +
+

Roles with No Guidance or Examples (29)

+ +
+ +
+

Roles with at Least One Guidance or Example (13)

+
NOTE: The HC abbreviation means example has High Contrast support.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleGuidanceExample
alertdialogAlert Dialog +
articleFeed +
columnheaderTable +
complementaryComplementary +Complementary Landmark +
feedFeed Pattern +Feed +
linkLink Pattern +Link +
mainMain +Main Landmark +
menuitemcheckboxEditor Menubar +
rowgroupTable +
searchSearch +Search Landmark +
separatorEditor Menubar +
tooltipTooltip Pattern +
treegridTreegrid Pattern +Treegrid Email Inbox +
+
+ +
+

Roles with More than One Guidance or Example (36)

+
NOTE: The HC abbreviation means example has High Contrast support.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleGuidanceExamples
alert + +
bannerBanner + +
button + +
cell +Table +
checkboxCheckbox Pattern + +
combobox + +
contentinfoContentinfo + +
dialog + +
form +Form Landmark +
grid + +
gridcell +
group + +
listbox + +
menu + +
menubarMenu and Menubar Pattern + +
menuitem +
menuitemradio +
meter +Meter +
navigation + +
none +
option +
presentation +
radio + +
radiogroup +
regionRegion + +
row +
slider + +
spinbuttonSpinbutton Pattern + +
switchSwitch Pattern + +
tabKeyboard Navigation Between Components (The Tab Sequence) + +
table +Table +
tablist +
tabpanel +
toolbar +Toolbar +
tree + +
treeitem +
+
+ +
+

Properties and States with No Guidance or Examples (12)

+
NOTE: The HC abbreviation means example has High Contrast support.
+ +
+ +
+

Properties and States with at Least One Guidance or Example (8)

+
NOTE: The HC abbreviation means example has High Contrast support.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property or StateGuidanceExample
aria-atomicAlert +
aria-busyFeed +
aria-colcountUsing aria-colcount and aria-colindex +Data Grid +
aria-colspanDefining cell spans using aria-colspan and aria-rowspan +
aria-multiselectableListboxes with Rearrangeable Options +
aria-orientationVertical Temperature Slider +
aria-ownsNavigation Treeview +
aria-rowspanDefining cell spans using aria-colspan and aria-rowspan +
+
+ +
+

Properties and States with More than One Guidance or Example (28)

+
NOTE: The HC abbreviation means example has High Contrast support.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property or StateGuidanceExamples
aria-activedescendantManaging Focus in Composites Using aria-activedescendant + +
aria-autocomplete +
aria-checked +
aria-colindex +Data Grid +
aria-controls +
aria-current +
aria-describedbyDescribing by referencing content with aria-describedby + +
aria-disabled +
aria-expanded +
aria-haspopup +
aria-hidden +
aria-labelNaming with a String Attribute Via aria-label + +
aria-labelledbyNaming with Referenced Content Via aria-labelledby + +
aria-level +
aria-live +
aria-modal +
aria-posinset +
aria-pressed +
aria-roledescription +
aria-rowcountUsing aria-rowcount and aria-rowindex + +
aria-rowindexUsing aria-rowcount and aria-rowindex + +
aria-selected +
aria-setsize +
aria-sortIndicating sort order with aria-sort + +
aria-valuemaxUsing aria-valuemin, aria-valuemax and aria-valuenow + +
aria-valuemin +
aria-valuenowUsing aria-valuemin, aria-valuemax and aria-valuenow + +
aria-valuetextUsing aria-valuetext + +
+
+ +
+

Code Quality

+ +

Coding Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Total Examples60
High Contrast Documentation31
Uses SVG33
Uses forced-color-adjust on SVG13
Uses event.KeyCode20
Uses event.which12
Use Class31
Use Prototype23
Mouse Events16
Pointer Events59
+ +

Coding Practices

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExampleCreated UsingUses event.keyCodeUses event.whichHigh Contrast DocumentationExample Code IDRoles in Javascript and HTMLRoles in Documentationaria-* Attributes in Javascript and HTMLaria-* Attributes in DocumentationDifferences between the documentation and the source code.
Accordionclassex14193heading,menu,menuitem,aria-busy,aria-haspopup,aria-hidden,aria-label,aria-required,aria-roledescription
Alertex14172heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-labelledby,aria-roledescription,aria-live,aria-atomic
Alert DialogprototypeYesYesex_alertdialog52114heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-hidden,aria-label,aria-roledescription
Breadcrumbex14082heading,menu,menuitem,navigation,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-labelledby,aria-roledescription
Button (IDL Version)Yesexample4192heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
ButtonYesexample4191heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-hidden,aria-label,aria-labelledby,aria-roledescription
Auto-Rotating Image Carousel with Buttons for Slide Controlprototypeex15284heading,menu,menuitem,aria-busy,aria-expanded,aria-haspopup,aria-labelledby
Auto-Rotating Image Carousel with Tabs for Slide ControlprototypeYesex17495heading,menu,menuitem,aria-busy,aria-expanded,aria-haspopup,aria-labelledby
Checkbox (Mixed-State)classYesex14182heading,menu,menuitem,aria-busy,aria-expanded,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
Checkbox (Two State)classYesex15282heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Editable Combobox With Both List and Inline AutocompleteclassYesex163116heading,menu,menuitem,aria-busy,aria-haspopup,aria-hidden,aria-labelledby,aria-roledescription
Editable Combobox With List AutocompleteclassYesex163116heading,menu,menuitem,aria-busy,aria-haspopup,aria-hidden,aria-labelledby,aria-roledescription
Editable Combobox without AutocompleteclassYesex163116heading,menu,menuitem,aria-busy,aria-haspopup,aria-hidden,aria-labelledby,aria-roledescription
Date Picker ComboboxclassYesex1731310gridcell,heading,menu,menuitem,aria-busy,aria-hidden,aria-roledescription
Select-Only Comboboxprototypeex15395heading,menu,menuitem,option,aria-busy,aria-haspopup,aria-label,aria-roledescription
Editable Combobox with Grid PopupprototypeYesYesex154107heading,menu,menuitem,row,gridcell,aria-busy,aria-label,aria-roledescription
Date Picker DialogprototypeYesYesexample62116gridcell,heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-roledescription
Modal DialogprototypeYesYesex14193heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Disclosure (Show/Hide) for Answers to Frequently Asked QuestionsclassYesex13072heading,menu,menuitem,aria-busy,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
Disclosure (Show/Hide) for Image DescriptionclassYesex13072heading,menu,menuitem,aria-busy,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
Disclosure Navigation Menu with Top-Level Linksclass, prototypeex17083banner,contentinfo,heading,menu,menuitem,navigation,region,aria-busy,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
Disclosure Navigation Menuclass, prototypeYesex15083heading,menu,menuitem,navigation,region,aria-busy,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
Feedex13275heading,menu,menuitem,feed,article,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription,aria-describedby,aria-posinset,aria-setsize
Feed DisplayprototypeYesYesnot found0060aria-busy,aria-describedby,aria-label,aria-labelledby,aria-posinset,aria-setsize
Advanced Data GridprototypeYesYesex130100heading,menu,menuitem,aria-busy,aria-colindex,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-labelledby,aria-roledescription,aria-rowindex,aria-sort
Data GridprototypeYesYesex151126button,heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Layout GridprototypeYesYesex183133button,heading,menu,menuitem,region,aria-busy,aria-colindex,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-live,aria-relevant,aria-roledescription,aria-sort
LinkYesnot found4171heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-labelledby,aria-roledescription
(Deprecated) Collapsible Dropdown ListboxprototypeYesYesex52125heading,menu,menuitem,aria-busy,aria-controls,aria-disabled,aria-keyshortcuts,aria-label,aria-multiselectable,aria-roledescription
Listbox with Grouped OptionsprototypeYesYesex73123heading,menu,menuitem,presentation,aria-busy,aria-controls,aria-disabled,aria-expanded,aria-haspopup,aria-keyshortcuts,aria-label,aria-multiselectable,aria-roledescription
Listboxes with Rearrangeable OptionsprototypeYesYesex162134heading,menu,menuitem,toolbar,aria-busy,aria-controls,aria-disabled,aria-expanded,aria-haspopup,aria-keyshortcuts,aria-label,aria-live,aria-roledescription
Scrollable ListboxprototypeYesYesex52123heading,menu,menuitem,aria-busy,aria-controls,aria-disabled,aria-expanded,aria-haspopup,aria-keyshortcuts,aria-label,aria-multiselectable,aria-roledescription
Actions Menu Button Using aria-activedescendantclassYesex13285heading,aria-busy,aria-label,aria-roledescription
Actions Menu Button Using element.focus()classYesex13274heading,aria-busy,aria-label,aria-roledescription
Navigation Menu ButtonclassYesex14374heading,aria-busy,aria-label,aria-roledescription
Editor MenubarclassYesex197116heading,none,aria-busy,aria-controls,aria-labelledby,aria-orientation,aria-roledescription
Navigation MenubarclassYesex110895heading,separator,aria-busy,aria-controls,aria-orientation,aria-roledescription
Meterprototypeexample41114heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-hidden,aria-label,aria-roledescription
Radio Group Using aria-activedescendantclassYesex15293heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Rating Radio GroupclassYesex16383heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-roledescription
Radio Group Using Roving tabindexclassYesex15282heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Horizontal Multi-Thumb SliderclassYesex152115heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-labelledby,aria-roledescription
Color Viewer SliderclassYesex152115heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Rating SliderclassYesex141126heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Media Seek SliderclassYesex152126heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Vertical Temperature SliderclassYesex152137heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Date Picker Spin ButtonprototypeYesexample52127heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-roledescription
Switch Using HTML ButtonclassYesex15293heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Switch Using HTML Checkbox InputclassYesex14181heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
SwitchclassYesex14192heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
Sortable TableclassYesex13092heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
Tableex18582heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-labelledby,aria-roledescription
Tabs with Automatic ActivationclassYesex16383heading,menu,menuitem,aria-busy,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Tabs with Manual ActivationclassYesex16383heading,menu,menuitem,aria-busy,aria-expanded,aria-haspopup,aria-label,aria-roledescription
Toolbarnot found3070heading,menu,menuitem,aria-busy,aria-controls,aria-expanded,aria-haspopup,aria-label,aria-labelledby,aria-roledescription
ToolbarprototypeYesex1861512heading,menuitem,aria-busy,aria-labelledby,aria-roledescription
Treegrid Email InboxprototypeYesex163125heading,menu,menuitem,aria-activedescendant,aria-busy,aria-controls,aria-current,aria-haspopup,aria-labelledby,aria-roledescription
File Directory Treeview Using Computed PropertiesprototypeYesex16383heading,menu,menuitem,aria-busy,aria-controls,aria-haspopup,aria-label,aria-roledescription
File Directory Treeview Using Declared PropertiesprototypeYesex163116heading,menu,menuitem,aria-busy,aria-controls,aria-haspopup,aria-label,aria-roledescription
Navigation TreeviewclassYesYesex111895heading,menu,menuitem,aria-busy,aria-controls,aria-haspopup,aria-roledescription
+ +

Graphics Techniques

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExampleSVG in HTMLSVG in CSSSVG in JSforced-color-adjustCSS ::beforeCSS ::afterCSS content
Alert DialogYesYes
BreadcrumbYesYes
Button (IDL Version)YesYesYesYes
ButtonYesYesYesYes
Auto-Rotating Image Carousel with Buttons for Slide ControlYesYes
Auto-Rotating Image Carousel with Tabs for Slide ControlYesYes
Checkbox (Mixed-State)YesYesYes
Checkbox (Two State)YesYesYes
Editable Combobox With Both List and Inline AutocompleteYesYes
Editable Combobox With List AutocompleteYesYes
Editable Combobox without AutocompleteYesYes
Date Picker ComboboxYesYesYes
Select-Only ComboboxYesYes
Date Picker DialogYes
Disclosure (Show/Hide) for Answers to Frequently Asked QuestionsYesYesYes
Disclosure (Show/Hide) for Image DescriptionYesYesYes
Disclosure Navigation Menu with Top-Level LinksYesYes
Disclosure Navigation MenuYesYes
Feed DisplayYes
Advanced Data GridYesYes
Data GridYesYes
Layout GridYesYesYes
LinkYesYesYes
(Deprecated) Collapsible Dropdown ListboxYesYesYes
Listbox with Grouped OptionsYesYesYes
Listboxes with Rearrangeable OptionsYesYesYes
Scrollable ListboxYesYesYes
Actions Menu Button Using aria-activedescendantYesYes
Actions Menu Button Using element.focus()YesYes
Navigation Menu ButtonYesYes
Editor MenubarYesYes
Navigation MenubarYesYesYes
MeterYes
Radio Group Using aria-activedescendantYesYesYes
Rating Radio GroupYesYesYes
Radio Group Using Roving tabindexYesYesYes
Horizontal Multi-Thumb SliderYesYesYesYes
Color Viewer SliderYesYesYesYes
Rating SliderYesYesYesYes
Media Seek SliderYesYesYesYes
Vertical Temperature SliderYesYesYesYes
Date Picker Spin ButtonYesYes
Switch Using HTML ButtonYesYesYesYes
Sortable TableYesYes
ToolbarYesYesYesYesYes
Treegrid Email InboxYesYesYes
File Directory Treeview Using Computed PropertiesYesYes
File Directory Treeview Using Declared PropertiesYesYes
Navigation TreeviewYesYes
+ +

Mouse and Pointer Events

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExampleMouse EventsPointer Events
AccordionYes
AlertYes
Alert DialogYes
BreadcrumbYes
Button (IDL Version)Yes
ButtonYes
Auto-Rotating Image Carousel with Buttons for Slide ControlYesYes
Auto-Rotating Image Carousel with Tabs for Slide ControlYesYes
Checkbox (Mixed-State)Yes
Checkbox (Two State)Yes
Editable Combobox With Both List and Inline AutocompleteYes
Editable Combobox With List AutocompleteYes
Editable Combobox without AutocompleteYes
Date Picker ComboboxYesYes
Select-Only ComboboxYesYes
Editable Combobox with Grid PopupYes
Date Picker DialogYesYes
Modal DialogYes
Disclosure (Show/Hide) for Answers to Frequently Asked QuestionsYes
Disclosure (Show/Hide) for Image DescriptionYes
Disclosure Navigation Menu with Top-Level LinksYes
Disclosure Navigation MenuYes
FeedYes
Advanced Data GridYes
Data GridYes
Layout GridYes
LinkYes
(Deprecated) Collapsible Dropdown ListboxYesYes
Listbox with Grouped OptionsYesYes
Listboxes with Rearrangeable OptionsYesYes
Scrollable ListboxYesYes
Actions Menu Button Using aria-activedescendantYesYes
Actions Menu Button Using element.focus()YesYes
Navigation Menu ButtonYesYes
Editor MenubarYes
Navigation MenubarYes
MeterYes
Radio Group Using aria-activedescendantYes
Rating Radio GroupYes
Radio Group Using Roving tabindexYes
Horizontal Multi-Thumb SliderYes
Color Viewer SliderYes
Rating SliderYes
Media Seek SliderYes
Vertical Temperature SliderYes
Date Picker Spin ButtonYes
Switch Using HTML ButtonYes
Switch Using HTML Checkbox InputYes
SwitchYes
Sortable TableYes
TableYes
Tabs with Automatic ActivationYes
Tabs with Manual ActivationYes
ToolbarYes
ToolbarYesYes
Treegrid Email InboxYes
File Directory Treeview Using Computed PropertiesYesYes
File Directory Treeview Using Declared PropertiesYesYes
Navigation TreeviewYesYes
+ +
+ +
+ + + \ No newline at end of file diff --git a/content/about/coverage-and-quality/prop-coverage.csv b/content/about/coverage-and-quality/prop-coverage.csv new file mode 100644 index 0000000000..973e524f43 --- /dev/null +++ b/content/about/coverage-and-quality/prop-coverage.csv @@ -0,0 +1,49 @@ +"Property or State","Guidance","Examples","References" +"aria-activedescendant","1","11","Guidance: Managing Focus in Composites Using aria-activedescendant","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Select-Only Combobox","Example: Editable Combobox with Grid Popup","Example: (Deprecated) Collapsible Dropdown Listbox","Example: Listbox with Grouped Options","Example: Listboxes with Rearrangeable Options","Example: Scrollable Listbox","Example: Actions Menu Button Using aria-activedescendant","Example: Radio Group Using aria-activedescendant" +"aria-atomic","0","1","Example: Alert" +"aria-autocomplete","0","5","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Date Picker Combobox","Example: Editable Combobox with Grid Popup" +"aria-busy","0","1","Example: Feed" +"aria-checked","0","9","Example: Checkbox (Mixed-State)","Example: Checkbox (Two State)","Example: Editor Menubar","Example: Radio Group Using aria-activedescendant","Example: Rating Radio Group","Example: Radio Group Using Roving tabindex","Example: Switch Using HTML Button","Example: Switch","Example: Toolbar" +"aria-colcount","1","1","Guidance: Using aria-colcount and aria-colindex","Example: Data Grid" +"aria-colindex","3","1","Guidance: Using aria-colcount and aria-colindex","Guidance: Using aria-colindex When Column Indices Are Contiguous","Guidance: Using aria-colindex When Column Indices Are Not Contiguous","Example: Data Grid" +"aria-colspan","1","0","Guidance: Defining cell spans using aria-colspan and aria-rowspan" +"aria-controls","0","20","Example: Accordion","Example: Auto-Rotating Image Carousel with Buttons for Slide Control","Example: Auto-Rotating Image Carousel with Tabs for Slide Control","Example: Checkbox (Mixed-State)","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Date Picker Combobox","Example: Select-Only Combobox","Example: Editable Combobox with Grid Popup","Example: Disclosure (Show/Hide) for Answers to Frequently Asked Questions","Example: Disclosure (Show/Hide) for Image Description","Example: Disclosure Navigation Menu with Top-Level Links","Example: Disclosure Navigation Menu","Example: Actions Menu Button Using aria-activedescendant","Example: Actions Menu Button Using element.focus()","Example: Navigation Menu Button","Example: Tabs with Automatic Activation","Example: Tabs with Manual Activation","Example: Toolbar" +"aria-current","0","5","Example: Breadcrumb","Example: Disclosure Navigation Menu with Top-Level Links","Example: Disclosure Navigation Menu","Example: Navigation Menubar","Example: Navigation Treeview" +"aria-describedby","1","6","Guidance: Describing by referencing content with aria-describedby","Example: Alert Dialog","Example: Date Picker Combobox","Example: Date Picker Dialog","Example: Modal Dialog","Example: Feed","Example: Table" +"aria-details","0","0" +"aria-disabled","0","3","Example: Alert Dialog","Example: Editor Menubar","Example: Toolbar" +"aria-dropeffect","0","0" +"aria-errormessage","0","0" +"aria-expanded","0","22","Example: Accordion","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Date Picker Combobox","Example: Select-Only Combobox","Example: Editable Combobox with Grid Popup","Example: Disclosure (Show/Hide) for Answers to Frequently Asked Questions","Example: Disclosure (Show/Hide) for Image Description","Example: Disclosure Navigation Menu with Top-Level Links","Example: Disclosure Navigation Menu","Example: (Deprecated) Collapsible Dropdown Listbox","Example: Actions Menu Button Using aria-activedescendant","Example: Actions Menu Button Using element.focus()","Example: Navigation Menu Button","Example: Editor Menubar","Example: Navigation Menubar","Example: Toolbar","Example: Treegrid Email Inbox","Example: File Directory Treeview Using Computed Properties","Example: File Directory Treeview Using Declared Properties","Example: Navigation Treeview" +"aria-flowto","0","0" +"aria-grabbed","0","0" +"aria-haspopup","0","9","Example: Date Picker Combobox","Example: Editable Combobox with Grid Popup","Example: (Deprecated) Collapsible Dropdown Listbox","Example: Actions Menu Button Using aria-activedescendant","Example: Actions Menu Button Using element.focus()","Example: Navigation Menu Button","Example: Editor Menubar","Example: Navigation Menubar","Example: Toolbar" +"aria-hidden","0","13","Example: Button (IDL Version)","Example: Editor Menubar","Example: Horizontal Multi-Thumb Slider","Example: Color Viewer Slider","Example: Rating Slider","Example: Media Seek Slider","Example: Vertical Temperature Slider","Example: Date Picker Spin Button","Example: Switch Using HTML Button","Example: Switch Using HTML Checkbox Input","Example: Switch","Example: Sortable Table","Example: Toolbar" +"aria-invalid","0","0" +"aria-keyshortcuts","0","0" +"aria-label","1","18","Guidance: Naming with a String Attribute Via aria-label","Example: Breadcrumb","Example: Auto-Rotating Image Carousel with Buttons for Slide Control","Example: Auto-Rotating Image Carousel with Tabs for Slide Control","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Date Picker Combobox","Example: Date Picker Dialog","Example: Link","Example: Editor Menubar","Example: Navigation Menubar","Example: Rating Radio Group","Example: Horizontal Multi-Thumb Slider","Example: Date Picker Spin Button","Example: Table","Example: Toolbar","Example: Treegrid Email Inbox","Example: Navigation Treeview" +"aria-labelledby","1","40","Guidance: Naming with Referenced Content Via aria-labelledby","Example: Accordion","Example: Alert Dialog","Example: Checkbox (Two State)","Example: Date Picker Combobox","Example: Select-Only Combobox","Example: Editable Combobox with Grid Popup","Example: Date Picker Dialog","Example: Modal Dialog","Example: Feed","Example: Data Grid","Example: Layout Grid","Example: (Deprecated) Collapsible Dropdown Listbox","Example: Listbox with Grouped Options","Example: Listboxes with Rearrangeable Options","Example: Scrollable Listbox","Example: Actions Menu Button Using aria-activedescendant","Example: Actions Menu Button Using element.focus()","Example: Navigation Menu Button","Example: Navigation Menubar","Example: Meter","Example: Radio Group Using aria-activedescendant","Example: Rating Radio Group","Example: Radio Group Using Roving tabindex","Example: Color Viewer Slider","Example: Rating Slider","Example: Media Seek Slider","Example: Vertical Temperature Slider","Example: Date Picker Spin Button","Example: Switch Using HTML Button","Example: Tabs with Automatic Activation","Example: Tabs with Manual Activation","Example: File Directory Treeview Using Computed Properties","Example: File Directory Treeview Using Declared Properties","Example: Navigation Treeview","Example: Complementary Landmark","Example: Form Landmark","Example: Main Landmark","Example: Navigation Landmark","Example: Region Landmark","Example: Search Landmark" +"aria-level","0","2","Example: Treegrid Email Inbox","Example: File Directory Treeview Using Declared Properties" +"aria-live","0","5","Example: Alert","Example: Auto-Rotating Image Carousel with Buttons for Slide Control","Example: Auto-Rotating Image Carousel with Tabs for Slide Control","Example: Date Picker Combobox","Example: Date Picker Dialog" +"aria-modal","0","4","Example: Alert Dialog","Example: Date Picker Combobox","Example: Date Picker Dialog","Example: Modal Dialog" +"aria-multiline","0","0" +"aria-multiselectable","0","1","Example: Listboxes with Rearrangeable Options" +"aria-orientation","0","1","Example: Vertical Temperature Slider" +"aria-owns","0","1","Example: Navigation Treeview" +"aria-placeholder","0","0" +"aria-posinset","0","3","Example: Feed","Example: Treegrid Email Inbox","Example: File Directory Treeview Using Declared Properties" +"aria-pressed","0","3","Example: Button (IDL Version)","Example: Button","Example: Toolbar" +"aria-readonly","0","0" +"aria-relevant","0","0" +"aria-required","0","0" +"aria-roledescription","0","2","Example: Auto-Rotating Image Carousel with Buttons for Slide Control","Example: Auto-Rotating Image Carousel with Tabs for Slide Control" +"aria-rowcount","1","2","Guidance: Using aria-rowcount and aria-rowindex","Example: Data Grid","Example: Layout Grid" +"aria-rowindex","1","2","Guidance: Using aria-rowcount and aria-rowindex","Example: Data Grid","Example: Layout Grid" +"aria-rowspan","1","0","Guidance: Defining cell spans using aria-colspan and aria-rowspan" +"aria-selected","0","16","Example: Auto-Rotating Image Carousel with Tabs for Slide Control","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Date Picker Combobox","Example: Select-Only Combobox","Example: Editable Combobox with Grid Popup","Example: Date Picker Dialog","Example: (Deprecated) Collapsible Dropdown Listbox","Example: Listbox with Grouped Options","Example: Listboxes with Rearrangeable Options","Example: Scrollable Listbox","Example: Tabs with Automatic Activation","Example: Tabs with Manual Activation","Example: File Directory Treeview Using Computed Properties","Example: File Directory Treeview Using Declared Properties" +"aria-setsize","0","3","Example: Feed","Example: Treegrid Email Inbox","Example: File Directory Treeview Using Declared Properties" +"aria-sort","1","2","Guidance: Indicating sort order with aria-sort","Example: Data Grid","Example: Sortable Table" +"aria-valuemax","1","8","Guidance: Using aria-valuemin, aria-valuemax and aria-valuenow","Example: Meter","Example: Horizontal Multi-Thumb Slider","Example: Color Viewer Slider","Example: Rating Slider","Example: Media Seek Slider","Example: Vertical Temperature Slider","Example: Date Picker Spin Button","Example: Toolbar" +"aria-valuemin","0","8","Example: Meter","Example: Horizontal Multi-Thumb Slider","Example: Color Viewer Slider","Example: Rating Slider","Example: Media Seek Slider","Example: Vertical Temperature Slider","Example: Date Picker Spin Button","Example: Toolbar" +"aria-valuenow","1","8","Guidance: Using aria-valuemin, aria-valuemax and aria-valuenow","Example: Meter","Example: Horizontal Multi-Thumb Slider","Example: Color Viewer Slider","Example: Rating Slider","Example: Media Seek Slider","Example: Vertical Temperature Slider","Example: Date Picker Spin Button","Example: Toolbar" +"aria-valuetext","1","5","Guidance: Using aria-valuetext","Example: Rating Slider","Example: Media Seek Slider","Example: Vertical Temperature Slider","Example: Date Picker Spin Button","Example: Toolbar" diff --git a/content/about/coverage-and-quality/role-coverage.csv b/content/about/coverage-and-quality/role-coverage.csv new file mode 100644 index 0000000000..9a3a1ea183 --- /dev/null +++ b/content/about/coverage-and-quality/role-coverage.csv @@ -0,0 +1,79 @@ +"Role","Guidance","Examples","References" +"alert","2","2","Guidance: Alert Pattern","Guidance: Alert and Message Dialogs Pattern","Example: Alert","Example: Alert Dialog" +"alertdialog","0","1","Example: Alert Dialog" +"application","0","0" +"article","0","1","Example: Feed" +"banner","1","3","Guidance: Banner","Example: Navigation Menubar","Example: Navigation Treeview","Example: Banner Landmark" +"button","2","2","Guidance: Button Pattern","Guidance: Menu Button Pattern","Example: Button (IDL Version)","Example: Button" +"caption","0","0" +"cell","3","1","Guidance: Whether to Focus on a Cell Or an Element Inside It","Guidance: Editing and Navigating Inside a Cell","Guidance: Defining cell spans using aria-colspan and aria-rowspan","Example: Table" +"checkbox","1","2","Guidance: Checkbox Pattern","Example: Checkbox (Mixed-State)","Example: Checkbox (Two State)" +"code","0","0" +"columnheader","0","1","Example: Table" +"combobox","2","6","Guidance: Combobox Pattern","Guidance: Combobox Keyboard Interaction","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Date Picker Combobox","Example: Select-Only Combobox","Example: Editable Combobox with Grid Popup" +"complementary","1","1","Guidance: Complementary","Example: Complementary Landmark" +"contentinfo","1","3","Guidance: Contentinfo","Example: Navigation Menubar","Example: Navigation Treeview","Example: Contentinfo Landmark" +"definition","0","0" +"deletion","0","0" +"dialog","2","3","Guidance: Dialog Popup Keyboard Interaction","Guidance: Dialog (Modal) Pattern","Example: Date Picker Combobox","Example: Date Picker Dialog","Example: Modal Dialog" +"directory","0","0" +"document","0","0" +"emphasis","0","0" +"feed","1","1","Guidance: Feed Pattern","Example: Feed" +"figure","0","0" +"form","2","1","Guidance: Form","Guidance: Naming Form Controls with the Label Element","Example: Form Landmark" +"generic","0","0" +"grid","3","5","Guidance: Grid Popup Keyboard Interaction","Guidance: Grid (Interactive Tabular Data and Layout Containers) Pattern","Guidance: Grid and Table Properties","Example: Date Picker Combobox","Example: Editable Combobox with Grid Popup","Example: Date Picker Dialog","Example: Data Grid","Example: Layout Grid" +"gridcell","0","3","Example: Editable Combobox with Grid Popup","Example: Layout Grid","Example: Treegrid Email Inbox" +"group","2","10","Guidance: Radio Group Pattern","Guidance: For Radio Group Contained in a Toolbar","Example: Auto-Rotating Image Carousel with Buttons for Slide Control","Example: Checkbox (Two State)","Example: Listbox with Grouped Options","Example: Editor Menubar","Example: Color Viewer Slider","Example: Date Picker Spin Button","Example: Switch Using HTML Button","Example: File Directory Treeview Using Computed Properties","Example: File Directory Treeview Using Declared Properties","Example: Navigation Treeview" +"heading","0","0" +"img","0","0" +"input","0","0" +"insertion","0","0" +"link","1","1","Guidance: Link Pattern","Example: Link" +"list","0","0" +"listbox","2","8","Guidance: Listbox Popup Keyboard Interaction","Guidance: Listbox Pattern","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Select-Only Combobox","Example: (Deprecated) Collapsible Dropdown Listbox","Example: Listbox with Grouped Options","Example: Listboxes with Rearrangeable Options","Example: Scrollable Listbox" +"listitem","0","0" +"log","0","0" +"main","1","1","Guidance: Main","Example: Main Landmark" +"marquee","0","0" +"math","0","0" +"menu","2","6","Guidance: Menu Button Pattern","Guidance: Menu and Menubar Pattern","Example: Actions Menu Button Using aria-activedescendant","Example: Actions Menu Button Using element.focus()","Example: Navigation Menu Button","Example: Editor Menubar","Example: Navigation Menubar","Example: Toolbar" +"menubar","1","2","Guidance: Menu and Menubar Pattern","Example: Editor Menubar","Example: Navigation Menubar" +"menuitem","0","5","Example: Actions Menu Button Using aria-activedescendant","Example: Actions Menu Button Using element.focus()","Example: Navigation Menu Button","Example: Editor Menubar","Example: Navigation Menubar" +"menuitemcheckbox","0","1","Example: Editor Menubar" +"menuitemradio","0","2","Example: Editor Menubar","Example: Toolbar" +"meter","2","1","Guidance: Meter Pattern","Guidance: Range properties with meter","Example: Meter" +"navigation","5","3","Guidance: Fundamental Keyboard Navigation Conventions","Guidance: Keyboard Navigation Between Components (The Tab Sequence)","Guidance: Keyboard Navigation Inside Components","Guidance: Ensure Basic Access Via Navigation","Guidance: Navigation","Example: Navigation Menubar","Example: Navigation Treeview","Example: Navigation Landmark" +"none","0","7","Example: Navigation Menu Button","Example: Navigation Menubar","Example: Rating Radio Group","Example: Horizontal Multi-Thumb Slider","Example: Media Seek Slider","Example: Vertical Temperature Slider","Example: Navigation Treeview" +"note","0","0" +"option","0","8","Example: Editable Combobox With Both List and Inline Autocomplete","Example: Editable Combobox With List Autocomplete","Example: Editable Combobox without Autocomplete","Example: Select-Only Combobox","Example: (Deprecated) Collapsible Dropdown Listbox","Example: Listbox with Grouped Options","Example: Listboxes with Rearrangeable Options","Example: Scrollable Listbox" +"paragraph","0","0" +"presentation","5","0","Guidance: Hiding Semantics with the presentation Role","Guidance: Common Uses of Role presentation","Guidance: Effects of Role presentation","Guidance: Conditions That Cause Role presentation to be Ignored","Guidance: Example Demonstrating Effects of the presentation Role" +"progressbar","0","0" +"radio","3","4","Guidance: Radio Group Pattern","Guidance: For Radio Groups Not Contained in a Toolbar","Guidance: For Radio Group Contained in a Toolbar","Example: Radio Group Using aria-activedescendant","Example: Rating Radio Group","Example: Radio Group Using Roving tabindex","Example: Toolbar" +"radiogroup","0","4","Example: Radio Group Using aria-activedescendant","Example: Rating Radio Group","Example: Radio Group Using Roving tabindex","Example: Toolbar" +"region","1","6","Guidance: Region","Example: Accordion","Example: Auto-Rotating Image Carousel with Buttons for Slide Control","Example: Auto-Rotating Image Carousel with Tabs for Slide Control","Example: Navigation Menubar","Example: Navigation Treeview","Example: Region Landmark" +"row","0","4","Example: Editable Combobox with Grid Popup","Example: Layout Grid","Example: Table","Example: Treegrid Email Inbox" +"rowgroup","0","1","Example: Table" +"rowheader","0","0" +"scrollbar","0","0" +"search","1","1","Guidance: Search","Example: Search Landmark" +"searchbox","0","0" +"separator","0","1","Example: Editor Menubar" +"slider","2","5","Guidance: Slider (Multi-Thumb) Pattern","Guidance: Slider Pattern","Example: Horizontal Multi-Thumb Slider","Example: Color Viewer Slider","Example: Rating Slider","Example: Media Seek Slider","Example: Vertical Temperature Slider" +"spinbutton","1","2","Guidance: Spinbutton Pattern","Example: Date Picker Spin Button","Example: Toolbar" +"status","0","0" +"switch","1","3","Guidance: Switch Pattern","Example: Switch Using HTML Button","Example: Switch Using HTML Checkbox Input","Example: Switch" +"tab","1","3","Guidance: Keyboard Navigation Between Components (The Tab Sequence)","Example: Auto-Rotating Image Carousel with Tabs for Slide Control","Example: Tabs with Automatic Activation","Example: Tabs with Manual Activation" +"table","2","1","Guidance: Table Pattern","Guidance: Grid and Table Properties","Example: Table" +"tablist","0","3","Example: Auto-Rotating Image Carousel with Tabs for Slide Control","Example: Tabs with Automatic Activation","Example: Tabs with Manual Activation" +"tabpanel","0","3","Example: Auto-Rotating Image Carousel with Tabs for Slide Control","Example: Tabs with Automatic Activation","Example: Tabs with Manual Activation" +"term","0","0" +"textbox","0","0" +"timer","0","0" +"toolbar","3","1","Guidance: For Radio Groups Not Contained in a Toolbar","Guidance: For Radio Group Contained in a Toolbar","Guidance: Toolbar Pattern","Example: Toolbar" +"tooltip","1","0","Guidance: Tooltip Pattern" +"tree","2","3","Guidance: Tree Popup Keyboard Interaction","Guidance: Tree View Pattern","Example: File Directory Treeview Using Computed Properties","Example: File Directory Treeview Using Declared Properties","Example: Navigation Treeview" +"treegrid","1","1","Guidance: Treegrid Pattern","Example: Treegrid Email Inbox" +"treeitem","0","3","Example: File Directory Treeview Using Computed Properties","Example: File Directory Treeview Using Declared Properties","Example: Navigation Treeview" diff --git a/content/apg-home.html b/content/apg-home.html new file mode 100644 index 0000000000..4dc3c07c83 --- /dev/null +++ b/content/apg-home.html @@ -0,0 +1,99 @@ + + + + + + + + ARIA Authoring Practices Guide + + + +
+

ARIA Authoring Practices Guide (APG) Home

+

+ Learn to use the accessibility semantics defined by the Accessible Rich Internet Application (ARIA) specification to create accessible web experiences. + This guide describes how to apply accessibility semantics to common design patterns and widgets. + It provides design patterns and functional examples complemented by in-depth guidance for fundamental practices. +

+ View Patterns + A laptop screen fills with an accessibility icon and emits a checkmark. +
+
+

APG Resources

+

Building blocks that help you make the web accessible

+ +
+ +
+

Get Involved

+

+ The APG Task Force relies on broad community representation and participation to continuously improve the usefulness and quality of the APG. + There are a variety of ways you can get involved and help promote development of accessible experiences. +

+ +
+ + diff --git a/img/DHTMLexample.png b/content/images/DHTMLexample.png similarity index 100% rename from img/DHTMLexample.png rename to content/images/DHTMLexample.png diff --git a/img/accessibleJSelement.png b/content/images/accessibleJSelement.png similarity index 100% rename from img/accessibleJSelement.png rename to content/images/accessibleJSelement.png diff --git a/img/accessibleelement.png b/content/images/accessibleelement.png similarity index 100% rename from img/accessibleelement.png rename to content/images/accessibleelement.png diff --git a/img/exampletree.png b/content/images/exampletree.png similarity index 100% rename from img/exampletree.png rename to content/images/exampletree.png diff --git a/img/index-1.svg b/content/images/index-1.svg similarity index 100% rename from img/index-1.svg rename to content/images/index-1.svg diff --git a/img/index-2.svg b/content/images/index-2.svg similarity index 100% rename from img/index-2.svg rename to content/images/index-2.svg diff --git a/img/index-3.svg b/content/images/index-3.svg similarity index 100% rename from img/index-3.svg rename to content/images/index-3.svg diff --git a/img/index-4.svg b/content/images/index-4.svg similarity index 100% rename from img/index-4.svg rename to content/images/index-4.svg diff --git a/img/index-5.svg b/content/images/index-5.svg similarity index 100% rename from img/index-5.svg rename to content/images/index-5.svg diff --git a/img/index-6.svg b/content/images/index-6.svg similarity index 100% rename from img/index-6.svg rename to content/images/index-6.svg diff --git a/img/index-7.svg b/content/images/index-7.svg similarity index 100% rename from img/index-7.svg rename to content/images/index-7.svg diff --git a/img/index-8.svg b/content/images/index-8.svg similarity index 100% rename from img/index-8.svg rename to content/images/index-8.svg diff --git a/img/inspectofpagetab.png b/content/images/inspectofpagetab.png similarity index 100% rename from img/inspectofpagetab.png rename to content/images/inspectofpagetab.png diff --git a/img/navlandmark.jpg b/content/images/navlandmark.jpg similarity index 100% rename from img/navlandmark.jpg rename to content/images/navlandmark.jpg diff --git a/img/taxonomy.png b/content/images/taxonomy.png similarity index 100% rename from img/taxonomy.png rename to content/images/taxonomy.png diff --git a/content/index/index.html b/content/index/index.html new file mode 100644 index 0000000000..a630eaaea2 --- /dev/null +++ b/content/index/index.html @@ -0,0 +1,905 @@ + + + + + Index + + + + + + + +
+

Index

+

About the Index

+

+ This page includes a list of all ARIA design pattern examples indexed + either by role or by ARIA properties and states. +

+ +
+

Examples by Role

+
NOTE: The HC abbreviation means example has High Contrast support.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleExamples
alert + +
alertdialogAlert Dialog
articleFeed
banner + +
button + +
cellTable
checkbox + +
columnheaderTable
combobox + +
complementaryComplementary Landmark
contentinfo + +
dialog + +
feedFeed
formForm Landmark
grid + +
gridcell + +
group + +
linkLink
listbox + +
mainMain Landmark
menu + +
menubar + +
menuitem + +
menuitemcheckboxEditor Menubar
menuitemradio + +
meterMeter
navigation + +
none + +
option + +
radio + +
radiogroup + +
region + +
row + +
rowgroupTable
searchSearch Landmark
separatorEditor Menubar
slider + +
spinbutton + +
switch + +
tab + +
tableTable
tablist + +
tabpanel + +
toolbarToolbar
tree + +
treegridTreegrid Email Inbox
treeitem + +
+
+
+

Examples By Properties and States

+
NOTE: The HC abbreviation means example has High Contrast support.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property or StateExamples
aria-activedescendant + +
aria-atomicAlert
aria-autocomplete + +
aria-busyFeed
aria-checked + +
aria-colcountData Grid
aria-colindexData Grid
aria-controls + +
aria-current + +
aria-describedby + +
aria-disabled + +
aria-expanded + +
aria-haspopup + +
aria-hidden + +
aria-label + +
aria-labelledby + +
aria-level + +
aria-live + +
aria-modal + +
aria-multiselectableListboxes with Rearrangeable Options
aria-orientationVertical Temperature Slider
aria-ownsNavigation Treeview
aria-posinset + +
aria-pressed + +
aria-roledescription + +
aria-rowcount + +
aria-rowindex + +
aria-selected + +
aria-setsize + +
aria-sort + +
aria-valuemax + +
aria-valuemin + +
aria-valuenow + +
aria-valuetext + +
+
+
+ + + diff --git a/content/patterns/accordion/accordion-pattern.html b/content/patterns/accordion/accordion-pattern.html new file mode 100644 index 0000000000..efcadf98df --- /dev/null +++ b/content/patterns/accordion/accordion-pattern.html @@ -0,0 +1,100 @@ + + + + + + Accordion Pattern + + + + + + + + + +
+

Accordion Pattern (Sections With Show/Hide Functionality)

+ +
+

About This Pattern

+

+ An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content. + The headings function as controls that enable users to reveal or hide their associated sections of content. + Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page. +

+

Terms for understanding accordions include:

+
+
Accordion Header:
+
Label for or thumbnail representing a section of content that also serves as a control for showing, and in some implementations, hiding the section of content.
+
Accordion Panel:
+
Section of content associated with an accordion header.
+
+

+ In some accordions, there are additional elements that are always visible adjacent to the accordion header. + For instance, a menubutton may accompany each accordion header to provide access to actions that apply to that section. And, in some cases, a snippet of the hidden content may also be visually persistent. +

+
+ +
+

Example

+

Accordion Example: demonstrates a form divided into three sections using an accordion to show one section at a time.

+
+ +
+

Keyboard Interaction

+ +
+ +
+

WAI-ARIA Roles, States, and Properties:

+ +
+
+ + diff --git a/content/patterns/accordion/examples/accordion.html b/content/patterns/accordion/examples/accordion.html new file mode 100644 index 0000000000..51a67c7920 --- /dev/null +++ b/content/patterns/accordion/examples/accordion.html @@ -0,0 +1,270 @@ + + + + + + Accordion Example + + + + + + + + + + + + + + +
+

Accordion Example

+ +
+

About This Example

+

The below example section contains a simple personal information input form divided into 3 sections that demonstrates the Accordion Pattern.

+
+ +
+
+

Example

+
+ +
+
+

+ +

+
+
+ +
+

+ + +

+

+ + +

+

+ + +

+

+ + +

+

+ + +

+

+ + +

+
+
+
+

+ +

+ +

+ +

+ +
+
+ +
+ +
+

Keyboard Support

+ + + + + + + + + + + + + + + + + + + + + +
KeyFunction
Space or EnterWhen focus is on the accordion header of a collapsed section, expands the section.
Tab +
    +
  • Moves focus to the next focusable element.
    • +
  • All focusable elements in the accordion are included in the page Tab sequence.
    • +
+
Shift + Tab +
    +
  • Moves focus to the previous focusable element.
    • +
  • All focusable elements in the accordion are included in the page Tab sequence.
    • +
+
+
+ +
+

Role, Property, State, and Tabindex Attributes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleAttributeElementUsage
h3 +
    +
  • Element that serves as an accordion header.
    • +
  • Each accordion header element contains a button that controls the visibility of its content panel.
    • +
  • The example uses heading level 3 so it fits correctly within the outline of the page; the example is contained in a section titled with a level 2 heading.
    • +
+
aria-expanded="true"buttonSet to true when the Accordion panel is expanded, otherwise set to false.
aria-controls="ID"buttonPoints to the ID of the panel which the header controls.
regiondivCreates a landmark region that contains the currently expanded accordion panel.
aria-labelledby="IDREF"div +
    +
  • Defines the accessible name for the region element.
    • +
  • References the accordion header button that expands and collapses the region.
    • +
  • region elements are required to have an accessible name to be identified as a landmark.
    • +
+
+
+ +
+

Javascript and CSS Source Code

+ +
+ +
+

HTML Source Code

+ +
+ + +
+
+ + + diff --git a/examples/accordion/css/accordion.css b/content/patterns/accordion/examples/css/accordion.css similarity index 100% rename from examples/accordion/css/accordion.css rename to content/patterns/accordion/examples/css/accordion.css diff --git a/examples/accordion/js/accordion.js b/content/patterns/accordion/examples/js/accordion.js similarity index 100% rename from examples/accordion/js/accordion.js rename to content/patterns/accordion/examples/js/accordion.js diff --git a/content/patterns/alert/alert-pattern.html b/content/patterns/alert/alert-pattern.html new file mode 100644 index 0000000000..5d319b4a93 --- /dev/null +++ b/content/patterns/alert/alert-pattern.html @@ -0,0 +1,56 @@ + + + + + + Alert Pattern + + + + + + + + + +
+

Alert Pattern

+ +
+

About This Pattern

+

+ An alert is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. + Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound. + It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before page load completes. +

+

+ Because alerts are intended to provide important and potentially time-sensitive information without interfering with the user's ability to continue working, it is crucial they do not affect keyboard focus. + The Alert Dialog Pattern is designed for situations where interrupting work flow is necessary. +

+

+ It is also important to avoid designing alerts that disappear automatically. + An alert that disappears too quickly can lead to failure to meet + WCAG 2.0 success criterion 2.2.3. + Another critical design consideration is the frequency of interruption caused by alerts. + Frequent interruptions inhibit usability for people with visual and cognitive disabilities, which makes meeting the requirements of + WCAG 2.0 success criterion 2.2.4 more difficult. +

+
+ +
+

Example

+

Alert Example

+
+ +
+

Keyboard Interaction

+

Not applicable.

+
+ +
+

WAI-ARIA Roles, States, and Properties

+

The widget has a role of alert.

+
+
+ + diff --git a/content/patterns/alert/examples/alert.html b/content/patterns/alert/examples/alert.html new file mode 100644 index 0000000000..1a74a97bd2 --- /dev/null +++ b/content/patterns/alert/examples/alert.html @@ -0,0 +1,148 @@ + + + + + + Alert Example + + + + + + + + + + + + + + + +
+

Alert Example

+ +
+

About This Example

+

+ The below example demonstrates the Alert Pattern. + Activating the Trigger Alert button causes a message to be inserted into the example alert element. +

+

Similar examples include:

+ +
+ +
+
+

Example

+
+

This is just a test. A typical alert is triggered by an event, such as an error, warning condition, or the arrival of information that is important in the context of the user's task.

+ +
+ + + + + + +
+ +
+ +
+

Accessibility Features

+

+ Because an alert is for critical information, assistive technologies may provide special behaviors designed to help call attention to changes in the text of an alert. + For example, screen readers may interrupt all other speech and preface announcement of the new alert text with a special sound or phrase. +

+
+ +
+

Keyboard Support

+

No keyboard interaction needed.

+
+ +
+

Role, Property, State, and Tabindex Attributes

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleAttributeElementUsage
alertdivIdentifies the element as the container where alert content will be added or updated.
+ aria-live=assertive + Implicit on div +
    +
  • This does not have to be declared in the code because it is implicit in the alert role.
    • +
  • Tells assistive technologies to interrupt other processes to provide users with immediate notification of relevant alert container changes.
    • +
+
+ aria-atomic=true + Implicit on div +
    +
  • This does not have to be declared in the code because it is implicit in the alert role.
    • +
  • Tells assistive technologies to use the entire content of the alert element as the alert message even if only a portion of it has changed.
    • +
+
+
+ +
+

Javascript and CSS Source Code

+ +
+ +
+

HTML Source Code

+ +
+ + +
+
+ + diff --git a/examples/alert/css/alert.css b/content/patterns/alert/examples/css/alert.css similarity index 100% rename from examples/alert/css/alert.css rename to content/patterns/alert/examples/css/alert.css diff --git a/examples/alert/js/alert.js b/content/patterns/alert/examples/js/alert.js similarity index 100% rename from examples/alert/js/alert.js rename to content/patterns/alert/examples/js/alert.js diff --git a/content/patterns/alertdialog/alertdialog-pattern.html b/content/patterns/alertdialog/alertdialog-pattern.html new file mode 100644 index 0000000000..88de2c6d36 --- /dev/null +++ b/content/patterns/alertdialog/alertdialog-pattern.html @@ -0,0 +1,62 @@ + + + + + + Alert and Message Dialogs Pattern + + + + + + + + + +
+

Alert and Message Dialogs Pattern

+ +
+

About This Pattern

+

+ An alert dialog is a modal dialog that interrupts the user's workflow to communicate an important message and acquire a response. + Examples include action confirmation prompts and error message confirmations. + The alertdialog role enables assistive technologies and browsers to distinguish alert dialogs from other dialogs so they have the option of giving alert dialogs special treatment, such as playing a system alert sound. +

+
+ +
+

Example

+

Alert Dialog Example: A confirmation prompt that demonstrates an alert dialog.

+
+ +
+

Keyboard Interaction

+

See the keyboard interaction section for the modal dialog pattern.

+
+ +
+

WAI-ARIA Roles, States, and Properties

+ +
+
+ + diff --git a/examples/dialog-modal/alertdialog.html b/content/patterns/alertdialog/examples/alertdialog.html similarity index 58% rename from examples/dialog-modal/alertdialog.html rename to content/patterns/alertdialog/examples/alertdialog.html index 48d4fac640..4a8921deac 100644 --- a/examples/dialog-modal/alertdialog.html +++ b/content/patterns/alertdialog/examples/alertdialog.html @@ -2,63 +2,66 @@ - Alert Dialog Example | WAI-ARIA Authoring Practices 1.2 - + + Alert Dialog Example + + - - - - - - - - - + + + + + + + + + -

Alert Dialog Example

-

- The below example of a confirmation prompt demonstrates the design pattern for an alert dialog. - It also includes an example of the design pattern for an alert to make comparing the experiences provided by the two patterns easy. -

-

To use this example:

- -

- Note: This example uses code from the modal dialog example to create the behaviors of the alertdialog so referencing that example may be useful. + +

+

About This Example

+

+ The below example of a confirmation prompt demonstrates the Alert Dialog Pattern. + It also includes an example of the Alert Pattern to make comparing the experiences provided by the two patterns easy.

-

Similar examples include:

- +

To use this example:

+ +

Similar examples include:

+ +
+

Example

@@ -77,22 +80,23 @@

Example

- +
-
+

Accessibility Features

+

Keyboard Support

@@ -118,7 +123,7 @@

Keyboard Support

- + - + @@ -144,15 +149,16 @@

Keyboard Support

- +
Tab
    @@ -136,7 +141,7 @@

    Keyboard Support
Escape Closes the dialog.
Command + S (Mac only) Save the contents of the notes textarea when focused.
Control + S (Windows only) Save the contents of the notes textarea when focused.
+
-

Role, Property, State, and Tabindex Attributes

+

Role, Property, State, and Tabindex Attributes

@@ -163,47 +169,37 @@

Role, Property, State, and Tabindex Attributes

- + - + - + - + - + - + - + - + + + + + + + - - - - - - - + @@ -217,9 +213,7 @@

Notes on aria-modal and aria-hidden

The aria-modal property was introduced in ARIA 1.1. As a relatively new property, screen reader users may experience varying degrees of support for it. -
  • - Applying the aria-modal property to the dialog element replaces the technique of using aria-hidden on the background for informing assistive technologies that content outside a dialog is inert. -
    • +
  • Applying the aria-modal property to the dialog element replaces the technique of using aria-hidden on the background for informing assistive technologies that content outside a dialog is inert.
  • In legacy dialog implementations where aria-hidden is used to make content outside a dialog inert for assistive technology users, it is important that:
      @@ -229,13 +223,15 @@

      Notes on aria-modal and aria-hidden

    +

    Javascript and CSS Source Code

    +

    HTML Source Code

    @@ -247,8 +243,5 @@

    HTML Source Code

    - diff --git a/content/patterns/alertdialog/examples/css/alertdialog.css b/content/patterns/alertdialog/examples/css/alertdialog.css new file mode 100644 index 0000000000..6f575b9dce --- /dev/null +++ b/content/patterns/alertdialog/examples/css/alertdialog.css @@ -0,0 +1,131 @@ +.hidden { + display: none; +} + +[role="alertdialog"] { + box-sizing: border-box; + padding: 15px; + border: 1px solid #000; + background-color: #fff; + min-height: 100vh; +} + +@media screen and (min-width: 640px) { + [role="alertdialog"] { + position: absolute; + top: 2rem; + left: 50vw; /* move to the middle of the screen (assumes relative parent is the body/viewport) */ + transform: translateX( + -50% + ); /* move backwards 50% of this element's width */ + + min-width: calc(640px - (15px * 2)); /* == breakpoint - left+right margin */ + min-height: auto; + box-shadow: 0 19px 38px rgb(0 0 0 / 12%), 0 15px 12px rgb(0 0 0 / 22%); + } +} + +.dialog_label { + text-align: center; +} + +.dialog_form_actions { + text-align: right; + padding: 0 20px 20px; +} + +.dialog_desc { + padding: 10px 20px; +} + +/* native element uses the ::backdrop pseudo-element */ + +/* dialog::backdrop, */ +.dialog-backdrop { + display: none; + position: fixed; + overflow-y: auto; + top: 0; + right: 0; + bottom: 0; + left: 0; +} + +@media screen and (min-width: 640px) { + .dialog-backdrop { + background: rgb(0 0 0 / 30%); + } +} + +.dialog-backdrop.active { + display: block; +} + +.no-scroll { + overflow-y: auto !important; +} + +/* this is added to the body when a dialog is open */ +.has-dialog { + overflow: hidden; +} + +/* styling for alertdialog example */ +.notes { + display: block; + font-size: 1rem; + line-height: 1.3; + min-width: 400px; + max-width: 100%; + width: 33%; +} + +.visually-hidden { + border: 0; + clip: rect(0 0 0 0); + height: auto; + margin: 0; + overflow: hidden; + padding: 0; + position: absolute; + width: 1px; + white-space: nowrap; +} + +#ex_alertdialog [aria-disabled="true"] { + opacity: 0.4; +} + +#notes_save { + display: inline-flex; + align-items: center; + gap: 0.5rem; +} + +#notes_save svg { + display: block; + width: 0.75rem; +} + +#notes_save .icon { + display: none; +} + +@keyframes rotate { + 0% { + transform: rotate(0deg); + } + + 100% { + transform: rotate(360deg); + } +} + +#notes_save.loading .spinner { + display: block; + animation: rotate 2s linear infinite; +} + +#notes_save.saved .check { + display: block; +} diff --git a/content/patterns/alertdialog/examples/js/alertdialog.js b/content/patterns/alertdialog/examples/js/alertdialog.js new file mode 100644 index 0000000000..d57ae3a3d1 --- /dev/null +++ b/content/patterns/alertdialog/examples/js/alertdialog.js @@ -0,0 +1,413 @@ +'use strict'; + +var aria = aria || {}; + +aria.Utils = aria.Utils || {}; + +/** + * @description Set focus on descendant nodes until the first focusable element is + * found. + * @param element + * DOM node for which to find the first focusable descendant. + * @returns {boolean} + * true if a focusable element is found and focus is set. + */ +aria.Utils.focusFirstDescendant = function (element) { + for (var i = 0; i < element.childNodes.length; i++) { + var child = element.childNodes[i]; + if ( + aria.Utils.attemptFocus(child) || + aria.Utils.focusFirstDescendant(child) + ) { + return true; + } + } + return false; +}; // end focusFirstDescendant + +/** + * @description Set Attempt to set focus on the current node. + * @param element + * The node to attempt to focus on. + * @returns {boolean} + * true if element is focused. + */ +aria.Utils.attemptFocus = function (element) { + if (!aria.Utils.isFocusable(element)) { + return false; + } + + aria.Utils.IgnoreUtilFocusChanges = true; + try { + element.focus(); + } catch (e) { + // continue regardless of error + } + aria.Utils.IgnoreUtilFocusChanges = false; + return document.activeElement === element; +}; // end attemptFocus + +aria.handleEscape = function (event) { + var key = event.which || event.keyCode; + + if (key === aria.KeyCode.ESC && aria.openedDialog) { + aria.openedDialog.close(); + event.stopPropagation(); + } +}; + +document.addEventListener('keyup', aria.handleEscape); + +/** + * @class + * @description Dialog object providing modal focus management. + * + * Assumptions: The element serving as the dialog container is present in the + * DOM and hidden. The dialog container has role='dialog'. + * @param dialogId + * The ID of the element serving as the dialog container. + * @param focusAfterClosed + * Either the DOM node or the ID of the DOM node to focus when the + * dialog closes. + * @param focusFirst + * Optional parameter containing either the DOM node or the ID of the + * DOM node to focus when the dialog opens. If not specified, the + * first focusable element in the dialog will receive focus. + */ +aria.Dialog = function (dialogId, focusAfterClosed, focusFirst) { + this.dialogNode = document.getElementById(dialogId); + if (this.dialogNode === null) { + throw new Error('No element found with id="' + dialogId + '".'); + } + + var validRoles = ['dialog', 'alertdialog']; + var isDialog = (this.dialogNode.getAttribute('role') || '') + .trim() + .split(/\s+/g) + .some(function (token) { + return validRoles.some(function (role) { + return token === role; + }); + }); + if (!isDialog) { + throw new Error( + 'Dialog() requires a DOM element with ARIA role of dialog or alertdialog.' + ); + } + + // Wrap in an individual backdrop element if one doesn't exist + // Native elements use the ::backdrop pseudo-element, which + // works similarly. + var backdropClass = 'dialog-backdrop'; + if (this.dialogNode.parentNode.classList.contains(backdropClass)) { + this.backdropNode = this.dialogNode.parentNode; + } else { + this.backdropNode = document.createElement('div'); + this.backdropNode.className = backdropClass; + this.dialogNode.parentNode.insertBefore(this.backdropNode, this.dialogNode); + this.backdropNode.appendChild(this.dialogNode); + } + this.backdropNode.classList.add('active'); + + // Disable scroll on the body element + document.body.classList.add(aria.Utils.dialogOpenClass); + + if (typeof focusAfterClosed === 'string') { + this.focusAfterClosed = document.getElementById(focusAfterClosed); + } else if (typeof focusAfterClosed === 'object') { + this.focusAfterClosed = focusAfterClosed; + } else { + throw new Error( + 'the focusAfterClosed parameter is required for the aria.Dialog constructor.' + ); + } + + if (typeof focusFirst === 'string') { + this.focusFirst = document.getElementById(focusFirst); + } else if (typeof focusFirst === 'object') { + this.focusFirst = focusFirst; + } else { + this.focusFirst = null; + } + + // Bracket the dialog node with two invisible, focusable nodes. + // While this dialog is open, we use these to make sure that focus never + // leaves the document even if dialogNode is the first or last node. + var preDiv = document.createElement('div'); + this.preNode = this.dialogNode.parentNode.insertBefore( + preDiv, + this.dialogNode + ); + this.preNode.tabIndex = 0; + var postDiv = document.createElement('div'); + this.postNode = this.dialogNode.parentNode.insertBefore( + postDiv, + this.dialogNode.nextSibling + ); + this.postNode.tabIndex = 0; + + this.addListeners(); + aria.openedDialog = this; + this.dialogNode.className = 'default_dialog'; // make visible + + if (this.focusFirst) { + this.focusFirst.focus(); + } else { + aria.Utils.focusFirstDescendant(this.dialogNode); + } + + this.lastFocus = document.activeElement; +}; // end Dialog constructor + +/** + * @description + * Hides the current top dialog, + * removes listeners of the top dialog, + * restore listeners of a parent dialog if one was open under the one that just closed, + * and sets focus on the element specified for focusAfterClosed. + */ +aria.Dialog.prototype.close = function () { + aria.openedDialog = null; + this.removeListeners(); + aria.Utils.remove(this.preNode); + aria.Utils.remove(this.postNode); + this.dialogNode.className = 'hidden'; + this.backdropNode.classList.remove('active'); + this.focusAfterClosed.focus(); + + document.body.classList.remove(aria.Utils.dialogOpenClass); +}; // end close + +aria.Dialog.prototype.addListeners = function () { + document.addEventListener('focus', this.trapFocus, true); +}; // end addListeners + +aria.Dialog.prototype.removeListeners = function () { + document.removeEventListener('focus', this.trapFocus, true); +}; // end removeListeners + +aria.Dialog.prototype.trapFocus = function (event) { + if (aria.Utils.IgnoreUtilFocusChanges) { + return; + } + var opened = aria.openedDialog; + if (opened.dialogNode.contains(event.target)) { + opened.lastFocus = event.target; + } else { + aria.Utils.focusFirstDescendant(opened.dialogNode); + if (opened.lastFocus == document.activeElement) { + aria.Utils.focusLastDescendant(opened.dialogNode); + } + opened.lastFocus = document.activeElement; + } +}; // end trapFocus + +aria.Utils.disableCtrl = function (ctrl) { + ctrl.setAttribute('aria-disabled', 'true'); +}; + +aria.Utils.enableCtrl = function (ctrl) { + ctrl.removeAttribute('aria-disabled'); +}; + +aria.Utils.setLoading = function (saveBtn, saveStatusView) { + saveBtn.classList.add('loading'); + this.disableCtrl(saveBtn); + + // use a timeout for the loading message + // if the saved state happens very quickly, + // we don't need to explicitly announce the intermediate loading state + const loadingTimeout = window.setTimeout(() => { + saveStatusView.textContent = 'Loading'; + }, 200); + + // set timeout for saved state, to mimic loading + const fakeLoadingTimeout = Math.random() * 2000; + window.setTimeout(() => { + saveBtn.classList.remove('loading'); + saveBtn.classList.add('saved'); + + window.clearTimeout(loadingTimeout); + saveStatusView.textContent = 'Saved successfully'; + }, fakeLoadingTimeout); +}; + +aria.Notes = function Notes( + notesId, + saveId, + saveStatusId, + discardId, + localStorageKey +) { + this.notesInput = document.getElementById(notesId); + this.saveBtn = document.getElementById(saveId); + this.saveStatusView = document.getElementById(saveStatusId); + this.discardBtn = document.getElementById(discardId); + this.localStorageKey = localStorageKey || 'alertdialog-notes'; + this.initialized = false; + + Object.defineProperty(this, 'controls', { + get: function () { + return document.querySelectorAll( + '[data-textbox=' + this.notesInput.id + ']' + ); + }, + }); + Object.defineProperty(this, 'hasContent', { + get: function () { + return this.notesInput.value.length > 0; + }, + }); + Object.defineProperty(this, 'savedValue', { + get: function () { + return JSON.parse(localStorage.getItem(this.localStorageKey)); + }, + set: function (val) { + this.save(val); + }, + }); + Object.defineProperty(this, 'isCurrent', { + get: function () { + return this.notesInput.value === this.savedValue; + }, + }); + Object.defineProperty(this, 'oninput', { + get: function () { + return this.notesInput.oninput; + }, + set: function (fn) { + if (typeof fn !== 'function') { + throw new TypeError('oninput must be a function'); + } + this.notesInput.addEventListener('input', fn); + }, + }); + + if (this.saveBtn && this.discardBtn) { + this.init(); + } +}; + +aria.Notes.prototype.save = function (val) { + const isDisabled = this.saveBtn.getAttribute('aria-disabled') === 'true'; + if (isDisabled) { + return; + } + localStorage.setItem( + this.localStorageKey, + JSON.stringify(val || this.notesInput.value) + ); + aria.Utils.disableCtrl(this.saveBtn); + aria.Utils.setLoading(this.saveBtn, this.saveStatusView); +}; + +aria.Notes.prototype.loadSaved = function () { + if (this.savedValue) { + this.notesInput.value = this.savedValue; + } +}; + +aria.Notes.prototype.restoreSaveBtn = function () { + this.saveBtn.classList.remove('loading'); + this.saveBtn.classList.remove('saved'); + this.saveBtn.removeAttribute('aria-disabled'); + + this.saveStatusView.textContent = ''; +}; + +aria.Notes.prototype.discard = function () { + localStorage.clear(); + this.notesInput.value = ''; + this.toggleControls(); + this.restoreSaveBtn(); +}; + +aria.Notes.prototype.disableControls = function () { + this.controls.forEach(aria.Utils.disableCtrl); +}; + +aria.Notes.prototype.enableControls = function () { + this.controls.forEach(aria.Utils.enableCtrl); +}; + +aria.Notes.prototype.toggleControls = function () { + if (this.hasContent) { + this.enableControls(); + } else { + this.disableControls(); + } +}; + +aria.Notes.prototype.toggleCurrent = function () { + if (!this.isCurrent) { + this.notesInput.classList.remove('can-save'); + aria.Utils.enableCtrl(this.saveBtn); + this.restoreSaveBtn(); + } else { + this.notesInput.classList.add('can-save'); + aria.Utils.disableCtrl(this.saveBtn); + } +}; + +aria.Notes.prototype.keydownHandler = function (e) { + var mod = navigator.userAgent.includes('Mac') ? e.metaKey : e.ctrlKey; + if ((e.key === 's') & mod) { + e.preventDefault(); + this.save(); + } +}; + +aria.Notes.prototype.init = function () { + if (!this.initialized) { + this.loadSaved(); + this.toggleCurrent(); + this.saveBtn.addEventListener('click', this.save.bind(this, undefined)); + this.discardBtn.addEventListener('click', this.discard.bind(this)); + this.notesInput.addEventListener('input', this.toggleControls.bind(this)); + this.notesInput.addEventListener('input', this.toggleCurrent.bind(this)); + this.notesInput.addEventListener('keydown', this.keydownHandler.bind(this)); + this.initialized = true; + } +}; + +/** initialization */ +document.addEventListener('DOMContentLoaded', function initAlertDialog() { + var notes = new aria.Notes( + 'notes', + 'notes_save', + 'notes_save_status', + 'notes_confirm' + ); + + window.closeDialog = function () { + aria.openedDialog.close(); + }; // end closeDialog + + window.discardInput = function () { + notes.discard.call(notes); + window.closeDialog(); + }; + + window.openAlertDialog = function (dialogId, triggerBtn, focusFirst) { + // do not proceed if the trigger button is disabled + if (triggerBtn.getAttribute('aria-disabled') === 'true') { + return; + } + + var target = document.getElementById( + triggerBtn.getAttribute('data-textbox') + ); + var dialog = document.getElementById(dialogId); + var desc = document.getElementById(dialog.getAttribute('aria-describedby')); + var wordCount = document.getElementById('word_count'); + if (!wordCount) { + wordCount = document.createElement('p'); + wordCount.id = 'word_count'; + desc.appendChild(wordCount); + } + var count = target.value.split(/\s/).length; + var frag = count > 1 ? 'words' : 'word'; + wordCount.textContent = count + ' ' + frag + ' will be deleted.'; + new aria.Dialog(dialogId, target, focusFirst); + }; +}); diff --git a/content/patterns/breadcrumb/breadcrumb-pattern.html b/content/patterns/breadcrumb/breadcrumb-pattern.html new file mode 100644 index 0000000000..1af0accdfb --- /dev/null +++ b/content/patterns/breadcrumb/breadcrumb-pattern.html @@ -0,0 +1,51 @@ + + + + + + Breadcrumb Pattern + + + + + + + + + +
    +

    Breadcrumb Pattern

    + +
    +

    About This Pattern

    +

    + A breadcrumb trail consists of a list of links to the parent pages of the current page in hierarchical order. + It helps users find their place within a website or web application. + Breadcrumbs are often placed horizontally before a page's main content. +

    +
    + +
    +

    Example

    +

    Breadcrumb design pattern example

    +
    + +
    +

    Keyboard Interaction

    +

    Not applicable.

    +
    + +
    +

    WAI-ARIA Roles, States, and Properties

    +
      +
    • Breadcrumb trail is contained within a navigation landmark region.
      • +
    • The landmark region is labelled via aria-label or aria-labelledby.
      • +
    • + The link to the current page has aria-current set to page. + If the element representing the current page is not a link, aria-current is optional. +
      • +
    +
    +
    + + diff --git a/content/patterns/breadcrumb/examples/breadcrumb.html b/content/patterns/breadcrumb/examples/breadcrumb.html new file mode 100644 index 0000000000..49c8d21089 --- /dev/null +++ b/content/patterns/breadcrumb/examples/breadcrumb.html @@ -0,0 +1,141 @@ + + + + + + Breadcrumb Example + + + + + + + + + + + + + + +
    +

    Breadcrumb Example

    + +
    +

    About This Example

    +

    The following example demonstrates the Breadcrumb Pattern.

    +
    + +
    +
    +

    Example

    +
    + + + +
    + +
    +

    Accessibility Features

    +
      +
    • The set of links is structured using an ordered list .
      • +
    • A nav element labeled Breadcrumb identifies the structure as a breadcrumb trail and makes it a navigation landmark so that it is easy to locate.
      • +
    • + To prevent screen reader announcement of the visual separators between links, they are added via CSS: +
        +
      • + The separators are part of the visual presentation that signifies the breadcrumb trail, which is already semantically represented by the nav element with its label of Breadcrumb. + So, using a display technique that is not represented in the accessibility tree used by screen readers prevents redundant and potentially distracting verbosity. +
        • +
      • Each link has a border on one side that is skewed with the CSS’ transform property so it resembles a slash.
        • +
      +
      • +
    +
    + +
    +

    Keyboard Support

    +

    No keyboard interaction needed.

    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    +
    • alertdialog div - Identifies the element that serves as the alert dialog container. - Identifies the element that serves as the alert dialog container.
    aria-labelledby="ID_REFERENCE" div - Gives the alert dialog an accessible name by referring to the element that provides the alert dialog title. - Gives the alert dialog an accessible name by referring to the element that provides the alert dialog title.
    aria-describedby="ID_REFERENCE" div - Gives the alert dialog an accessible description by referring to the alert dialog content that describes the primary message or purpose of the alert dialog. - Gives the alert dialog an accessible description by referring to the alert dialog content that describes the primary message or purpose of the alert dialog.
    aria-modal="true" div - Tells assistive technologies that the windows underneath the current alert dialog are not available for interaction (inert). - Tells assistive technologies that the windows underneath the current alert dialog are not available for interaction (inert).
    alertdivIdentifies the element that serves as the alert notification.
    alertdiv - Identifies the element that serves as the alert notification. -
    aria-disabled="true" button
    + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    + aria-label=Breadcrumb + + nav + Provides a label that describes the type of navigation provided in the nav element.
    + aria-current=page + + a + Applied to the last link in the set to indicate that it represents the current page.
    +
    + +
    +

    Javascript and CSS Source Code

    + +
    + +
    +

    HTML Source Code

    + +
    + + +
    +
    + + diff --git a/examples/breadcrumb/css/breadcrumb.css b/content/patterns/breadcrumb/examples/css/breadcrumb.css similarity index 100% rename from examples/breadcrumb/css/breadcrumb.css rename to content/patterns/breadcrumb/examples/css/breadcrumb.css diff --git a/content/patterns/button/button-pattern.html b/content/patterns/button/button-pattern.html new file mode 100644 index 0000000000..a4716b3dfd --- /dev/null +++ b/content/patterns/button/button-pattern.html @@ -0,0 +1,108 @@ + + + + + + Button Pattern + + + + + + + + + +
    +

    Button Pattern

    + +
    +

    About This Pattern

    +

    + A button is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation. + A common convention for informing users that a button launches a dialog is to append "…" (ellipsis) to the button label, e.g., "Save as…". +

    +

    In addition to the ordinary button widget, WAI-ARIA supports 2 other types of buttons:

    + +
    +

    Note

    +

    + The types of actions performed by buttons are distinctly different from the function of a link (see link pattern). + It is important that both the appearance and role of a widget match the function it provides. + Nevertheless, elements occasionally have the visual style of a link but perform the action of a button. + In such cases, giving the element role button helps assistive technology users understand the function of the element. + However, a better solution is to adjust the visual design so it matches the function and ARIA role. +

    +
    +
    + +
    +

    Examples

    + +
    + +
    +

    Keyboard Interaction

    +

    When the button has focus:

    + +
    + +
    +

    WAI-ARIA Roles, States, and Properties

    + +
    +
    + + diff --git a/content/patterns/button/examples/button.html b/content/patterns/button/examples/button.html new file mode 100644 index 0000000000..51ccbb6277 --- /dev/null +++ b/content/patterns/button/examples/button.html @@ -0,0 +1,200 @@ + + + + + + Button Examples + + + + + + + + + + + + + + + + +
    +

    Button Examples

    + +
    +

    About This Example

    +

    The following command and toggle button examples demonstrate the Button Pattern.

    +

    Similar examples include:

    + +
    + +
    +
    +

    Example

    +
    + + + +
    +

    This Print action button uses a div element.

    +
    Print Page
    + +

    This Mute toggle button uses an a element.

    + + Mute + + + + +
    + + +
    + +
    +

    Keyboard Support

    + + + + + + + + + + + + + + + + + + +
    KeyFunction
    EnterActivates the button.
    SpaceActivates the button.
    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    buttondiv, a +
      +
    • Identifies the element as a button widget.
      • +
    • Accessible name for the button is defined by the text content of the element.
      • +
    +
    + tabindex="0" + div, a +
      +
    • Includes the element in the tab sequence.
      • +
    • Needed on the a element because it does not have a href attribute.
      • +
    +
    aria-pressed="false"a +
      +
    • Identifies the button as a toggle button.
      • +
    • Indicates the toggle button is not pressed.
      • +
    +
    aria-pressed="true"a +
      +
    • Identifies the button as a toggle button.
      • +
    • Indicates the toggle button is pressed.
      • +
    +
    +
    + +
    +

    Javascript and CSS Source Code

    + + +
    + +
    +

    HTML Source Code

    + +
    + + +
    +
    + + diff --git a/content/patterns/button/examples/button_idl.html b/content/patterns/button/examples/button_idl.html new file mode 100644 index 0000000000..d078e695ac --- /dev/null +++ b/content/patterns/button/examples/button_idl.html @@ -0,0 +1,213 @@ + + + + + + Button Examples (IDL Version) + + + + + + + + + + + + + + + + +
    +

    Button Examples (IDL Version)

    + +
    +

    About This example

    +

    The following examples of the Button Pattern demonstrate a new JavaScript syntax for coding ARIA attributes.

    +

    + The JavaScript for the example buttons on this page uses the IDL Interface defined in ARIA 1.2. + The purpose of these examples is to illustrate how to use ARIA Attribute Reflection and provide a test case for browser and assistive technology interoperability. + Specifically, the role and ariaPressed attributes are accessed using dot notation instead of setAttribute() and getAttribute(). + In all other respects, these examples are identical to the Button Examples. +

    +
    + +
    +
    +

    Example

    +
    + + + +
    +
    +

    Important

    +

    + This example is coded using syntax that was not introduced until version 1.2 of the ARIA specification. + When using a + browser that does not yet provide support for ARIA attribute reflection, + the buttons will not be styled correctly. +

    +
    + +

    This Print action button uses a div element.

    +
    Print Page
    + +

    This Mute toggle button uses an a element.

    + + Mute + + + + +
    + + +
    + +
    +

    Keyboard Support

    + + + + + + + + + + + + + + + + + + +
    KeyFunction
    EnterActivates the button.
    SpaceActivates the button.
    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    buttondiv, a +
      +
    • Set in javascript with element.role = 'button';.
      • +
    • Identifies the element as a button widget.
      • +
    • Accessible name for the button is defined by the text content of the element.
      • +
    +
    + tabindex="0" + div, a +
      +
    • Includes the element in the tab sequence.
      • +
    • Needed on the a element because it does not have a href attribute.
      • +
    +
    aria-pressed="false"a +
      +
    • Set in javascript with button.ariaPressed = 'false';.
      • +
    • Identifies the button as a toggle button.
      • +
    • Indicates the toggle button is not pressed.
      • +
    +
    aria-pressed="true"a +
      +
    • Set in javascript with button.ariaPressed = 'true';.
      • +
    • Identifies the button as a toggle button.
      • +
    • Indicates the toggle button is pressed.
      • +
    +
    aria-hidden="true"svgExcludes SVG from accessible name calculation for the button.
    +
    + +
    +

    Javascript and CSS Source Code

    + + +
    + +
    +

    HTML Source Code

    + +
    + + +
    +
    + + diff --git a/examples/button/css/button.css b/content/patterns/button/examples/css/button.css similarity index 100% rename from examples/button/css/button.css rename to content/patterns/button/examples/css/button.css diff --git a/examples/button/js/button.js b/content/patterns/button/examples/js/button.js similarity index 100% rename from examples/button/js/button.js rename to content/patterns/button/examples/js/button.js diff --git a/examples/button/js/button_idl.js b/content/patterns/button/examples/js/button_idl.js similarity index 100% rename from examples/button/js/button_idl.js rename to content/patterns/button/examples/js/button_idl.js diff --git a/content/patterns/carousel/carousel-pattern.html b/content/patterns/carousel/carousel-pattern.html new file mode 100644 index 0000000000..6dd1c48a93 --- /dev/null +++ b/content/patterns/carousel/carousel-pattern.html @@ -0,0 +1,187 @@ + + + + + + Carousel (Slide Show or Image Rotator) Pattern + + + + + + + + + +
    +

    Carousel (Slide Show or Image Rotator) Pattern

    + +
    +

    About This Pattern

    +

    + A carousel presents a set of items, referred to as slides, by sequentially displaying a subset of one or more slides. + Typically, one slide is displayed at a time, and users can activate a next or previous slide control that hides the current slide and "rotates" the next or previous slide into view. + In some implementations, rotation automatically starts when the page loads, and it may also automatically stop once all the slides have been displayed. + While a slide may contain any type of content, image carousels where each slide contains nothing more than a single image are common. +

    +

    + Ensuring all users can easily control and are not adversely affected by slide rotation is an essential aspect of making carousels accessible. + For instance, the screen reader experience can be confusing and disorienting if slides that are not visible on screen are incorrectly hidden, e.g., displayed off-screen. + Similarly, if slides rotate automatically and a screen reader user is not aware of the rotation, the user may read an element on slide one, execute the screen reader command for next element, and, instead of hearing the next element on slide one, hear an element from slide 2 without any knowledge that the element just announced is from an entirely new context. +

    +

    Features needed to provide sufficient rotation control include:

    + +
    + +
    +

    Examples

    + +
    + +
    +

    Terms

    +

    The following terms are used to describe components of a carousel.

    +
    +
    Slide
    +
    A single content container within a set of content containers that hold the content to be presented by the carousel.
    +
    Rotation Control
    +
    An interactive element that stops and starts automatic slide rotation.
    +
    Next Slide Control
    +
    An interactive element, often styled as an arrow, that displays the next slide in the rotation sequence.
    +
    Previous Slide Control
    +
    An interactive element, often styled as an arrow, that displays the previous slide in the rotation sequence.
    +
    Slide Picker Controls
    +
    A group of elements, often styled as small dots, that enable the user to pick a specific slide in the rotation sequence to display.
    +
    +
    + +
    +

    Keyboard Interaction

    + +
    + +
    +

    WAI-ARIA Roles, States, and Properties

    +

    This section describes the element composition for three styles of carousels:

    + +

    Basic carousel elements

    + +

    Tabbed Carousel Elements

    +

    The structure of a tabbed carousel is the same as a basic carousel except that:

    + +

    Grouped Carousel Elements

    +

    A grouped carousel has the same structure as a basic carousel, but it also includes slide picker controls where:

    + +
    +
    + + diff --git a/content/patterns/carousel/examples/carousel-1-prev-next.html b/content/patterns/carousel/examples/carousel-1-prev-next.html new file mode 100644 index 0000000000..42fc6bc7a4 --- /dev/null +++ b/content/patterns/carousel/examples/carousel-1-prev-next.html @@ -0,0 +1,536 @@ + + + + + + Auto-Rotating Image Carousel Example with Buttons for Slide Control + + + + + + + + + + + + + + + +
    +

    Auto-Rotating Image Carousel Example with Buttons for Slide Control

    + +
    +

    About This Example

    +

    + The following example implementation of the Carousel Pattern demonstrates features of the pattern that are essential to accessibility for carousels that automatically start rotating when the page loads. + For instance, rotation stops when users either move focus into the carousel or hover the mouse over carousel content, and users can manually control which slide is displayed with previous and next slide buttons. + The accessibility features section that follows the example describes these features in detail. +

    +

    Similar examples include:

    + +
    + +
    +

    Example Options

    + +
    + Carousel View and Behavior Options + + +

    This option is more accessible than rendering controls and captions within the image, because controls are easier to perceive and captions are easier to read without rotating images behind them.

    + + +

    + This option controls whether the carousel is paused or playing on page load. + The paused option improves accessibility for users with visual impairments and people who are distracted or confused by auto-rotation, but allows users to start auto-rotation using the start/stop button.

    +

    Note: If the user has chosen reduced motion in system settings, auto-rotation will always be paused on load.

    + + +

    + This option improves accessibility for users with visual impairments and people who are distracted or confused by auto-rotation by disabling the auto-rotation feature and removing the start/stop button from the user interface. + Users can use the previous and next buttons to manually navigate through the slides. +

    +
    +
    + +
    +
    +

    Example

    +
    + +
    + + + +
    +
    + +
    + +
    +

    Accessibility Features

    +

    Controlling Automatic Slide Rotation

    +

    + Users can stop and start slide rotation, which is an essential aspect of accessibility of the carousel for a variety of people with disabilities. + People with low vision or a cognitive disability that affects visual processing or reading benefit from being able to control slide rotation so they have sufficient time to explore slide content. + Similarly, since screen reader users cannot perceive automatic rotation, it can make reading the page confusing and disorienting. + For example, when slides are automatically rotating, a screen reader user may read an element on slide one, execute a screen reader command to read the next element, and, instead of hearing the next element on slide one, hear an element from slide 2 without any knowledge that the element just announced is from an entirely new context. +

    +

    This example includes the following features for giving users control over slide rotation:

    + +

    Color Contrast of Text and Rotation Controls

    +

    + In the view of this carousel where the controls and captions are displayed inside the image, background images could cause color contrast for the controls and text to become insufficient. + However, this view includes the following features to prevent this potential problem and ensure it meets WCAG 2.1 color contrast requirements: +

    + + +

    + One way to avoid the color contrast issues caused by displaying controls and text within the images is to position the controls outside the image. + Displaying the controls and text on a solid background makes it easier to control color contrast. + One of the view options provides an example of this technique. +

    + +

    Screen Reader Announcement of Slide Changes

    +

    + When automatic rotation is turned off, the carousel slide content is included in a live region. + This makes it easier for screen reader users to scan through the carousel slides. + When screen reader users activate the next or previous slide button, the new slide content is announced, giving users immediate feedback that helps them determine whether or not to interact with the content. + Very importantly, if automatic rotation is turned on, the live region is disabled. + If it were not, the page would become unusable as announcements of the continuously changing content constantly interrupt anything else the user is reading. +

    +
    + +
    +

    Keyboard Support

    +
    +

    Rotation Control Button

    + + + + + + + + + + + + + + + + + +
    KeyFunction
    Tab +
      +
    • Moves focus through interactive elements in the carousel.
      • +
    • Rotation control, previous slide, and next slide buttons precede the slide content in the Tab sequence.
      • +
    +
    Enter or SpaceToggle the auto rotation of slides in the carousel.
    +
    + +
    +

    Next and Previous Slide Buttons

    + + + + + + + + + + + + + +
    KeyFunction
    Enter
    Space    		Display next or previous slide in the carousel.
    +
    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    + region + + section + +
      +
    • Role region is implied for any section element that has an accessible name.
      • +
    • Defines the carousel and its controls as a landmark region.
      • +
    +
    + aria-roledescription="carousel" + + section + +
      +
    • Informs assistive technologies to identify the element as a "carousel" rather than a "region."
      • +
    • Affects how the assistive technology renders the role but does not affect functionality, such as commands for navigating to landmark regions.
      • +
    +
    + aria-label="Highlighted television shows" + + section + Provides a label that describes the content in the carousel region.
    + aria-live="off" + + div.carousel-items + +
      +
    • Applied to a div element that contains all the slides.
      • +
    • Identifies the container element as a live region that is in the "off" state, meaning assistive technology users are not informed about changes to the region.
      • +
    • The live region is off when the carousel is automatically rotating.
      • +
    +
    + aria-live="polite" + + div.carousel-items + +
      +
    • Applied to a div element that contains all the slides.
      • +
    • Identifies the container element as a live region in the "polite" state, meaning assistive technology users are informed about changes to the region at the next available opportunity.
      • +
    • This causes screen readers to automatically announce the content of slides when the next and previous slide buttons are activated.
      • +
    +
    + group + + div.carousel-item + +
      +
    • Applied to each of the elements that contains the content of a single slide.
      • +
    • Enables assistive technology users to perceive the boundaries of a slide.
      • +
    +
    + aria-roledescription="slide" + + div.carousel-item + +
      +
    • Informs assistive technologies to identify the element as a "slide" rather than a "group."
      • +
    • Affects how the assistive technology renders the role but does not remove any assistive technology functions related to group elements.
      • +
    +
    + aria-label="N of 6" + + div.carousel-item + +
      +
    • Provides each slide with a distinct label that helps the user understand which of the 6 slides is displayed.
      • +
    • + Note: Normally, including set position and size information in an accessible name is not appropriate. + An exception is helpful in this implementation because group elements do not support aria-setsize or aria-posinset. +
      • +
    +
    + aria-label="LABEL_STRING" + + button + Defines the accessible name for the pause auto-rotation button and the next and previous slide buttons.
    + aria-controls="IDREF" + + button + +
      +
    • Identifies the content on the page that the button controls.
      • +
    • Refers to the div that contains all the slides.
      • +
    +
    +
    + +
    +

    Javascript and CSS Source Code

    + +
    + +
    +

    HTML Source Code

    + +
    + + +
    +
    + + diff --git a/examples/carousel/carousel-2-tablist.html b/content/patterns/carousel/examples/carousel-2-tablist.html similarity index 57% rename from examples/carousel/carousel-2-tablist.html rename to content/patterns/carousel/examples/carousel-2-tablist.html index 5c5dfe1a81..9ccc41caeb 100644 --- a/examples/carousel/carousel-2-tablist.html +++ b/content/patterns/carousel/examples/carousel-2-tablist.html @@ -2,45 +2,45 @@ - Auto-Rotating Image Carousel with Tabs for Slide Control Example | WAI-ARIA Authoring Practices 1.2 + + Auto-Rotating Image Carousel with Tabs for Slide Control Example - + - - - - - - - + + + + + + + + - +

    Auto-Rotating Image Carousel with Tabs for Slide Control Example

    -

    - The following example implementation of the - carousel design pattern - demonstrates features of the pattern that are essential to accessibility for carousels that automatically start rotating when the page loads. - This example also illustrates how to use the - tabs pattern - to provide users with a way to skip slides in the sequence by directly choosing which one to view. - Navigation among slides is provided by a series of circular buttons that function as tabs and are rendered over the rotating slides. - Automatic rotation stops when users move focus to any control or link in the carousel or hover the mouse over carousel content. - The accessibility features section that follows the example describes these aspects of the design in detail. -

    -

    Similar examples include:

    - + +
    +

    About This Example

    +

    + The following example implementation of the Carousel Pattern demonstrates features of the pattern that are essential to accessibility for carousels that automatically start rotating when the page loads. + This example also illustrates how to use the tabs pattern to provide users with a way to skip slides in the sequence by directly choosing which one to view. + Navigation among slides is provided by a series of circular buttons that function as tabs and are rendered over the rotating slides. + Automatic rotation stops when users move focus to any control or link in the carousel or hover the mouse over carousel content. + The accessibility features section that follows the example describes these aspects of the design in detail. +

    +

    Similar examples include:

    + +

    Example Options

    @@ -58,14 +58,20 @@

    Example Options

    Pause auto-rotation on load (reload needed) -

    This option controls whether the carousel is paused or playing on page load. The paused option improves accessibility for users with visual impairments and people who are distracted or confused by auto-rotation, but allows users to start auto-rotation using the start/stop button.

    +

    + This option controls whether the carousel is paused or playing on page load. + The paused option improves accessibility for users with visual impairments and people who are distracted or confused by auto-rotation, but allows users to start auto-rotation using the start/stop button. +

    Note: If the user has chosen reduced motion in system settings, auto-rotation will always be paused on load.

    -

    This option improves accessibility for users with visual impairments and people who are distracted or confused by auto-rotation by disabling the auto-rotation feature and removing the start/stop button from the user interface. Users can use the tablist to manually navigate through the slides.

    +

    + This option improves accessibility for users with visual impairments and people who are distracted or confused by auto-rotation by disabling the auto-rotation feature and removing the start/stop button from the user interface. + Users can use the tablist to manually navigate through the slides. +

    @@ -75,279 +81,194 @@

    Example

    - + + +
    +
    @@ -371,16 +292,20 @@

    Controlling Automatic Slide Rotation

    Moving keyboard focus to any of the carousel content, including the tab elements, pauses automatic rotation. Automatic rotation only resumes if the user explicitly activates the Play button. -
  • The carousel also contains a rotation control button that can stop and start automatic rotation. +
  • + The carousel also contains a rotation control button that can stop and start automatic rotation.
    • -
  • The example includes an option to completely disable automatic slide rotation. When this option is selected the start/stop button is not rendered and slides can only be rotated through activation of the tab controls.
    • +
  • + The example includes an option to completely disable automatic slide rotation. + When this option is selected the start/stop button is not rendered and slides can only be rotated through activation of the tab controls. +

    • Color Contrast of Text and Rotation Controls

    @@ -395,7 +320,11 @@

    Color Contrast of Text and Rotation Controls

  • The transparency of the caption area is decreased so the caption text meets the WCAG 2.1 color contrast requirements.
    • -

    One way to avoid the color contrast issues of controls and text inside the image is to move them to outside the image. Moving the controls and text to a solid background makes it easier for the author to control color contrast and for the user to perceive them. An example of this technique is one of the view options.

    +

    + One way to avoid the color contrast issues of controls and text inside the image is to move them to outside the image. + Moving the controls and text to a solid background makes it easier for the author to control color contrast and for the user to perceive them. + An example of this technique is one of the view options. +

    Focus Styling of the Tablist and Tabs

    +

    HTML Source Code

    -
    - - + diff --git a/examples/menu-button/menu-button-actions.html b/content/patterns/menu-button/examples/menu-button-actions.html similarity index 74% rename from examples/menu-button/menu-button-actions.html rename to content/patterns/menu-button/examples/menu-button-actions.html index 4ccb51a37f..f99a2e7f02 100644 --- a/examples/menu-button/menu-button-actions.html +++ b/content/patterns/menu-button/examples/menu-button-actions.html @@ -1,46 +1,49 @@ - + + - Actions Menu Button Example Using element.focus() | WAI-ARIA Authoring Practices 1.2 + + Actions Menu Button Example Using element.focus() - + - - - - + + + + + - + - +

    Actions Menu Button Example Using element.focus()

    -

    - This example demonstrates how the - menu button design pattern - can be used to create a button that opens an actions menu. - In this example, choosing an action from the menu will cause the chosen action to be displayed in the Last Action edit box. -

    -

    - In this implementation, each item in the menu is made focusable by setting tabindex="-1" so the JavaScript can use element.focus() to set focus in response to events that trigger focus movement inside the menu. - An alternative technique for managing focus movement among menu items is demonstrated in - the action menu button example that uses aria-activedescendant. -

    -

    Similar examples include:

    - + +
    +

    About This Example

    +

    + This example demonstrates how the Menu Button Pattern can be used to create a button that opens an actions menu. + In this example, choosing an action from the menu will cause the chosen action to be displayed in the Last Action edit box. +

    +

    + In this implementation, each item in the menu is made focusable by setting tabindex="-1" so the JavaScript can use element.focus() to set focus in response to events that trigger focus movement inside the menu. + An alternative technique for managing focus movement among menu items is demonstrated in the action menu button example that uses aria-activedescendant. +

    +

    Similar examples include:

    + +
    +

    Example

    @@ -48,14 +51,10 @@

    Example

    - @@ -66,9 +65,9 @@

    Example

  • Action 4
    • -

    - -

    +

    + +

    @@ -77,7 +76,8 @@

    Example

    Accessibility Features

    1. A down arrow icon is included to help users understand that the button opens a menu.
      2. -
    2. To support operating system high contrast settings: +
    3. + To support operating system high contrast settings:
      • Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements. @@ -116,7 +116,7 @@

        Menu Button

        -

        Menu

        +

        Menu

        @@ -130,8 +130,8 @@

        Menu

        @@ -153,7 +153,7 @@

        Menu

        - +
        • Activates the menu item, causing the Last Action textbox to be updated.
          • -
        • Closes the menu.
          • -
        • Sets focus on the menu button
          • +
        • Closes the menu.
          • +
        • Sets focus on the menu button.
        Down Arrow
          @@ -184,7 +184,7 @@

          Menu

          -

          Role, Property, State, and Tabindex Attributes

          +

          Role, Property, State, and Tabindex Attributes

          Menu Button

          @@ -226,17 +226,20 @@

          Menu Button

          - - - - + + + +
          aria-expanded="true"button -
            -
          • Added when the menu is open.
            • -
          • Indicates that the menu is displayed and that activating the menu button closes the menu.
            • -
          • The aria-expanded attribute is removed when the menu is closed.
            • -
          • Included to support touch devices where screen reader users can touch the menu button when the menu is displayed. Keyboard users cannot focus the menu button when the menu is open.
            • -
          -           		aria-expanded="true"button +
            +
          • Added when the menu is open.
            • +
          • Indicates that the menu is displayed and that activating the menu button closes the menu.
            • +
          • The aria-expanded attribute is removed when the menu is closed.
            • +
          • + Included to support touch devices where screen reader users can touch the menu button when the menu is displayed. + Keyboard users cannot focus the menu button when the menu is open. +
            • +
          +
          @@ -306,7 +309,6 @@

          Menu

        -
        @@ -317,25 +319,17 @@

        Javascript and CSS Source Code

      • Javascript: menu-button-actions.js
      +

      HTML Source Code

      -
      -
    - - + diff --git a/examples/menu-button/menu-button-links.html b/content/patterns/menu-button/examples/menu-button-links.html similarity index 69% rename from examples/menu-button/menu-button-links.html rename to content/patterns/menu-button/examples/menu-button-links.html index bfc41ae6ea..be03552141 100644 --- a/examples/menu-button/menu-button-links.html +++ b/content/patterns/menu-button/examples/menu-button-links.html @@ -2,50 +2,53 @@ - Navigation Menu Button Example | WAI-ARIA Authoring Practices 1.2 + + Navigation Menu Button Example - + - - - - + + + + + - + - +

    Navigation Menu Button Example

    -

    - This example demonstrates the - menu button design pattern - for a button that displays a menu of link targets. - The menu items are made from HTML links, so they maintain their HTML link behaviors. - That is, activating a menuitem loads the link target, and the browser's link context menu and associated actions are available. -

    -

    - In this implementation, an HTML button element reveals a menu structure made with an HTML ul element. - The menuitem role is on the HTML a element contained by each li element so link behaviors are available when focus is set on the menu item. - Another reason for applying the menuitem role to the a element instead of the li element is that the semantics of descendants of menuitem elements are not exposed in the accessibility tree. - That is, an item in a menu can only be a menuitem because accessibility APIs do not enable assistive technologies to render elements contained inside of an item in a menu. - For a more detailed description of this constraint, see - Roles That Automatically Hide Semantics by Making Their Descendants Presentational. -

    -

    Similar examples include:

    - + +
    +

    About This Example

    +

    + This example demonstrates the Menu Button Pattern for a button that displays a menu of link targets. + The menu items are made from HTML links, so they maintain their HTML link behaviors. + That is, activating a menuitem loads the link target, and the browser's link context menu and associated actions are available. +

    +

    + In this implementation, an HTML button element reveals a menu structure made with an HTML ul element. + The menuitem role is on the HTML a element contained by each li element so link behaviors are available when focus is set on the menu item. + Another reason for applying the menuitem role to the a element instead of the li element is that the semantics of descendants of menuitem elements are not exposed in the accessibility tree. + That is, an item in a menu can only be a menuitem because accessibility APIs do not enable assistive technologies to render elements contained inside of an item in a menu. + For a more detailed description of this constraint, see + Roles That Automatically Hide Semantics by Making Their Descendants Presentational. +

    +

    Similar examples include:

    + +
    +

    Example

    @@ -53,47 +56,31 @@

    Example

    -
    @@ -105,7 +92,8 @@

    Example

    Accessibility Features

    1. A down arrow icon is included to help users understand that the button opens a menu.
      2. -
    2. To support operating system high contrast settings: +
    3. + To support operating system high contrast settings:
      • Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements. @@ -144,7 +132,7 @@

        Menu Button

        -

        Menu

        +

        Menu

        @@ -155,9 +143,7 @@

        Menu

        - + @@ -177,7 +163,7 @@

        Menu

        - +
        Space
        Enter        		 - Activates the menu item, which is equivalent to activating the link element from which the menu item is made. - Activates the menu item, which is equivalent to activating the link element from which the menu item is made.
        Escape
        Down Arrow
          @@ -207,8 +193,8 @@

          Menu

    -
    -

    Role, Property, State, and Tabindex Attributes

    +
    +

    Role, Property, State, and Tabindex Attributes

    Menu Button

    @@ -250,17 +236,20 @@

    Menu Button

    - - - - + + + +
    aria-expanded="true"button -
      -
    • Added when the menu is open.
      • -
    • Indicates that the menu is displayed and that activating the menu button closes the menu.
      • -
    • The aria-expanded attribute is removed when the menu is closed.
      • -
    • Included to support touch devices where screen reader users can touch the menu button when the menu is displayed. Keyboard users cannot focus the menu button when the menu is open.
      • -
    -     		aria-expanded="true"button +
      +
    • Added when the menu is open.
      • +
    • Indicates that the menu is displayed and that activating the menu button closes the menu.
      • +
    • The aria-expanded attribute is removed when the menu is closed.
      • +
    • + Included to support touch devices where screen reader users can touch the menu button when the menu is displayed. + Keyboard users cannot focus the menu button when the menu is open. +
      • +
    +
    @@ -313,7 +302,9 @@

    Menu

    @@ -352,24 +343,17 @@

    Javascript and CSS Source Code

  • Javascript: menu-button-links.js
    • +

    HTML Source Code

    -
    - diff --git a/content/patterns/menu-button/menu-button-pattern.html b/content/patterns/menu-button/menu-button-pattern.html new file mode 100644 index 0000000000..950768b9bd --- /dev/null +++ b/content/patterns/menu-button/menu-button-pattern.html @@ -0,0 +1,73 @@ + + + + + + Menu Button Pattern + + + + + + + + + +
    +

    Menu Button Pattern

    + +
    +

    About This Pattern

    +

    + A menu button is a button that opens a menu as described in the Menu and Menubar Pattern. + It is often styled as a typical push button with a downward pointing arrow or triangle to hint that activating the button will display a menu. +

    +
    + +
    +

    Examples

    + +
    + +
    +

    Keyboard Interaction

    + +
    + +
    +

    WAI-ARIA Roles, States, and Properties

    + +
    +
    + + diff --git a/examples/menubar/css/menubar-editor.css b/content/patterns/menubar/examples/css/menubar-editor.css similarity index 100% rename from examples/menubar/css/menubar-editor.css rename to content/patterns/menubar/examples/css/menubar-editor.css diff --git a/examples/menubar/css/menubar-navigation.css b/content/patterns/menubar/examples/css/menubar-navigation.css similarity index 100% rename from examples/menubar/css/menubar-navigation.css rename to content/patterns/menubar/examples/css/menubar-navigation.css diff --git a/examples/menubar/js/menubar-editor.js b/content/patterns/menubar/examples/js/menubar-editor.js similarity index 100% rename from examples/menubar/js/menubar-editor.js rename to content/patterns/menubar/examples/js/menubar-editor.js diff --git a/examples/menubar/js/menubar-navigation.js b/content/patterns/menubar/examples/js/menubar-navigation.js similarity index 100% rename from examples/menubar/js/menubar-navigation.js rename to content/patterns/menubar/examples/js/menubar-navigation.js diff --git a/examples/menubar/js/style-manager.js b/content/patterns/menubar/examples/js/style-manager.js similarity index 100% rename from examples/menubar/js/style-manager.js rename to content/patterns/menubar/examples/js/style-manager.js diff --git a/content/patterns/menubar/examples/menubar-editor.html b/content/patterns/menubar/examples/menubar-editor.html new file mode 100644 index 0000000000..f645022039 --- /dev/null +++ b/content/patterns/menubar/examples/menubar-editor.html @@ -0,0 +1,794 @@ + + + + + + Editor Menubar Example + + + + + + + + + + + + + + + + +
    +

    Editor Menubar Example

    + +
    +

    About This Example

    +

    + The following example demonstrates using the Menubar Pattern to provide access to editing actions for a text area. + Each item in the menubar identifies a category of text formatting actions that can be executed from its submenu. + The submenus demonstrate menuitemradio and menuitemcheckbox elements. +

    +

    Similar examples include:

    + +
    + +
    +
    +

    Example

    +
    + +
    +
    +
      +
    • + +
        +
      • Sans-serif
        • +
      • Serif
        • +
      • Monospace
        • +
      • Fantasy
        • +
      +
      • +
    • + +
        +
      • +
          +
        • Bold
          • +
        • Italic
          • +
        +
        • +
      • +
      • +
          +
        • Black
          • +
        • Blue
          • +
        • Red
          • +
        • Green
          • +
        +
        • +
      • +
      • +
          +
        • None
          • +
        • Overline
          • +
        • Line-through
          • +
        • Underline
          • +
        +
        • +
      +
      • + +
    • + +
        +
      • Left
        • +
      • Center
        • +
      • Right
        • +
      • Justify
        • +
      +
      • + +
    • + +
        +
      • Smaller
        • +
      • Larger
        • +
      • +
      • +
          +
        • X-Small
          • +
        • Small
          • +
        • Medium
          • +
        • Large
          • +
        • X-Large
          • +
        +
        • +
      +
      • +
    + +
    + +

    + More information on Gettysburg Address +

    +
    + +
    + +
    +

    Accessibility Features

    + +
    + +
    +

    Keyboard Support

    +

    Menubar

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyFunction
    Space
    Enter    		Opens submenu and moves focus to first item in the submenu.
    + Escape + + If a submenu is open, closes it. + Otherwise, does nothing. +
    + Right Arrow + +
      +
    • Moves focus to the next item in the menubar.
      • +
    • If focus is on the last item, moves focus to the first item.
      • +
    +
    + Left Arrow + +
      +
    • Moves focus to the previous item in the menubar.
      • +
    • If focus is on the first item, moves focus to the last item.
      • +
    +
    + Down Arrow + Opens submenu and moves focus to first item in the submenu.
    + Up Arrow + Opens submenu and moves focus to last item in the submenu.
    + Home + Moves focus to first item in the menubar.
    + End + Moves focus to last item in the menubar.
    + Character + +
      +
    • Moves focus to next item in the menubar having a name that starts with the typed character.
      • +
    • If none of the items have a name starting with the typed character, focus does not move.
      • +
    +
    + +

    Submenu

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyFunction
    Space
    Enter    		Activates menu item, causing action to be executed, e.g., bold text, change font.
    + Escape + +
      +
    • Closes submenu.
      • +
    • Moves focus to parent menubar item.
      • +
    +
    + Right Arrow + +
      +
    • Closes submenu.
      • +
    • Moves focus to next item in the menubar.
      • +
    • Opens submenu of newly focused menubar item, keeping focus on that parent menubar item.
      • +
    +
    + Left Arrow + +
      +
    • Closes submenu.
      • +
    • Moves focus to previous item in the menubar.
      • +
    • Opens submenu of newly focused menubar item, keeping focus on that parent menubar item.
      • +
    +
    + Down Arrow + +
      +
    • Moves focus to the next item in the submenu.
      • +
    • If focus is on the last item, moves focus to the first item.
      • +
    +
    + Up Arrow + +
      +
    • Moves focus to previous item in the submenu.
      • +
    • If focus is on the first item, moves focus to the last item.
      • +
    +
    + Home + Moves focus to the first item in the submenu.
    + End + Moves focus to the last item in the submenu.
    + Character + +
      +
    • Moves focus to the next item having a name that starts with the typed character.
      • +
    • If none of the items have a name starting with the typed character, focus does not move.
      • +
    +
    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    +

    Menubar

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    + menubar + + ul + + +
    + aria-label="string" + + ul + +
      +
    • Defines an accessible name for the menubar.
      • +
    • Helps assistive technology users understand the purpose of the menubar and distinguish it from any other menubars or similar elements on the page.
      • +
    +
    + menuitem + + span + +
      +
    • Identifies the element as a menu item within the menubar.
      • +
    • Accessible name comes from the text content.
      • +
    +
    + tabindex="-1" + + span + Makes the menuitem element keyboard focusable but not part of the Tab sequence of the page.
    + tabindex="0" + + span + +
      +
    • Makes the menuitem element keyboard focusable and part of the tab sequence of the page.
      • +
    • Only one menuitem in the menubar has tabindex="0".
      • +
    • When the page loads, the first item in the menubar has tabindex="0".
      • +
    • + Focus is managed using the practice for + Managing Focus Within Components Using a Roving tabindex. +
      • +
    +
    + aria-haspopup="true" + + span + Indicates that the menuitem has a submenu.
    + aria-expanded="true" + + span + +
      +
    • Indicates the submenu is open.
      • +
    • The visual appearance of the expanded state is synchronized with the aria-expanded value using CSS attribute selectors and hidden from screen readers with aria-hidden="true".
      • +
    +
    + aria-expanded="false" + + span + +
      +
    • Indicates the submenu is closed.
      • +
    • The visual appearance of the expanded state is synchronized with the aria-expanded value using CSS attribute selectors and hidden from screen readers with aria-hidden="true".
      • +
    +
    + aria-hidden="true" + + span + Removes the character entities used to represent the down arrow icons for parent menu items from the accessibility tree to prevent them from being included in the accessible name of the menu item.
    +

    Submenu

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    + menu + + ul + + +
    + aria-label="string" + + ul + Defines an accessible name for the menu.
    + menuitem + + li + +
      +
    • Identifies the element as an item in the submenu.
      • +
    • Accessible name comes from the text content.
      • +
    +
    + tabindex="-1" + + li + Makes the item focusable but not part of the page tab sequence.
    + aria-disabled="false" + + li + Used on the font size "Smaller" and "Larger" options to indicate they are active.
    + aria-disabled="true" + + li + Used on the font size "Smaller" and "Larger" options to indicate one of the options is not active because the largest or smallest font has been selected.
    + menuitemcheckbox + + li + +
      +
    • Identifies the element as a menuitemcheckbox.
      • +
    • Accessible name comes from the text content.
      • +
    +
    + tabindex="-1" + + li + Makes the menuitemcheckbox focusable but not part of the page tab sequence.
    + aria-checked="true" + + li + +
      +
    • Indicates that the menuitemcheckbox is checked.
      • +
    • The visual appearance of the selected state is synchronized with the aria-checked value using CSS attribute selectors and hidden from screen readers with aria-hidden="true".
      • +
    +
    + aria-checked="false" + + li + +
      +
    • Indicates that the menuitemcheckbox is NOT checked.
      • +
    • The visual appearance of the selected state is synchronized with the aria-checked value using CSS attribute selectors and hidden from screen readers with aria-hidden="true".
      • +
    +
    + aria-hidden="true" + + span + Removes the character entities that visually represent the checked state of menuitemcheckbox elements from the accessibility tree to prevent them from being included in the accessible name of the menu item.
    + separator + + li + +
      +
    • Identifies the element as a visual separator between groups of items within a menu, such as groups of menuitemradio or menuitemcheckbox elements.
      • +
    • Is not focusable but may be perceivable by a screen reader user when using a reading cursor that does not depend on focus.
      • +
    +
    + group + + ul + +
      +
    • Identifies the element as a container for a set of menuitemradio elements.
      • +
    • Enables browsers to compute values of aria-setsize and aria-posinset.
      • +
    +
    + aria-label="string" + + ul + Provides an accessible name for the group of menu items.
    + menuitemradio + + li + +
      +
    • Identifies the element as a menuitemradio element.
      • +
    • When all items in a submenu are members of the same radio group, the group is defined by the menu element; a group element is not necessary.
      • +
    • Accessible name is computed from the text content.
      • +
    +
    + tabindex="-1" + + li + Makes the menuitemradio focusable but not part of the page tab sequence.
    + aria-checked="true" + + li + +
      +
    • Indicates the menuitemradio is checked.
      • +
    • The visual appearance of the selected state is synchronized with the aria-checked value using CSS attribute selectors and hidden from screen readers with aria-hidden="true".
      • +
    +
    + aria-checked="false" + + li + +
      +
    • Indicates that the menuitemradio is NOT checked.
      • +
    • The visual appearance of the selected state is synchronized with the aria-checked value using CSS attribute selectors and hidden from screen readers with aria-hidden="true".
      • +
    +
    + aria-hidden="true" + + span + Removes the character entities that visually represent the checked state of menuitemradio elements from the accessibility tree to prevent them from being included in the accessible name of the menu item.
    +

    Textarea

    + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    + aria-label="string" + + textarea + Defines an accessible name for the textarea.
    +
    + +
    +

    Javascript and CSS Source Code

    + +
    + +
    +

    HTML Source Code

    + +
    + + +
    +
    + + diff --git a/content/patterns/menubar/examples/menubar-navigation.html b/content/patterns/menubar/examples/menubar-navigation.html new file mode 100644 index 0000000000..6e3ad6ed93 --- /dev/null +++ b/content/patterns/menubar/examples/menubar-navigation.html @@ -0,0 +1,828 @@ + + + + + + Navigation Menubar Example + + + + + + + + + + + + + + + +
    +

    Navigation Menubar Example

    + +
    +

    About This Example

    +
    +

    Caution!

    +

    Before considering use of the Menubar Pattern for site navigation, it is important to understand:

    +
      +
    • The menubar pattern requires complex functionality that is unnecessary for typical site navigation that is styled to look like a menubar with expandable sections or fly outs.
      • +
    • + A pattern more suited for typical site navigation with expandable groups of links is the Disclosure Pattern. + For an example, see Example Disclosure Navigation Menu. +
      • +
    +
    +

    + The following implementation of the Menubar Pattern demonstrates how a menubar can provide navigation menus. + The parent menu items in the menubar represent a section of a mythical university web site and open a submenu containing menu items that link to pages within that section. + The navigation system it illustrates is comparable to the navigation illustrated in the + Example Disclosure Navigation Menu. + As noted above, the disclosure pattern is better suited for most web sites because few sites need the additional keyboard functionality required to support the ARIA menubar and menu roles. +

    +

    Similar examples include:

    + +
    + +
    +
    +

    Example

    +
    + +
    +
    + +
    +
    Mythical University
    +
    Using a Menubar for navigation links
    +
    + + +
    +
    +

    Mythical University

    +
    +

    +
    +
    +
    + +
    Mythical University footer information
    +
    +
    + +
    + +
    +

    Accessibility Features

    +
      +
    1. + Menu items that trigger navigation move focus to the target page title: +
        +
      • + An important aspect of designing a navigation menu experience is where keyboard focus moves when an item that triggers navigation is activated and the menu closes. + If activating a menubar item changes content on the page without triggering a browser page load, i.e., works like typical single-page apps, the focus position after the content load significantly effects efficiency for keyboard and assistive technology users. +
        • +
      • + This example behaves like a single page app and activating a menu item that loads new content moves focus to the beginning of the new content, which is a level one heading with content that matches the name of the activated menu item. + Focusing on the heading informs screen reader users that navigation is complete and confirms the destination. +
        • +
      • To view other pages, keyboard users need to navigate back to the menubar . To optimize keyboard efficiency, this example locates the menubar immediately before the content display area in the Tab sequence.
        • +
      +
      2. +
    2. To help communicate that the arrow keys are available for directional navigation within the menubar and its submenus, a border is added to the menubar container when focus is within the menubar.
      3. +
    3. + To help users locate the menu item that loads the currently displayed page, visual indicators of the path to that menu item are added to the menu items in the path: +
        +
      • The parent menubar item in the path has an extra thick (4 pixel) bottom border.
        • +
      • If the current page menu item is nested within a deeper submenu, the parent submenu item in the path has an extra thick (4 pixel) left side border.
        • +
      • Finally, the menu item that loads the currently displayed page is styled with an extra thick border on the left side.
        • +
      +
      4. +
    4. + To support operating system high contrast settings: +
        +
      • + Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements. + Instead of using transparency, the focused element has a thicker border and less padding. + When an element receives focus, its border changes from 0 to 2 pixels and padding is reduced by 2 pixels. + When an element loses focus, its border changes from 2 to 0 pixels and padding is increased by 2 pixels. +
        • +
      • + To ensure the arrow icons used to indicate the expanded or collapsed state have sufficient contrast with the background when high contrast settings invert colors, the CSS currentcolor value for the fill and stroke properties of the SVG polygon element is used to synchronize the color with text content. + If specific colors are used to specify the fill and stroke properties, these colors will remain the same in high contrast mode, which could lead to insufficient contrast between the icon and the background or even make the icon invisible if its color matches the high contrast mode background. +
        • +
      +
      5. +
    5. Since the menubar presents a site navigation system, it is wrapped in a navigation region implemented with a nav element that has an aria-label that matches the label on the menubar.
      6. +
    +
    + +
    +

    Keyboard Support

    +

    Menubar

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyFunction
    Space
    Enter    		 +
      +
    • If the item is a parent menu item, opens submenu and moves focus to first item in the submenu.
      • +
    • Otherwise, activates the menu item, which loads new content and places focus on the heading that titles the content.
      • +
    +
    + Right Arrow + +
      +
    • Moves focus to the next item in the menubar.
      • +
    • If focus is on the last item, moves focus to the first item.
      • +
    +
    + Left Arrow + +
      +
    • Moves focus to the previous item in the menubar.
      • +
    • If focus is on the first item, moves focus to the last item.
      • +
    +
    + Down Arrow + Opens submenu and moves focus to first item in the submenu.
    + Up Arrow + Opens submenu and moves focus to last item in the submenu.
    + Home + Moves focus to first item in the menubar.
    + End + Moves focus to last item in the menubar.
    + Character + +
      +
    • Moves focus to next item in the menubar having a name that starts with the typed character.
      • +
    • If none of the items have a name starting with the typed character, focus does not move.
      • +
    +
    + +

    Submenu

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyFunction
    Space
    Enter    		 +
      +
    • If the item is a parent menu item, opens submenu and moves focus to first item in the submenu.
      • +
    • Otherwise, activates the menu item, which loads new content and places focus on the heading that titles the content.
      • +
    +
    + Escape + +
      +
    • Closes submenu.
      • +
    • Moves focus to parent menubar item.
      • +
    +
    + Right Arrow + +
      +
    • If focus is on an item with a submenu, opens the submenu and places focus on the first item.
      • +
    • + If focus is on an item that does not have a submenu: +
        +
      • Closes submenu.
        • +
      • Moves focus to next item in the menubar.
        • +
      • Opens submenu of newly focused menubar item, keeping focus on that parent menubar item.
        • +
      +
      • +
    +
    + Left Arrow + +
      +
    • Closes submenu and moves focus to parent menu item.
      • +
    • + If parent menu item is in the menubar, also: +
        +
      • moves focus to previous item in the menubar.
        • +
      • Opens submenu of newly focused menubar item, keeping focus on that parent menubar item.
        • +
      +
      • +
    +
    + Down Arrow + +
      +
    • Moves focus to the next item in the submenu.
      • +
    • If focus is on the last item, moves focus to the first item.
      • +
    +
    + Up Arrow + +
      +
    • Moves focus to previous item in the submenu.
      • +
    • If focus is on the first item, moves focus to the last item.
      • +
    +
    + Home + Moves focus to the first item in the submenu.
    + End + Moves focus to the last item in the submenu.
    + Character + +
      +
    • Moves focus to the next item having a name that starts with the typed character.
      • +
    • If none of the items have a name starting with the typed character, focus does not move.
      • +
    +
    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    + +

    Landmarks

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    bannerheader +
      +
    • Identifies the top section of content that is common across pages in a web site.
      • +
    • + NOTE: The banner role declaration is only necessary because it is an example that is nested inside the content of this page. + In an actual website, the header element would be a top level element, i.e., it would have the body as its scope. + If the scope of the header element were body, browsers would automatically treat the header as an ARIA banner, so the header would not need role="banner". +
      • +
    +
    navigationnavIdentifies the region containing the mythical university navigation.
    aria-label="Mythical University"navProvides an accessible name for the navigation landmark that describes the purpose of the navigation.
    regionsection +
      +
    • Identifies the main content region of the page depicted in the example.
      • +
    • In an actual web page, this region would be identified by a main landmark, but since this page already has a main landmark, role region is used to avoid having two main landmarks on the page.
      • +
    +
    aria-labelledby="idref"sectionProvides the region with an accessible name from the h1 element.
    contentinfofooter +
      +
    • Identifies the bottom section of content common across pages in a web site.
      • +
    • + NOTE: The contentinfo role declaration is only necessary because the footer is an example that is nested inside the content of this page. + In an actual website, the footer element would be a top level element, i.e., it would have the body as its scope. + If the scope of the footer element were body, browsers would automatically treat the footer as a ARIA contentinfo landmark, so the footer would not need role="contentinfo". +
      • +
    +
    + +

    Menubar

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    + menubar + + ul + + +
    + aria-label="string" + + ul + +
      +
    • Defines an accessible name for the menubar.
      • +
    • Helps assistive technology users understand the purpose of the menubar and distinguish it from any other menubars or similar elements on the page.
      • +
    +
    + menuitem + + a + +
      +
    • Identifies the element as a menu item.
      • +
    • The accessible name is calculated from the text content of the a element.
      • +
    +
    + tabindex="-1" + + a + Makes the a element keyboard focusable, but not part of the tab sequence.
    + tabindex="0" + + a + + +
    + aria-current="page" + + a + +
      +
    • Identifies the link URL has the same URL as the web page.
      • +
    • If the link URL is not the same, the attribute is removed.
      • +
    • Menu items in the menubar in the path to the current page menu item are given a title attribute with the text content of "Contains current page link" to indicate to screen reader users the menu item contains the current page link.
      • +
    +
    + aria-haspopup="true" + + a + Indicates the menuitem has a submenu.
    + aria-expanded="true" + + a + Indicates the submenu is open.
    + aria-expanded="false" + + a + Indicates the submenu is closed.
    + none + + li + +
      +
    • Removes the implied listitem role of the li element.
      • +
    • Necessary because the parent ul is serving as a menu so the li elements are not in their required list context.
      • +
    +
    +

    Submenu

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    + menu + + ul + Identifies the element as a menu container for a set of menu items.
    + aria-label="string" + + ul + +
      +
    • Defines an accessible name for the menu.
      • +
    • Helps assistive technology users understand the purpose of the menu and distinguish it from any other menu or similar elements (e.g. menubar) on the page.
      • +
    +
    + menuitem + + a + +
      +
    • Identifies the element as a menu item.
      • +
    • The accessible name is calculated from the text content of the a element.
      • +
    +
    + tabindex="-1" + + a + Keeps the a element focusable but removes it from the Tab sequence.
    + aria-haspopup="true" + + a + Indicates the menu item has a submenu.
    + aria-expanded="true" + + a + Indicates the submenu is open.
    + aria-expanded="false" + + a + Indicates the submenu is closed.
    + none + + li + +
      +
    • Removes the implied listitem role of the li element.
      • +
    • Necessary because the parent ul is serving as a menu so the li elements are not in their required list context.
      • +
    +
    +
    + +
    +

    Javascript and CSS Source Code

    + +
    + +
    +

    HTML Source Code

    + +
    + + +
    +
    + + diff --git a/content/patterns/menubar/menu-and-menubar-pattern.html b/content/patterns/menubar/menu-and-menubar-pattern.html new file mode 100644 index 0000000000..d3cf541029 --- /dev/null +++ b/content/patterns/menubar/menu-and-menubar-pattern.html @@ -0,0 +1,246 @@ + + + + + + Menu and Menubar Pattern + + + + + + + + + +
    +

    Menu and Menubar Pattern

    + +
    +

    About This Pattern

    +

    + A menu is a widget that offers a list of choices to the user, such as a set of actions or functions. + Menu widgets behave like native operating system menus, such as the menus that pull down from the menubars commonly found at the top of many desktop application windows. + A menu is usually opened, or made visible, by activating a menu button, choosing an item in a menu that opens a sub menu, or by invoking a command, such as Shift + F10 in Windows, that opens a context specific menu. + When a user activates a choice in a menu, the menu usually closes unless the choice opened a submenu. +

    + +

    + A menu that is visually persistent is a menubar. + A menubar is typically horizontal and is often used to create a menu bar similar to those found near the top of the window in many desktop applications, offering the user quick access to a consistent set of commands. +

    + +

    A common convention for indicating that a menu item launches a dialog box is to append "…" (ellipsis) to the menu item label, e.g., "Save as …".

    +
    + +
    +

    Examples

    + +
    + +
    +

    Keyboard Interaction

    +

    The following description of keyboard behaviors assumes:

    +
      +
    1. A horizontal menubar containing several menuitem, menuitemradio, or menuitemcheckbox elements.
      2. +
    2. Some menuitem elements in the menubar have child submenus that contain vertically arranged items.
      3. +
    3. Some of the menuitem elements in the submenus have child submenus with items that are also vertically arranged.
      4. +
    +

    When reading the following descriptions, also keep in mind that:

    +
      +
    1. Focusable elements, which may have role menuitem, menuitemradio, or menuitemcheckbox, are referred to as items.
      2. +
    2. If a behavior applies to only certain types of items, e.g., menuitem elements, the specific role name is used.
      3. +
    3. Submenus, also known as popup menus, are elements with role menu.
      4. +
    4. Except where noted, menus opened from a menubutton behave the same as menus opened from a menubar.
      5. +
    +

    + When a menu opens, or when a menubar receives focus, keyboard focus is placed on the first item. + Because menubar and menu elements are composite widgets as described in the practice for + Keyboard Navigation Inside Components, + Tab and Shift + Tab do not move focus among the items in the menu. + Instead, the keyboard commands described in this section enable users to move focus among the elements in a menubar or menu. +

    + +
    +

    Note

    +
      +
    1. Disabled menu items are focusable but cannot be activated.
      2. +
    2. A separator in a menu is not focusable or interactive.
      3. +
    3. + If a menu is opened or a menubar receives focus as a result of a context action, Escape or Enter may return focus to the invoking context. + For example, a rich text editor may have a menubar that receives focus when a shortcut key, e.g., alt + F10, is pressed while editing. + In this case, pressing Escape or activating a command from the menu may return focus to the editor. +
      4. +
    4. + 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. +
      5. +
    5. + When items in a menubar are arranged vertically and items in menu containers are arranged horizontally: +
        +
      1. Down Arrow performs as Right Arrow is described above, and vice versa.
        2. +
      2. Up Arrow performs as Left Arrow is described above, and vice versa.
        3. +
      +
      6. +
    +
    +
    + +
    +

    WAI-ARIA Roles, States, and Properties

    + +
    +

    Note

    +

    If aria-owns is set on the menu container to include elements that are not DOM children of the container, those elements will appear in the reading order in the sequence they are referenced and after any items that are DOM children. + Scripts that manage focus need to ensure the visual focus order matches this assistive technology reading order.

    +
    +
    +
    + + diff --git a/examples/meter/css/meter.css b/content/patterns/meter/examples/css/meter.css similarity index 100% rename from examples/meter/css/meter.css rename to content/patterns/meter/examples/css/meter.css diff --git a/examples/meter/js/meter.js b/content/patterns/meter/examples/js/meter.js similarity index 100% rename from examples/meter/js/meter.js rename to content/patterns/meter/examples/js/meter.js diff --git a/content/patterns/meter/examples/meter.html b/content/patterns/meter/examples/meter.html new file mode 100644 index 0000000000..212207ee33 --- /dev/null +++ b/content/patterns/meter/examples/meter.html @@ -0,0 +1,144 @@ + + + + + + Meter Example + + + + + + + + + + + + + + + + +
    +

    Meter Example

    + +
    +

    About This Example

    +

    The following example of a CPU meter demonstrates the Meter Pattern.

    +
    + +
    +
    +

    Example

    +
    + + +
    +

    + The value of this meter changes every 5 seconds. + Use the pause button to stop changes. +

    +

    Central Processing Unit (CPU) Usage

    +

    + +

    +
    + +
    +
    + +
    + +
    +

    Keyboard Support

    +

    Not applicable.

    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    meter + div + +
      +
    • Identifies the element as a meter.
      • +
    +
    aria-valuemin="NUMBER"divSpecifies the minimum value the meter can have.
    aria-valuemax="NUMBER"divSpecifies the maximum value the meter can have.
    aria-valuenow="NUMBER"divSpecifies the current value of the meter.
    aria-labelledbydivIdentifies the element that provides the accessible name of the meter.
    +
    + +
    +

    Javascript and CSS Source Code

    + + +
    + +
    +

    HTML Source Code

    + +
    + + +
    +
    + + diff --git a/content/patterns/meter/meter-pattern.html b/content/patterns/meter/meter-pattern.html new file mode 100644 index 0000000000..fb7cc6f5ec --- /dev/null +++ b/content/patterns/meter/meter-pattern.html @@ -0,0 +1,67 @@ + + + + + + Meter Pattern + + + + + + + + + +
    +

    Meter Pattern

    + +
    +

    About This Pattern

    +

    + A meter is a graphical display of a numeric value that varies within a defined range. + For example, a meter could be used to depict a device's current battery percentage or a car's fuel level. +

    +
    +

    Note

    +
      +
    • A meter should not be used to represent a value like the current world population since it does not have a meaningful maximum limit.
      • +
    • + The meter should not be used to indicate progress, such as loading or percent completion of a task. + To communicate progress, use the progressbar role instead. +
      • +
    +
    +
    + +
    +

    Example

    +

    Meter Example

    +
    + +
    +

    Keyboard Interaction

    +

    Not applicable.

    +
    + +
    +

    WAI-ARIA Roles, States, and Properties

    + +
    +
    + + diff --git a/content/patterns/patterns.html b/content/patterns/patterns.html new file mode 100644 index 0000000000..97a3732e8a --- /dev/null +++ b/content/patterns/patterns.html @@ -0,0 +1,12 @@ + + + + + + + Patterns + + + In a future iteration this file will contain a list of all patterns. + + diff --git a/examples/radio/css/radio-rating.css b/content/patterns/radio/examples/css/radio-rating.css similarity index 100% rename from examples/radio/css/radio-rating.css rename to content/patterns/radio/examples/css/radio-rating.css diff --git a/examples/radio/css/radio.css b/content/patterns/radio/examples/css/radio.css similarity index 100% rename from examples/radio/css/radio.css rename to content/patterns/radio/examples/css/radio.css diff --git a/examples/radio/js/radio-activedescendant.js b/content/patterns/radio/examples/js/radio-activedescendant.js similarity index 100% rename from examples/radio/js/radio-activedescendant.js rename to content/patterns/radio/examples/js/radio-activedescendant.js diff --git a/examples/radio/js/radio-rating.js b/content/patterns/radio/examples/js/radio-rating.js similarity index 100% rename from examples/radio/js/radio-rating.js rename to content/patterns/radio/examples/js/radio-rating.js diff --git a/examples/radio/js/radio.js b/content/patterns/radio/examples/js/radio.js similarity index 100% rename from examples/radio/js/radio.js rename to content/patterns/radio/examples/js/radio.js diff --git a/examples/radio/radio-activedescendant.html b/content/patterns/radio/examples/radio-activedescendant.html similarity index 67% rename from examples/radio/radio-activedescendant.html rename to content/patterns/radio/examples/radio-activedescendant.html index 4fb8c418ca..bb83ff4595 100644 --- a/examples/radio/radio-activedescendant.html +++ b/content/patterns/radio/examples/radio-activedescendant.html @@ -1,107 +1,80 @@ - + - Radio Group Example Using aria-activedescendant | WAI-ARIA Authoring Practices 1.2 + + Radio Group Example Using aria-activedescendant - + - - - - + + + + + - + - +

    Radio Group Example Using aria-activedescendant

    -

    - This example implements the features of the Radio Group Design Pattern - for two radio groups -- one for choosing a pizza crust and another for choosing a delivery method. - This implementation uses aria-activedescendant for informing assistive technologies which radio button has visual focus. -

    -

    Similar examples include:

    - -
    -
    -

    Example

    -
    - -
    -

    Pizza Crust

    -
      - - - +
      +

      About This Example

      +

      + This example implements the features of the Radio Group Pattern for two radio groups -- one for choosing a pizza crust and another for choosing a delivery method. + This implementation uses aria-activedescendant for informing assistive technologies which radio button has visual focus. +

      +

      Similar examples include:

      + +
      + +
      +
      +

      Example

      +
      + +
      +

      Pizza Crust

      -

      Pizza Delivery

      +
        + + + +
      -
        - - - -
      +

      Pizza Delivery

      -
      - -
      +
        + + + +
      +
    + +

    Accessibility Features

    -
    -

    Role, Property, State, and Tabindex Attributes

    +
    +

    Role, Property, State, and Tabindex Attributes

    @@ -225,10 +197,10 @@

    Role, Property, State, and Tabindex Attributes

    • When a radio button in the radio group is visually indicated as having keyboard focus, refers to that radio button.
    • When arrow keys are pressed, the JavaScript changes the value.
      • -
    • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the radio group element.
      • +
    • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the radio group element.
    • For more information about this focus management technique, see - Using aria-activedescendant to Manage Focus. + Managing Focus in Composites Using aria-activedescendant.
    @@ -275,8 +247,8 @@

    Role, Property, State, and Tabindex Attributes

    Javascript and CSS Source Code

    @@ -285,19 +257,11 @@

    HTML Source Code

    - - - + diff --git a/content/patterns/radio/examples/radio-rating.html b/content/patterns/radio/examples/radio-rating.html new file mode 100644 index 0000000000..f279ab5875 --- /dev/null +++ b/content/patterns/radio/examples/radio-rating.html @@ -0,0 +1,297 @@ + + + + + + Rating Radio Group Example + + + + + + + + + + + + + + + +
    +

    Rating Radio Group Example

    + +
    +

    About This Example

    +

    + Following is an example of a rating input that demonstrates the Radio Group Pattern. + The rating is indicated by the number of stars selected by the user. +

    +

    Similar examples include:

    + +
    + +
    +
    +

    Example

    +
    + +
    +
    +
    Rating
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + +
    + +
    +

    Accessibility Features

    +
      +
    • + To enhance perceivability when operating the radios, visual keyboard focus and hover are styled using CSS: +
        +
      • The focus ring has a width of 2 pixels and at least 2 pixels of spacing between it and the star borders.
        • +
      • The cursor changes to a pointer when hovering over the stars so it is easier to perceive that the rating stars are interactive.
        • +
      +
      • +
    • + To ensure the borders of the stars and the focus ring have sufficient contrast with the background when high contrast settings invert colors, the color of the borders are synchronized with the color of the text content. + For example, the color of the focus ring border is set to match the foreground color of high contrast mode text by specifying the CSS currentcolor value for the stroke property of the inline SVG polygon to draw the star borders and rect element used to draw the focus ring border. + To make the background of the polygon and rect elements match the high contrast background color, the fill-opacity attribute of the rect is set to zero. + If specific colors were instead used to specify the stroke and fill properties, those colors would remain the same in high contrast mode, which could lead to insufficient contrast between the star and the background or even make them invisible if their color matched the high contrast mode background.
      + Note: The SVG element needs to have the CSS forced-color-adjust property set to auto for the currentcolor value to be updated in high contrast mode. + Some browsers do not use auto for the default value. +
      • +
    +
    + +
    +

    Keyboard Support

    +
    + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyFunction
    Tab +
      +
    • Moves focus to the checked radio button in the radiogroup.
      • +
    • If a radio button is not checked, focus moves to the first radio button in the group.
      • +
    +
    Space +
      +
    • If the radio button with focus is not checked, changes the state to checked.
      • +
    • Otherwise, does nothing.
      • +
    • Note: The state where a radio is not checked only occurs on page load.
      • +
    +
    Down arrow
    Right arrow    		 +
      +
    • Moves focus to and checks the next radio button in the group.
      • +
    • If focus is on the last radio button, moves focus to the first radio button.
      • +
    • The state of the previously checked radio button is changed to unchecked.
      • +
    +
    Up arrow
    Left arrow    		 +
      +
    • Moves focus to and checks the previous radio button in the group.
      • +
    • If focus is on the first radio button, moves focus to and checks the last radio button.
      • +
    • The state of the previously checked radio button is changed to unchecked.
      • +
    +
    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributesElementUsage
    + none + + svg + The use of the none role on the SVG element ensures assistive technologies do not interpret the SVG element as an image or some other role.
    radiogroupdiv +
      +
    • Identifies the div element as a container for a group of radio buttons.
      • +
    • Is not focusable because focus is managed using a roving tabindex strategy as described below.
      • +
    +
    aria-labelledby="ID_REFERENCE"divRefers to the element that contains the label of the radio group.
    radiogIdentifies the g element as an ARIA radio button.
    aria-label="name"gDefines an accessible name that identifies the number of stars associated with the radio button (e.g. "one star", two stars", ..).
    tabindex="-1"g +
      +
    • Makes the element focusable but not part of the page Tab sequence.
      • +
    • Applied to all radio buttons contained in the radio group except for one that is included in the page Tab sequence.
      • +
    • + This approach to managing focus is described in the practice for + Managing Focus Within Components Using a Roving tabindex. +
      • +
    +
    tabindex="0"g +
      +
    • Makes the radio button focusable and includes it in the page Tab sequence.
      • +
    • Set on only one radio in the radio group.
      • +
    • On page load, is set on the first radio button in the radio group.
      • +
    • Moves with focus inside the radio group so the most recently focused radio button is included in the page Tab sequence.
      • +
    • + This approach to managing focus is described in the practice for + Managing Focus Within Components Using a Roving tabindex. +
      • +
    +
    aria-checked="false"g +
      +
    • Identifies radio buttons which are not checked.
      • +
    • CSS attribute selectors (e.g. [aria-checked="false"]) are used to synchronize the visual states with the value of the aria-checked attribute.
      • +
    • The CSS ::before pseudo-element is used to indicate visual state of unchecked radio buttons to support high contrast settings in operating systems and browsers.
      • +
    +
    aria-checked="true"g +
      +
    • Identifies the radio button which is checked.
      • +
    • CSS attribute selectors (e.g. [aria-checked="true"]) are used to synchronize the visual states with the value of the aria-checked attribute.
      • +
    • The CSS ::before pseudo-element is used to indicate visual state of checked radio buttons to support high contrast settings in operating systems and browsers.
      • +
    +
    +
    + +
    +

    Javascript and CSS Source Code

    + +
    + +
    +

    HTML Source Code

    + +
    + + +
    +
    + + diff --git a/examples/radio/radio.html b/content/patterns/radio/examples/radio.html similarity index 80% rename from examples/radio/radio.html rename to content/patterns/radio/examples/radio.html index 1d2b3d6dc2..e0fb798e6a 100644 --- a/examples/radio/radio.html +++ b/content/patterns/radio/examples/radio.html @@ -1,76 +1,67 @@ - + - Radio Group Example Using Roving tabindex | WAI-ARIA Authoring Practices 1.2 + + Radio Group Example Using Roving tabindex - + - - - - + + + + + - + - +

    Radio Group Example Using Roving tabindex

    -

    - This example implements the features of the Radio Group Design Pattern - for two radio groups -- one for choosing a pizza crust and another for choosing a delivery method. - This implementation uses a roving tabindex for managing focus within the radio group. -

    -

    Similar examples include:

    - + +
    +

    About This Example

    +

    + This example implements the features of the Radio Group Pattern for two radio groups -- one for choosing a pizza crust and another for choosing a delivery method. + This implementation uses a roving tabindex for managing focus within the radio group. +

    +

    Similar examples include:

    + +
    +

    Example

    -
    +

    Pizza Crust

    -
    - Regular crust -
    -
    - Deep dish -
    -
    - Thin crust -
    +
    Regular crust
    +
    Deep dish
    +
    Thin crust
    -
    +

    Pizza Delivery

    -
    - Pickup -
    +
    Pickup
    -
    - Home Delivery -
    +
    Home Delivery
    -
    - Dine in -
    +
    Dine in
    -
    @@ -79,7 +70,8 @@

    Pizza Delivery

    Accessibility Features