Add accessibleName and helpText

[pixelzoom]

In 9/25/24 standup meeting, @DianaTavares mentioned that she has been adding accessibleName and helpText attributes to the sim design document. She is doing it for practice; there are no plans to implement this for the 1.0 release.

@jbphet suggested creating this issue so that future developers/designers will know that this work had been started.

[pixelzoom]

Related to my estimate in phetsims/scenery-phet#71, @kathy-phet asked us to proceed with the accessibleName part of this issue, so removing the deferred label. Kathy's instructions in Slack#models-of-the-hydrogen-atom were:

@DianaTavares - You had previously asked, I believe, about doing accessibleName in MOTHA, and with Chris' assessment, I think we can proceed within budget and you @Nancy-Salpepi. @terracoda and @arouinfar can work on coming up with the accessibleNames strings for this sim. Would you have time to focus on meeting to design those names this coming iteration? (which starts on Thursday)? Please keep track of how much design time it takes, so we can get a sense of that as well as implementation time.

[DianaTavares]

We finish with the design for accessible names and help Text in the design doc. I add them in the design doc, as it was proposed by the accessibility team, in the Interactivity section of each screen.

I think that plan this in the design doc is good! But we need a meeting to communicate to @pixelzoom how to convert the content in the document to code for the a11y view. I am not sure if is better to meet soon or until spectrometer and the second screen have more development,

[pixelzoom]

Thanks @DianaTavares. It would be best to add these features incrementally, as the sim is implemented -- there's no need to wait until the sim is feature-complete. With that in mind, I'll review the design document, then schedule a meeting for next week to review how to implement what is specified.

[arouinfar]

@DianaTavares @pixelzoom I added a few suggestions/clarifying comments to the doc.

[pixelzoom]

As part of this work, @kathy-phet also requested that I "work with dev team around strategy for translation of these (that would scale for more complex strings)."

I plan to start with the approach used in the past. That is, put all of these strings under ModelsOfTheHydrogenAtomStrings.a11y, where they are not translatable. This will allow the designers to test/review the strings and their behavior.

Then I'll start a disussion with devs about how to make these translatable and scalable.

[pixelzoom]

@arouinfar pointed me to ConcentrationControlModeRadioButtonGroup in GreenhouseGasConcentrationPanel.ts as an example of how accessibleName and helpText are done for radio button groups. See relevant code below. MOTHA radio button groups would probably be labelTagName: 'h3'.

        // pdom
        labelTagName: 'h4',
        labelContent: GreenhouseEffectStrings.a11y.concentrationPanel.experimentModeStringProperty,
        helpText: GreenhouseEffectStrings.a11y.concentrationPanel.experimentModeHelpTextStringProperty,

[pixelzoom]

In the commits above, I fleshed out the Energy Levels screen, and added correct names and numbering for the Spectrometer snapshots. There is a lot of duplication in the ScreenView subclasses that I plan to address later. But this addresses the immediate goal of making it easier to review description features.

[pixelzoom]

@terracoda This issue is ready for your review and feedback, including:

• Does accessible name, help text, and focus order match the specification in the Interactivity sections of the design document? You can test-drive in A11y View.
• Are there any additional change requests?
• Anything else for this issue?

[pixelzoom]

• Are there any additional change requests?

In Slack#models-of-the-hydrogen-atom...

• Help text for screen buttons (on Home screen and in navigation bar) was missing from the design specification. Tracking that in Add "call to action" as helpText for screen buttons. #73.

• The pattern for ABSwitch needs common-code work, see ABSwitch: support for accessibleName and helpText scenery-phet#880 (comment). Tracking that for MOTHA in "Experiment or Model" ABSwitch requires common-code description work. #74.

[terracoda]

The Light Source interaction is not being communicated as an on/off switch like in Molecules and Light. Are they not the same component?

Electron Energy Levels accordion title - "Levels" is plural in the PDOM, but singular on the screen. They should be the same, whichever one is correct.

• @pixelzoom , I hear "Electron Energy Levels, empty region," after the help text. Is that intentional or because the component not yet complete? I hear it even when the accordion is collapsed. Maybe need a new issue?

I have a proposed design for the Experiment - Model A-B Switch. I will create a separate issue for this. The on/off switch doesn't work for an A-B Switch.

Absorption/ Emission checkbox - @DianaTavares would it make sense to say "chart" or "table" in the name and/or help text instead of "dialog." Now that I have seen the content several times, the content looks like a single column or two column chart or table to me. For help text, I propose:

• Show Absorption and Emission chart for electron state transitions and their associated wavelengths.

• Questions:

  • Is it a pedagogical problem that there is no "transition" information in Experiment mode?
  • How difficult is it to put the static content of the dialog in the sim, assuming the content is static? Are the different symbols different types of photons?
  • And also wondering how easy it would be to add the the legend for proton, electron and photon to the PDOM? This goes beyond accessible names and help text, so just asking.

  Noting that sim crashed during this state with VO enabled - no interactions are functioning here:

Atomic Model radiogroup on screen 1
@DianaTavares, upon a closer look, I see "Classical" and "Quantum" flow for the models. Would it make sense to capture that representation in the help text?

• I propose changing: Choose atomic model to explore.
• To something like these:
  • Choose from a range of classical and quantum models to explore.
  • Explore a range of classical and quantum models.

[terracoda]

Assigning to @DianaTavares and @pixelzoom to review suggested changes to help text.

Any additional descriptions - the ones that go beyond accessible names and help text - would likely require a discussion with @kathy-phet. They may not be appropriate for the upcoming release.

[terracoda]

@pixelzoom, The change requests and additional comments are in the comment.

[pixelzoom]

@terracoda thanks for the feedback!

The Light Source interaction is not being communicated as an on/off switch like in Molecules and Light. Are they not the same component?

Needs more discussion. Tracking in #76.

Electron Energy Levels accordion title - "Levels" is plural in the PDOM, but singular on the screen. They should be the same, whichever one is correct.

It should be singular, and was singular in the Java version -- I've fixed the accessible name (b1583e2) and the design doc. Singular is appropriate because hydrogen has 1 electron, the electron has 1 energy level at any given time, and the accordion box shows the enery level (state) that the electron is currently in.

@pixelzoom , I hear "Electron Energy Levels, empty region," after the help text. Is that intentional or because the component not yet complete? I hear it even when the accordion is collapsed. Maybe need a new issue?

Needs more discussion. Tracking in #75.

I have a proposed design for the Experiment - Model A-B Switch. I will create a separate issue for this. The on/off switch doesn't work for an A-B Switch.

No additional issue is needed. It’s being tracked in #74.

Absorption/ Emission checkbox - @DianaTavares would it make sense to say "chart" or "table" in the name and/or help text instead of "dialog." Now that I have seen the content several times, the content looks like a single column or two column chart or table to me. For help text, I propose: Show Absorption and Emission chart for electron state transitions and their associated wavelengths.

Needs more discussion. Tracking in #77.

Is it a pedagogical problem that there is no "transition" information in Experiment mode?

Not a problem. It is a pedagogical design decision.

How difficult is it to put the static content of the dialog in the sim, assuming the content is static? Are the different symbols different types of photons?

Needs more discussion, and approval from @kathy-phet to spend time on this. Tracking in #79.

And also wondering how easy it would be to add the the legend for proton, electron and photon to the PDOM? This goes beyond accessible names and help text, so just asking.

Needs more discussion, and approval from @kathy-phet to spend time on this. Tracking in #80

Noting that sim crashed during this state with VO enabled - no interactions are functioning here:

Thanks for reporting. For future reference, when a sim crashes, it's helpful to open the browser console and report any details that are provided there. I'm guessing it hit #59, since that is a known problem in the Scrodinger model, "Experiment" uses the Schrodinger model, and you had the mode set to "Experiment". So we don't need to be concerned about this crash for the purposes of this GitHub issue.

@DianaTavares, upon a closer look, I see "Classical" and "Quantum" flow for the models. Would it make sense to capture that representation in the help text? …

Needs more discussion. Tracking in #78.

[pixelzoom]

11/7/24 design meeting: @DianaTavares @arouinfar @kathy-phet @terracoda @LindaStegemann @ariel-phet @KatieWoe @pixelzoom

All feedback was discussed. Remaining work is being tracked in other GitHub issues. So closing this issue.