diff --git a/ARIA/apg/about/about.md b/ARIA/apg/about/about.md index 669a2bce0..922059fae 100644 --- a/ARIA/apg/about/about.md +++ b/ARIA/apg/about/about.md @@ -67,6 +67,13 @@ lang: en ARIA Basics.

+
  • +

    Contributing to the APG

    +

    + The APG Task Force relies on broad community representation and participation to continuously improve the usefulness and quality of the APG. + Learn how you can contribute and help promote development of accessible experiences. +

    +

  • Acknowledgements

    diff --git a/ARIA/apg/about/contributing/contributing.md b/ARIA/apg/about/contributing/contributing.md new file mode 100644 index 000000000..274226480 --- /dev/null +++ b/ARIA/apg/about/contributing/contributing.md @@ -0,0 +1,176 @@ +--- +# This file was generated by scripts/pre-build/library/formatForJekyll.js +title: "Contributing to the APG" +ref: /ARIA/apg/about/contributing/ + +github: + repository: w3c/aria-practices + branch: main + path: content/about/contributing/contributing.html +feedbackmail: public-aria-practices@w3.org +permalink: /ARIA/apg/about/contributing/ + +sidebar: true + + + +# Context here: https://github.com/w3c/wai-aria-practices/issues/31 +type_of_guidance: APG + +lang: en +--- + + +Contributing to the APG + + + + + + + + + + + + + + +

    + +
    + + +
    +

    Introduction

    +

    + Continuous improvement to the utility and quality of the ARIA Authoring Practices Guide (APG) depends on broad community input and participation. + Anyone may contribute feedback, suggestions, or code via the channels described below. + However, if you would like to contribute regularly, please consider + joining the Authoring Practices Task Force. + As a task force participant, you and your organization have greater influence over APG development, and are listed as contributors where appropriate. +

    +
    + +
    +

    Providing feedback

    +

    + The APG provides two public feedback channels -- GitHub and email. + Links to both are provided at the bottom of every page in the APG. +

    +

    + GitHub issues are the best way to ask a question, make a suggestion, or report a problem. + Before creating a new issue, it is helpful if you first review existing issues to determine whether there is an issue addressing the same concern. + If so, please comment on that issue rather than raising another. + If the concern you would like addressed is related to an example implementation of an APG pattern, at the bottom of the page, next to the revision date, there is a link named "Related Issues". + That link opens a GitHub project containing all issues associated with the relevant pattern and its examples. +

    +

    + View and create APG issues on GitHub. +

    +

    + The task force also uses the aria-practices public mailing list for email discussion. + Meeting announcements, agendas, and links to minutes are sent to the mailing list. + While GitHub issues are the preferred place to discuss APG content, the mailing list is available to anyone who would prefer to communicate by + sending email to the ARIA Authoring Practices public mailing list. +

    +

    + View the aria-practices mailing list archive. +

    +
    + +
    +

    Making improvements to documentation or code

    +

    + If you would like to help improve the APG with enhancements or fixes to documentation or code, please adhere to the following procedure. +

    +
      +
    1. Get your development environment ready: + +
      2. +
    2. Comment in an existing issue or raise a new issue, expressing your willingness to help and briefly summarizing the nature of your proposed resolution.
      3. +
    3. An editor will confirm there are no conflicting plans and, if needed, provide guidance.
      4. +
    4. Do some fabulous work and submit a pull request.
      5. +
    5. Watch your GitHub notifications and respond to feedback during the pull request review process.
      6. +
    +

    + If you run into any difficulties, please feel free to ask questions either via a GitHub issue or by + sending email to the ARIA Authoring Practices public mailing list. +

    +
    + +
    +

    Joining The Authoring Practices Task Force

    +

    + The APG is developed by the + ARIA Authoring Practices Task Force, + which is a sub-group of the + ARIA Working Group. + The task force meets weekly to coordinate work on development of the APG. + Task force participants are expected to regularly attend meetings and to actively contribute. + Examples of contributions include: +

    +
      +
    • Testing the functionality and accessibility of example implementations of the APG patterns
      • +
    • Fixing bugs and implementing enhancements in example implementations of the APG patterns
      • +
    • Helping write responses to community feedback
      • +
    • Reviewing and editing documentation
      • +
    • Designing or engineering pattern implementation examples
      • +
    • Creating and editing patterns and practices for ARIA usage
      • +
    +

    + To participate in the Authoring Practices Task Force, you first need to + become a participant in the ARIA Working Group. + If you are already a participant in the ARIA Working Group, contact + Daniel Montalvo + and request membership in the Authoring Practices Task Force. +

    +
    + +
    +

    Helping provide assistive technology support data

    +

    + The assistive technology support tables included on APG example pages, e.g., + Assistive Technology Support for Radio Group Example Using aria-activedescendant, + are provided by the + ARIA and Assistive Technologies (ARIA-AT) Community Group. + The ARIA-AT community group aims to ensure APG patterns have consistent and interoperable accessibility support. + If you would like to contribute to this aspect of the APG, you can learn more about the ARIA-AT project and how to contribute at + ARIA and Assistive Technologies Home. +

    +
    + +
    + +
    + diff --git a/ARIA/apg/index/index.md b/ARIA/apg/index/index.md index 1beaf1124..6d4b286de 100644 --- a/ARIA/apg/index/index.md +++ b/ARIA/apg/index/index.md @@ -667,6 +667,9 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); diff --git a/ARIA/apg/patterns/listbox/examples/listbox-rearrangeable.md b/ARIA/apg/patterns/listbox/examples/listbox-rearrangeable.md index 339ede0fa..c219ca4f0 100644 --- a/ARIA/apg/patterns/listbox/examples/listbox-rearrangeable.md +++ b/ARIA/apg/patterns/listbox/examples/listbox-rearrangeable.md @@ -12,7 +12,7 @@ permalink: /ARIA/apg/patterns/listbox/examples/listbox-rearrangeable/ sidebar: true -footer: "

    View issues related to this example

    Page last updated: 8 August 2023

    " +footer: "

    View issues related to this example

    Page last updated: 2 October 2023

    " # Context here: https://github.com/w3c/wai-aria-practices/issues/31 type_of_guidance: APG @@ -32,7 +32,6 @@ lang: en href="../../../../../../content-assets/wai-aria-practices/patterns/listbox/examples/css/listbox.css" rel="stylesheet" /> - @@ -128,56 +127,89 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
    Important Features: -
      -
    • Proximity of public K-12 schools
      • -
    • Proximity of child-friendly parks
      • -
    • Proximity of grocery shopping
      • -
    • Proximity of fast food
      • -
    • Proximity of fine dining
      • -
    • Neighborhood walkability
      • -
    • Availability of public transit
      • -
    • Proximity of hospital and medical services
      • -
    • Level of traffic noise
      • -
    • Access to major highways
      • +
        +
      • + + Proximity of public K-12 schools +
        • +
      • + + Proximity of child-friendly parks
        • +
      • + + Proximity of grocery shopping
        • +
      • + + Proximity of fast food
        • +
      • + + Proximity of fine dining
        • +
      • + + Neighborhood walkability
        • +
      • + + Availability of public transit
        • +
      • + + Proximity of hospital and medical services
        • +
      • + + Level of traffic noise
        • +
      • + + Access to major highways
    Unimportant Features: -
      - +
        +
        Last change:
        -

        Notes

        -
          -
        1. - Assistive technologies are told which option in the list is visually focused by the value of aria-activedescendant: -
            -
          1. DOM focus remains on the listbox element.
            2. -
          2. When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of aria-activedescendant on the listbox element.
            3. -
          3. If the listbox element does not contain any options, aria-activedescendant does not have a value.
            4. -
          -
          2. -
        2. - When Tab moves focus into either listbox: -
            -
          1. If none of the options are selected, the first option receives focus.
            2. -
          2. If an option is selected, the selected option receives focus.
            3. -
          -
          3. -
        3. Only one option may be selected at a time (have aria-selected="true").
          4. -
        4. - As the user moves focus in the list, selection also moves. - That is, both the value of aria-activedescendant and the element that has aria-selected="true" change. -
          5. -
        @@ -190,73 +222,99 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
        Available upgrades: -
          -
        • Leather seats
          • -
        • Front seat warmers
          • -
        • Rear bucket seats
          • -
        • Rear seat warmers
          • -
        • Front sun roof
          • -
        • Rear sun roof
          • -
        • Cloaking capability
          • -
        • Food synthesizer
          • -
        • Advanced waste recycling system
          • -
        • Turbo vertical take-off capability
          • +
            +
          • + + Leather seats +
            • +
          • + + Front seat warmers +
            • +
          • + + Rear bucket seats +
            • +
          • + + Rear seat warmers +
            • +
          • + + Front sun roof +
            • +
          • + + Rear sun roof +
            • +
          • + + Cloaking capability +
            • +
          • + + Food synthesizer +
            • +
          • + + Advanced waste recycling system +
            • +
          • + + Turbo vertical take-off capability +
          - +
        Upgrades you have chosen: -
          - +
            +
          +
          Last change:
          -

          Notes

          -
            -
          1. - Like in example 1, assistive technologies are told which option in the list is visually focused by the value of aria-activedescendant: -
              -
            1. DOM focus remains on the listbox element.
              2. -
            2. When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of aria-activedescendant on the listbox element.
              3. -
            3. If the listbox element does not contain any options, aria-activedescendant does not have a value.
              4. -
            -
            2. -
          2. - When Tab moves focus into either listbox: -
              -
            1. If none of the options are selected, focus is set on the first option.
              2. -
            2. If one or more options are selected, focus is set on the first selected option.
              3. -
            -
            3. -
          3. - Unlike example 1, more than one option may be selected at a time (have aria-selected="true"). -
              -
            1. The multi-select capability is communicated to assistive technologies by setting aria-multiselectable="true" on the listbox element.
              2. -
            2. All option elements have a value set for aria-selected.
              3. -
            3. Selected options have aria-selected set to true and all others have it set to false.
              4. -
            4. Keys that move focus do not change the selected state of an option.
              5. -
            -
            4. -
          4. Users can toggle the selected state of the focused option with Space or click.
            5. -

          Accessibility Features

          -
            +
            • Keyboard shortcuts for action buttons: -
                +
                • Action buttons have the following shortcuts:
                    -
                  • "Up": Alt + Up Arrow
                    • -
                  • "Down": Alt + Down Arrow
                    • -
                  • "Add": Enter
                    • -
                  • "Not Important", "Important", and "Remove": Delete
                    • +
                  • "Up": Alt + Up Arrow
                    • +
                  • "Down": Alt + Down Arrow
                    • +
                  • "Add": Enter
                    • +
                  • "Not Important", "Important", and "Remove": Delete
                • Availability of the shortcuts is communicated to assistive technologies via the aria-keyshortcuts property on the button elements.
                  • @@ -266,15 +324,26 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
                • Using a shortcut key intentionally places focus to optimize both screen reader and keyboard usability. - For example, pressing Alt + Up Arrow in the "Important Features" list keeps focus on the option that is moved up, enabling all keyboard users to easily perform consecutive move operations for an option and screen reader users to hear the position of an option after it is moved. + For example, pressing Alt + Up Arrow in the "Important Features" list keeps focus on the option that is moved up, enabling all keyboard users to easily perform consecutive move operations for an option and screen reader users to hear the position of an option after it is moved. Similarly, pressing Enter in the available options list leaves focus in the available options list. If the option that had focus before the add operation is no longer present in the list, focus lands on the first of the subsequent options that is still present.
                  • -
              +
          1. In example 1, since there are four action buttons, a toolbar widget is used to group all the action buttons into a single tab stop.
          2. Live regions provide confirmation of completed actions.
            3. -
          +
        • + Because this listbox implementation is scrollable and manages which option is focused by using aria-activedescendant, the JavaScript must ensure the focused option is visible. + So, when a keyboard or pointer event changes the option referenced by aria-activedescendant, if the referenced option is not fully visible, the JavaScript scrolls the listbox to position the option in view. +
          • +
        • + To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS :hover and :focus pseudo-classes: +
            +
          • To help people with visual impairments identify the listbox as an interactive element, the cursor is changed to a pointer when hovering over the list.
            • +
          • To make it easier to distinguish the selected listbox option from other options, selection creates a 2 pixel border above and below the option.
            • +
          +
          • +
          @@ -283,6 +352,12 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); The example listboxes on this page implement the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Pattern.

          +

          + NOTE: When visual focus is on an option in these implementations of listbox, DOM focus remains on the listbox element and the value of aria-activedescendant on the listbox refers to the descendant option that is visually indicated as focused. + Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator, not DOM focus. + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +

          @@ -291,6 +366,18 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); + + + + + + + +
          Tab +
            +
          • Moves focus into and out of the listbox.
            • +
          • + When the listbox receives focus, if none of the options are selected, the first option receives focus. + Otherwise, the first selected option receives focus. +
            • +
          +
          Down Arrow @@ -327,15 +414,23 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
          Printable Characters +
            +
          • 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 keys supported in example 2

          -
          -

          Note

          -

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

          @@ -402,19 +497,19 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); - + - + - + - + @@ -445,7 +544,7 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); - + - + + + + + + +
          aria-labelledby="ID_REF"aria-labelledby="ID_REF" ul Applied to the element with the listbox role, it refers to the span containing its label.
          tabindex="0"tabindex="0" ul Applied to the element with the listbox role, it puts the listbox in the tab sequence.
          aria-multiselectable="true"aria-multiselectable="true" ul
            @@ -426,14 +521,18 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
          aria-activedescendant="ID_REF"aria-activedescendant="ID_REF" ul
            -
          • Applied to the element with the listbox role, tells assistive technologies which of the options, if any, is visually indicated as having keyboard focus.
            • -
          • DOM focus remains on the ul element and the idref specified for aria-activedescendant refers to the li element that is visually styled as focused.
            • +
          • When an option in the listbox is visually indicated as having keyboard focus, refers to that option.
            • +
          • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element.
          • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
            • -
          • When the listbox is empty, aria-activedescendant="".
            • +
          • When the listbox is empty, aria-activedescendant="".
            • +
          • + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +
          aria-selected="true"aria-selected="true" li
            @@ -458,7 +557,7 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
          aria-selected="false"aria-selected="false" li
            @@ -468,6 +567,14 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
          aria-hidden="true"span + Removes the character entities used for the check mark, left arrow and right arrow from the accessibility tree to prevent them from being included in the accessible name of an option or button. +
          @@ -481,7 +588,7 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
        • Javascript: - listbox.js, toolbar.js, listbox-rearrangeable.js, utils.js + listbox.js, toolbar.js, listbox-rearrangeable.js
          • diff --git a/ARIA/apg/patterns/listbox/examples/listbox-scrollable.md b/ARIA/apg/patterns/listbox/examples/listbox-scrollable.md index 526b571dc..4890e5c9f 100644 --- a/ARIA/apg/patterns/listbox/examples/listbox-scrollable.md +++ b/ARIA/apg/patterns/listbox/examples/listbox-scrollable.md @@ -12,7 +12,7 @@ permalink: /ARIA/apg/patterns/listbox/examples/listbox-scrollable/ sidebar: true -footer: "

          View issues related to this example

          Page last updated: 8 August 2023

          " +footer: "

          View issues related to this example

          Page last updated: 2 October 2023

          " # Context here: https://github.com/w3c/wai-aria-practices/issues/31 type_of_guidance: APG @@ -32,7 +32,6 @@ lang: en href="../../../../../../content-assets/wai-aria-practices/patterns/listbox/examples/css/listbox.css" rel="stylesheet" /> - @@ -122,67 +121,146 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
          Transuranium elements:
          -

          Notes

          -

          This listbox is scrollable; it has more options than its height can accommodate.

          -
            -
          1. - Scrolling only works as expected if the listbox is the options' offsetParent. - The example uses position: relative on the listbox to that effect. -
            2. + + +
            +

            Accessibility Features

            +
          +

          Keyboard Support

          - The example listboxes on this page implement the following keyboard interface. + The example listbox on this page implements the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Pattern.

          +

          + NOTE: When visual focus is on an option in this listbox implementation, DOM focus remains on the listbox element and the value of aria-activedescendant on the listbox refers to the descendant option that is visually indicated as focused. + Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator, not DOM focus. + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +

          @@ -191,6 +269,10 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); + + + + @@ -207,6 +289,15 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); + + + +
          TabMoves focus into and out of the listbox.
          Down Arrow Moves focus to and selects the next option.End Moves focus to and selects the last option.
          Printable Characters +
            +
          • 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.
            • +
          +
          @@ -214,7 +305,7 @@ if (enableSidebar) document.body.classList.add('has-sidebar');

          Role, Property, State, and Tabindex Attributes

          - The example listboxes on this page implement the following ARIA roles, states, and properties. + The example listbox on this page implements the following ARIA roles, states, and properties. Information about other ways of applying ARIA roles, states, and properties is available in the Roles, States, and Properties section of the Listbox Pattern.

          @@ -235,25 +326,29 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); - + - + - + @@ -265,7 +360,7 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); - + + + + + + +
          aria-labelledby="ID_REF"aria-labelledby="ID_REF" ul Refers to the element containing the listbox label.
          tabindex="0"tabindex="0" ul Includes the listbox in the page tab sequence.
          aria-activedescendant="ID_REF"aria-activedescendant="ID_REF" ul
            -
          • Tells assistive technologies which of the options, if any, is visually indicated as having keyboard focus.
            • -
          • DOM focus remains on the ul element and the idref specified for aria-activedescendant refers to the li element that is visually styled as focused.
            • +
          • When an option in the listbox is visually indicated as having keyboard focus, refers to that option.
            • +
          • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element.
          • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
            • +
          • + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +
          aria-selected="true"aria-selected="true" li
            @@ -275,6 +370,14 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
          aria-hidden="true"span + Removes the character entity used for the check mark icon from the accessibility tree to prevent it from being included in the accessible name of the option. +
          @@ -288,7 +391,7 @@ if (enableSidebar) document.body.classList.add('has-sidebar');
        • Javascript: - listbox.js, listbox-scrollable.js, utils.js + listbox.js, listbox-scrollable.js
          • diff --git a/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant.md b/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant.md index 97a0e3453..91331573a 100644 --- a/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant.md +++ b/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant.md @@ -12,7 +12,7 @@ permalink: /ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-de sidebar: true -footer: "

          View issues related to this example

          Page last updated: 8 August 2023

          " +footer: "

          View issues related to this example

          Page last updated: 2 October 2023

          " # Context here: https://github.com/w3c/wai-aria-practices/issues/31 type_of_guidance: APG @@ -148,7 +148,7 @@ if (enableSidebar) document.body.classList.add('has-sidebar'); To support operating system high contrast settings: