-
-

Push Buttons

+
+

General UI Components

-

Common info or all push buttons.

+

Here's the general information about the misc. UI components listed below.

-
-
-

RoundPushButton

- - -

No markdown content for RoundPushButton yet.

-
- -
-

Sim Examples

-
-
-
-
-
-
+
-

RectangularPushButton

+

AccordionBox

-

No markdown content for RectangularPushButton yet.

-
- -
-

Sim Examples

-
-
-
-
-
-
-
-

HTMLPushButton

- +

General Design Considerations

+

Here’s when and why we use accordion boxes:

+
    +
  • Default state can be expanded or collapsed depending on how the designer wants to scaffold the user interaction. A closed panel can be used to keep the default opening condition of sim from being visually overwhelming, and suggesting a logical route for exploration, for example in Build an Atom and in GE:B (what's GE:B?).
    • +
  • Accordion boxes can also be useful for teachers to ask predictive questions.
    • +
  • Can contain non-interactive readouts, interactive controls, but not sprites (e.g., draggable toolbox items).
    • +
+

Note this design pattern covers multiple PhET Component Types

+ +

Aesthetic Considerations

+
    +
  • If space is a concern, the title can be hidden while the accordion box is expanded.
    • +
  • An expanded accordion box cannot overlap other elements when opened (unlike combo box, for instance).
    • +
  • Always includes an iconed button (+/-), typically to the left of the title.
    • +
  • Other sim content does not fill the space when an accordion box is collapsed.
    • +
  • The accordion box content can be expanded or collapsed by default and a change of state for one accordion does not affect the state of other accordion boxes.
    • +
+

Accessibility Considerations

+

Accessible Components of an Accordion Box

+

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

+
    +
  • Accordion Header: Label (usually a heading with a +/- icon signalling expand/collapse behaviour) for a section of content (usually a collapsible box). The accordion header could also be an icon, alone. The accordion header serves as a control that can show or hide a section of content.
    • +

  • Accordion Panel: Section of content (e.g., the content box) associated with an accordion header

    +
    • +

  • Typically, has a visual title with an icon that indicates expanded and collapsed state.

    +
      +
    • The title may disappear when box is expanded.
      • +
    • Focus highlight would go around title in both the expanded and collapsed states, if title remains visible.
      • +
    • If title visually disappears when expanded, the focus highlight would be limited to the open/close icon and the designer would need to consider extra padding to ensure a reasonable clickable area.
      • +
    • It is possible that the focus highlight can change size when toggling between expanded/collapsed states in the scenario when the expanded box does not have a title.
      • +
    +
    • +
  • The typical structure is a button nested within the parent titling element, likely a heading.
    • +
  • Typically, the open/close icon does not need to be represented in the Parallel DOM.
    • +
  • For accessibility the expanded and collapsed states of the box are communicated through a combination of ARIA attributes, aria-expanded, aria-controls, aria-hidden that have to be managed through javascript.
    • +
+

Gesture Support

+

ToDO.

+

Keyboard Support

+

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyFunction
Enter or SpaceWhen focus is on the accordion header of a collapsed section, expands or collapses the accordion panel.
Down Arrow (optional)- If focus is on an accordion header, moves focus to the next accordion header. If focus is on the last accordion header, either does nothing or moves focus to the first accordion header.
- If there is only one accordion, doing nothing with focus is likely appropirate.
Up Arrow (Optional)- If focus is on an accordion header, moves focus to the previous accordion header. If focus is on the first accordion header, either does nothing or moves focus to the last accordion header.
- If there is only one accordion, doing nothing with focus is likely appropirate.
Home and End (Optional)Likely only relevant if there are several to many accordions (to discuss)
Control + Page Down
and
Control + Page Up (Optional)		Behave the same way as Up and Down Arrows. (to discuss)
+

QUESTION: It's not clear to me how users get inside a panel, if the panel has no focusable items.

+

Management of Role, Property, State, and Tabindex Attributes

+

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleAttributeElementUsageNotes
----buttonThe title content of each accordion header is contained in an element with role button.
----h3 (or appropriate level)PhET Sims use native HTML, so we use native heading and button elements to create the accordion header.The button element is the only element inside the heading element. That is, if there are other visually persistent elements, they are not included inside the heading element.
-aria-expanded="true/false"divAdded to accordion panel dynamically with Javascript to indicate when the panel associated with the header is visible (aria-expanded="true"), or if the panel is not visible, aria-expanded is set to false.
-aria-controls="[ID REF of element contianing accordion panel]"
button-
-aria-disabled="true"-If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true. (I think this is NOT RELEVANT for PhET sims?)
region (optional)aria-labelledby=[ID REF of button that controls the display of the panel]div-
+

DRAFT: Sample HTML

+
<! -- expanded state -->
+    <h3>
+       <button id="accordion-header-01" aria-expanded="true" aria-controls="accordion-panel-01">Factors</button>
+    </h3>
+    <div id="accordion-panel-01" role="region" aria-labelledby="accordion-header-01">
+       <p>Box content.</p>
+       <p>More content or even other HTML controls.</p>
+    </div>
+<! -- collapsed state -->
+  <h3>
+     <button id="accordion-header-02" aria-expanded="false" aria-controls="accordion-panel-02">Product</button>
+  </h3>
+  <div id="accordion-panel-02" role="region" aria-labelledby="accordion-header-02" aria-hidden="true">
+     <p>Box content.</p>
+     <p>More content or even other HTML controls.</p>
+  </div>
+
+

Supporting Accessibility Resources

+ +

Design Doc Content Template Text

+

Accordion Box

+
    +
  • Accordion Box Title (header):
    • +
  • Accessible Name: content for the accordon box title
      +
    • Header contains a title? Yes/No, default Yes
      • +
    • Title is a heading? Yes/No, defaults to Yes
      • +
    • If title is heading, set heading level, defaults to H3
      • +
    • Accordion Title Hidden: Yes/No (defaults to No)
      • +
    +
    • +
  • Accordion Box Content (panel):
      +
    • Parent container accordion box contents: defaults to a div
      • +
    • Use same convention as other objects and controls.
      • +
    • Default open state: expanded/collapsed (Question: What is the best default?)
      • +
    +
    • +
-

No markdown content for HTMLPushButton yet.

Sim Examples

-
-
-
-
- -
-
-

Toggle Buttons

- -

General information about the PhET Toggle buttons.

- - -
-
-
-

RoundStickyToggleButton

- - -

No markdown content for RoundStickyToggleButton yet.

-
- -
-

Sim Examples

-
-
-
-
-
-
-
-

RectangularStickyToggleButton

- - -

No markdown content for RectangularStickyToggleButton yet.

-
- -
-

Sim Examples

-
-
-
-
-
- -
-
-

Sliders

- -

Here's some great information about sliders.

-

Here are our subtypes:

- - -
-
-
-

HSlider

- - -

Information specific to the HSlider Type

- -
- -
-

Sim Examples

-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
-
- -
    -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
-
-
- -
    -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
-
-
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
      +
    • PhET Simulation Page
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
      • +
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
    -
    • -
    • -
    • -
    • -
    • -
-
-
-
-
-
-
-
-

FrequencySlider

- - -

No markdown content for FrequencySlider yet.

-
- -
-

Sim Examples

-
-
-
-
-
-
-
-

WavelengthSlider

- - -

No markdown content for WavelengthSlider yet.

-
- -
-

Sim Examples

-
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
+
+ + +
+
+ + +
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
+
+ + +
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ +
    +
  • PhET Simulation Page
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ + +
- -
-
-

General UI Components

- -

Here's the general information about the misc. UI components listed below.

- - -
-
+
-

AccordionBox

+

Checkbox

General Design Considerations

-

Here’s when and why we use accordion boxes:

+

Here’s the when and why we use a checkbox (traditional looking checkbox user interface component) in simulation design.

    -
  • Default state can be expanded or collapsed depending on how the designer wants to scaffold the user interaction. A closed panel can be used to keep the default opening condition of sim from being visually overwhelming, and suggesting a logical route for exploration, for example in Build an Atom and in GE:B (what's GE:B?).
    • -
  • Accordion boxes can also be useful for teachers to ask predictive questions.
    • -
  • Can contain non-interactive readouts, interactive controls, but not sprites (e.g., draggable toolbox items).
    • +
  • Generally, when a secondary or non-essential option needs to be toggled between on and off states
    • +
  • To toggle more than one option in a group of options
    • +
  • Checkboxes are often used to allow users to layer on more complex representations, or to view multiple, related represenations simultaneously. More complex options are generally off by default.

Note this design pattern covers multiple PhET Component Types

-
    -
  • AccordionBox.js
    • -
  • ExpandCollapseBar.js
    • -
  • ExpandCollpaseButton.js
    • +
      +
    • Question: Are there any other types of visual checkboxes?

    Aesthetic Considerations

      -
    • If space is a concern, the title can be hidden while the accordion box is expanded.
      • -
    • An expanded accordion box cannot overlap other elements when opened (unlike combo box, for instance).
      • -
    • Always includes an iconed button (+/-), typically to the left of the title.
      • -
    • Other sim content does not fill the space when an accordion box is collapsed.
      • -
    • The accordion box content can be expanded or collapsed by default and a change of state for one accordion does not affect the state of other accordion boxes.
      • +
    • Checkbox appears checked or not checked on simulation load
      • +
    • Appears with a text-based label, or an icon as the label, or a combination of both text and icon
      • +
    • Title case is used for text-based labels for checkboxes

    Accessibility Considerations

    -

    Accessible Components of an Accordion Box

    -

    Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

    -
      -
    • Accordion Header: Label (usually a heading with a +/- icon signalling expand/collapse behaviour) for a section of content (usually a collapsible box). The accordion header could also be an icon, alone. The accordion header serves as a control that can show or hide a section of content.
      • -

    • Accordion Panel: Section of content (e.g., the content box) associated with an accordion header

      -
      • -

    • Typically, has a visual title with an icon that indicates expanded and collapsed state.

        -
      • The title may disappear when box is expanded.
        • -
      • Focus highlight would go around title in both the expanded and collapsed states, if title remains visible.
        • -
      • If title visually disappears when expanded, the focus highlight would be limited to the open/close icon and the designer would need to consider extra padding to ensure a reasonable clickable area.
        • -
      • It is possible that the focus highlight can change size when toggling between expanded/collapsed states in the scenario when the expanded box does not have a title.
        • -
      -
      • -
    • The typical structure is a button nested within the parent titling element, likely a heading.
      • -
    • Typically, the open/close icon does not need to be represented in the Parallel DOM.
      • -
    • For accessibility the expanded and collapsed states of the box are communicated through a combination of ARIA attributes, aria-expanded, aria-controls, aria-hidden that have to be managed through javascript.
      • +
    • HTML checkboxes (i.e., input type="checkbox") and possibly all visual PhET sim checkboxes are two-state controls that represent the element's "checkedness" state.
      • +
    • Traditional looking checkboxes with visual labels are generally best represented in the PDOM as an input of type checkbox with an associated label element.
      • +
    • When the visual label content is an image or a string of text that does immediately translate into a name that clearly communicates what the checkbox is for, non-visually, consider changing the visual string, adding clarifying help text, or providing a more descriptive name as the label element's content in the PDOM. Keep in mind that ideally, the visual text and the text in the PDOM should be the same to support users who use voiced commands.
      • +
    • Groups of related checkboxes may benefit from being explicitly grouped using a containing element (e.g., fieldset or div) with the ARIA role="group". Grouping checkboxes is optional.
      • +
    • Explicitly grouped checkboxes may benefit from a group name provided by either an h3 or a legend.
      • +
    • Checkboxes that appear visually grouped (e.g., by proximity or with a visual box) for convenience or space-saving may not benefit from explicit group semantics in the PDOM.
      • +
    • When a group is very important, consider using a heading, e.g., h3 as headings are placed in the heading outline which can be navigated with screen reader software whereas the legend element is not placed in the heading hierarchy.
    +

    Note: Known issue that some screen readers (i.e., VoiceOver) repeat the checkbox's label content when the label is associated with the input via the for attribute. The aria-label attribute does not cause any repetition.

    Gesture Support

    ToDO.

    Keyboard Support

    -

    Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

    - - + + - - - - - - - - - - - - - - + + - - + +
    KeyFunctionKeyFunction
    Enter or SpaceWhen focus is on the accordion header of a collapsed section, expands or collapses the accordion panel.
    Down Arrow (optional)- If focus is on an accordion header, moves focus to the next accordion header. If focus is on the last accordion header, either does nothing or moves focus to the first accordion header.
    - If there is only one accordion, doing nothing with focus is likely appropirate.
    Up Arrow (Optional)- If focus is on an accordion header, moves focus to the previous accordion header. If focus is on the first accordion header, either does nothing or moves focus to the last accordion header.
    - If there is only one accordion, doing nothing with focus is likely appropirate.
    Home and End (Optional)Likely only relevant if there are several to many accordions (to discuss)TabMoves keyboard focus to the checkbox.
    Control + Page Down
    and
    Control + Page Up (Optional)    		Behave the same way as Up and Down Arrows. (to discuss)SpaceToggles checkbox between checked and unchecked states.
    -

    QUESTION: It's not clear to me how users get inside a panel, if the panel has no focusable items.

    Management of Role, Property, State, and Tabindex Attributes

    -

    Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    RoleAttributeElementUsageNotes
    ----buttonThe title content of each accordion header is contained in an element with role button.
    ----h3 (or appropriate level)PhET Sims use native HTML, so we use native heading and button elements to create the accordion header.The button element is the only element inside the heading element. That is, if there are other visually persistent elements, they are not included inside the heading element.
    -aria-expanded="true/false"divAdded to accordion panel dynamically with Javascript to indicate when the panel associated with the header is visible (aria-expanded="true"), or if the panel is not visible, aria-expanded is set to false.
    -aria-controls="[ID REF of element contianing accordion panel]"
    button-
    -aria-disabled="true"-If the accordion panel associated with an accordion header is visible, and if the accordion does not permit the panel to be collapsed, the header button element has aria-disabled set to true. (I think this is NOT RELEVANT for PhET sims?)
    region (optional)aria-labelledby=[ID REF of button that controls the display of the panel]div-
    -

    DRAFT: Sample HTML

    -
    <! -- expanded state -->
-    <h3>
-       <button id="accordion-header-01" aria-expanded="true" aria-controls="accordion-panel-01">Factors</button>
-    </h3>
-    <div id="accordion-panel-01" role="region" aria-labelledby="accordion-header-01">
-       <p>Box content.</p>
-       <p>More content or even other HTML controls.</p>
-    </div>
-<! -- collapsed state -->
-  <h3>
-     <button id="accordion-header-02" aria-expanded="false" aria-controls="accordion-panel-02">Product</button>
-  </h3>
-  <div id="accordion-panel-02" role="region" aria-labelledby="accordion-header-02" aria-hidden="true">
-     <p>Box content.</p>
-     <p>More content or even other HTML controls.</p>
-  </div>
+
    Respecting the first rule of ARIA, "use a native HTML element whenever possible", we use native checkbox elements in the PDOM to represent traditional looking checkbox interactions. An HTML checkbox could represent other "switching" interactions that may not visaully look like a checkbox in the simulation, but examples for those are provided elsewhere. Because we use native HTML for checkbox interactions, some of the guidance provided in ARIA Practices for checkbox widgets is not relevant. I have adapted the content from the ARIA practices section for checkbox.
    
+
      
+
    • No explicit ARIA role of checkbox is needed on an native HTML checkbox (input type="checkbox").
      • 
+
    • No tabindex required, native HTML checkboxes are focusable elements.
      • 
+
    • An HTML checkbox has an accessible label (i.e., accessible name) provided by one of two of the following ways:
        
+
      • Visible text content contained within a label element and assocaited to its input with the for attribute.
        • 
+
      • Content within an aria-label attribute set on the input element with type="checkbox".
        • 
+
      
+
      • 
+
    • When checked, the checkbox element has the attribute checked present.
      • 
+
    • When not checked, the checked attribute is not present.
      • 
+
    • When partially checked, it has state aria-checked set to mixed. (tri-state checkboxes only)
      • 
+
    • When a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role="group" that has the property aria-labelledby set to the ID of the element containing the label or name for the group.
      • 
+
    • When the presentation includes additional descriptive static text (i.e., help text) relevant to a checkbox or group of checkboxes, using aria-describedby is an option to provide automatically read help text. We have, however, that automatic helptext is not needed in our sims. Users seem to prefer on-demand help text.
      • 
+
    
+
    Simplified HTML Examples for PDOM
    
+
    (Suggested) Options for Checkbox in the A11y API
    
+
    When creating the common code component, it would be useful to have options to use either a label element or an aria-label attribute to provide the accessible name for the checkbox. Using aria-labelledby is a possible option, but likely rarely the best choice for a native HTML input element.
    
+
    Checkbox with visual label text
    
+
    Energy Forms and Changes
    
+
    Visual checkbox with a text-based label:
+alt text "Sample unchecked checkbox for Engery Symbols"
    
+
    <input id=”energy-symbols” type=”checkbox”> <!-- not checked checkbox-->
+<label for=”energy-symbols”>Energy Symbols</label>
+<p>Observe energy chunks move and change through system.</p>
+
    
+
    Checkbox without visual label text (option with aria-label)
    
+
    Area Model Introduction
    
+
    Visual checkbox with different label
+alt text "Sample check"
    
+
    <input id="counting-numbers" type="checkbox" aria-label="Counting numbers">
+<p>Use area grid with or without counting numbers in grid cells.</p>
+
    
+
    Unnamed group of checkboxes
    
+
    Gravity Force Lab
    
+
    Note: still need to finish this example.
    
+
    <input id=”” type=”checkbox”> <!-- not checked checkbox-->
+<label for=””>Constant Size</label>
+<p>When changing mass, observe constant or changing size of spheres.</p>
+
+<input id=”” type=”checkbox”> <!-- not checked checkbox-->
+<label for=””>Force Values</label>
+<p>Explore value of forces in newtons.</p>
+
+<input id=”” type=”checkbox”> <!-- not checked checkbox-->
+<label for=””>Scientific Notation</label>
+<p>Listen to newtons in scientific notation.</p>
 
    
 
    Supporting Accessibility Resources
    
 
 
    Design Doc Content Template Text
    
-
    Accordion Box
    
+
    Energy Symbols, Checkbox
    
 
      
-
    • Accordion Box Title (header):
      • 
-
    • Accessible Name: content for the accordon box title
        
-
      • Header contains a title? Yes/No, default Yes
        • 
-
      • Title is a heading? Yes/No, defaults to Yes
        • 
-
      • If title is heading, set heading level, defaults to H3
        • 
-
      • Accordion Title Hidden: Yes/No (defaults to No)
        • 
-
      
-
      • 
-
    • Accordion Box Content (panel):
        
-
      • Parent container accordion box contents: defaults to a div
        • 
-
      • Use same convention as other objects and controls.
        • 
-
      • Default open state: expanded/collapsed (Question: What is the best default?)
        • 
+
      • PhET Component: Checkbox.js
        • 
+
      • Accessible Name: Energy Symbols (e.g. Example 1)  
        • 
+
      • (Optional) Help Text: (e.g., Observe energy chunks move and change through system.)
        • 
 
      
-
      • 
+
      TO DO:
      
+
        
+
      • Group example, could use one from GFL series (no heading required)
        •
@@ -950,1877 +2333,1214 @@

Design Doc Content Template Text

Sim Examples

- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + + +
+
+ + +
+
+ + +
+
+ +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + + +
+
+ + +
+
+ +
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + + +
+
+ +
- -
+
+ + +
+
+ +
- -
+
+ + +
+
+ +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + + +
+
+ +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
    -
    • + + +
+
+ +
- -
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + + +
+
+ +
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + + +
+
+ + +
+
+ + +
+
+ +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
+
+
+
+
+
+
+

ComboBox

+ + +

General Design Considerations

+
    +
  • Generally used with limited space and/or a long list of choices
    • +
  • PhET comboboxes are not auto-select when hovering options with a mouse or when navigating through options with the arrow keys (i.e., different from radio button lists)
    • +
  • Label for control serves a dual purpose: identifies the combobox (list of options) and identifies the selected option
    • +
  • Selected item is communicated clearly upon focus and when the list is closed
    • +
  • Large pointer/click areas: box label and selected item; option labels and images
    • +
+

Aesthetic Considerations

+
    +
  • List can appear above or below the button depending on space considerations
    • +
  • Can include an indicator image (to the left of the list item)
    • +
  • The rounded corners of the list should match the rounded corners of the button
    • +
  • Generally, the list panel is often the same width as the button
    • +
  • Mouse hover and focus highlights should be considered together
    • +
+

Accessibility

+

The PhET combobox interaction, visually looks and behaves as a combobox in the sense that a list hidden options can be revealed on demand; however, the accessible representation that we have found to work nicely is actually a button with a dynamic label that can pop-up listbox with a list of options. Design and interaction details are below.

+

Gesture Support

+

ToDO.

+

Keyboard Support

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyFunction
Enter and SpaceIf the listbox is NOT displayed, opens/expands the listbox and moves focus to selected option in the opened list. (Note Space key is not specified in the standard, but that's how our example and the W3C example work. Space key works on a button, but not specifically on a list.)
EnterIf the listbox is displayed, selects item and collapses the listbox and moves focus to the button.
EscapeIf the listbox is displayed, collapses the listbox without changing the slection and moves focus to the button.
Down ArrowMoves focus to the next option.
Up ArrowMoves focus to the previous option.
Home (Optional)Moves focus to first option. (Recommended when there are more than 5 items)
End (Optional)Moves focus to last option. (Recommended when there are more than 5 items)
+

Role, Property, State, and Tabindex Attributes

+

(adjusted content from W3C listbox collapsible example, see https://www.w3.org/TR/wai-aria-practices-1.1/examples/listbox/listbox-collapsible.html)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleAttributeElementUsage
-aria-haspopup="listbox"buttonIndicates that activating the button displays a listbox (i.e., a list of options)
-aria-expanded="true"buttonSet by the JavaScript when the listbox is displayed. Otherwise, is not present.
-aria-labelledby="listbox-static-label listbox-option-dynamic-label"buttonReads out a combined name for the interaction when focus is placed on the button, first the name for the "combobox interaction", then the name of the selected option. Javascript sets the inner content of the button to be the selected item.
role="listbox"-ulIdentifies the focusable element that has listbox behaviors and contains the listbox options.
-aria-labelledby="listbox-static-label"ulRefers to the element containing the listbox label (i.e., the accessible name for the listbox).
-tabindex="-1"ul- Makes the listbox focusable.
+
    +
  • The JavaScript sets focus on the listbox when the listbox is displayed. | +| - | aria-activedescendent | - | - Set by the JavaScript when the listbox is displayed and sets focus on the listbox; otherwise is not present.
    • +
  • Refers to the option in the listbox that is visually indicated as having keyboard focus.
    • +
  • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
    • +
  • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the ul element. | +| role="option" | -| li | Identifies each selectable element containing the name of an option. | +| - | aria-selected="true"| li | - Indicates that the option is selected.
    • +
  • Applied to the element with role option that is visually styled as selected.
    • +
  • Set by the Javascript when Enter is pressed on the option referenced by aria-activedescendant.
    • +
  • Note that in an auto-select listbox where selection follows focus, the option with this attribute is always the same as the option that is referenced by aria-activedescendant. |
    • +
+

Sample HTML for Combobox

+

The PhET combobox interaction, visually looks and behaves as a combobox; however, the ARIA role combobox is not yet well supported. Fo the accessible representation in the Parallel DOM we implement this widget as a dynamic button and a popped-up listbox. The HTML example is below.

+

Note: The HTML for this interaction may change when the ARIA role combobox has better support accross assitive technologies.

+

Molarity Example (10 options)

+
    <div tabindex="-1" id="container-for-labels">
+    <span id="listbox-static-label">Solute</span>
+      <button id="listbox-option-dynamic-label" tabindex="0" aria-haspopup="listbox" aria-labelledby="listbox-static-label listbox-option-dynamic-label">Drink Mix</button>
+    </div>
+    <ul role="listbox" tabindex="0" id="listbox" aria-activedescendant="option-1" aria-labelledby="listbox-static-label" style="list-style:none;">
+      <li role="option" id="option-1" class="selected" aria-selected="true">Drink mix</li>
+      <li role="option" id="option-2">Cobalt (II) nitrate</li>
+      <li role="option" id="option-3">Cobalt Chloride</li>
+      <li role="option" id="option-4">Potassium dichromate</li>
+      <li role="option" id="option-5">Gold (III) chloride</li>
+      <li role="option" id="option-6">Potassium chromate</li>
+      <li role="option" id="option-7">Nickel (II) chloride</li>
+      <li role="option" id="option-8">Copper sulfate</li>
+      <li role="option" id="option-9">Potassium permanganate</li>
+      <li role="option" id="option-10">Potassium dichromate</li>
+    </ul>
+    <!-- help text for combobox -->
+    <p>Change a solute and observe differences.</p>
+
+

Supporting Accessibility Resources

+ +

Design Doc Content Template Text

+

Solute Combobox

+
    +
  • Accessible Name for combobox interaction (i.e., lisbox label): (e.g. Solute)
    • +
  • Accessible name for pop-up button is dynamic: {{Selected list item, e.g. Drink Mix}}
    • +
  • Listbox: ul with role="listbox"
    • +
  • Listbox items: li's with role="option"
    • +
  • List Item 1 (e.g., Drink Mix)
    • +
  • List Item 2 (e.g., Cobalt (II) nitrate)
    • +
  • List Item 3
    • +
  • Or as listed in simulation
    • +
  • (Optional) Help Text:
    • +
+ +
+ +
+

Sim Examples

+
- -
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • +
+
+ +
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
- -
- -
- -
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • + +
- -
- -
-
+
-

Checkbox

+

RadioButtonGroup

General Design Considerations

-

Here’s the when and why we use a checkbox (traditional looking checkbox user interface component) in simulation design.

+

Here’s when and why we use radio button groups:

    -
  • Generally, when a secondary or non-essential option needs to be toggled between on and off states
    • -
  • To toggle more than one option in a group of options
    • -
  • Checkboxes are often used to allow users to layer on more complex representations, or to view multiple, related represenations simultaneously. More complex options are generally off by default.
    • +
  • Used to group a set of mutually exclusive buttons, known as radio buttons, where only one button in the group may be in a selected state.
    • +
  • Radio button groups, may look like a group of traditional radio buttons, or may look like a group of items that users switch between.
    • +
  • In PhET sims, traditional-looking groups of radio buttons are refered to as "vertical aqua radio buttons", and have a corresponding look.
    • +
  • All other groups of radio buttons are generally made up of rectangular buttons with images or symbols. Their size, image style, and spacing are visually group the individual radio buttons.

Note this design pattern covers multiple PhET Component Types

Aesthetic Considerations

    -
  • Checkbox appears checked or not checked on simulation load
    • -
  • Appears with a text-based label, or an icon as the label, or a combination of both text and icon
    • -
  • Title case is used for text-based labels for checkboxes
    • +
  • Label text is succinct and ideally sounds good when read as "selected". For example, in Area Model, the first Area Grid Size radio button might sound like, "10 by 10, selected". In Balloons and Static Electricity, a user may hear, "Show all charges, selected".
    • +
  • Occasionally a small icon follows the label text.
    • +
  • Radio buttons generally show the selected button as fully opaque with a thick black stroke, and the unselected buttons have reduced opacity and a thin stroke.
    • +
  • Focus highlight has a light focus around the group, and a thicker pink focus around the selected item.

Accessibility Considerations

    -
  • HTML checkboxes (i.e., input type="checkbox") and possibly all visual PhET sim checkboxes are two-state controls that represent the element's "checkedness" state.
    • -
  • Traditional looking checkboxes with visual labels are generally best represented in the PDOM as an input of type checkbox with an associated label element.
    • -
  • When the visual label content is an image or a string of text that does immediately translate into a name that clearly communicates what the checkbox is for, non-visually, consider changing the visual string, adding clarifying help text, or providing a more descriptive name as the label element's content in the PDOM. Keep in mind that ideally, the visual text and the text in the PDOM should be the same to support users who use voiced commands.
    • -
  • Groups of related checkboxes may benefit from being explicitly grouped using a containing element (e.g., fieldset or div) with the ARIA role="group". Grouping checkboxes is optional.
    • -
  • Explicitly grouped checkboxes may benefit from a group name provided by either an h3 or a legend.
    • -
  • Checkboxes that appear visually grouped (e.g., by proximity or with a visual box) for convenience or space-saving may not benefit from explicit group semantics in the PDOM.
    • -
  • When a group is very important, consider using a heading, e.g., h3 as headings are placed in the heading outline which can be navigated with screen reader software whereas the legend element is not placed in the heading hierarchy.
    • +
  • The following information is useful for fully communicating the interaction in the non-visual experience.
      +
    • the name of the radio button in the group that has focus,
      • +
    • the state (selected or not selected) of the radio button,
      • +
    • the fact that button is in a radiogroup, or in a radio button list,
      • +
    • the name of the group, and
      • +
    • the number of buttons or options in the group,
      • +
    +
    • +
  • It is important for a designer to consider upfront if the group's name should be part of the heading outline of the simulation or not. Placing the group's name in the heading outline (Sample HTML 1) gives the group's name more visibility (e.g., findability) in the non-visual experience. If that visibility is not necessary, you could use a legend element (Sample HTML 2).
    • +
+

Special Notes and Questions

+
    +
  • Using either a div or fieldset as the containing parent with the role="radiogroup" provides similar experiences. Note that we still need to test in NVDA and JAWS to confirm that fieldset is the best parent container.
    • +
  • Note the HTML is different from the ARIA Practices Examples because it uses more native HTML. The ARIA Examples, however, sound slightly better, consistently reading out radiogroup role and radio count without any duplicate list semantics. I'm not sure if the ARIA examples require heavier explicit handling of keyboard support because they do not use native form elements?

    Gesture Support

    +
    • +
  • ToDo
-

Note: Known issue that some screen readers (i.e., VoiceOver) repeat the checkbox's label content when the label is associated with the input via the for attribute. The aria-label attribute does not cause any repetition.

-

Gesture Support

-

ToDO.

Keyboard Support

+

From: Aria Practices, 3.16 Radio Group

@@ -2831,79 +3551,176 @@

Keyboard Support

- + - + + + + + + + + +
TabMoves keyboard focus to the checkbox.Moves focus to the radio group and focus is set to the selected radio button. (PhET radio group's generally have a pre-selected radio button). If a radio button is not selected, focus moves to the first radio button in the group. PhET's keyboard focus highlight goes on the radio button, and a group focus highlight goes on the group.
SpaceToggles checkbox between checked and unchecked states.If the radio button with focus is not selected, it changes the state to selected. Otherwise, does nothing. Note: The state where a radio button is not selected only occurs on page load. (Note: a radio button button group starting without a pre-selected radio buton is unlikely for a PhET Sim.)
Right arrow, Down arrowMoves focus to and selects the next radio button in the group. If focus is on the last radio button, focus moves to the first radio button in the group. The state of the previously selected radio button is changed to unchecked.
Left arrow, Up arrowMoves focus to and selects the previous radio button in the group. If focus is on the first radio button, moves focus to and selects the last radio button. The state of the previously selected radio button is changed to unselected.
-

Management of Role, Property, State, and Tabindex Attributes

-

Respecting the first rule of ARIA, "use a native HTML element whenever possible", we use native checkbox elements in the PDOM to represent traditional looking checkbox interactions. An HTML checkbox could represent other "switching" interactions that may not visaully look like a checkbox in the simulation, but examples for those are provided elsewhere. Because we use native HTML for checkbox interactions, some of the guidance provided in ARIA Practices for checkbox widgets is not relevant. I have adapted the content from the ARIA practices section for checkbox.

-
    -
  • No explicit ARIA role of checkbox is needed on an native HTML checkbox (input type="checkbox").
    • -
  • No tabindex required, native HTML checkboxes are focusable elements.
    • -
  • An HTML checkbox has an accessible label (i.e., accessible name) provided by one of two of the following ways:
      -
    • Visible text content contained within a label element and assocaited to its input with the for attribute.
      • -
    • Content within an aria-label attribute set on the input element with type="checkbox".
      • -
    -
    • -
  • When checked, the checkbox element has the attribute checked present.
    • -
  • When not checked, the checked attribute is not present.
    • -
  • When partially checked, it has state aria-checked set to mixed. (tri-state checkboxes only)
    • -
  • When a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role="group" that has the property aria-labelledby set to the ID of the element containing the label or name for the group.
    • -
  • When the presentation includes additional descriptive static text (i.e., help text) relevant to a checkbox or group of checkboxes, using aria-describedby is an option to provide automatically read help text. We have, however, that automatic helptext is not needed in our sims. Users seem to prefer on-demand help text.
    • -
-

Simplified HTML Examples for PDOM

-

(Suggested) Options for Checkbox in the A11y API

-

When creating the common code component, it would be useful to have options to use either a label element or an aria-label attribute to provide the accessible name for the checkbox. Using aria-labelledby is a possible option, but likely rarely the best choice for a native HTML input element.

-

Checkbox with visual label text

-
Energy Forms and Changes
-

Visual checkbox with a text-based label: -alt text "Sample unchecked checkbox for Engery Symbols"

-
<input id=”energy-symbols” type=”checkbox”> <!-- not checked checkbox-->
-<label for=”energy-symbols”>Energy Symbols</label>
-<p>Observe energy chunks move and change through system.</p>
+
From: Aria Practices, 3.16 Radio Group

+
Management of Roles, States, Properties, and Focus (DRAFT)

+
Content adpated from: Aria Practices, 3.16 Radio Group

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
RoleAttributeElementUsage
radiogroupfieldsetIdentifies the fieldset element as a container for a group of radio buttons. Group is not focusable because focus is managed using a roving tabindex strategy as described below. (Question: How are we managing focus?)
aria-labelledby="[IDREF"h3 (heading with appropriate heading level)Refers to the element that contains the label of the radio group. The legend element can be used instead of a heading, and would provide the group's name implicitly without aria-labelledby. Note, however, the legend element is not included in the heading outline for screen readers.
tabindex="0"ulIncludes the radio group in the page Tab sequence. Applied to the radio group because aria-activedescendant is used to manage focus as described below. (Question: How are we managing focus?)
aria-activedescendant="[IDREF]"ulWhen a radio button in the radio group is visually indicated as having keyboard focus, refers to that radio button. When arrow keys are pressed, the JavaScript changes the value. Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the radio group element. For more information about this focus management technique, see Using aria-activedescendant to Manage Focus.
type="radio"inputIdentifies the input element as a radio button. The accessible name is computed from the child text content of the label element.
for="[IDREF of input]"labelThe accessible name for the radio is computed from the child text content of the label element.
aria-checked="true", or checked (Question: Do we use the aria attribute or the HTML5 attribute currently?)Identifies the radio button which is selected. CSS attribute selectors (e.g. [aria-checked="true"]) are used to synchronize the visual states with the value of the aria-checked attribute. (N/A in PhET's case) The CSS ::before pseudo-class is used to indicate visual state of selected radio buttons to support high contrast settings in operating systems and browsers. (N/A in PhET's case)

+
Sample 1 HTML with heading & aria-labelledby (heading semantics required)

+
Moleules and Light Example

+
Example is based on the light sources radio buttons in Moelcules and Light. The visual appearence of these buttons are large square buttons with flashlight-like icons, rather than traditional radio buttons with text-based labels. The paragraph containig help text is placed after the h3 heading in this example.

+
<fieldset role="radiogroup" aria-labelledby="rg16-heading">
+  <h3 id="rg16-heading">Light Sources</h3>
+   <p>Change light source in observation window.</p>
+    <ul>
+      <li><input id="r16-1" type="radio" tabindex="0" checked>
+          <label for="r16-1">Microwave</label>
+      </li>
+      <li><input id="r16-2" type="radio">
+          <label for="r16-2">Infared</label>
+      </li>
+     <li><input id="r16-3" type="radio">
+         <label for="r16-3">Visible</label>
+      </li>
+      <li><input id="r16-4" type="radio">
+          <label for="r16-4">Ultraviolet</label>
+       </li>
+    </ul>
+</fieldset>
 

-
Checkbox without visual label text (option with aria-label)

-
Area Model Introduction

-
Visual checkbox with different label
-alt text "Sample check"

-
<input id="counting-numbers" type="checkbox" aria-label="Counting numbers">
-<p>Use area grid with or without counting numbers in grid cells.</p>
+
Sample 2 HTML with legend (heading semantics not required)

+
Area Model Introduction Example

+
Example is based on the "scene selection" radio buttons in Area Model Introduction. The visual appearence of these buttons small square buttons, rather than traditional radio buttons. There is no help text content for this example. By using a legend element instead of a heading element to name the group, the group's name will not be placed in the heading outline of the simulation. The aria-labelledby attribute is not needed with the legend element.

+
<fieldset role="radiogroup">
+  <legend>Area Grid Size</legend>
+    <ul id="group-r18">
+      <li>
+        <input id="r18-1" type="radio" tabindex="0" checked>
+        <label for="r18-1">10 by 10</label>
+      </li>
+      <li id="container-r10-2">
+        <input id="r18-2" type="radio">
+        <label for="r18-2">12 by 12</label>
+      </li>
+    </ul>
+</fieldset>
 

-
Unnamed group of checkboxes

-
Gravity Force Lab

-
Note: still need to finish this example.

-
<input id=”” type=”checkbox”> <!-- not checked checkbox-->
-<label for=””>Constant Size</label>
-<p>When changing mass, observe constant or changing size of spheres.</p>
-
-<input id=”” type=”checkbox”> <!-- not checked checkbox-->
-<label for=””>Force Values</label>
-<p>Explore value of forces in newtons.</p>
-
-<input id=”” type=”checkbox”> <!-- not checked checkbox-->
-<label for=””>Scientific Notation</label>
-<p>Listen to newtons in scientific notation.</p>
+
Sample 3 HTML early simple solution with no ARIA

+
Balloons and Static Electricity Example

+
Example is based on the charge radio buttons in Balloons and Static Electricity. The visual appearence of this group looks like radio buttons. The paragraph containig help text is placed after the h3 heading in this example.

+
Note This simple structure does not use any aria roles or attributes. Early usability testing (2015-2016) found simple was better. AT for fieldset, role="radiogroup", and aria-labelledby has improved since early testing with this simulation, so we are moving forward with the fieldset examples above.

+
<div id-"rgroup-container-id">
+  <h3 id="rgroup-label-id">Charge Settings</h3>
+   <p>Choose how you see or hear charge information.</p>
+    <ul>
+      <li><input id="radiobutton-1" tabindex="0" type="radio" checked>
+          <label for="radiobutton-1">Show all charges</label>
+      </li>
+      <li><input id="radiobutton-2" type="radio">
+          <label for="radiobutton-2">Show no charges</label>
+      </li>
+     <li><input id="radiobutton-3" type="radio">
+         <label for="radiobutton-3">Show charge differences</label>
+      </li>
+    </ul>
+</div>
 

 
Supporting Accessibility Resources

 
 
Design Doc Content Template Text

-
Energy Symbols, Checkbox

+
Light Sources, Radio Button Group

 
    
-
  • PhET Component: Checkbox.js
    • 
-
  • Accessible Name: Energy Symbols (e.g. Example 1)  
    • 
-
  • (Optional) Help Text: (e.g., Observe energy chunks move and change through system.)
    • 
+
  • PhET Component: RadioButtonGroup.js
    • 
+
  • Group Name via h3 with aria-labelledby: Light Sources (e.g. Sample 1)
    • 
+
  • Radio button group: fieldset with role="radiogroup"
    • 
+
  • Radio buttons contained in an ul with list items, li
    • 
+
  • Names for radio buttons in the group
      
+
    • List Item 1: Name (e.g. Microwave)
      • 
+
    • List Item 2: Name (e.g. Infared)
      • 
+
    • List Item 3: Name (e.g. Visible)
      • 
+
    • List Item 4: Name (e.g. Ultraviolet)
      • 
+
    • Or as listed in simulation
      • 
 
    
-
    TO DO:
    
+
    • 
+
  • (Optional) Help Text: (e.g. Change light source in observation window.)
    • 
+

+
Area Grid Size, Radio Button Group

 
    
-
  • Group example, could use one from GFL series (no heading required)
    • 
+
  • PhET Component: RadioButtonGroup.js
    • 
+
  • Group Name via legend: Area Grid Size (e.g. Sample 2)  
    • 
+
  • Radio button group: fieldset with role="radiogroup"
    • 
+
  • Radio buttons contained in an ul with list items, li
    • 
+
  • List names for radio buttons in the group
      
+
    • List Item 1: Name (e.g. 10 by 10)
      • 
+
    • List Item 2: Name (e.g. 12 by 12)
      • 
+
    • Or as listed in simulation
      • 
+
    
+
    • 
+
  • (Optional) Help Text:
    •
@@ -2912,1591 +3729,1443 @@

Design Doc Content Template Text

Sim Examples

- -
    -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
-
-
- -
    -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- -
- -
- -
- -
- -
- -
- -
+
+ +
+
+
+
+
+ +
+
+

Push Buttons

+ +

Common info or all push buttons.

+ + +
+
+
+

RoundPushButton

+ + +

No markdown content for RoundPushButton yet.

+
+ +
+

Sim Examples

+
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
-
-
-
-
-
-
-

ComboBox

- - -

General Design Considerations

-
    -
  • Generally used with limited space and/or a long list of choices
    • -
  • PhET comboboxes are not auto-select when hovering options with a mouse or when navigating through options with the arrow keys (i.e., different from radio button lists)
    • -
  • Label for control serves a dual purpose: identifies the combobox (list of options) and identifies the selected option
    • -
  • Selected item is communicated clearly upon focus and when the list is closed
    • -
  • Large pointer/click areas: box label and selected item; option labels and images
    • -
-

Aesthetic Considerations

-
    -
  • List can appear above or below the button depending on space considerations
    • -
  • Can include an indicator image (to the left of the list item)
    • -
  • The rounded corners of the list should match the rounded corners of the button
    • -
  • Generally, the list panel is often the same width as the button
    • -
  • Mouse hover and focus highlights should be considered together
    • -
-

Accessibility

-

The PhET combobox interaction, visually looks and behaves as a combobox in the sense that a list hidden options can be revealed on demand; however, the accessible representation that we have found to work nicely is actually a button with a dynamic label that can pop-up listbox with a list of options. Design and interaction details are below.

-

Gesture Support

-

ToDO.

-

Keyboard Support

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyFunction
Enter and SpaceIf the listbox is NOT displayed, opens/expands the listbox and moves focus to selected option in the opened list. (Note Space key is not specified in the standard, but that's how our example and the W3C example work. Space key works on a button, but not specifically on a list.)
EnterIf the listbox is displayed, selects item and collapses the listbox and moves focus to the button.
EscapeIf the listbox is displayed, collapses the listbox without changing the slection and moves focus to the button.
Down ArrowMoves focus to the next option.
Up ArrowMoves focus to the previous option.
Home (Optional)Moves focus to first option. (Recommended when there are more than 5 items)
End (Optional)Moves focus to last option. (Recommended when there are more than 5 items)
-

Role, Property, State, and Tabindex Attributes

-

(adjusted content from W3C listbox collapsible example, see https://www.w3.org/TR/wai-aria-practices-1.1/examples/listbox/listbox-collapsible.html)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
RoleAttributeElementUsage
-aria-haspopup="listbox"buttonIndicates that activating the button displays a listbox (i.e., a list of options)
-aria-expanded="true"buttonSet by the JavaScript when the listbox is displayed. Otherwise, is not present.
-aria-labelledby="listbox-static-label listbox-option-dynamic-label"buttonReads out a combined name for the interaction when focus is placed on the button, first the name for the "combobox interaction", then the name of the selected option. Javascript sets the inner content of the button to be the selected item.
role="listbox"-ulIdentifies the focusable element that has listbox behaviors and contains the listbox options.
-aria-labelledby="listbox-static-label"ulRefers to the element containing the listbox label (i.e., the accessible name for the listbox).
-tabindex="-1"ul- Makes the listbox focusable.
-
    -
  • The JavaScript sets focus on the listbox when the listbox is displayed. | -| - | aria-activedescendent | - | - Set by the JavaScript when the listbox is displayed and sets focus on the listbox; otherwise is not present.
    • -
  • Refers to the option in the listbox that is visually indicated as having keyboard focus.
    • -
  • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
    • -
  • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the ul element. | -| role="option" | -| li | Identifies each selectable element containing the name of an option. | -| - | aria-selected="true"| li | - Indicates that the option is selected.
    • -
  • Applied to the element with role option that is visually styled as selected.
    • -
  • Set by the Javascript when Enter is pressed on the option referenced by aria-activedescendant.
    • -
  • Note that in an auto-select listbox where selection follows focus, the option with this attribute is always the same as the option that is referenced by aria-activedescendant. |
    • -
-

Sample HTML for Combobox

-

The PhET combobox interaction, visually looks and behaves as a combobox; however, the ARIA role combobox is not yet well supported. Fo the accessible representation in the Parallel DOM we implement this widget as a dynamic button and a popped-up listbox. The HTML example is below.

-

Note: The HTML for this interaction may change when the ARIA role combobox has better support accross assitive technologies.

-

Molarity Example (10 options)

-
    <div tabindex="-1" id="container-for-labels">
-    <span id="listbox-static-label">Solute</span>
-      <button id="listbox-option-dynamic-label" tabindex="0" aria-haspopup="listbox" aria-labelledby="listbox-static-label listbox-option-dynamic-label">Drink Mix</button>
-    </div>
-    <ul role="listbox" tabindex="0" id="listbox" aria-activedescendant="option-1" aria-labelledby="listbox-static-label" style="list-style:none;">
-      <li role="option" id="option-1" class="selected" aria-selected="true">Drink mix</li>
-      <li role="option" id="option-2">Cobalt (II) nitrate</li>
-      <li role="option" id="option-3">Cobalt Chloride</li>
-      <li role="option" id="option-4">Potassium dichromate</li>
-      <li role="option" id="option-5">Gold (III) chloride</li>
-      <li role="option" id="option-6">Potassium chromate</li>
-      <li role="option" id="option-7">Nickel (II) chloride</li>
-      <li role="option" id="option-8">Copper sulfate</li>
-      <li role="option" id="option-9">Potassium permanganate</li>
-      <li role="option" id="option-10">Potassium dichromate</li>
-    </ul>
-    <!-- help text for combobox -->
-    <p>Change a solute and observe differences.</p>
-
-

Supporting Accessibility Resources

- -

Design Doc Content Template Text

-

Solute Combobox

-
    -
  • Accessible Name for combobox interaction (i.e., lisbox label): (e.g. Solute)
    • -
  • Accessible name for pop-up button is dynamic: {{Selected list item, e.g. Drink Mix}}
    • -
  • Listbox: ul with role="listbox"
    • -
  • Listbox items: li's with role="option"
    • -
  • List Item 1 (e.g., Drink Mix)
    • -
  • List Item 2 (e.g., Cobalt (II) nitrate)
    • -
  • List Item 3
    • -
  • Or as listed in simulation
    • -
  • (Optional) Help Text:
    • -
- -
- -
-

Sim Examples

-
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
-
-
-
-
-
-
-

RadioButtonGroup

- - -

General Design Considerations

-

Here’s when and why we use radio button groups:

-
    -
  • Used to group a set of mutually exclusive buttons, known as radio buttons, where only one button in the group may be in a selected state.
    • -
  • Radio button groups, may look like a group of traditional radio buttons, or may look like a group of items that users switch between.
    • -
  • In PhET sims, traditional-looking groups of radio buttons are refered to as "vertical aqua radio buttons", and have a corresponding look.
    • -
  • All other groups of radio buttons are generally made up of rectangular buttons with images or symbols. Their size, image style, and spacing are visually group the individual radio buttons.
    • -
-

Note this design pattern covers multiple PhET Component Types

- -

Aesthetic Considerations

-
    -
  • Label text is succinct and ideally sounds good when read as "selected". For example, in Area Model, the first Area Grid Size radio button might sound like, "10 by 10, selected". In Balloons and Static Electricity, a user may hear, "Show all charges, selected".
    • -
  • Occasionally a small icon follows the label text.
    • -
  • Radio buttons generally show the selected button as fully opaque with a thick black stroke, and the unselected buttons have reduced opacity and a thin stroke.
    • -
  • Focus highlight has a light focus around the group, and a thicker pink focus around the selected item.
    • -
-

Accessibility Considerations

-
    -
  • The following information is useful for fully communicating the interaction in the non-visual experience.
      -
    • the name of the radio button in the group that has focus,
      • -
    • the state (selected or not selected) of the radio button,
      • -
    • the fact that button is in a radiogroup, or in a radio button list,
      • -
    • the name of the group, and
      • -
    • the number of buttons or options in the group,
      • -
    -
    • -
  • It is important for a designer to consider upfront if the group's name should be part of the heading outline of the simulation or not. Placing the group's name in the heading outline (Sample HTML 1) gives the group's name more visibility (e.g., findability) in the non-visual experience. If that visibility is not necessary, you could use a legend element (Sample HTML 2).
    • -
-

Special Notes and Questions

-
    -
  • Using either a div or fieldset as the containing parent with the role="radiogroup" provides similar experiences. Note that we still need to test in NVDA and JAWS to confirm that fieldset is the best parent container.
    • -
  • Note the HTML is different from the ARIA Practices Examples because it uses more native HTML. The ARIA Examples, however, sound slightly better, consistently reading out radiogroup role and radio count without any duplicate list semantics. I'm not sure if the ARIA examples require heavier explicit handling of keyboard support because they do not use native form elements?

    Gesture Support

    -
    • -
  • ToDo
    • -
-

Keyboard Support

-

From: Aria Practices, 3.16 Radio Group

- - - - - - - - - - - - - - - - - - - - - - - - - -
KeyFunction
TabMoves focus to the radio group and focus is set to the selected radio button. (PhET radio group's generally have a pre-selected radio button). If a radio button is not selected, focus moves to the first radio button in the group. PhET's keyboard focus highlight goes on the radio button, and a group focus highlight goes on the group.
SpaceIf the radio button with focus is not selected, it changes the state to selected. Otherwise, does nothing. Note: The state where a radio button is not selected only occurs on page load. (Note: a radio button button group starting without a pre-selected radio buton is unlikely for a PhET Sim.)
Right arrow, Down arrowMoves focus to and selects the next radio button in the group. If focus is on the last radio button, focus moves to the first radio button in the group. The state of the previously selected radio button is changed to unchecked.
Left arrow, Up arrowMoves focus to and selects the previous radio button in the group. If focus is on the first radio button, moves focus to and selects the last radio button. The state of the previously selected radio button is changed to unselected.
-

From: Aria Practices, 3.16 Radio Group

-

Management of Roles, States, Properties, and Focus (DRAFT)

-

Content adpated from: Aria Practices, 3.16 Radio Group

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
RoleAttributeElementUsage
radiogroupfieldsetIdentifies the fieldset element as a container for a group of radio buttons. Group is not focusable because focus is managed using a roving tabindex strategy as described below. (Question: How are we managing focus?)
aria-labelledby="[IDREF"h3 (heading with appropriate heading level)Refers to the element that contains the label of the radio group. The legend element can be used instead of a heading, and would provide the group's name implicitly without aria-labelledby. Note, however, the legend element is not included in the heading outline for screen readers.
tabindex="0"ulIncludes the radio group in the page Tab sequence. Applied to the radio group because aria-activedescendant is used to manage focus as described below. (Question: How are we managing focus?)
aria-activedescendant="[IDREF]"ulWhen a radio button in the radio group is visually indicated as having keyboard focus, refers to that radio button. When arrow keys are pressed, the JavaScript changes the value. Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the radio group element. For more information about this focus management technique, see Using aria-activedescendant to Manage Focus.
type="radio"inputIdentifies the input element as a radio button. The accessible name is computed from the child text content of the label element.
for="[IDREF of input]"labelThe accessible name for the radio is computed from the child text content of the label element.
aria-checked="true", or checked (Question: Do we use the aria attribute or the HTML5 attribute currently?)Identifies the radio button which is selected. CSS attribute selectors (e.g. [aria-checked="true"]) are used to synchronize the visual states with the value of the aria-checked attribute. (N/A in PhET's case) The CSS ::before pseudo-class is used to indicate visual state of selected radio buttons to support high contrast settings in operating systems and browsers. (N/A in PhET's case)
-

Sample 1 HTML with heading & aria-labelledby (heading semantics required)

-

Moleules and Light Example

-

Example is based on the light sources radio buttons in Moelcules and Light. The visual appearence of these buttons are large square buttons with flashlight-like icons, rather than traditional radio buttons with text-based labels. The paragraph containig help text is placed after the h3 heading in this example.

-
<fieldset role="radiogroup" aria-labelledby="rg16-heading">
-  <h3 id="rg16-heading">Light Sources</h3>
-   <p>Change light source in observation window.</p>
-    <ul>
-      <li><input id="r16-1" type="radio" tabindex="0" checked>
-          <label for="r16-1">Microwave</label>
-      </li>
-      <li><input id="r16-2" type="radio">
-          <label for="r16-2">Infared</label>
-      </li>
-     <li><input id="r16-3" type="radio">
-         <label for="r16-3">Visible</label>
-      </li>
-      <li><input id="r16-4" type="radio">
-          <label for="r16-4">Ultraviolet</label>
-       </li>
-    </ul>
-</fieldset>
-
-

Sample 2 HTML with legend (heading semantics not required)

-

Area Model Introduction Example

-

Example is based on the "scene selection" radio buttons in Area Model Introduction. The visual appearence of these buttons small square buttons, rather than traditional radio buttons. There is no help text content for this example. By using a legend element instead of a heading element to name the group, the group's name will not be placed in the heading outline of the simulation. The aria-labelledby attribute is not needed with the legend element.

-
<fieldset role="radiogroup">
-  <legend>Area Grid Size</legend>
-    <ul id="group-r18">
-      <li>
-        <input id="r18-1" type="radio" tabindex="0" checked>
-        <label for="r18-1">10 by 10</label>
-      </li>
-      <li id="container-r10-2">
-        <input id="r18-2" type="radio">
-        <label for="r18-2">12 by 12</label>
-      </li>
-    </ul>
-</fieldset>
-
-

Sample 3 HTML early simple solution with no ARIA

-

Balloons and Static Electricity Example

-

Example is based on the charge radio buttons in Balloons and Static Electricity. The visual appearence of this group looks like radio buttons. The paragraph containig help text is placed after the h3 heading in this example.

-

Note This simple structure does not use any aria roles or attributes. Early usability testing (2015-2016) found simple was better. AT for fieldset, role="radiogroup", and aria-labelledby has improved since early testing with this simulation, so we are moving forward with the fieldset examples above.

-
<div id-"rgroup-container-id">
-  <h3 id="rgroup-label-id">Charge Settings</h3>
-   <p>Choose how you see or hear charge information.</p>
-    <ul>
-      <li><input id="radiobutton-1" tabindex="0" type="radio" checked>
-          <label for="radiobutton-1">Show all charges</label>
-      </li>
-      <li><input id="radiobutton-2" type="radio">
-          <label for="radiobutton-2">Show no charges</label>
-      </li>
-     <li><input id="radiobutton-3" type="radio">
-         <label for="radiobutton-3">Show charge differences</label>
-      </li>
-    </ul>
-</div>
-
-

Supporting Accessibility Resources

- -

Design Doc Content Template Text

-

Light Sources, Radio Button Group

-
    -
  • PhET Component: RadioButtonGroup.js
    • -
  • Group Name via h3 with aria-labelledby: Light Sources (e.g. Sample 1)
    • -
  • Radio button group: fieldset with role="radiogroup"
    • -
  • Radio buttons contained in an ul with list items, li
    • -
  • Names for radio buttons in the group
      -
    • List Item 1: Name (e.g. Microwave)
      • -
    • List Item 2: Name (e.g. Infared)
      • -
    • List Item 3: Name (e.g. Visible)
      • -
    • List Item 4: Name (e.g. Ultraviolet)
      • -
    • Or as listed in simulation
      • -
    -
    • -
  • (Optional) Help Text: (e.g. Change light source in observation window.)
    • -
-

Area Grid Size, Radio Button Group

-
    -
  • PhET Component: RadioButtonGroup.js
    • -
  • Group Name via legend: Area Grid Size (e.g. Sample 2)
    • -
  • Radio button group: fieldset with role="radiogroup"
    • -
  • Radio buttons contained in an ul with list items, li
    • -
  • List names for radio buttons in the group
      -
    • List Item 1: Name (e.g. 10 by 10)
      • -
    • List Item 2: Name (e.g. 12 by 12)
      • -
    • Or as listed in simulation
      • -
    -
    • -
  • (Optional) Help Text:
    • -
- -
- -
-

Sim Examples

-
- -
- -
- -
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
+
+ + +
+
+ +
+
+ + +
+
+ + +
+
+
+
+
+
+
+

RectangularPushButton

+ + +

No markdown content for RectangularPushButton yet.

+
+ +
+

Sim Examples

+
+
+
+
+
+
+
+

HTMLPushButton

+ + +

No markdown content for HTMLPushButton yet.

+
+ +
+

Sim Examples

+
+
+
+
+
+ +
+
+

Sliders

+ +

Here's some great information about sliders.

+

Here are our subtypes:

+ + +
+
+
+

HSlider

+ + +

Information specific to the HSlider Type

+ +
+ +
+

Sim Examples

+
+
+
+
+
+
+
+

FrequencySlider

+ + +

No markdown content for FrequencySlider yet.

+
+ +
+

Sim Examples

+
+
+
+
+
+
+
+

WavelengthSlider

+ + +

No markdown content for WavelengthSlider yet.

+
+ +
+

Sim Examples

+
+
+
+
+
+ +
+
+

Toggle Buttons

+ +

General information about the PhET Toggle buttons.

+ + +
+
+
+

RoundStickyToggleButton

+ + +

No markdown content for RoundStickyToggleButton yet.

+
+ +
+

Sim Examples

+
+
+
+
+
+
+
+

RectangularStickyToggleButton

+ + +

No markdown content for RectangularStickyToggleButton yet.

+
+ +
+

Sim Examples

+
diff --git a/js/createHTMLString.js b/js/createHTMLString.js index 75bac7a..d0b81db 100644 --- a/js/createHTMLString.js +++ b/js/createHTMLString.js @@ -83,16 +83,22 @@ const createHTMLString = function( data ) { } let parentComponents = Object.values( mdData ).filter( component => component.data.parent ); - parentComponents.sort( (a,b) => a.data.order - b.data.order ); - // loop over each parent component for ( let parent of parentComponents ) { let componentsHTML = ''; for ( const component of parent.data.components ) { - const key = `${parent.repo}/${component}`; - const sims = data[ key ]; - const simCount = sims ? Object.keys( sims ).length : 0; + const repoComponent = `${parent.repo}/${component}`; + const simObject = data[ repoComponent ]; + const simCount = simObject ? Object.keys( simObject ).length : 0; + const sims = simObject ? + Object.keys( simObject ).map( simName => { + return { + name: simName, + images: simObject[ simName ] + }; + } ) : []; + let markdown = mdData[ component ] ? mdData[ component ].content : `

No markdown content for ${component} yet.

`; markdown = new handlebars.SafeString( markdown ); const componentContext = { @@ -128,6 +134,12 @@ handlebars.registerHelper( 'componentLink', ( repo, component ) => { ); } ); +handlebars.registerHelper( 'simPageLink', ( simName ) => { + return new handlebars.SafeString( + `PhET Simulation Page` + ); +} ); + handlebars.registerHelper( 'navList', (components, repo) => { let itemsHTML = components.map( c => `
  • ${c}
    • ` ).join('\n'); return '
      ' + itemsHTML + '
    '; diff --git a/templates/base.html b/templates/base.html index e850b32..04f1d24 100644 --- a/templates/base.html +++ b/templates/base.html @@ -17,6 +17,10 @@ .bd-sidenav li { padding-left: 10px; } + + .list-group-item { + border: none; + } diff --git a/templates/singleComponent.html b/templates/singleComponent.html index 0b68d2a..24fe746 100644 --- a/templates/singleComponent.html +++ b/templates/singleComponent.html @@ -12,16 +12,21 @@

    {{component}}

    Sim Examples

    - {{#each sims as |imgList|}} + {{#if sims}} + {{#each sims}}
    - -
      - {{#each imgList}} + +
        +
      • {{simPageLink this.name}}
        • + {{#if this.images}} + {{#each this.images}}
        • {{/each}} + {{/if}}
    {{/each}} + {{/if}}