Consider renaming Accessibility.js trait and other references

[jessegreenberg]

In a discussion with @emily-phet and @zepumph, we realized that Accessibility is likely too broad of a term for what the trait is responsible for. Furthermore, it monopolizes the term and separates the trait from other projects we are working on that are also related to inclusive design. We would like to consider renaming it to avoid this and the indication that this trait is all of "Accessibility".

During the meeting PDOM.js or something like that was suggested but we should brainstorm some more before going forward.

[terracoda]

@jessegreenberg, this is a great question.
Are you thinking of more specific categories like:

• alternative input (keyboard, switch, mobile a11y)
• simple description
• full description
• sound and sonification

Or maybe thinking of the features that relate specifically to the requirement of having a PDOM present in order to implement?

The reason I ask, is that I am not sure a PDOM is required in order to implement sound alone. But the other features, I think all require a PDOM.

[jessegreenberg]

That is exactly what we were thinking about @terracoda. Currently Accessibilility.js is what provides everything related to the PDOM. But it doesn't include sound, haptics, magnification, or any other a11y features that may come in the future. It feels incorrect to call PDOM features "Accessibility" and the rest "Other".

[terracoda]

Awesome, @jessegreenberg. I agree, a less broad term like PDOM seems much more appropriate.

[zepumph]

This issue also came out of documentation discussion from phetsims/phet-info#114.

[zepumph]

While working on phetsims/chipper#786 I thought about how we should likely change the a11y string prefix here too. This should likely match whatever we name Accessibility.js

[zepumph]

• Another place I just thought of that could use a rename is in the QA issue templates. They have a section for "a11y" but really it is just PDOM descriptions. In fact sound is not included in that section at all. It seems like instead each a11y feature should get its own details section to test if that feature is included in the sim.

[jessegreenberg]

We discussed this today during a meeting. Overall, we are liking PDOM.js as the name replacement for Accessibility.js and will likely rename lots of other things to match. Summarizing discussion notes below:

We started by considering what features were included by what is currently supported by the PDOM and alert system:

• Description support
• Alternative input support
• Interface with assistive tech
• Screen reader accessibility
• Screen reader descriptions
• Interactive alerts

We agreed that all of this can be boiled down into a term that we are going to call "Interactive Descriptions". We feel that this term encompasses all of the features provided by interactive accessible HTML and ARIA

Features contained in "Interactive Descriptions":

• Description support (PDOM Content) -> Supported by PDOM -> Implemented by Accessibility.js
• Alternative input -> Supported by PDOM -> Implemented by Accessibility.js/Input.js
• Interactive alerts -> Supported by aria-live -> Implemented by UtteranceQueue.js

Seeing as how Accessibility.js is responsible for the PDOM which supports Interactive Descriptions, we like the idea of naming Accessibility.js -> PDOM.js.

[zepumph]

@jessegreenberg what is the next step here? Should we bring it up at developer meeting? Discuss more ourselves? Proceed with PDOM.js?

[zepumph]

@jessegreenberg and I, and @twant and I separately discussed this more today. We came up with the following game plan.

The feature that has been a large part of scenery descriptions, and accessibilty implementation in sims shall henceforth be known as "Interactive Descriptions." This feature is comprised of the following three sub-features: Parenthesis indicate the name of the technology that is implementing them.

• State Descriptions - accessed on-demand by the user
  a. Static States (PDOM)
  b. Dynamic States (PDOM)
• Responsive Descriptions
  a. Object Responses (UtteranceQueue/PDOM/Both)
  b. Context Responses (UtteranceQueue)
• Alternative Input (PDOM):
  a. keyboard/mobile/switch/etc

We are marking for developer meeting to gather opinions and see if anyone has other suggestions of "a11y" usages or comments on the current outline of work. Here is the current TODO list. Much of this should be broken out into separate issues to keep this issue from becoming a monster.

1. create scenery/js/accessibility/pdom/

2. Under that dir move and rename a fair number files, most of which from "Accessibility/Accessible" to "PDOM":

   • Accessibility.js -> PDOM.js
   • AccessibilityFuzzer.js -> PDOMFuzzer.js
   • PDOMInputTests.js
   • PDOMTests.js
   • PDOMTree.js
   • PDOMUtil.js
   • PDOMUtilTests.js
   • PDOMDisplaysInfo.js
   • PDOMInstance.js
   • PDOMPeer.js
   • PDOMSiblingStyle.js
   • PDOMSiblingTests.js
   • PartialAccessibleTrail -> PartialPDOMTrail.js

3. Rename many methods in PDOM.js

4. Rename A11yPointer.js (Maybe PDOMPointer.js?)

5. Rename Event.isA11y()

6. As of right now we do not want to change the a11y specific string prefix from a11y to pdom. We are on the fence about this, but feel like this could encompass more than just PDOM related strings, for example interactive alerts, or if we include live talk back.

7. In options blocks, preface with the feature instead of general a11y. // a11y -> // pdom in general, these options pertain to the PDOM! (but not // a11y strings)

8. Make a new issue to change the QA templates to reflect individual features (like "Interactive Descriptions") instead of a11y.

9. audit of this doc: /scenery/doc/accessibility.html

10. Audit of "how to instrument" doc, including likely renaming it to "how to add Interactive Descriptions" etc. . . see Review "how to outfit a sim with interactive descriptions" document phet-info#114

11. Sun traits convert Accessible-> PDOM:

    • AccessibleValueHandler.js
    • AccessibleNumberSpinner.js
    • AccessibleSlider.js
    • AccessibleValueHandler options:
    • a11y prefix to pdom

12. joist/sim infrastructure:

    • Currently the ?a11y and ?accessibility query parameters just pertain to Interactive Descriptions. Instead we will make those encompass all a11y features, like turning on haptics and sonification as well. We will then add another query parameter to enable just Interactive Descriptions. Perhaps ?pdom or ?descriptions or ?interactiveDescriptions or ?supportsDescriptions (like ?supportsSound).

13. Do not rename the following because they pertain to multiple accessibility features:

    • "accessible" flag in package.json
    • a11y view runnable
    • perennial/data/accessibility

14. class a11y-root on the PDOM root should be pdom-root

15. maybe something else, we will keep thinking.

16. PDOMPointer has a pointer event type prefix called 'a11y'

17. Display.rootAccessibleInstance

take it to dev meeting!!!

[pixelzoom]

Responding to developer meeting label... I don't know enough about a11y to comment. Will this change make it more difficult to patch release branches, and is that even a concern?

[terracoda]

@zepumph, in #997 (comment) you posted:

The feature that has been a large part of scenery descriptions, and accessibility implementation in sims shall henceforth be known as "Interactive Descriptions." This feature is comprised of the following three sub-features:

• Description support (PDOM Content) -> Supported by PDOM -> Implemented by Accessibility.js
• Alternative input -> Supported by PDOM -> Implemented by Accessibility.js/Input.js
• Interactive alerts -> Supported by aria-live -> Implemented by UtteranceQueue.js

I'm wondering if it is worth discussing the terms a little more. I literally just finished a paper describing the refined description design framework and the terminology has evolved a little bit.

In terms of design, we now have two main categories of description, and the each have 2 types of descriptions:

1. State Descriptions - accessed on-demand by the user
   a. Static States
   b. Dynamic States
2. Responsive Descriptions - delivered automatically upon activation and interaction
   a. Object Responses
   b. Context Responses

I'm wondering if it might be prudent to have a conversation about exactly what is meant by "Interactive Descriptions" and "Interactive Alerts". Perhaps "State Descriptions" and "Responsive Descriptions" covers it?

[zepumph]

@terracoda thanks for that contribution. We definitely should have included you in discussion about naming for the "Description" feature. @terracoda, @jessegreenberg, @emily-phet, and I will continue to work out the terminology with this as it pertains to design/development communication. The numbered list above is a bit orthogonal to that discussion though. For the most part, it is the culminating desire for the implementation of the PDOM to be renamed to reflect that feature instead of naming like "accessible" or "accessibility" or "a11y." Largely the work in this issue is based on changes in the implementation only. For tomorrow's dev meeting I still think it would be pertinent to go through any concerns there are with the numbered list in #997 (comment).

[jessegreenberg]

Deferring this issue for dev meeting for now, we want to make sure that the whole a11y team is on board with this and agrees it is worth the effort before notifying the dev team.

[terracoda]

@jessegreenberg asked:

I'm wondering if it might be prudent to have a conversation about exactly what is meant by "Interactive Descriptions" and "Interactive Alerts". Perhaps "State Descriptions" and "Responsive Descriptions" covers it?

@jessegreenberg State Descriptions and Responsive Descriptions cover all the descriptions that we design.

State Descriptions are made up of Static States and Dynamic States (formerly Static and Dynamic descriptions) accessed on-demand.

Whereas Responsive Descriptions strictly speaking are not specifically what we have been calling "Interactive Alerts". Responsive Descriptions are made up of Object Responses and Context Responses.
For example:

• changes to an object's value are captured by "Object Responses" and
• changes to the surrounding context are captured by "Context Responses".

In all the sims we have designed, I can't think of nor can I imagine any examples of Context Responses that would not be delivered by ARIA-Live Regions and the utterance queue.

However, for Object Responses I see that depending on the interaction Object Responses could be delivered via aria-valuetext or ARIA-Live Regions.

With slider-type interactions it is clear, Object Responses are delivered via arai-valuetext. In some situations, I could imagine object responses (specific object changes) begin delivered individually or in combination with together with context responses via ARIA-Live Regions.

Changes to object values have always conceptually straddled our implementation technologies, so this is not new. We just have a new name for them to help in the design process.

I know it is impossible to map all design concepts to developer concepts, but I think it would be useful to make sure what you mean by "Interactive Descriptions" and "Interactive Alerts" is consistent with what I think it might using our new description framework language:

@jessegreenberg does this capture your categories? And if so, do you think the category names capture the essence of what you are trying to accomplish with them?

Interactive Descriptions

• static state descriptions
• dynamic state descriptions
• object values deliverable through aria-valuetext or some similar PDOM-embedded method.

Interactive Alerts

• context responses
• object responses when there is no PDOM-embedded method for delivery.

[zepumph]

After discussing more with @terracoda and @jessegreenberg, we are ready again to bring this the developers. I have made a few updates in the above list accordingly.

[terracoda]

@zepumph and @jessegreenberg I think we decided that we won't in a formal way use the term "interactive alerts", right? We'll just use "Interactive Descriptions" and refer to the subsets as needed as we described in phetsims/a11y-research#145

[zepumph]

Notes from discussion during today's dev meeting:

• use all caps form PDOM instead of pdom, so the options comment would be // PDOM, as an acronym.

[samreid]

I described some problems with the "parallel dom" terminology in phetsims/a11y-research#101. Also, I wonder if ParallelDOM would be preferable to PDOM in most of the namings?