Discuss HTML structures for Ohm's Law PDOM

[terracoda]

A very basic PDOM for Ohm's Law is available here: ohms-law-pdom.html

Adding succinct version: ohms-law-pdom-succinct.html

This example is completely static. The highlighted bits of content represent dynamic parameters in the sim.

This issue is to discuss ideas or improvements to this initial structure.

One question in particular is how best to represent the equation and the circuit.

@emily-phet, @jessegreenberg, @zepumph , and more can comment. Need to find everyone's handles.

[jessegreenberg]

@terracoda do you want to designate a "Play Area" in this sim that wraps the equation, circuit and the sliders?

I can't remember if we wanted that for all sims, or if it isn't always necessary.

[zepumph]

With [[3] batteries totalling [[4.5]] volts

There can be partial batteries, so we will probably want to change that language accordingly. If there were 3.2 batteries because there were 4.8 volts, then it could say:

• With more than [[3]] batteries totaling [[4.8]] volts
• With between [[3] and [[4]] batteries totaling [[4.8]] volts
• With [[3.2]] batteries totaling [[4.5]] volts NOTE: (probably would be a bit ugly, but we could round these decimals down if they got too big)

[zepumph]

This also brings up another, larger, topic for discussion. In the sim, there is a MAX_NUMBER_OF_BATTERIES constant that controls the number of batteries that can be on the wire. In general, developers of a sim we try to make sure that constants like these aren't completely tied in to the implementation of the sim, and changing it is possible (with the need for minor changes probable) without the sim breaking.

How does this fit into Accessibility? Outfitting a sim with accessibility is no small order, and everything has to be very specific to create a high quality product. That being said, does the idea of maintainability and sim change/churn come into play with the design process? How?

[jessegreenberg]

That is a great question @zepumph, I have wondered similar things. I have been thinking of accessibility like a second view observing the model, and we should be careful to make sure that descriptions are robust enough to handle model changes. In the case of ohms-law, changing the value of MAX_NUMBER_OF_BATTERIES would change the scaling of V, I, and R. Just like we would need to tweak the view to make sure everything looks good/is still on screen, we might need to modify how descriptions are mapped out.

In this case, the most robust solution could be to map the description of those values to the max/min values possible in the sim (calculated by MAX_NUMBER_OF_BATTERIES). But for complex sims, it could definitely be a maintainability issue.

[zepumph]

I think you are correct. That sounds like a good plan for this sim. I brought it up to make sure that we continue to minimize the distance between design and implementation. It could be a good strategy for a designer to look through the contants file of a simulation as a list of potential tools that they have to work with. In case you want to @terracoda, the constants of a simulation (if one exists) is always located in {{sim-repo}}/js/{{SimNameCamelCase}}Constants.js. Where strings surrounded by '{{}}' are filled in based on the specific name. I'm not sure if it will be too helpful for this sim, but you can see nice things like:

  var RESISTANCE_RANGE = new RangeWithValue( 10, 1000, 500 ); // in ohms
  var VOLTAGE_RANGE = new RangeWithValue( 0.1, 9, 4.5 ); // in volts

which can tell you values without having to go into the sim and manually figure them out.

[terracoda]

@zepumph, I like your wording suggestions for the partial numbers of batteries. I had left that off intentionally because I wasn't sure how best to word it. Like you, I thought 3.5 batters was a bit messy. Will iterate on yours and Emily's wording which is already in the design document.

Thanks!

[terracoda]

@zepumph thanks, yes, the model mappings and the constants are useful to know about!

[terracoda]

@jessegreenberg and @zepumph, I updated the PDOM based on feedback from August 8th's meeting. I added a little more list structure, as it seemed to fit well with the newer descriptions.

In this version, the Play Area's accessible name is in an h2 heading. It could be moved into an aria-label (similar to the approach in Build an Atom) if people think it makes sense. I think the objects in the Play Area are few enough that using an h2 to label the Play Area is fine.

[zepumph]

There are two sliders for adjusting voltage and resistance. In the Control Panel, you find buttons to reset sim and mute sound.

I always thought of the sliders as part of the control panel also, but I guess for a sim this simple, its smart to include them in the play area. I think I like it as is best, just potentially worth a bit of discussion.

[terracoda]

@jessegreenberg, re https://github.com/phetsims/a11y-research/issues/48#issuecomment-320293701, in earlier versions, the Play Area's label was in an aria-label.

In some sims with many objects, like Build an Atom, I think it makes sense to reserve as much heading hierarchy as possible for play area objects, themselves.

Either way, there is a clearly labeled Play Area that wraps the sim's most relevant "playing objects".

[zepumph]

Sounds good. Thanks for all the great work here, it looks very nice.

[terracoda]

@zepumph, there seems to be wiggle room on where objects fall. It's something that can be discussed. It is not always perfectly clear, but thus far, the strategy has been to put the most pedagogically focused control objects in the Play Area.

The Wall's button in BASE might be an exception to the strategy.

[terracoda]

@jessegreenberg, @zepumph, and @emily-phet I've updated the PDOM with the latest descriptions and created a succinct version as well.

• Full PDOM
• Succinct PDOM

Latest version of design document is here: Ohm's Law Descriptions google sheet It contains the full version and succinct versions side by side. I think I captured all the feedback I got this week. Thanks everyone!

Note: I'm not sure that the fieldset with legend is the best structure to create a group for the two sliders as I'm not sure how it will sound in all platforms.

[jessegreenberg]

Here is latest ohms law with the descriptions implemented: http://www.colorado.edu/physics/phet/dev/html/ohms-law/1.4.0-dev.8/ohms-law_en.html

I sent an email to @terracoda and @emily-phet requesting review of this version.

[terracoda]

@jessegreenberg amd @zepumph, we have a working PDOM for Ohm's Law, and are on our second draft of descriptions, so closing this issue.