structure and semantics updates?

shawna-slh commented 2 years ago

Let's review structure and semantics in the templates, tools, and pages. For example:

Banners/Headers

[ ] Should the top part with the logos be marked <banner> or <header>?
- [ ] Is that implemented consistently in the main site, the report tools, the listings, the minimal-headers /standalone-resources?
[ ] Is <header> used where it should not be? e.g., is <header> not good within the <aside> for Page Contents, and it should have an h2 or other instead?

Asides

[ ] Some HTML elements have implicit ARIA roles — e.g., HTML <aside> and ARIA complementary. Are we using them in ways that work well for ARIA?
[ ] Are <aside>s used where they should not be? (Asides are for "content that is tangentially related... and which could be considered separate from that content". HTML spec)
e.g., is <aside> not good for "Rule Mapping" in Rules because it is essential content. Is it not good for the Page Contents box, because that is neither tangential or separate?

Navigation

[ ] Are the navigation areas appropriately marked up? Including:
- [ ] Main navigation (along the top)
- [ ] Secondary navigation (along the left)
- [ ] Page Contents (inline for main WAI site, float right for most minimal-header pages)

ARIA

[ ] Are we providing landmarks and labels as we would like to?

More info below.

shawna-slh commented 2 years ago

from @mcking65 https://github.com/w3c/wai-aria-practices/issues/24#issuecomment-1115084048:

Currently, the page table of contents links are inside of a region with role complementary. The role should be navigation, not complementary. I didn't inspect, but I am assuming this might be because an aside element was used and the role was not [explicitly] set.

shawna-slh commented 2 years ago

fyi, @SteveALee --- not sure when we can get to this...

shawna-slh commented 2 years ago

from @matt

I hope this can be rectified in the template rather than having to mod the content of all WAI pages that have this problem because there are many. On many pages, there are complementary landmarks inside of main. Main should not contain complementary elements. By definition of something complements main, it is not part of main. While that is the technical reason to fix the issue, the practical reason is that having too many landmark regions reduces, or in extreme cases eliminates, the value of the landmark regions.

The complementary regions are a side effect of using the aside element. I think there was a decision at some point to have browsers avoid mapping aside elements inside of main as landmark regions, so there may also be a browser bug at play here as well.

Nonetheless, in my reading of the aside specification, it seems like the content inside the aside elements is not conforming to the spec. The spec says the aside content is to be tangential to the main content. The content I perceive to be included in the aside elements is the core content of main. One exception might be the page summary, which is something like a pull quote. In that case, aside could potentially fit. However, it would be helpful to screen reader users if the aside then had role="none" to ensure it is not mapped as a landmark region.

The spec for aside:

The aside element represents a section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content. Such sections are often represented as sidebars in printed typography.

The element can be used for typographical effects like pull quotes or sidebars, for advertising, for groups of nav elements, and for other content that is considered separate from the main content of the page.

Note It's not appropriate to use the aside element just for parentheticals, since those are part of the main flow of the document.

Here is an example from [Planning Audio and Video Media](https://www.w3.org/WAI/media/av/planning/() where the aside should be changed to asection or div. Note that if section is used, it is essential that it not have an accessible name (aria-label) or it will be mapped as a landmark region.

<aside class="box box-highlighted" id="checklist-ap"><header class="box-h  box-h-highlighted"> 
<img src="/WAI/content-images/wai-media-guide/recorded.svg" alt="" style="height:1em"> Pre-Recorded Audio-only
</header><div class="box-i">

<ul class="alt">
  <li><strong><a href="/WAI/media/av/transcripts/">Transcript</a> (A)</strong> separate from the audio</li>
  <li><strong><a href="/WAI/media/av/captions/">Captions</a></strong> synchronized with the audio</li>
  <li><strong><a href="/WAI/media/av/sign-languages/">Sign language(s)</a></strong></li>
</ul>

</div></aside>

shawna-slh commented 2 years ago

Related issue: where in H1 for standalone-resource__type-of-guidance ? https://github.com/w3c/wai-minimal-header-design/issues/99 (including https://github.com/w3c/wai-minimal-header-design/issues/99#issuecomment-1156955979)

shawna-slh commented 2 years ago

In Curricula it's included in the h1:

<header class="in-resource">
  <h1> Foundation Modules <span class="in-resource-sub"> in <a lang="en" href="/WAI/curricula/"><span>Curricula on Web Accessibility: A Framework to Build Your Own Courses</span></a></span> </h1>
</header>

Also in media resource it's in the h1:

<header class="in-resource">
<h1> <img src="/WAI/content-images/wai-media-guide/body.svg" alt="" class="title-image right" style="height: 2em;"> User Experiences and Benefits to Organizations </h1>

In Stories of Web Users it's currently not in h1:

<header class="in-resource">
  <h1> Stories of Web Users </h1>
  <p>in <a lang="en" href="/WAI/people-use-web/"><span>How People with Disabilities Use the Web</span></a></p>
</header>

w3c / wai-website