a11y semantics for PhET navigation bar

[jessegreenberg]

From #13, @terracoda added some information about the semantics for PhET's navigation bar. Here is the content, copied from that issue:

I updated a sample html template for the sim’s bottom bar.
I used a footer element instead of a tool or menu bar. This might be more reliable and provide a nice landmark.

I've used some nav elements with aria-labels, so it sounds pretty good in Voice Over, but it’s still quite rough. The PhET Menu buttons are not being read out yet (when expanded), and are not navigable with arrow keys (when expanded), so I think I have done something wrong there. I've adapted some tips from Pickering's Inclusive Design Patterns.

Also, I am not 100% sure if sim screen navigation should go inside or outside this footer. This decision does not have to happen immediately, but soon.

The sample template is in my own repo at this link:
https://github.com/terracoda/phet-templates/blob/master/a11y-menu-template.html

@jesse, also, is this the active issue for this topic, or is issue #12, the proper place?

Note: Pickering has an nice pattern for using SVG on the button icon. I haven't included that as we likely do not need it in the hidden PDOM. It might be useful for other situations, though.

Note: I moved my HTML mock-ups to the A11y-Research repo. New links are:

• Bottom bar - two options
• PhET Menu Nested

[jessegreenberg]

Here is the HTML for the navigation bar as it is now (In this case, only one screen):

<div role="navigation" id="60-67">
  <button id="60-67-69-120">Hot Keys and Help</button>
  <button aria-haspopup="true" id="60-67-69-112">PhET</button>
</div>

And when the PhET Menu is open:

<div role="navigation" id="60-67">
  <button id="60-67-69-120">Hot Keys and Help</button>
  <button aria-haspopup="true" id="60-67-69-112">PhET</button>
</div>
<ul role="menu" id="60-159-71">
    <li id="parent-container-60-159-71-97-78" role="menuitem">
        <button role="link" id="60-159-71-97-78">‪‪‪‪‪‪PhET Website…‬‬‬‬‬‬</button>
    </li>
    <li id="parent-container-60-159-71-97-81" role="menuitem">
        <button role="link" id="60-159-71-97-81">‪‪‪‪‪‪‪Report a Problem…‬‬‬‬‬‬‬</button>
    </li>
    <li id="parent-container-60-159-71-97-84" role="menuitem">
        <button id="60-159-71-97-84">‪‪‪‪‪‪‪‪‪‪Check for Updates…‬‬‬‬‬‬‬‬‬‬</button>
    </li>
    <li id="parent-container-60-159-71-97-87" role="menuitem">
        <button id="60-159-71-97-87">‪‪‪‪‪‪‪‪Screenshot‬‬‬‬‬‬‬‬</button>
    </li>
    <li id="parent-container-60-159-71-97-90" role="menuitem">
        <button id="60-159-71-97-90">‪‪‪‪‪‪‪‪‪Full Screen‬‬‬‬‬‬‬‬‬</button>
    </li>
    <li id="parent-container-60-159-71-97-94" role="menuitem">
        <button id="60-159-71-97-94">‪‪‪About…‬‬‬</button>
    </li>
</ul>

Here is a version of it running:
http://www.colorado.edu/physics/phet/dev/html/john-travoltage/1.3.0-dev.18/john-travoltage-a11y-view.html

[jessegreenberg]

I had a few questions about the HTML in the template:

1. Screens are represented as <a>'s. Can they be buttons?
2. Having the menu inside the footer would be non-trivial to implement due to the way modal dialogs are added to the view. Is the structure in a11y semantics for PhET navigation bar #25 (comment) acceptable?
3. <a>'s are used in the PhET menu, could we use <button>'s with role="link"?

[jessegreenberg]

For instance, the recommendation for the PhET Menu is

<!-- Design pattern adapted from Pickering's menu button.-->
<nav aria-label="Sim tools and links">
  <button aria-expanded="false">PhET Menu</button>
  <!-- <p>Tools and links for this sim.</p> -->
  <ul hidden aria-hidden="true">
    <li><button>View Options</button></li> 
    <li><button>Check for Updates</button></li>
    <li><button>Take Screenshot</button></li>
    <li><button>Full Screen</button></li>
    <li><a href="https://phet.colorado.edu/files/troubleshooting/?BIG-LONG-LINK">Report Problem</a></li>
    <li><button>About this Sim</button></li>
    <li><a href="http://phet.colorado.edu/">PhET Website</a></li>
  </ul>
</nav><!-- end PheT Menu Nav -->

Could it be something like

<footer>
  <...other stuff...>
  <nav aria-label="Sim tools and links">
    <button aria-dexpanded="false">PhET Menu</button>
  </nav>
</footer>

<!-- When open this is visible, otherwise it isn't in the DOM -->
<ul hidden aria-hidden="true">
  <li><button>View Options</button></li> 
  <li><button>Check for Updates</button></li>
  <li><button>Take Screenshot</button></li>
  <li><button>Full Screen</button></li>
  <li><button role="link">Report Problem></button</li>
  <li><button>About this Sim</button></li>
  <li><button role="link">PhET Website</button></li>
</ul>

[terracoda]

@jessegreenberg, having the list of items immediately after the button is a progressive enhancement technique. Basically, it means if the css or js fail, the items are still right there inside the labeled nav and immediately after the button that provides the iconic identification.

In your examples, does Scenery place the list outside the footer once it is visible? Structurally to me this makes no sense.

Is the problem the placement of the list, or the operation of the buttons in the list if the buttons are embedded too deeply?

I think, if the menu has to be "disconnected" from the button, in the PDOM hierarchy, then it would it be useful to establish the relationship using aria. The problem is that aria-controls is very unreliable.

[terracoda]

@jessegreenberg, excellent questions

1. Screens are represented as <a>'s. Can they be buttons?

I used <a>'s for the list of screens in the template because my understanding of the sim screens is that they are part of the same page. Buttons generally indicate some kind of function, not a link to other content. However, buttons can be used to show and hide content. Buttons are a possibility. Tab panel navigation is usually a list of links, however with some special aria attributes.

2. Having the menu inside the footer would be non-trivial to implement due to the way modal dialogs are added to the view. Is the structure in a11y semantics for PhET navigation bar #25 (comment) acceptable?

One of the goals at this point is to implement with as little change to Scenery as possible, so maybe we should revisit how hierarchical relationships are managed soon, but not now. I think of the PDOM as a well-structured, semantically rich HTML document. Often the simplest way to show relationships is through the natural hierarchy. There are other ways to communicate relationship, but they may be less robust. Let's see how users interpret the bar and the menu with less natural nesting.

3. <a>s are used in the PhET menu, could we use <button>'s with role="link"?

A button with the role link is not a good idea. Links and buttons have different key presses and communicate different things to the users. The presence of a link tells the user that they will be taken somewhere, either to another section, page, or site. A button tells the user they are going to do something (but not go anywhere necessarily), submit a form, open a dialog, show hidden content. These 2 items in the PhET Menu go to urls, so they are semantically links to other pages.

@jessegreenberg, can Scenery not put a link in this context?

[terracoda]

@jessegreenberg, Pickerings says to avoid:

• Background images for icon rendering.
• Omitting accessible names and labels.
• Small touch (or hit) areas.
• Foregoing accessible state communication.
  Excerpt From: Heydon Pickering. “Inclusive Design Patterns." iBooks.

The second and third items are the relevant in our PDOM.

[jessegreenberg]

In your examples, does Scenery place the list outside the footer once it is visible?
Is the problem the placement of the list, or the operation of the buttons in the list if they buttons are embedded too deeply?

In the example, Scenery places the list outside the footer when it is visible. When invisible, the list does not exist in the DOM.
The problem is the placement of the list. The simulation hierarchy looks like

<simulation>
  <screens>
  <navigation-bar>
    <screen-buttons>
    <keyboard-help-button>
    <PhET-Menu-Button>
  <dialog-layer>
    <options-dialog>
    <about-dialog>
    <updates-dialog>
    <PhET-Menu-list>
<simulation>

Which is why Scenery places the PhET menu list outside of the navigation bar in the parallel DOM as well. To change this, we would need to change the simulation hierarchy or the way scenery structures the PDOM. It would take some effort to do either of these, so it seemed worth investigating an aria solution if possible.

[jessegreenberg]

Thanks @terracoda!

I used 's for the list of screens in the template because my understanding of the sim screens is that they are part of the same page. Buttons generally indicate some kind of function, not a link to other content. Would it help to add the link role to the buttons to indicate that the user is "going" to new content?

Thanks, that makes sense. The problem is that the user ins't really "going" anywhere when they click on a button on the bottom, and there is no meaningful href (not even to another place in the same page). In that case, <a> tags aren't clickable.

One of the goals at this point is to implement with as little change to Scenery as possible, so maybe we should revisit how hierarchical relationships are managed soon, but not now. I think of the PDOM as a well-structured, semantically rich HTML document. Often the simplest way to show relationships is through the natural hierarchy. There are other ways to communicate relationship, but they may be less robust. Let's see how users interpret the bar and the menu with less natural nesting.

Understood, thanks @terracoda. If it becomes a problem, we can certainly investigate further.

A button with the role link is not a good idea. Links and buttons have different key presses and communicate different things to the users. The presence of a link tells the user that they will be taken somewhere, either to another section, page, or site.
@jessegreenberg, can Scenery not put a link in this context?

Understood, thanks! Scenery can do it, but it is a matter of implementation. <button role="link"> would be trivial to implement, while <a href="..."> would take more time. Since there is a difference, I will look into using <a> tags.

[terracoda]

@jessegreenberg, regarding your comment:

The problem is that the user isn't really "going" anywhere when they click on a button on the bottom, and there is no meaningful href (not even to another place in the same page). In that case, tags aren't clickable.

If the user is taken to a new sim screen, how can that be "not really going anywhere"? I assume that each screen has an id. Can Scenery use the screen id for the href? An anchor does indeed need an href to be a clickable link, but the value of the href does not have to be a url. It can be like this:

 <nav aria-label="Sim Screens">
    <ul>
        <li><a href="#screen-01"><span class="visually-hidden">Current screen:</span> Screen 1</a></li>
        <li><a href="#screen-02">Screen 2</a></li>
        <li><a href="#sreen-home">home</a></li>
    </ul>
</nav>

[jessegreenberg]

If the user is taken to a new sim screen, how can that be "not really going anywhere"

All the screen buttons at the bottom really do is toggle graphical visibility of the active screen. Screens don't have an id to point to with an href. The user is choosing to view new content, so I see how a link makes semantic sense. Would href="#" work?

[terracoda]

@jessegreenberg, a button can make hidden content visible. For example, the accordion design pattern does this. There are accordion designs that only allow one accordion to be open at a time. It is then our responsibility to communicate the states of the accordions to the user. It's possible the accordion design pattern could work or the screens. I was even considering this, yesterday.

Browser/AT implementation of aria-controls, however, currently does not work as it should. See Pickerings article, ARIA_Controls is Poop.

We will have to make sure we can communicate the states of the accordions and their relationships to the sim screens clearly.

[terracoda]

@jessegreenberg, I am having trouble with a design pattern for the bottom bar. I think we need to answer the question, What is the bottom bar?

Working on some pros and cons based on comments from the W3C ARIA 1.1 Specification

Navigation?

• Pros: provides a landmark for easy navigation, possible useful role for sim screen navigation, can be anywhere on the page.
• Cons: the items in the bar itself do not function like a normal navigation items. For example, in a single-screen sim there are no items that are like navigation items.

Footer?

• Pros: provides a landmark for easy navigation, usually at the bottom (for main footer anyways) so might indicate the end of the page, aria-label can add a meaningful name/label to clarify role.
• Cons: role may be confusing to users. A clear label may help communicate the role of the footer for sim use, but it may not, users may skip info in a footer.

Menu Role?

• Pros: "offers a list of choices to the user, such as a set of actions or functions", usually opened with a menu button (possible good choice for PhET Menu)
• Cons: not usually persistent.
  Related Note:

A common convention for indicating that a menu item launches a dialog box is to append "…" (ellipsis) to the menu item label, e.g., "Save as …".

Menubar Role?
Similar to role menu

• Pros: used for a persistent menu, usually horizontal, offers quick access to common set of commands, often contain sub menus that pop-up or drop-down
• Cons: normally at top of application.

Toolbar Role?

• Pros: collection of commonly used function buttons or controls, compact form, have an implicit horizontal orientation, group container is not focusable.
• Cons: often a subset of functions found in a menubar

It is looking like a menubar, this far to me.

[jessegreenberg]

Thanks for listing these out @terracoda, that really helps guide things! I agree that Menubar makes a lot of sense. I also like Footer based on its Pros and Cons.

[terracoda]

Also, I read about the region role, but forgot to put that solution idea in the pros and cons post above (#25 (comment)).

Another consideration on menu/menubar role

The menu role is appropriate when a list of menu items is presented in a manner similar to a menu on a desktop application.

@jessegreenberg, please correct me if I am wrong, but I think the bottom bar does exhibit desktop-like behaviour.

How do these stripped down examples for a single screen sim look:

Footer with un-ordered list containing buttons

<footer aria-label="Sim Resources and Tools">
<!-- Could also use menubar and menu item roles in the list inside the footer, if that is valid. Need to check. -->
<ul>
<li>
    <button aria-haspopup="true">Keyboard Shortcuts</button>
    <p role="tooltip">Tips on how to use this sim with a keyboard.</p>
</li>
<li>
    <button id="phet-menu-button" aria-haspopup="true">PhET Menu</button>
    <p role="tooltip">Tools and links for this sim.</p>
</li>
</ul>
</footer>
<!-- PhET Menu items dynamically placed into PDOM. -->
<ul role="menu" aria-labelledby="phet-menu-button" hidden>
<!-- When menu is open, focus is placed on first item. -->
    <li role="menuitem"><button>View Options</button></li> 
    <!-- Rest of the Phet Menu Items -->
</ul>

Div with region role, label, and menubar

<div role="region" aria-label="Sim Resources and Tools">
<ul role="menubar">
<li role="menuitem">
    <button  aria-haspopup="true">Keyboard Shortcuts</button>
    <p role="tooltip">Tips on how to use this sim with a keyboard.</p>
</li>
<li role="menuitem">
    <button id="phet-menu-button" aria-haspopup="true">PhET Menu</button>
    <p role="tooltip">Tools and links for this sim.</p>
</li>
</ul>
</footer>
<!-- PhET Menu items dynamically placed into PDOM. -->
<!-- Same as above -->

General Notes

• The on-demand help text may not be needed; however, it does provide context for users who need it (and read it).
• The use of aria-controls to create a relationship between the PhET Menu button and the actual PhET Menu does not currently provide much help for AT users (see a11y semantics for PhET navigation bar #25 (comment)). Proximity of the menu may be more useful, but not currently possible in Scenery. Perhaps aria-owns can be used? I need to read the spec more for aria-owns.
• Also, note that a couple of the PhET Menu items might actually be checkboxes.

[terracoda]

@jessegreenberg, there's a mistake in the same code above. The role menuitem has to go on the actual item, not the parent li according to the Navigation Menu Button example which actually has anchor tags inside the list items.

Since we have buttons and links inside the li, the code should be like this:
Div with region role, label, and menubar

<div role="region" aria-label="Sim Resources and Tools">
<ul role="menubar">
<li>
    <button role="menuitem" aria-haspopup="true">Keyboard Shortcuts</button>
    <p role="tooltip">Tips on how to use this sim with a keyboard.</p>
</li>
<li>
    <button id="phet-menu-button" role="menuitem" aria-haspopup="true">PhET Menu</button>
    <p role="tooltip">Tools and links for this sim.</p>
</li>
</ul>
</div>
<!-- PhET Menu items dynamically placed into PDOM. -->
<ul role="menu" aria-labelledby="phet-menu-button" hidden>
<!-- When menu is open, focus is placed on first item. -->
    <li><button role="menuitem">View Options</button></li> 
    <!-- Rest of the Phet Menu Items -->
</ul>

[terracoda]

@jessegreenberg, I did some further digging and found this comment from the ARIA Practices repo (w3c/aria-practices#13 (comment)).

I have a feeling that the sim's bottom bar is too essential, more akin to primary site navigation, to be using the role menubar, maybe we should go back to role navigation, and simple lists with clear labels. The PhET Menu still seems to be a good fit for a menu button. I'll look again Heydon Pickering's example again.

What a design-code circle? I can't believe how complicated this has been :-) Maybe that's why Pickering wrote a whole chapter on the Menu Button design pattern!

[terracoda]

@jessegreenberg, how does the following code and keyboard pattern look to you?
Will it fit currently with Scenery? Do you think it will help users find the bar easily and use the PhET Menu button easily.
Stripped-down Code

<div>
<ul role="navigation" aria-label="Sim Resources and Tools">
  <li>
    <button aria-haspopup="true">Keyboard Shortcuts</button>
    <p>Tips on how to use this sim with a keyboard.</p>
  </li>
  <li>
    <button id="phet-menu-button" aria-haspopup="true">PhET Menu</button>
    <p>Tools and links for this sim.</p>
  </li>
</ul>
</div>
<!-- PhET Menu items dynamically placed into PDOM. -->
<ul role="menu" aria-labelledby="phet-menu-button" hidden>
  <li><button role="menuitem">View Options</button></li> 
    <!-- Rest of the Phet Menu Items -->
</ul>

Keyboard Design Pattern

1. Navigation landmark accessible to AT users by their landmark navigation hot key.
2. Top-level buttons are part of the page's tabindex order, but I think they will be clearly identified as being part of the navigation region, "Sim Resources and Tools". AT vary, but usually landmark information is read out upon entering and exiting the landmark region.
3. Tab key moves keyboard focus forward from the first button to the second (in the navigation list), then to next focusable item, the browser bar.
4. Shift Tab goes from second button to first button, then back into the sim on to the last focusable sim item, the Reset All button.
5. Enter or Space key on the Keyboard Shortcuts button open the Dialog.
6. Enter or Space key on the PhET Menu button opens the list of PhET Menu items.

In the popped-up menu

7. Initial focus is set on the first item.
8. Up and Down Arrow keys are used for navigating the items and move visual keyboard focus to next menu item and cycle through last item to first item, so users can re-read the items without closing the menu.
9. The Tab key closes the popped-up menu and goes to the next focusable item (i.e., browser bar). Shift Tab closes the menu and goes to the previous focusable item (i.e., the Keyboard Shortcuts button).
   Adding item 10.
10. ESC key closes the popped-up menu and returns focus to last focused item, the PhET Menu button.

The Left and Right Arrow keys
I need to double check how these should work.

[terracoda]

@jessegreenberg, also I don't think navigation landmarks receive visual keyboard focus. The landmark information is just read out when the first at last items inside the landmark get focus.

[jessegreenberg]

Yes, that looks great to me @terracoda! Also, i just figured out that the aria role=none needs to be on the li items in the menu, or else focus doesn't work correctly in JAWS.

Discovered in the link you posted: https://www.w3.org/TR/wai-aria-practices-1.1/examples/menu-button/menu-button-2/menu-button-2.html, thank you!

But another problem, is that JAWS won't read any of the semantic information about the buttons/links in the menu - just its label content. Do have any ideas for how to get around this?

[jessegreenberg]

But another problem, is that JAWS won't read any of the semantic information about the buttons/links in the menu - just its label content.

Actually, VO is doing the same now, presumably because we added none to the list item parent?

[terracoda]

@jessegreenberg, I also noticed role=none, sorry I thought I shared that info :-) I'll have to investigate why the semantics are lost.

[terracoda]

@jessegreenberg, I do hear that it is a menu in VO, just don't hear about buttons and links.

[terracoda]

Posting an article by Adrian Roselli on ARIA menus that I need to review in more detail
http://adrianroselli.com/2017/10/dont-use-aria-menu-roles-for-site-nav.html

[terracoda]

@jessegreenberg, based on our decision in the keyboard nav meeting (March 6th) to re-organize the bottom bar into two things for multi-screen sims:

1. a navigation region for sim screen buttons
2. a "Sim Resources" region for the actual bottom
   I am going to close this issue, and start a new one that references this one.

See also RIAW for first example of "Sim Resources" phetsims/resistance-in-a-wire#136 (comment).