AccordionBox

• Source Code and Options
• Number of sims that use this component: 66

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 (please spell out simulation name).
• 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

• AccordionBox.ts
• ExpandCollapseBar.ts
• ExpandCollpaseButton.ts

Aesthetic Considerations

• If space is a concern, the title can be hidden while the accordion box is expanded. Note that an accessible name for the title is always needed and available for the non-visual experience.
• 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

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

DRAFT: Sample HTML

<! -- expanded state -->
    <h3>
       <button id="accordion-header-01" aria-expanded="true">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">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

• Adapted from ARIA Practices 3.1 Accordion (Sections With Show/Hide Functionality)

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 - actually, title for header should be required.
  • Title is a heading? Yes/No, defaults to Yes
  • If title is heading, set heading level, defaults to H3
  • Accordion title is visually 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 (defaults to expanded)

Checkbox

• Source Code and Options
• Number of sims that use this component: 97

Design Considerations

We generally use a checkbox in simulation design:

• To toggle on (or off) a secondary or non-essential option;
• To provide a group of options that can be toggled on or off;
• To layer on more complex representations, or to view multiple, related represenations simultaneously. More complex options are generally off by default.

Aesthetic Considerations

• Appear checked or not checked on simulation load.
• Appear 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.

Considerations for Interactive Description Design

A checkbox in SceneryStack code renders as a native HTML element with the role of "checkbox." It comes with two native states, "checked" and "unchecked." These details are communicated automatically when interacted with when using screen reader software.

To be fully screen reader accessible 2 design cycles may be required to complete the design:

• 1 - Core/Essential Description:
  • Accessible Name - must be unique;
  • Accessible Help Text - must read true in either state;
• 2 - Interactive Description:
  • Two Accessible Context Responses - one describing what happens upon getting checked, and one that describes what happens upon getting unchecked.

Description Desgin Tips

• Avoid using a verb in the name, e.g. "Show Values." It works well for Interactive Descripton, but it does not work well for Voicing.
• Capture the idea of the changing context in the help text (if needed), "Explore with or without units visible."
• Be clear on the what, e.g., "Values" can be vague without context.

A checkbox focus event communicates:

• [The designed accessible name] + [unchecked] + [checkbox]

A checkbox toggle event communicates:

• Changed state automatically: [checked] or [unchecked] +
• If designed [An accessible context response describing what happens for each state change.]

Example 1 Interactive Description: Greenhouse Effect:

* accessible name: "Cloud"
* accessible help text: "Experiment with cloudy sky."
* initial state: checked
* accessible context response unchecked: "Cloud removed from sky."
* accessible context response checked: "Cloud added to sky."

What a learner hears when interacting with the Cloud checkbox:

* On focus: "Cloud, checked, checkbox"
* When toggled to unchecked: "unchecked", then "Cloud removed from sky."
* When toggled to checked: "checked", then "Cloud added to sky."

Example 2 "Essential/Core" Description : Special Angles in Trig Tour:

* accessible name: Special Angles
* accessible help text: Explore with or without constrained angles.
* initial state: unchecked
* accessible context response unchecked: TBD
* accessible context response checked: TBD

What a learner hears when interacting with the Special Angles checkbox:

* On focus: "Special Angles, unchecked, checkbox"
* When toggled to checked: "checked"
* When toggled to unchecked: "unchecked"

Considerations for Voicing Design

The Voicing feature is a system of responses available to all input methods. Responses are delivered in direct response to user action on focus or on activation. (ToDo: link to about Voicing Response System).

To have a complete Voicing feature 2 design cycles may be required to design required voicing responses:

• 1 - Core/Essential Voicing:
  • a Voicing Name Response - must be unique, and ideally identical to the accessible name;
  • Voicing Help Text Response - ideally indicating there are two available states. It is great if the accessible help text and Voicing help text are the same (options available to make them different, if needed);
• 2 - Voicing:
  • Two Voicing Context Responses - preferably identical to the accessible context responses;

The Voicing experience of a checkbox can vary based input method and the Sim Voicing Options that are seletected in Preferences;

• With keyboard input users:
  • Always hear voicing name response;
  • Can hear a voicing help text response;
  • Never hear changed states, "checked" or "unchecked";
  • Can hear a voicing context response.
• With mouse and touch users:
  • Always hear voicing name response;
  • Never hear voicing help text response;
  • Never hear changed states, "checked" or "unchecked";
  • Can hear a voicing context response.

Keyboard Support

Identical across Description and Voicing features.

Gesture Support

• Swipe left or right to move focus.
• Double tap to toggle state of checkbox.

Supporting Resources for Design and Development

• ToDo - Add links to releveant design resources available in the description design course.
• ToDo - Link to API Quick Start Guides
• ARIA Authoring Practice Guide: Checkbox Example (Two State)
• Using ARIA, working draft
• HTML Living Standard, Section 4.10.5.1.15 Checkbox state (type=checkbox))
• ARIA Authoring Practice Guide: Checkbox Example (Two State)

ComboBox

• Source Code and Options
• Number of sims that use this component: 42

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 of hidden options can be revealed on demand; however, the accessible representation that we have found to work nicely is actually a button, which may have a dynamic label (i.e., accessible name) that pops up a listbox with a list of options. Design and interaction details are below.

Gesture Support

ToDO.

Keyboard Support

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)

Sample HTML for Combobox

The PhET combobox interaction, visually looks and behaves as a combobox; however, the ARIA 1.1 Combobox design pattern wasn't and will never be supported. For the accessible representation in the Parallel DOM we implemented this widget as a dynamic button and a popped-up listbox (Bryan Garanventa, 2016). 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

• Adapted from ARIA Practices Collapsible Listbox Example( 2016)
• The above pattern has been adopted as the 1.2 Combobox design pattern( 2022)

Design Doc Content Template Text

{{Name of combobox}}, combobox

Accessible Name (dynamic): Text + {{Name of Selected list item}} (e.g. Solute: {{Drink Mix}})

Interaction Type: Combobox (i.e., Combobox.ts composed of subcomponents ComboBoxButton.ts (tagName: 'button') and ComboBoxListBox.ts (ariaRole: 'listbox')

Button Label with initial selection:

Listbox list items:

• List Item 1 (e.g., Drink Mix)
• List Item 2 (e.g., Cobalt (II) nitrate)
• List Item 3

(Optional) Help Text:

(Optional) Link to section with object & context responses

(Optional) Design Note: Special things about this combobox, if any.

RectangularRadioButtonGroup

• Source Code and Options
• Number of sims that use this component: 77

No markdown content for RectangularRadioButtonGroup yet.

ToolboxPattern

• Source Code and Options
• Number of sims that use this component: 4

Toolbox Design Pattern

Here’s the when and why we use a toolbox pattern.

• The toolbox pattern is a custom interaction pattern used to group 2 or more tools (e.g., measurement tools). These tools can be added to the Play Area of a simulation for different purposes.
• The tools in the toolbox present as button interactions. They are placed in the PDOM order as single focusable objects (i.e., no grouping behavior yet available on the toolbox).
• The activated tool is visually transformed, receives focus, and becomes draggable with Arrow keys (and alternatives).

Note: This pattern is also referred to as the Creator Pattern.

Aesthetic Considerations

• Toolbox appears in a visually defined space like a outlined box.
• The toolbox and tools usually appear without any visual names, but in some cases visual names appear in addition to the tools (e.g., Circuit Construction Kit: AC, Membrane Transport).
• Title case is used for text-based tool names.
• An activated tool becomes full size. Depending on input method, the full-sized tool is dragged to a desired placed by the learner (pointer input), or it is placed near the toolbox or automatically in a useful place in the Play Area.

Interaction Design Considerations for Alternative Input

• Ensure the PDOM placement of the activated tool makes sense to the use of the activated tool.
• Ensure focus goes on the activated tool so it can be easily moved once activated.
• Ensure it is not too easy to accidentally return the tool to the tool box when using Alt Input.
• Ensure the Escape key works to return a focused-activated tool to the toolbox.
• Consider sim-specific shortcuts to make using the tool more efficient and effective for Alternative Input users.

Keyboard Interaction & Support

Note: Optional: Sim-specific shortcuts can be designed and implemented to jump a focused-activated tool to useful places in the simulation.

Toolbox Visual Example

• Geometric Optics Visual toolbox with no visual names:

Checkbox as Alternative to the Toolbox Pattern

The checkbox interaction can be used as an alternative to using the toolbox pattern. If a checkbox is used:

1. The Escape key does not work as a shortcut to uncheck the checkbox, and thus hide the activated-focused tool.
2. A tool activated by a checkbox does not need an additional two-step drag interaction. The action of checking the checkbox is the user's intentional activation of the tool. The Arrow keys (or alternatives) are then immediately operable to move the tool. For tools in a toolbox, the pressing of Space or Enter indicates the user's intention in the same way.
3. Like other tools, tools activated by a checkbox need consideration for sim-specific shortcuts to make using the tool more efficient and effective for Alternative Input users.

Description Design Considerations (Future)

• The tool activation step for both the toolbox and the checkbox tool provides the opportunity to give instructions to blind users once description is implemented. The activation step is what was determined to be needed for BASE's Yellow Balloon, Friction's Chemistry Book, and others (Faraday's Law, Gravity Force Lab) where the custom draggable object is already in the Play Area.
• It's these "already-in-the-Play-Area" draggable sim objects that may need to be revisited once the sims that contain these readily available draggable objects get a description feature.

State Descriptions

<h3>Toolbox</h3>
<p>Grab a ruler or marker as needed.</p>
<button>Horizontal Ruler</button>
<button>Vertical Ruler</button>

Responsive Descriptions

• When activated: Added to {{locationInPlayArea}}. Use Arrow keys or W, A, S, or D keys to move {{Horizontal Ruler}}.
• When returned: Back in toolbox.

KeyboardHelpDialog

• Source Code and Options
• Number of sims that use this component: 48

General Design Considerations

• A keyboard help dialog helps guide users with keyboard interaction.
• If an interaction comes first as an interaction in the sim, it should likely come first in the help dialog.

RoundPushButton

• Source Code and Options
• Number of sims that use this component: 133

No markdown content for RoundPushButton yet.

RectangularPushButton

• Source Code and Options
• Number of sims that use this component: 127

No markdown content for RectangularPushButton yet.