w3c / wai-aria-practices

WAI Website Resource for aria-practices guidelines

WAI-ARIA Authoring Practices

This repository contains the source code for the ARIA Authoring Practices Guide which is hosted as part of the Web Accessibility Initiative website.

The WAI website is built in Jekyll and brings together several git submodules into one website.

This project implements a pipeline to convert the aria-practices repository (which is currently a single static HTML file served by gh-pages which has been formatted and post-processed with ReSpec) into a multi-page static website to be served as a standalone resource on the wai-website.

Local development

• Ensure Ruby and Node (v14 or greater) are installed.
• Clone this repo: git clone [email protected]:w3c/wai-aria-practices.git
• Initialize or update submodules: git submodule update --init --recursive
• Install Jekyll: bundle install.
• Install npm dependencies: npm install -C scripts/pre-build
• Run the pre-build script: node ./scripts/pre-build
• Run Jekyll: bundle exec jekyll serve -w --livereload. (-w --livereload doesn't work on native Windows, OK in WSL)
• View the webpage at http://localhost:4000/WAI/ARIA/apg/

Netlify CD status

wai-aria-practices's Issues

Skip to Content menu Mockups

Skip to content menu - Text-based and visual Mockups

These mockups present an always-visible "Skip to Content" button located on the upper left side of the site; right before what would be considered the website's "logo".

When the button is clicked or focused a menu gets displayed. This "Skip to Content" button and menu look like this:

"Skip to Content" menu - Collapsed

When the "Skip to Content" menu is in its default state, meaning is collapsed, the "Skip to Content" button looks very similar to what a clothing tag would look like. It is aligned to the top of the page, it has a white background, 3px rounded corners on the bottom, and a subtle shadow effect to make it pop a little bit from the W3C blue background from the header of the page.

Inside this button, there's an icon in W3C blue that combines the "skip" and "content" icons. This new icon attempts to represent "Skip to Content". The icon is comprised of a triangle pointing down simulating an arrow, followed by 3 lines underneath that look like a "hamburger menu".

"Skip to Content" menu - Expanded

When the "Skip to Content" button gets clicked or focused, a menu containing all the navigation options on the page gets displayed and the "Skip to Content" button is attached to the bottom of the menu. The "Skip to Content" button's icon changes and the triangle that simulates an arrow points up; the three lines that look like a "hamburger menu" underneath the triangle remain the same.

cc @a11ydoer @jongund @mcking65 @shawna-slh

Adjust banner to include title and subtitle consistent with WAI minimal design template

e.g.:

1. name (ARIA Authoring Practices)

What are pros and cons of "ARIA Authoring Practices" vs "ARIA Authoring Practices Guide"?

2. tagline

Brief explanatory phrase with important point (e.g., Supplemental Guidance includes “not required to meet WCAG”, Rules has "For developers of evaluation tools and test methodologies" to clarify that it's probably too much for others)

Consider a short phrase that would:

• provide context for people who land here from a search engine and don't know about ARIA, &/or
• clarify an important point, &/or
• address a common misunderstanding
• provide expansion of "ARIA"

<joking>maybe "No ARIA is better than bad ARIA" ;-)

3. link to About page (About ARIA Authoring Practices)

Note EOWG can help with ideas on 1 and 2 if useful. (@iadawn probably has ideas)

code

https://wai-website-theme.netlify.app/writing/standalone-resources/#header-name-of-set-of-resources-and-tagline

standalone_resource_header:
  title: ARIA Authoring Practices
  subtitle: @@ to be determined @@

standalone_resource_header:
  link:
    ref: /@@/about/
    title: About ARIA Authoring Practices

Include string in 2nd segment of HTML title tag to indicate page is part of APG

straw proposal:

text-of-h1 | ARIA Authoring | WAI | W3C

Change H1 container from `header` to `div` to avoid undesirable landmark

H1 elements are contained in a header element, e.g.:

        <header>
            <h1>
              Combobox
            </h1>
        </header>

Gecko and Webkit are mapping the header to a ARIA banner, creating a useless landmark region that creates excess screen reader verbosity. I think this may be a browser bug, but not one that is likely to be resolved soon. The work around is trivial. The best solution is to change the header element to a ``divelement. Alternatively, we can addrole="none"` to the header element.

ARIA APG in WAI design

The WAI “minimal header” design is based on user task analysis, several iterations, and informal usability testing. This design is/will be used for:

• Understanding WCAG
• WCAG Techniques
• WCAG 2 Test Rules
• Supplemental Guidance to WCAG 2
• ARIA Authoring Practices Guide (APG)
• and a related design is used in WCAG-EM Report Tool and ATAG Report Tool.

It would be good for ARIA APG redesign to follow the same UI, except where there are compelling reason not to.

The following issues address aspects of the differences between the existing “minimal header” design and a draft/prototype of ARIA APG:

• Navigation first page #34
• Sections, Navigation #35
• About page content #33
• header — For people who land on a page (e.g., from a search engine) and don’t know what they’re looking at, the header includes a short phrase to explain what it is, and a link to “About…”

Need clarification of publication process

Build and publication

CC @shawna-slh FYI

The build of this resource appears to be two step

• prebuild shell script to generate the examples
• jekyll SSG build

What is the correct workflow for updates publication?

My expectations are:

• Jekyll source files are updated
• and /or examples are updated and regenerated
• preview using local dev or netlify PR preview
• check with Shawn/Steve that is good time to publish
• commit and push to main
• Shawn publishes

Explicitly, the publish only grabs what is in main - does not run the pre-build script

Netlify build config

Currently the Netlify build calls build.sh but this now simply duplicates code already run. Can this be removed thus making the netlify build consistent with all other resources?

JAWS, VoiceOver, and Narrator do not work correctly when accessing links in cards on APG Patterns and Fundamentals pages when using Chrome, Edge, or Safari

The links contained in h2 elements in the cards on the Patterns
and Fundamentals
pages exhibit some severely buggy behavior when using JAWS, Narrator, or VoiceOver in Chrome, Edge, or Safari. The behaviors are slightly different for each screen reader. NVDA is not impacted. And similar problems are not observable with JAWS or Narrator in Firefox.

I don't see any reason for the problems in the HTML; it looks perfect:

        <li class="tile tile-accordion">
                <h2 class="tile-name">
                  <a href="/patterns/accordion/">
                    <img src="/assets/img/accordion.svg" alt="">
                    <span>Accordion (Sections With Show/Hide Functionality)</span>
                  </a>
                </h2>
                <div class="tile-introduction">
        An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content.</div>
              </li>

Perhaps the buggy behaviors are related to the CSS???

Note that links contained inside headings on other sites work correctly; the problems do not appear to be caused by the link being wrapped by a heading.

JAWS Behavior in Chrome and Edge

Open the patterns page. With the virtual cursor active, use down arrow or 'h' to navigate to the heading for a card and press enter to activate the link contained in the heading.

Expected behavior: The target page is opened.

Actual behavior: JAWS repeats the name of the link and nothing else happens; the link is not activated. Users may think the link is broken.

Note: there are 3 ways to get around the problem: 1) press enter a second time. 2) use Tab to navigate to the link instead of using virtual cursor reading keys. 3) use the JAWS list of links to choose and activate the link.

Narrator behavior in Edge and Chrome

Open the patterns page. With Narrator scan mode on (capslock+s),
use down arrow or 'h' to navigate to the heading for a card and press enter to activate the link contained in the heading.

Expected behavior: The target page is opened.

Actual behaviors:

• When navigating with "h", Narrator announces "command not available" before reading the heading.
• After pressing enter, a portion of the title tag is announced, and focus seems to be set to the body; pressing insert+tab after pressing enter indicates the focus is on the body.

VoiceOver behavior in Chrome and Safari

Open the patterns page.
Reading with ctrl-opt-right, navigate to the second H2. Continue using ctrl-opt-right to navigate by element and navigate through several cards.

Expected behavior: The content of an h2 element is announced when the VO reading cursor is on an h2 element.

Actual behavior: Instead of reading the heading content, VO says "dimmed", e.g., VO announces "Heading 2, dimmed, 3 of 29"

Design element for highlighting and linking to Read This First Section

After the H1 and above the cards on the Fundamentals and Design Patterns and Widgets pages, display an element that will draw the user's attention to the following link and text:

Read This First
No ARIA is better than Bad ARIA. Before using any ARIA, it is essential to understand why.

Include a visual element, icon or symbol, that accompanies this link and text to help call attention to it.

Fundamentals: Structural roles section missing

The fundamentals page is missing the structural roles section.

The first sentence is not a very good short description. I will make some editorial changes to the heading and first sentence in the main document so it will be a better editorial fit.

Update links to use W3C styling

Off W3C site, use this icon: https://wai-website-theme.netlify.app/components/icons/#external-link

Within W3C site, use this icon: https://wai-website-theme.netlify.app/components/icons/#different-view

Sections, Navigation

Background is in other issues.

Ideas:

1. All (h1:All ARIA Authoring Guidance) [see https://github.com//issues/34]
2. Patterns and Widgets (h1: Design Patterns and Widgets)
3. Examples Index [it is lists of Examples. include “Index” for those familiar with previous /TR/ doc]
4. General [or something other than fundamentals]
5. Current Work [or maybe “Updates and Contributing” or “Get Involved” ?]

Question: Is everything users might want from the /TR/ doc included in this redesign? What about 10. Roles That Automatically Hide Semantics by Making Their Descendants Presentational and 11. Structural Roles ?

Create page footers for example pages

Most WAI pages have a page footer in additional to the site-wide footer. It is used for info like updated date and acknowledgements.

• template
• example Rules footer

Maybe put this for after launch?

Review features that are not in the wai-website-theme

This is resource uses quite a few custom features - e.g., cards.

It would be good to review these and see if we want these added to WAI website theme - so if they are used elsewhere, they are consistent.

That may also improve site efficiency by including any custom inline CSS and JS in site optimisations.

Move table of contents sidebar to right of body content, fix title, and change role to navigation

There is currently a table of contents sidebar on the Pattern, Fundamental, Example, and Index pages.

The sidebar should be moved to the right side of the content (maintaining its current location in the DOM) to match the redesigned supplemental material template: example here, source here.

For the Example page, the miscellaneous links under the table of contents (in yellow box) should be removed. "Report Issue" and "Related Issues" are superseded by the "Help us improve this page" section. The "Browser and Assistive Technology Support" link is no longer necessary.

To-do list for this issue

The following to-do items are all described in more detail in comments below.

• Remove "Report Issue" and "Related Issues" links from yellow box in page contents section. They will be added to the the new page footer as part of #32 .
• Remove the related links link from the yellow box in the page contents section; it will be added to footer as part of issue #32.
• Remove the "Browser and Assistive Technology Support" link from the yellow box in page contents section; it is not necessary because it is included in the disclosure that follows the H1.
• Change DOM location of page contents to be before and outside main
• Set role of page contents region to "navigation" (this should be done in template)
• Set name of navigation region to "Page Contents" (e.g., aria-label="Page Contents")
• Change title from "Table of Contents" to "Page Contents"
• Ensure title remains H2 (best to enforce in template)

Edited: "Related Issues" should be moved to footer instead of "Help us improve this page", see new issue linked above

Move "Read me first" content from "About" page to its own page within fundamentals section

The content from the section Read me first needs to have its own fundamentals page that is a sibling of the sections for landmarks and accessible names. It is currently buried in the "About" page; it should be removed from there.

Per suggestion from @shawna-slh, change the title to "Read This First".

List it first on the fundamentals page.

Also List it first on the patterns and widgets page.

We will also need to find a good spot for it on the home page, perhaps as the first resource.

Name top-level navigation region "APG"

Currently the top-level navigation region that includes links for Home, Patterns and Widgets, etc., is named "Context for this document". That is not a suitable name.

The most effective name for a navigation region is a simple, clear, and brief string that tells the user what using the elements inside the navigation region will navigate. So, for example, the top-level navigation in the APG is navigating across all of APG. So, an ideal name is "APG". I think the acronym is better here because brevity in the landmark region that you use most often is especially valueable. This will only work if we have APG expanded elsewhere, like in the banner.

Adjust primary navigation to remove "fundamentals" conflict and improve link/title consistency

The goal of this issue is to resolve two problems with the primary navigation which includes links named Home, patterns and widgets, fundamentals, Index, and About.

Problem 1: The first link violates a primary principle of accessible navigation -- consistency in meaning between the text of a link and the title of the page targeted by the link. The first page is titled "Get empowered to create accessible rich internet applications" and the text of the first link is "Home". That title and link text are not sufficiently consistent in meaning.

Problem 2: As @shawna-slh pointed out in #34, the name "fundamentals" in the APG IA could eventually cause some confusion between APG and a similarly named section in the WAI site. While risk and impact is likely fairly low, it is something we can avoid altogether by choosing a different word.

Solution to Title/link name inconsistency

• Change the H1 title on the home page to "ARIA Authoring Practices Guide Home".
• Change text of first link in navigation to "APG Home"

Solution to conflict with WAI use of term "Fundamentals"

• Change title in H1 of the Fundamentals page to "Practices"
• Change link text in navigation to "Practices"

Multiple people, including most recently @richnoah, have suggested "practices" as an alternative to "Fundamentals". I originally dismissed this suggestion with the response that the entire site is "practices". But, after considerable thought, I think that is not necessarily the case. In addition to the fundamentals content, the other two primary elements of the guide are patterns, which are essentially abstract implementation of practices, and examples, which are the concrete implementation of practices. In other words, it is quite useful to think of the primary elements of the guide as patterns and examples that are based on practices.

Thinking of the IA this way, it is probably also to go a step further with the simplification and reduce "Patterns and Widgets" to "Patterns". On the patterns page, we regard every section as a pattern, regardless of whether that pattern is for an interactive widget or something else, e.g., an alert or table. We do not specifically name some of them as patterns and some as widgets. In fact, most of them are patterns for a widget. We do a good job in multiple places of helping people understand that.

So, I'd like to also suggest two more changes for this issue:

• Change title in H1 of the Patterns and Widgets page to "Patterns"
• Change link text in navigation from "Patterns and Widgets" to "Patterns"

Set URI for APG in w3.org site config

suggestion is to use /WAI/ARIA/practices/ any thoughts?

Fix broken links in important usage notes disclosure on example pages

Depends on #48

At the start of the "About This Example" section on every example page is a disclosure named "Important Note About Use of This Example".

That disclosure contains multiple links to content in the Read This First content referenced in #48. All those links are broken.

Update "Help Improve this Section" to point to APG email

"Help Improve this Section" should use the [email protected] rather than [email protected].

For now we will postpone the larger improvements in issue #25.

Edit: fixed email above per @shawna-slh’s correction below

Develop new approach to documenting and maintaining information about editors and acknowledgements

At launch of wai/aria/apg on May 19, 2022, we are extracting information about current editors, past editors, and acknowledgements from the old aria-practices.html respec doc. This doc pulled some information from aria-common.

• Where do we want to maintain such information?
• Should the APG rely on an external source for some of the information?
• To what extent should we maintain acknowledgements about major contributions to past versions?
• What information should be included in every page footer?

Some of the guiding principles the TF has used in the past:

• Author names are not included in source comments because all source is a work of the entire TF, there are often multiple authors over time, and it is difficult to ensure such information is accurate.
• Similarly, the TF strives to convey that the APG is developed with the broader accessibility community.
• At the same time, the APG TF understands it is important to provide appropriate individual recognition for contributions
  Related: #87

Top navigation: aria-current not set when index is loaded

When links in the to nav are activated, aria-current="page" is getting correctly set in all cases except when index is activated.

To repro:

1. Activate the patterns link in the top nav
2. Inspect an observe that aria-current is set on the patterns link.
3. Activate index in the nav
4. Inspect and observe that aria-current is correctly removed from patterns but is not set on the index link

Fixing this before launch would be good but is not required.

Remove obsolete content from About page and move list of editors under acknowledgements

Before launch, we need to simplify the about page to make it more useful to new-comers and remove content that is obsolete due to APG no longer being a TR document.

Needed changes to about.md:

• Remove dt/dd elements containing version links for this version, latest published, latest, editors draft
• Remove dt/dd elements containing links to TR history and Git Commit History
• Move editors and former editors to a subsection titled "Editors under acknowledgements
• Remove dd/dt elements containing feedback information
• Remove section with id=abstract
• Complete #48 to remove the sections with headings of No ARIA is better than Bad ARIA, Browser, and Assistive Technology Support, and Mobile and Touch Support.
• Remove section for "Status of this Document" that starts on line 179

The result should be an about page with 4 sections with the following titles in H2 elements:

1. Introduction
2. Change History
3. Acknowledgements
4. References

This text file about.html.txt
contains HTML that represents the desired resulting structure.
Note that it is just the structure containing the current content, including movement of editors and former editors into an acknowledgements subsection. It is otherwise not the specific desired content. I am making edits to the introduction and change history in the main aria-practices.html file.

provide list alternative to cards

Where there are cards (Patterns and Widgets, Fundamentals), provide an option to get a list view. Make it persistent.

Rationale: For some users, the card view is very difficult to deal with, including many users with low vision.

Local build broken libatk-1.0.so

Trying to local build I get the following error. looks like an unmet dep on libatk-1.0.so. I'm using WSL Ubuntu on Windows so that is possible.

Also I have respec installed but you script does a very simple test for existence, not a version and I probably have an old version.

$ ./scripts/build.sh
/home/wsl/.nvm/versions/node/v16.14.2/bin/respec
[FATAL] Error: Failed to launch the browser process!
/home/wsl/.nvm/versions/node/v16.14.2/lib/node_modules/respec/node_modules/puppeteer/.local-chromium/linux-982053/chrome-linux/chrome: error while loading shared libraries: libatk-1.0.so.0: cannot open shared object file: No such file or directory


TROUBLESHOOTING: https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md

    at onClose (/home/wsl/.nvm/versions/node/v16.14.2/lib/node_modules/respec/node_modules/puppeteer/lib/cjs/puppeteer/node/BrowserRunner.js:241:20)
    at Interface.<anonymous> (/home/wsl/.nvm/versions/node/v16.14.2/lib/node_modules/respec/node_modules/puppeteer/lib/cjs/puppeteer/node/BrowserRunner.js:231:68)
    at Interface.emit (node:events:538:35)
    at Interface.close (node:readline:586:8)
    at Socket.onend (node:readline:277:10)
    at Socket.emit (node:events:538:35)
    at endReadableNT (node:internal/streams/readable:1345:12)
    at processTicksAndRejections (node:internal/process/task_queues:83:21)

The suggested https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md is no help at all

Home page builder retains deleted content and semantics

This is important for launch.

When the w3c/aria-practices/index.html file
is processed to build the content/index.md file , it is including deleted content and re-arranging content. I may be trying to have it do something it was not designed to do, however the fallback in this scenario is itself concerning me, especially keeping content that was deleted. I'll describe the two issues I have noticed related to keeping deleted content and deleted semantics. Then, I'll describe the end goal I am hoping to achieve.

Incorrectly retained deleted content

In APG pull 2309,
I removed lines 37-40 from the index.html file. Yet, after the PR was merged and the APG site was built and other changes in that PR are rendered, the content from those lines is still on lines 49-53 in
content/index.md:

49        <p>
50            Learn how to make common rich internet application patterns and
51            widgets accessible by applying WAI-ARIA roles, states and
52            properties, and implementing keyboard support.
53          </p>

Retained deleted semantics

In APG PR 2312,
I changed the H3 on line 35 to a paragraph. However, the H3 remains on line 48 of
content/index.md.
Since I didn't specify content for that H3, the code duplicated the content from the subsequent H3.

47        <h2>APG Resources</h2>
48        <h3>Design Patterns and Widgets</h3>
49        <p>Building blocks that help you make the web accessible</p>

What I'd like to get

The design has an H2 that titles each section of cards, e.g., <h2>APG Resources</h2>.
That H2 is followed by 2 elements of content before the first card, an H3, and a paragraph.
Because each card is an H3, this creates a confusing experience for a screen reader user.
The content in the paragraph is not really adding value, so I'd like to have only one content element after the section title. That element would be a short paragraph. For example, the desired rendering for the APG resources section is:

<h2>APG Resources</h2>
<p>Building blocks that help you make the web accessible</p>

That would then be followed by the H3 for the first card.

I'd like to have this reduced format for all sections after APG resources as well.

Fix assets and image location and references [Required for launch]

CC @shawna-slh

All static assets must be updated due to the limitations of Jekyll and the requirements to link to them in the integrated wai-website repo for publication.

What you need to do is:

• move assets to {projectroot}/content-assets/wai-aria-practices/ - eg see ACT rules assets
• Edit all assets references to be of the form `{{ @@@="/content-assets/wai-aria-practices/styles.css"}}

Likewise for the SVG files in 'content/assets' use {projectroot}/content-images/wai-aria-practices/ - you should rename the incorrect {projectroot}/content-images/wai-website-theme/

Hide extraneous "Skip to main" link

We currently have 2 "Skip to main" links. One is from APG, the other is injected from the Supplemental Resource parent template.

We should hide the one from the parent template so that only one "Skip to main" link is present.

(In a future issue, we will mitigate the root issue by working to improve the parent "Skip to main" link from the parent template.)

About page content

In the WAI “minimal header” design, the About page is designed primarily for new users. We think most people who have a sense of what ARIA Authoring Practices are not follow the “About” link.

The About page briefly explains the specific resource suite (that is, Supplemental Guidance or Authoring Practices). It does not cover parent information and instead links to it elsewhere, to avoid overlapping info. This is a principle that the WAI website follows to limit user confusion and to simplify maintenance.

For example, notice About Supplemental Guidance has one sentence of what WCAG is, then links to the WCAG Overview. Then one sentence about the additional resources, then links to the WCAG 2 Documents.

About pages have a brief Summary at the top like the main WAI website.

Some About pages will include Acknowledgements, and that section is collapsed by default.

fyi, When linking to these resources from WAI website pages, we are usually linking to both the About page and the first list/index page. For example:

Cognitive Accessibility Guidance — short design patterns, explained briefly in About Supplemental Guidance

and

• About WCAG 2 Test Rules
• All WCAG 2 Test Rules List

---

**Questions:**

1. Are there compelling reasons to do anything different with the About ARIA Authoring Practices page? -- other than cooler visual design

2. What of the info that’s in the draft now will stay or go elsewhere?

3. Do we want to update anything in the ARIA Overview (other than changing the links to Authoring Practices)?

examples pages should have a date stamp

Folks end up linking to these and it would be helpful to have an indication of when they were published.
Alternatively if there is a more recent version a link to that would be fine too.

Links to landmark examples are broken

Go to the landmarks page:
https://wai-aria-practices2.netlify.app/fundamentals/landmark-regions/

Go to any of the examples sections and follow the link. For example, in complementary, the example points to:
https://wai-aria-practices2.netlify.app/index/landmarks/complementary.html

That page does not exist.

Similarly, go to the index page and follow the link to a landmark page example, and the link is broken there too.

Also, go to the patterns and widgets page, open "landmarks" and then try to get to the examples from there, and the links are broken.

Create new user intro page to link from banner

Related to #28, develop content for an intro page for new users that can be linked from the banner.

Finalize permalinks to match published URIs [Required for Launch]

permalinks for each page

Currently of the form /patterns/carousel/.

Needs to change to @@@/patterns/carousel/ where @@@ is where the resource will appear in the published site. As decided by @shawna-slh

Also need to update netlify.toml to match the @@@ so preview links work correctly

links to other pages

Currently href="{{ site.baseurl }}/patterns/button/"
Needs to be href="{{"/patterns/button/" | relative_url}}"

They might end up being the same but that is the style we use in the WAI site and definitely works correctly

Files in /index [Required for Launch]

This is more a question than something that necessarily needs to be fixed.

Is there a reason the files under /index are not in /content/index? /content is the correct location for all files that are processed by Jeckyll and end up as pages. Unless they are a collection.

But I see you have a mixture of Jekyll processed SSG source files and statically served files. As these are relative URIs I think it should be OK in the main site. Would have been good to have had time to test before launch.

Also I'm seeing an error

ERROR/index/index.htmlexamples/js/jumpto.js' not found.`

This is seems to be saying the error in /index/index.html in is examples/js/jumpto.js not found (missing space)

The only ref to jump.js I find is in the external repo .../aria-practices/examples/js/app.js

Set github.path for all pages [Required for Launch]

eg for about.md

github:
  repository: w3c/aria-practices
  path: content/about.md

APG Redesign

Overview

Given that w3c/aria-practices#2169 has been approved and merged, we'd like to move forward with adding the technical elements required to support the APG's redesign and also enabling it to be a 'resource' of WAI. See WAI Website Manual and specifically WAI Website Manual - Technical Information for more context. We intend to use this repository as a content transformer and to also hold the redesign content as shown at http://wai-aria-practices.s3-website-us-east-1.amazonaws.com.

How deploys will work

The diagram displays that when the production branch for w3c/aria-practices is updated, a wai-trigger-deploy workflow is triggered, which in turn triggers a deploy workflow action on w3c/wai-aria-practices. deploy is responsible for retrieving the latest content from w3c/aria-practices, updating the content files and pushing it back to the repository's production branch, which in turn triggers a Netlify site update.

How pull requests will work

The diagram displays that when a PR is submitted or updated on w3c/aria-practices, the wai-trigger-pr workflow is triggered, which in turn triggers a pr-create workflow action on w3c/wai-aria-practices. This action will create (or update) a generated PR branch on w3c/wai-aria-practices, update the Netlify deploy preview URL, retrieve the Netlify deploy URL preview and update the top comment of the triggering PR from w3c/aria-practices. The diagram also displays that when a PR on w3c/aria-practices is closed (or merged), or the branch is deleted, the related PR and branch is also removed on w3c/wai-aria-practices. This is done by a wai-trigger-cleanup workflow on w3c/aria-practices triggering a remove-branch workflow action on w3c/wai-aria-practices.

Remove redundant headings and fix heading levels on 5 of the fundamentals pages

Five of the fundamental pages (listed below) have the following problems:

1. There is an H2 with content that is a duplicate of the H1 content
2. All the H3 headings should be H2, H4 headings should be H3, etc.

After #24 is resolved, remove the extraneous H2 that duplicates the H1 and promote the level of subsequent headings within the main content.

This problem is unique to the following 5 of the 6 fundamentals pages. It does not occur elsewhere in the site.

1. Landmark Regions
2. Providing Accessible Names and Descriptions
3. Developing a Keyboard Interface
4. Grid and Table Properties
5. Communicating Value and Limits for Range Widgets

Accessible name calculations for separators on example pages are broken by code that is replacing ID attribute values specified in the source

Some code is overriding ID attribute values, causing some accessible labels to break.

For example, look at line 111 in alertdialog.md

          <h2 id="ex_label">Example</h2>

Now, inspect the H2 on the rendered page.
The id has been changed from 'ex_label' to 'example':

<h2 id="example">Example</h2>

This is breaking the label for the separators that mark the boundaries of the example for screen reader users. The first one for the start is on line 113:

        <div role="separator" id="ex_start_sep" aria-labelledby="ex_start_sep ex_label" aria-label="Start of"></div>

If there is a method that needs an ID on an element, and an ID is already present, it doesn't seem like it should replace the existing ID; it should just use the existing one.

Complementary region for help improve this page is missing accessible name

Could be fixed by w3c/wai-minimal-header-design#97

Otherwise, specify aria-label="feedback" on the complementary region containing the "Help Improve This Page" content.

Index page: "About the Index" missing from page contents

On the index page, the page contents is missing a link to the section titled "About the Index".

h1 - optional type

Note that the parent design has a provision for including the type in the h1.

For example: "Propose Test Rule:"

For example: "Cognitive Accessibility Design Pattern:"

With HTML title of:

Make Short Critical Paths | Cognitive Accessibility Design Pattern | WAI | W3C
(related to #31 )

This is optional. Fee free to close this issue.

Home page: links to patterns and practices have incorrect href

The links to the patterns and practices in the body of the home page are not using the new full paths in the href values, so they are failing.

Should we be fixing this in the home page file in the aria-practices repo? Perhaps this issue should be in that repo.

Top-navigation: Move index between practices and about

@isaacdurazo, the "Index" link feels out of place to me. It seems like we should have the two primary sections, patterns and practices, juxtaposed. What do you think of moving Index between practices and about?

Consider how I have described the APG structure in the new Introduction section:

The APG is organized into two major sections: patterns and practices. Each pattern explains how to make a common user interface element, such as a button, menu, or dialog, accessible, and provides functional example implementations of the pattern. The practices section gives in-depth explanation of how to satisfy a variety of accessibility needs that surface when making rich internet application experiences accessible. For instance, the practices section on providing accessible names and descriptions gives detailed descriptions of seven different naming techniques as well as a table providing guidance for naming more than 80 types of elements.

Also consider that the index page will eventually cover all content, not just examples.

Originally posted by @mcking65 in #60 (comment)

Example pages and Index page: remove extraneous broken link and navigation region from end of main content

On the index page, and on all example pages,
there is a nav element at the end of the main content containing a single link
named "WAI-ARIA Authoring Practices 1.2".

The link is broken, and because it is in a nav element, it is prominent for screen reader users. We need to remove the nav element and link. I think we should do this before launch.

The question is whether to filter it out during build or remove it from the roughly 60 pages that contain it in the aria-practices source repo. Eventually we definitely need to remove it from the source. Should we bite the bullet and do that now? Or add some filtering code to the build?

Differences in APG navigation and information architecture when compared to WAI minimal template

The WAI “minimal header” design is optimized for repeat users, many of whom use these resources frequently. The first link in the navigation is to the list of contents in the resource. It is the page most users will use, most of the time. For example: All Supplemental Guidance

A few observations:

• The current draft prototype has no way to get a list of all of the content.
• From Sept usability testing: “When asked to find some examples of Landmark roles, people would generally look under fundamentals last.”
• From Sept usability testing: “Almost half of the participants considered we should re-think the order of the navigation elements and have Fundamentals come first. Right after Home.” Thoughts from Shawn: Yet, I think users use the “Design Patterns and Widgets” more frequently. Maybe the user experience can be improved by 1. changing the category name “fundamentals”, and 2. putting more clear info in the first page.
• A frequent APG user from EOWG suggest that the first page include the principles from section 2 of the TR doc – because that is important for all users to know and not all know it. (and he frequently points people to it)
• The first link in the navigation of the main WAI website is “Accessibility Fundamentals”. Thus, “Fundamentals” APG navigation would be confusing to some users.

A straw proposal for the first page:

• First section is Read this First. It is collapsible, and that is persistent. It is expanded by default.
• List of all content, with expand-collapse for each section and for all, and choice is persistent. (Note: then could probably do without the list view option for the cards, as noted in #29)
• Summary at the top with 1-2 sentences and a link to the About page

What would be the page title? Maybe h1: “All ARIA Authoring Guidance” (which would relate to “Supplemental Guidance”) and nav just “All”.

Change path of example URIs so examples are in subdirectory of their respective pattern

Change the URI path of examples so an example implementation of a pattern is in a subdirectory of the pattern.

For instance, for combobox examples, instead of the examples being in /index/ like this:

/examples-index/combobox/combobox-autocomplete-both.html
/examples-index/combobox/combobox-autocomplete-list.html
/examples-index/combobox/combobox-autocomplete-none.html

Make the URI path to be /patterns/PATTERN_DIR/examples, like this:

/patterns/combobox/examples/combobox/combobox-autocomplete-both.html
/patterns/combobox/examples/combobox/combobox-autocomplete-list.html
/patterns/combobox/examples/combobox/combobox-autocomplete-none.html

This will re-enforce the relationship between a pattern and its examples.

It would be good to do this as soon as possible to avoid bookmark churn for users.

Originally posted by @mcking65 in #76 (comment)

Jumpto menu: hot key broken and incorrectly specified on Mac

The jumpto hot key should be "alt+0" on all platforms. Remember that we do not use accesskey because access keys are incompatible with VO on Mac and have inconsistent behavior and assignments across browsers. We are using alt because it does not conflict with browser tab navigation. Windows browsers use ctrl+number and Mac usses command-Number to move to focus to a tab.

The jumpto key on Windows is working correctly and correctly documented in the menu label.

However there is a regression on Mac. I remember testing this before the 1.2 publication, and all was working.

In the 1.2 version on TR
and in the editor's draft,
the name of the button is now being announced as "Jump to content command+0". Command+0 does not open the menu. Alt+0 correctly opens the menu.

Unfortunately in the new wai/aria/apg site preview, the situation is worse. the VoiceOver announcement says to use ctrl-opt-0, and announces it as an access key. But, there are no shortcut keys that will open it, at least not if VoiceOver is running.

Test href of WAI link in banner in prod

Once the site is pushed to prod, test the banner WAI link to be sure it resolves correctly.

In netlify preview, the href of the WAI logo is https://wai-aria-practices2.netlify.app/

It should be https://w3.org/wai/

This seems like it would be a template bug, but the logo has the correct href on other sites using the template, e.g., https://www.w3.org/WAI/standards-guidelines/act/rules/

Revise content for "Help improve this page" section

The "Help improve this page" section should be updated to better suit APG.

Description

"Please share your ideas, suggestions, or comments via e-mail to the publicly-archived list [email protected] or via GitHub." should be replaced with "Please share your ideas, suggestions, or comments via e-mail to the publicly-archived list [email protected] or via GitHub."

Buttons

1. E-mail: [email protected]
2. New GitHub Issue: https://github.com/w3c/aria-practices/issues
3. Related GitHub Issues: * see below

Related GitHub issues

For Pattern and Example pages, the Related GitHub Issues link should be the relevant project board, e.g. https://github.com/w3c/aria-practices/projects/8 for Accordion.

For other pages, the Related GitHub Issues link is TBD.

Develop page footer for all APG pages that is more consistent with WAI page footers

Depends on #88

@shawna-slh wrote:

On some pages, I am seeing the wrong date intro and wrong date format, e.g.,

Page last updated: November 23, 2021

On others, no date at all.

I also want to check more broadly whether we want (or even should have) more acknowledgements on every page, which is a main purpose of the page footer throughout the WAI website.

Originally posted by @shawna-slh in #32 (comment)