From dcc2bba3c4359f6bea604db6060beaf0c328bff9 Mon Sep 17 00:00:00 2001 From: Matt King Date: Wed, 2 Nov 2022 00:44:22 -0700 Subject: [PATCH 1/4] Fix notes in button and combobox patterns --- content/patterns/button/button-pattern.html | 17 ++- .../patterns/combobox/combobox-pattern.html | 134 ++++++++++-------- 2 files changed, 84 insertions(+), 67 deletions(-) diff --git a/content/patterns/button/button-pattern.html b/content/patterns/button/button-pattern.html index 044c0e18e3..a4716b3dfd 100644 --- a/content/patterns/button/button-pattern.html +++ b/content/patterns/button/button-pattern.html @@ -34,13 +34,16 @@

About This Pattern

  • Menu button: as described in the menu button pattern, a button is revealed to assistive technologies as a menu button if it has the property aria-haspopup set to either menu or true.
    • -

    - 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. -

    +
    +

    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. +

    +
    diff --git a/content/patterns/combobox/combobox-pattern.html b/content/patterns/combobox/combobox-pattern.html index d463d63eb3..03776ee2a0 100644 --- a/content/patterns/combobox/combobox-pattern.html +++ b/content/patterns/combobox/combobox-pattern.html @@ -154,6 +154,7 @@

    Combobox Keyboard Interaction

    +

    Note

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

    1. include keys for input, cursor movement, selection, and text manipulation.
      2. @@ -198,13 +199,16 @@

      Listbox Popup Keyboard Interaction

    2. Backspace (Optional): If the combobox is editable, returns focus to the combobox and deletes the character prior to the cursor.
    3. 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.
      4. -
        -
      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. -
      +
      +

      Note

      +
        +
      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. @@ -268,35 +272,38 @@

      Grid Popup Keyboard Interaction

    4. Backspace (Optional): If the combobox is editable, returns focus to the combobox and deletes the character prior to the cursor.
    5. 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.
      6. -
        -
      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. -
      +
      +

      Note

      +
        +
      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. @@ -337,29 +344,32 @@

      Tree Popup Keyboard Interaction

      -
        -
      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. -
      +
      +

      Note

      +
        +
      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:

        @@ -375,7 +385,10 @@

        Dialog Popup Keyboard Interaction

      • 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.

      +
      +

      Note

      +

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

      +
    @@ -423,6 +436,7 @@

    WAI-ARIA Roles, States, and Properties

    +

    Note

    1. In ARIA 1.0, the combobox referenced its popup with aria-owns instead of aria-controls. From e1ed08089d6370c1eaa5c4700165cafe0d3d1315 Mon Sep 17 00:00:00 2001 From: Matt King Date: Wed, 2 Nov 2022 00:57:29 -0700 Subject: [PATCH 2/4] Fix slider warning --- .../slider-multithumb-pattern.html | 15 +++++++++------ content/patterns/slider/slider-pattern.html | 15 +++++++++------ 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/content/patterns/slider-multithumb/slider-multithumb-pattern.html b/content/patterns/slider-multithumb/slider-multithumb-pattern.html index 545dea6ecc..7e579c8c78 100644 --- a/content/patterns/slider-multithumb/slider-multithumb-pattern.html +++ b/content/patterns/slider-multithumb/slider-multithumb-pattern.html @@ -27,12 +27,15 @@

      About This Pattern

      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. -

      +
      +

      Warning

      +

      + 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. +

      +
    diff --git a/content/patterns/slider/slider-pattern.html b/content/patterns/slider/slider-pattern.html index e116a0d546..09a3f86f4f 100644 --- a/content/patterns/slider/slider-pattern.html +++ b/content/patterns/slider/slider-pattern.html @@ -22,12 +22,15 @@

    About This Pattern

    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, rail, 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. -

    +
    +

    Warning

    +

    + 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. +

    +
    From 8a1234e5998fcae11c552bd73a8844997501fb0e Mon Sep 17 00:00:00 2001 From: Jon Gunderson Date: Wed, 2 Nov 2022 17:48:12 -0500 Subject: [PATCH 3/4] updated markup for notes --- .../dialog-modal/dialog-modal-pattern.html | 122 +++++++++--------- content/patterns/feed/feed-pattern.html | 39 +++--- content/patterns/grid/grid-pattern.html | 85 ++++++------ content/patterns/link/link-pattern.html | 9 +- .../examples/listbox-rearrangeable.html | 9 +- content/patterns/listbox/listbox-pattern.html | 116 +++++++++-------- .../menubar/menu-and-menubar-pattern.html | 52 ++++---- content/patterns/meter/meter-pattern.html | 17 ++- .../patterns/radio/radio-group-pattern.html | 18 +-- content/patterns/slider/slider-pattern.html | 11 +- .../spinbutton/spinbutton-pattern.html | 27 ++-- content/patterns/table/table-pattern.html | 14 +- content/patterns/tabs/tabs-pattern.html | 37 +++--- content/patterns/toolbar/toolbar-pattern.html | 33 ++--- content/patterns/tooltip/tooltip-pattern.html | 17 ++- .../patterns/treegrid/treegrid-pattern.html | 41 +++--- .../patterns/treeview/treeview-pattern.html | 114 ++++++++-------- .../windowsplitter-pattern.html | 5 +- .../keyboard-interface-practice.html | 5 +- 19 files changed, 424 insertions(+), 347 deletions(-) diff --git a/content/patterns/dialog-modal/dialog-modal-pattern.html b/content/patterns/dialog-modal/dialog-modal-pattern.html index 5ede084e2c..71fdeefd61 100644 --- a/content/patterns/dialog-modal/dialog-modal-pattern.html +++ b/content/patterns/dialog-modal/dialog-modal-pattern.html @@ -70,46 +70,49 @@

    Keyboard Interaction

  • 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. -
    +
    +

    Note

    +
      +
    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. +
    +
    @@ -133,24 +136,27 @@

    WAI-ARIA Roles, States, and Properties

    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. - +
    +

    Note

    +
      +
    • + 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. +
      +
      • +
    +
    diff --git a/content/patterns/feed/feed-pattern.html b/content/patterns/feed/feed-pattern.html index fe6d6389b8..9b57aa0ece 100644 --- a/content/patterns/feed/feed-pattern.html +++ b/content/patterns/feed/feed-pattern.html @@ -81,24 +81,27 @@

    Keyboard Interaction

  • 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. -
    +
    +

    Note

    +
      +
    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. +
    +
    diff --git a/content/patterns/grid/grid-pattern.html b/content/patterns/grid/grid-pattern.html index 2d990cfed4..0da5270e99 100644 --- a/content/patterns/grid/grid-pattern.html +++ b/content/patterns/grid/grid-pattern.html @@ -111,17 +111,20 @@

    Keyboard Interaction For Data Grids

  • Control + Home: moves focus to the first cell in the first row.
  • Control + End: moves focus to the last cell in the last row.
    • - +
    +

    Note

    +
      +
    • + 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.

    -

    - See Key Assignment Conventions for Common Functions for cut, copy, and paste key assignments.

    +
    +
    Note
    +

    See Key Assignment Conventions for Common Functions for cut, copy, and paste key assignments.

    +
    @@ -212,18 +217,20 @@

    Keyboard Interaction For Layout Grids

  • 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.
    • - - +
    +

    Note

    + +

    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. @@ -241,10 +248,11 @@

    Keyboard Interaction For Layout Grids

  • Shift + Down Arrow: Extends selection one cell down.
  • Shift + Up Arrow: Extends selection one cell Up.
    • -

    - See Key Assignment Conventions for Common Functions - for cut, copy, and paste key assignments. -

    +
    +

    Note

    +

    See Key Assignment Conventions for Common Functions + for cut, copy, and paste key assignments.

    +
    @@ -397,14 +405,17 @@

    WAI-ARIA Roles, States, and Properties

    - +
    +

    Note

    + +
    diff --git a/content/patterns/link/link-pattern.html b/content/patterns/link/link-pattern.html index 289e3e47d2..8f80e94e99 100644 --- a/content/patterns/link/link-pattern.html +++ b/content/patterns/link/link-pattern.html @@ -22,11 +22,12 @@

    About This Pattern

    A link widget provides an interactive reference to a resource. The target resource can be either external or local, i.e., either outside or within the current page or application.

    -

    - Authors are strongly encouraged to use a native host language link element, such as an HTML <A> element with an href attribute. +

    +

    note

    +

    Authors are strongly encouraged to use a native host language link element, such as an HTML <A> element with an href attribute. As with other WAI-ARIA widget roles, applying the link role to an element will not cause browsers to enhance the element with standard link behaviors, such as navigation to the link target or context menu actions. - When using the link role, providing these features of the element is the author's responsibility. -

    + When using the link role, providing these features of the element is the author's responsibility.

    +
    diff --git a/content/patterns/listbox/examples/listbox-rearrangeable.html b/content/patterns/listbox/examples/listbox-rearrangeable.html index 2b5b782979..b8b980b78c 100644 --- a/content/patterns/listbox/examples/listbox-rearrangeable.html +++ b/content/patterns/listbox/examples/listbox-rearrangeable.html @@ -261,11 +261,12 @@

    Keyboard Support

    Multiple selection keys supported in example 2

    -

    - The selection behavior demonstrated differs from the behavior provided by browsers for native HTML <select multiple> elements. +

    +

    Note

    +

    The selection behavior demonstrated differs from the behavior provided by browsers for native HTML <select multiple> elements. The HTML select element behavior is to alter selection with unmodified up/down arrow keys, requiring the use of modifier keys to select multiple options. - This example demonstrates the multiple selection interaction model recommended in the Keyboard Interaction section of the Listbox Pattern, which does not require the use of modifier keys. -

    + This example demonstrates the multiple selection interaction model recommended in the Keyboard Interaction section of the Listbox Pattern, which does not require the use of modifier keys.

    +
    diff --git a/content/patterns/listbox/listbox-pattern.html b/content/patterns/listbox/listbox-pattern.html index ac140c8d19..a85f5d6b59 100644 --- a/content/patterns/listbox/listbox-pattern.html +++ b/content/patterns/listbox/listbox-pattern.html @@ -151,30 +151,33 @@

    Keyboard Interaction

    -
      -
    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. -
    +
    +

    Note

    +
      +
    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. +
    +
    @@ -227,37 +230,40 @@

    WAI-ARIA Roles, States, and Properties

    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. -
    +
    +

    Note

    +
      +
    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. +
    +
    diff --git a/content/patterns/menubar/menu-and-menubar-pattern.html b/content/patterns/menubar/menu-and-menubar-pattern.html index f9d1ef36c5..d3cf541029 100644 --- a/content/patterns/menubar/menu-and-menubar-pattern.html +++ b/content/patterns/menubar/menu-and-menubar-pattern.html @@ -150,26 +150,29 @@

    Keyboard Interaction

  • Any key that corresponds to a printable character (Optional): Move focus to the next item in the current menu whose label begins with that printable character.
  • Escape: Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent menuitem, from which the menu was opened.
    • -
      -
    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. -
    +
    +

    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. +
    +
    @@ -232,10 +235,11 @@

    WAI-ARIA Roles, States, and Properties

    The default value of aria-orientation for a menu is vertical. -

    - 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. -

    +
    +

    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/content/patterns/meter/meter-pattern.html b/content/patterns/meter/meter-pattern.html index 4c74feb82a..fb7cc6f5ec 100644 --- a/content/patterns/meter/meter-pattern.html +++ b/content/patterns/meter/meter-pattern.html @@ -22,13 +22,16 @@

    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. +
      • +
    +
    diff --git a/content/patterns/radio/radio-group-pattern.html b/content/patterns/radio/radio-group-pattern.html index 0b6ae111aa..04f0f89be2 100644 --- a/content/patterns/radio/radio-group-pattern.html +++ b/content/patterns/radio/radio-group-pattern.html @@ -60,10 +60,11 @@

    For Radio Groups Not Contained in a Toolbar

    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. -

    +
    +

    Note

    +

    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

    @@ -107,10 +108,11 @@

    For Radio Group Contained in a Toolbar

    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. -

    +
    +

    Note

    +

    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.

    +
    diff --git a/content/patterns/slider/slider-pattern.html b/content/patterns/slider/slider-pattern.html index 09a3f86f4f..6045f7b5ad 100644 --- a/content/patterns/slider/slider-pattern.html +++ b/content/patterns/slider/slider-pattern.html @@ -55,10 +55,13 @@

    Keyboard Interaction

  • 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. -
    +
    +

    Note

    +
      +
    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. +
    +
    diff --git a/content/patterns/spinbutton/spinbutton-pattern.html b/content/patterns/spinbutton/spinbutton-pattern.html index bda121fb58..51a8693abf 100644 --- a/content/patterns/spinbutton/spinbutton-pattern.html +++ b/content/patterns/spinbutton/spinbutton-pattern.html @@ -59,18 +59,21 @@

    Keyboard Interaction

    -
      -
    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. -
    +
    +

    Note

    +
      +
    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. +
    +
    diff --git a/content/patterns/table/table-pattern.html b/content/patterns/table/table-pattern.html index 8a3316512f..b2a99ed0b9 100644 --- a/content/patterns/table/table-pattern.html +++ b/content/patterns/table/table-pattern.html @@ -28,11 +28,12 @@

    About This Pattern

    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. +

    +

    Note

    +

    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. -

    + It is thus advisable to test implementations thoroughly with each browser and assistive technology combination that could be used by the target audience.

    +
    @@ -83,7 +84,10 @@

    WAI-ARIA Roles, States, and Properties

    Grid and Table Properties Practice. -

    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.

    +
    +

    Note

    +

    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.

    +
    diff --git a/content/patterns/tabs/tabs-pattern.html b/content/patterns/tabs/tabs-pattern.html index 2468ff472b..d77bd8168d 100644 --- a/content/patterns/tabs/tabs-pattern.html +++ b/content/patterns/tabs/tabs-pattern.html @@ -95,23 +95,26 @@

    Keyboard Interaction

    -
      -
    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 Deciding When to Make Selection Automatically Follow Focus. -
      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. -
    +
    +

    Note

    +
      +
    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 Deciding When to Make Selection Automatically Follow Focus. +
      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. +
    +
    diff --git a/content/patterns/toolbar/toolbar-pattern.html b/content/patterns/toolbar/toolbar-pattern.html index aaa71ecfea..53e1d1a61f 100644 --- a/content/patterns/toolbar/toolbar-pattern.html +++ b/content/patterns/toolbar/toolbar-pattern.html @@ -83,21 +83,24 @@

    Keyboard Interaction

  • 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 Focusability of disabled controls. -
      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. -
    +
    +

    Note

    +
      +
    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 Focusability of disabled controls. +
      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. +
    +
    diff --git a/content/patterns/tooltip/tooltip-pattern.html b/content/patterns/tooltip/tooltip-pattern.html index e2b32d99da..4628c4383a 100644 --- a/content/patterns/tooltip/tooltip-pattern.html +++ b/content/patterns/tooltip/tooltip-pattern.html @@ -40,13 +40,16 @@

    Example

    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. -
    +
    +

    Note

    +
      +
    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. +
    +
    diff --git a/content/patterns/treegrid/treegrid-pattern.html b/content/patterns/treegrid/treegrid-pattern.html index 05ab4e9184..715bc1fed7 100644 --- a/content/patterns/treegrid/treegrid-pattern.html +++ b/content/patterns/treegrid/treegrid-pattern.html @@ -184,17 +184,20 @@

    Keyboard Interaction

    -
      -
    • - 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.
      • -
    +
    +

    Note

    +
      +
    • + 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.

    • @@ -244,7 +247,10 @@

      Keyboard Interaction

    -

    See Key Assignment Conventions for Common Functions for cut, copy, and paste key assignments.

    +
    +

    Note

    +

    See Key Assignment Conventions for Common Functions for cut, copy, and paste key assignments.

    +
    @@ -305,10 +311,13 @@

    WAI-ARIA Roles, States, and Properties

    Grid and Table Properties Practice. -
      -
    • 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.
      • -
    +
    +

    Note

    +
      +
    • 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.
      • +
    +
    diff --git a/content/patterns/treeview/treeview-pattern.html b/content/patterns/treeview/treeview-pattern.html index 44a391c2ef..f7c0af88bc 100644 --- a/content/patterns/treeview/treeview-pattern.html +++ b/content/patterns/treeview/treeview-pattern.html @@ -169,30 +169,33 @@

    Keyboard Interaction

    -
      -
    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. -
    +
    +

    Note

    +
      +
    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. +
    +
    @@ -239,36 +242,39 @@

    WAI-ARIA Roles, States, and Properties

    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. -
    +
    +

    Note

    +
      +
    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. +
    +
    diff --git a/content/patterns/windowsplitter/windowsplitter-pattern.html b/content/patterns/windowsplitter/windowsplitter-pattern.html index 6452137805..afd6590343 100644 --- a/content/patterns/windowsplitter/windowsplitter-pattern.html +++ b/content/patterns/windowsplitter/windowsplitter-pattern.html @@ -67,7 +67,10 @@

    Keyboard Interaction

  • F6 (Optional): Cycle through window panes.
    • -

    A fixed size splitter omits implementation of the arrow keys.

    +
    +

    Note

    +

    A fixed size splitter omits implementation of the arrow keys.

    +
    diff --git a/content/practices/keyboard-interface/keyboard-interface-practice.html b/content/practices/keyboard-interface/keyboard-interface-practice.html index 5716088c6d..8f166f268b 100644 --- a/content/practices/keyboard-interface/keyboard-interface-practice.html +++ b/content/practices/keyboard-interface/keyboard-interface-practice.html @@ -609,7 +609,10 @@

    Assigning Keyboard Shortcuts

    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.

    +
    +

    Note

    +

    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

    From 0d63ee3fd2923fb0d37d39231820caf8376ab3ca Mon Sep 17 00:00:00 2001 From: Jon Gunderson Date: Wed, 2 Nov 2022 18:37:29 -0500 Subject: [PATCH 4/4] udpated warning markup --- .../names-and-descriptions-practice.html | 65 ++++++++++--------- 1 file changed, 36 insertions(+), 29 deletions(-) diff --git a/content/practices/names-and-descriptions/names-and-descriptions-practice.html b/content/practices/names-and-descriptions/names-and-descriptions-practice.html index 20c07b8ec5..b139683c58 100644 --- a/content/practices/names-and-descriptions/names-and-descriptions-practice.html +++ b/content/practices/names-and-descriptions/names-and-descriptions-practice.html @@ -198,11 +198,12 @@

    Naming with Child Content

    </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. +

    +

    Warning

    +

    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. -

    + 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.

    +
    @@ -224,18 +225,21 @@

    Naming with a String Attribute Via aria-label

    <!-- 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. -
    +
    +

    Warning

    +
      +
    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. +
    +
    @@ -284,19 +288,22 @@

    Naming with Referenced Content Via aria-labelledby

    <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. -
    +
    +

    Warning

    +
      +
    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. +
    +