Add accessible names to pdom components

[marlitas]

@amanda-phet and I talked about adding in accessible names throughout the sim. We think this could be done quickly without much fuss (but add a lot of value), before QA testing.

[terracoda]

Great News!

@marlitas, please make note of any implementation pain points because having accessible names on interactions is essential for several WCAG Level A and AA criteria.

[terracoda]

Also, please reach out if you get stuck or have questions.

[marlitas]

@terracoda this is great to know. I will prioritize to get your input sooner rather than later.

[terracoda]

The names are directly related to making Alternative Input non-visually accessible. I'll add how description and alt input labels since we do not have an accessible names label. Please adjust as you see fit.

[marlitas]

This has been done in the above commits. I tried to reference other sims for the naming, but please let me know if there are any you'd like to adjust.

[terracoda]

Screen 1

Pipe Switch Interactions

• the first Pipe Switch button in the notebook is missing a name. This is an interesting description challenge because you have a button and a on/off switch that control the same interaction, and interaction names need to be unique. AND I just remembered our On/Off Switch interaction pattern (See MAL's Light Source on/off switch) does not work on iOS VoiceOver. I suggest the following approach if it is doable:
  • The first "Pipe Switch" button can be a button with a dynamic name like in BASE's Remove Wall/Add Wall button like this:
    • "Open Pipe"/"Close Pipe" (my preference is a clear action) OR
    • "Pipe Switch Open"/"Pipe Switch Closed"
    • I hope this is a common code pattern. If not and if it is easy to do so, you can check in with @jessegreenberg
  • The second "Pipe Switch" interaction can be an HTML toggle button with a single name, "Pipe Switch" and the state comes from the HTML code, like this:
    • Accessible name: Pipe Switch
    • Role: toggle button
    • States: pressed and not pressed
    • Result on focus: When open "Pipe Switch, toggle button, not pressed" and when closed "Pipe Switch, toggle button, pressed."

Oh sorry, the Pipe Switch outside the notebook is already implemented with the on/off switch role. Nice! In order to not repeat the actual role in the action's name, consider how the following sound:

• Pipe Switch, off, switch
• Pipe Switch, on, switch
• Pipe Flow, off, switch
• Pipe Flow, on, switch

Predict mean pencil, slider

Pencil slider is currently missing a name. I suggest some ideas:

• Predict Mean Pencil; Predict Mean Marker; Predict Mean Mark;
  - or possibly, Mean Prediction Mark
• I prefer Mark or Marker because Pencil does really have a value.
• Value and role are read out on focus, you hear: "0, Predict Mean Mark, slider"
• If you add orientation, you will hear, "vertical slider"
• MORE below after thinking about the names for the checkboxes

The Cup Water Level sliders have names. Awesome! I suggest changes:

• Start the Cup count at 1. It will match the count on the screen, and having a "Cup 0" doesn't make that much sense.
• Reverse the order of the name, so it is: "Cup {{1}} Water Level".
• Value, role, and orientation are read out on focus, you hear: "0.75, Cup 1 Water Level, vertical slider"

The water level and predict mean values (SCOPE SCREEP!)

• With no rounding, slider values are read out to like 10 decimal places.
• Any chance the values can be rounded to two decimal places before being read out? I realize this is not about the name, but rather the values.
• This is an issue on almost all, if not all sliders.

Number of Cups

• The accessible name looks fine on screen, and can work as is. It could be improved though.
• Screen reader says, "2, Number of Cups, vertical number spinner "
  • Orientation is incorrect. Remove orientation or change it to horizontal; horizontal is the default.
  • "2, Cups, number spinner", would be nice. Help text is for later adding any needed additional context for screen reader user.
  • If there is a desire by the design team, you could put the help text in the name now, like this:
    • "2, Change Number of Cups, number spinner"
    • “2, Change Cups, number spinner"
  • My preference is just "Cups" as both the accessible name and the on-screen name.

Edited to add another name option. Edited again for clarity and to fix typos.

Screen 2

The Notebook Candy Bars

• The bar in the notebook should have a button role before it is grabbed, and the button's name should be "Grab Candy Bar" or "Grab Bar".
• Sorry, the Candy Bar in the notebook, is more like the stacks of soccer balls on CaV. The group grab/sort might have a different role than button for the grabbing part of the interaction. I still think you need the word "Grab", though, so still recommending "Grab Candy Bar"

The Plates of Candy Bars on the Table

There are lots of possibilities here! What's the simplest and clearest path for now? The most meaningful words for the interaction?

• Start the count of plates at "1", just like I suggested for the cup water-level sliders.
• It sounds weird to have a plate have a numeric value "3, Plate {{1}}". How about adding "Candy Bars" or "Servings" to the name. This would mirror "water level" on the water-level cup sliders:
  • "3, Plate {{1}} Candy Bars, vertical number spinner"
  • "3, Plate {{1}} Servings, vertical number spinner"
• For the future, "candy bars" might make sense as part of the aria-valuetext number. We might want to do something quite different, possibly name the characters: Maria's Plate, Mo's Plate, Tammy's Plate, Sara's Plate? Which would sound like, "3 candy bars, Maria's Plate, vertical number spinner." That's maybe more fun, but also more complicated.

Number of People, Number of People with Plates, or People with Plates

• Note: Like Cups number spinner, remover orientation or make it horizontal.
  For the water-level cup sliders, the word "cup" is in the slider name, so that makes a connection between the interaction that adds and removes cups, and the interaction that changes the water level in the cups. For the people and plates, the word "people" is not part of the number spinner's name. You need the word "plate" to make that connection. I suggest:
• "People with Plates"
• A screen reader would say, "2, People with Plates, number spinner"
• That would pair nicely with "Cups" on Screen 1. Otherwise, you have to re-think the name of the number spinners on the table.

Sync Button

• the Sync button's name might be more clear as "Sync to/with Data" or "Sync to/with Table" or "Sync to/with Plates"?
• I leave this decision to the design team. Future help text would clarify a button named "Sync." For example, the help text placed in a p-tag right after the button could be, "Sync arrangement of bars in notebook with candy bar data on table." You see how much context that adds?

Info button role

• This button's role does not indicate that it is a pop-up, but neither does the keyboard button. I guess we can leave it for now. I am going to check with @jessegreenberg on the history of keyboard dialog button which is also pops up a dialog.

Screen 3

The Apple Action Radio Buttons

• This one is hard.
• The actions are kind of meaningless without a description of what happens to the apples in the animation, and we are not doing that right now. That said, adding "Apples" to the accessible name on each radio button might work well for now:
  • "Synch Apples, radiobutton, 1 of 3,"
  • "Collect Apples, radiobutton, 2 of 3,"
  • "Share Apples, radiobutton, 3 of 3,"
• Alternatively, radio button groups typically incorporate a heading to name the group, so adding an H3 heading like "Actions for Apples" or something similar might work as well. The heading does not appear on the screen. A screen reader user might then hear the following on focus of the selected radio button:
• "Sync, radiobutton, 1 of 3, Actions for Apples, group"
• "Sync, radiobutton, 1 of 3, Apple Actions, group"

I don't think think the group name repeats, so upon selection of the next radiobutton, they might hear:

• "Collect, radiobutton, 2 of 3,"
• "Share, radiobutton, 3 of 3."

I recommend taking the simplest route above as radio button groups can get quite nuanced when help text and context responses are added with full description.

Plate {{plateNumber}} Apples

• same considerations as the plates of candy bars.

Number of People

• same considerations as Screen 2

Total Checkboxes (screens 2, 3, and 4)

The name, "Total" is too vague, actually meaningless without context. In previous description work on sims, we have always changed vague names to be more explicit, adding a word about what the checkbox hides and shows. For example, "Values" was changes to "Force Values" in GFLB, and "Solution Values" in Molarity. "Total" needs to be more explicit. I highly recommend the following for screens 2, 3, and 4. It will help everyone:

• Total Candy Bars
• Total Apples
• Total Distance

Predict Mean Indicators (screens 1, 2 and 4)

Predict Mean Checkboxes (screen 1 and 2)

I didn't think too hard about these on-screen checkbox names at first, but as I progressed through the screens, I think it makes better sense to NOT use an "action-oriented" name for the checkboxes. The checkbox does not predict the mean, it makes the pencil slider available, and that tool can be used to predict the mean. The words in the names for the checkbox and the added slider should make it clear these actions are related.

So upon rethinking these interactions, I suggest either of these names for the checkbox:

• Mean Prediction Marker, unchecked, checkbox OR
• Mean Prediction Pencil, checked, checkbox

AND then depending on the above one of the following names for the added pencil slider. Each of these goes nicely with a numeric value in front of it:

• 0, Predict Mean Mark, vertical slider
• 2.5, Mean Prediction Mark, vertical slider
• 3, Prediction Mark, vertical slider
• 1, Mean Prediction, vertical slider
• 4.5, Pencil Mark, vertical slider

Name design can be made shorter when more context is added through help text, object responses, and context responses. Without that context, I am trying to make a clear connection between the action that turns the pencil on, and the action that changes the value of the mean prediction.

Screen 4

Here are my ideas and suggestions based on what I have learned from all the screens.
H2: Play Area

• Kick, button
• 5, Balance Prediction, slider OR Balance Point Prediction, Mean Prediction
• Check Balance, button

Before and after grab:

• Grab Ball, web application

• Ball

• 2, Balls, number spinner

H2: Control Area
H3: Fulcrum Options

• Movable Fulcrum, radiobutton, 1 of 2

• Fulcrum Balanced, 2 of 2

• Tick Marks, unchecked, checkbox

• Total Distance, unchecked, checkbox

• Info, button

• Reset All, button

[marlitas]

I went ahead and applied some of the above notes.

@terracoda I have a question about the button for Grab Candy Bar though. What if there are not candy bars? We can still focus on that area as was requested for GroupSortInteraction, but there are no candy bars to grab. We have this same situation in Balance Point.

[marlitas]

The read out of the value is automatic and with no rounding, the number is read out to like 10 decimal places. Any chance the values on the sliders can be rounded to two decimal places before being read out? I realize this is not an accessible, but rather a value.

I'm not sure how comfortable I feel about doing this without messing up the rest of the model of the sim... Let me look into it.

[terracoda]

@marlitas , I realize rounding can cause issues. I have plenty of experience there. Let’s just focus on the names for now. I still need to listen to screens 2,3 and 4.

[terracoda]

@marlitas asked:

@terracoda I have a question about the button for Grab Candy Bar though. What if there are not candy bars? We can still focus on that area as was requested for GroupSortInteraction, but there are no candy bars to grab. We have this same situation in Balance Point.

On the Balance Point screen, you have a message. I would suggest doing the same on screens 2 and 3.

[terracoda]

@marlitas, I made several iterations to the big comment above as I worked through the screens.

To Summarize these ideas, here's a table.

[marlitas]

Changes to apply:

• Water Level Cup 1 => Cup 1 Water Level
• Pipe Switch => Pipe Flow
• Plate 1 => Person 1 Candy Bars
• After Grabbing Candy Bar: Grab Candy Bar => Movable Candy Bar
• Sync with Plates => Sync
• Implement radio button group with heading: "Apple Actions" (Look to ratio and proportion or molecules and light)
• Plate 1 => Person 1 Apples
• Implement radio button group with heading: "Fulcrum Options"
• Movable Fulcrum => Manual Fulcrum
• Fixed Fulcrum => Automatic Fulcrum

Take Aways:

• @amanda-phet will talk to design team about changing the checkbox label "Total" to "Total Count"

[marlitas]

I went ahead and changed the group sort interaction for candy bars to be:
Before Grabbing: "Grab or select candy bar"
After Grabbing: "Move candy bar"

I know we were still nailing that down, but that should be pushed up it @terracoda or @amanda-phet want to take a look.

[marlitas]

• change "predict mean handle" => "Prediction Mark"
• Capitalize "candy bars" and "apples"
• Group Sort Balance Point: Before Grab "Grab Soccer Ball at 1"
• Group Sort Balance Point: After Grab "Change Value"

[marlitas]

I believe everything has been addressed as requested now. Over to @amanda-phet and @terracoda for design review.

Next up will be me moving the strings into the strings file, so please do not close quite yet.

[terracoda]

@amanda-phet and @marlitas, the "Check" button that checks the balance on screen 4 was not in my table. I suggest changing both the visual name and the accessible name to "Check Balance." I can't imagine any pedagogically harmful side-effect of adding "Balance" to that name. It just makes the action much clearer.

I would suggest making that the accessible name regardless of whether if fits on the screen or not. Which makes me want to circle back to the "Total" check box.

[terracoda]

@marlitas and @amanda-phet if you are ammenable, I would like the following updates:

• "Total Number of Candy Bars" for accessible name
• "Total Number of Apples" for accessible name
• "Total Distance" for accessible name
• "Check Balance" for accessible name with "Check" as visual name ("Check Balance" won't fit)
• "Reset Pillars" for accessible name with "Reset" as visual name

[terracoda]

I am opening a separate issue for Group Sort. It is more complicated.

[marlitas]

I am opening a separate issue for Group Sort. It is more complicated.

I do want to emphasize, though I do believe that nailing down the group sort behavior is important, I am not considering it blocking for MSaB. It may be out of scope for this particular publication. Not to say that we shouldn't do the work, it just might not be prioritized right now depending on the lift required.

[amanda-phet]

@marlitas and @marlitas if you are ammenable, I would like the following updates:

"Total Number of Candy Bars" for accessible name
"Total Number of Apples" for accessible name

That sounds good to me!

I think "Check Balance" is too long for the button. Did you notice it also turns into "Reset" once pressed? I wonder if we should do "Check Prediction" or "Check Balance" for the accessible name. And "Reset Pillars" for the other button?

[marlitas]

@terracoda & @amanda-phet should I also change to accessible name in the Balance Point screen to "Total Distance"?

[marlitas]

I went ahead and changed the total on the Balance Point screen as well. It felt more consistent.

[terracoda]

@marlitas, Re "Total Distance" I forgot to put it in the list (sorry). I wanted to ask if it could be both accessible and visual names, since it wasn't confusing like the other totals. I leave that decision to you both.

@amanda-phet - re the check balance button, I have not fully played with it. I need to look at all the words to decide the check balance name, but I do like "Reset Pillars". That adds another detail to the words.

[marlitas]

I wanted to ask if it could be both accessible and visual names, since it wasn't confusing like the other totals. I leave that decision to you both.

I think the decision was to keep it consistent between all the screens. @amanda-phet can you confirm?

[terracoda]

@amanda-phet and @marlitas, I think the list of visual and accessible names that we agreed upon are in the check list in #307 (comment)

[terracoda]

Close this issue when all names are in except the Group Sort names. This names will be followed in phetsims/scenery-phet#860

[marlitas]

All the accessible names have been updated. I am creating a new issue to track moving the strings to the strings file: #309