From 3c04b80929b9294edd75e05a39b7e6630a6b6e1d Mon Sep 17 00:00:00 2001 From: fstrr Date: Mon, 16 May 2022 17:09:31 -0700 Subject: [PATCH 1/7] initial commit of H100 Addresses Issue 291. Creates a new HTML technique document for using HTML landmarks to identify regions of a page. --- techniques/html/H100.html | 164 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 techniques/html/H100.html diff --git a/techniques/html/H100.html b/techniques/html/H100.html new file mode 100644 index 0000000000..b6f7788d6b --- /dev/null +++ b/techniques/html/H100.html @@ -0,0 +1,164 @@ + + + Using HTML landmarks to identify regions of a page + + + +

Using HTML landmarks to identify regions of a page

+
+

ID: HTML100

+

Technology: html

+

Type: Technique

+
+
+

When to Use

+

Technologies that support Accessible Rich Internet Applications (WAI-ARIA).

+
+
+

Description

+ +

The purpose of this technique is to provide programmatic access to sections of a web page. Landmark roles (or "landmarks") programmatically identify sections of a page. Landmarks help assistive technology (AT) users orient themselves to a page and help them navigate easily to various sections of a page.

+ +

Landmarks also provide an easy way for users of assistive technology to skip over blocks of content that are repeated on multiple pages and notify them of programmatic structure of a page. For instance, if there is a common navigation menu found on every page, landmarks can be used to skip over it and navigate from section to section. This will save assistive technology users and keyboard users the trouble and time of tabbing through a large amount of content to find what they are really after, much like a traditional "skip links" mechanism. A blind user who may be familiar with a news site's menu, and is only interested in getting to the top story, could easily navigate to the "main" landmark, and bypass dozens of menu links. In another circumstance, a user who is blind may want to quickly find a navigation menu, and can do so by jumping to the navigation landmark.

+ +

Landmarks also can help sighted keyboard-only users navigate to sections of a page using a browser plugin

+ +

Landmarks are inserted into the page when certain semantic HTML elements are added to a web page. These elements are:

+ + + +

There are cases when a particular landmark role can be used more than once on a page, for example, primary and secondary blocks of navigation. In these cases, identical roles should be labeled using a valid technique for labelling regions.

+ +

Landmarks are interpretable by WAI-ARIA-aware assistive technologies and are not exposed by browsers directly to users.

+ +

It is a best practice to include all content on the page in landmarks, so that screen reader users who rely on landmarks to navigate from section to section do not lose track of content.

+ +
+ +
+

Examples

+ +
+

Simple landmarks

+

The following example shows how landmarks might be added to an HTML document:

+ 
<header> site logo and name, etc. here </header>
+<form aria-label="site search"> search functionality here </form>
+<nav> a list of navigation links here </nav>
+<main> the page's main content here </main>
+<section> a sponsor's promotion here </aside>
+<aside> sidebar content here </aside>
+<footer> site contact details, copyright information, etc. here </footer>
+
+ +
+

Multiple landmarks of the same type and aria-labelledby

+ +

The following example shows a best practice of how landmarks might be added to an HTML document in situations where there are two or more of the same type of landmark on the same page. For instance, if a nav element is used multiple times on a page, each instance may have a unique label specified using aria-labelledby:

+ 
<nav aria-labelledby="site-nav-heading">
+  <h2 id="site-nav-heading">Site</h2>
+    <ul>
+      <li>nav link 1</li>
+      <li>nav link 2</li>
+      <li>nav link 3</li>
+   </ul>
+</nav>
+<nav aria-labelledby="related-nav-heading">
+  <h2 id="related-nav-heading">Related Topics</h2>
+    <ul>
+      <li>topic link 1</li>
+      <li>topic link 2</li>
+      <li>topic link 3</li>
+    </ul>
+</nav>
+
+ +
+

Multiple landmarks of the same type and aria-label

+ +

The following example shows a best practice of how landmarks might be added to an HTML document in situations where there are two or more of the same type of landmark on the same page, and there is no existing text on the page that can be referenced as the label:

+ 
<nav aria-label="Site">
+  <ul>
+    <li>nav link 1</li>
+    <li>nav link 2</li>
+    <li>nav link 3</li>
+  </ul>
+</nav>
+<nav aria-label="Tags">
+  <ul>
+    <li>tag link 1</li>
+    <li>tag link 2</li>
+    <li>tag link 3</li>
+  </ul>
+</nav>
+
+ +
+

Search form

+

The following example shows a search form. A form element must have an accessible name to be exposed as a landmark area:

+ 
<form aria-labelledby="search-label">
+  <label for="product-search" id="search-label">Search</label>
+  <input id="product-search" placeholder="title, author, or ISBN" type="text">
+  <button type="submit">Find Books</button>
+</form>
+
+
+
+

Tests

+
+

Procedure

+
    +
  1. Examine each HTML element that creates a landmark role.
    2. +
  2. Examine whether the correct element has been used to mark up content. For example: a nav element has been used to mark up a section with navigation links, or the main element is used to contain the page's main content.
    3. +
  3. If a landmark region needs to have an accessible name to be exposed as a landmark, check to see that there is an accessible name.
    4. +
  4. Where multiple types of the same landmark are used, for example: multiple nav elements, examine whether an accurate descriptive label has been given to each one.
    5. +
+
+
+

Expected Results

+
    +
  • #1, #2, #3, and #4 are true.
    • +
+
+
+ +
+

Resources

+ +
+ + From 3f5cc4d482498054afe515aaf2853ec260a1427b Mon Sep 17 00:00:00 2001 From: fstrr Date: Mon, 16 May 2022 17:14:48 -0700 Subject: [PATCH 2/7] update ARIA11 1. removes outdated content (HTML 4.01, XHTML 1.0). 2. updates links to out-of-date URLs, adds https, etc. 3. updates code examples to match HTML100 4. Adds two new Tests and Expected Results --- techniques/aria/ARIA11.html | 237 +++++++++++++++++++++--------------- 1 file changed, 136 insertions(+), 101 deletions(-) diff --git a/techniques/aria/ARIA11.html b/techniques/aria/ARIA11.html index 83cfe52789..4fb58fc9a7 100644 --- a/techniques/aria/ARIA11.html +++ b/techniques/aria/ARIA11.html @@ -1,120 +1,155 @@ -Using ARIA landmarks to identify regions of a page

Using ARIA landmarks to identify regions of a page

ID: ARIA11

Technology: aria

Type: Technique

When to Use

+ + + + Using ARIA landmarks to identify regions of a page + + + +

Using ARIA landmarks to identify regions of a page

+
+

ID: ARIA11

+

Technology: aria

+

Type: Technique

+
+

When to Use

Technologies that support Accessible Rich Internet Applications (WAI-ARIA).

-

Description

-

The purpose of this technique is to provide programmatic access to sections of a web page. Landmark roles (or "landmarks") programmatically identify sections of a page. Landmarks help assistive technology (AT) users orient themselves to a page and help them navigate easily to various sections of a page. -

+
+

Description

+

The purpose of this technique is to provide programmatic access to sections of a web page. Landmark roles (or "landmarks") programmatically identify sections of a page. Landmarks help assistive technology (AT) users orient themselves to a page and help them navigate easily to various sections of a page.

They also provide an easy way for users of assistive technology to skip over blocks of content that are repeated on multiple pages and notify them of programmatic structure of a page. For instance, if there is a common navigation menu found on every page, landmark roles (or "landmarks") can be used to skip over it and navigate from section to section. This will save assistive technology users and keyboard users the trouble and time of tabbing through a large amount of content to find what they are really after, much like a traditional "skip links" mechanism. (Refer to User Agent Notes above for specifics of AT support). A blind user who may be familiar with a news site's menu, and is only interested in getting to the top story could easily navigate to the "main" landmark, and bypass dozens of menu links. In another circumstance, a user who is blind may want to quickly find a navigation menu, and can do so by jumping to the navigation landmark.

-

Landmarks also can help sighted keyboard-only users navigate to sections of a page using a browser plugin. -

-

Landmarks are inserted into the page using the role attribute on an element that marks the section. The value of the attribute is the name of the landmark. These role values are listed below: +

Landmarks also can help sighted keyboard-only users navigate to sections of a page using a browser plugin.

+

Landmarks are inserted into the page using the role attribute on an element that marks the section. The value of the attribute is the name of the landmark. These role values are listed below:

    -
  • banner: A region that contains the prime heading or internal title of a page. -
    • -
  • complementary: Any section of the document that supports the main content, yet is separate and meaningful on its own. -
    • -
  • contentinfo: A region that contains information about the parent document such as copyrights and links to privacy statements. -
    • -
  • form: A region of the document that represents a collection of form-associated elements, some of which can represent editable values that can be submitted to a server for processing. -
    • -
  • main: Main content in a document. In almost all cases a page will have only one role="main". -
    • -
  • navigation: A collection of links suitable for use when navigating the document or related documents. -
    • -
  • search: The search tool of a Web document. -
    • +
  • banner: A region that contains the prime heading or internal title of a page.
    • +
  • navigation: A collection of links suitable for use when navigating the document or related documents.
    • +
  • main: Main content in a document. In almost all cases a page will have only one role="main".
    • +
  • region: A region that contains a perceivable section of the page containing content that is sufficiently important for users to be able to navigate to the section. A region landmark isn't exposed as a landmark region unless it has an accessible name.
    • +
  • form: A region of the document that represents a collection of form-associated elements, some of which can represent editable values that can be submitted to a server for processing.
    • +
  • search: A region of the page containing search functionality.
    • +
  • complementary: Any section of the document that supports the main content, yet is separate and meaningful on its own.
    • +
  • contentinfo: A region that contains information about the parent document such as copyrights and links to privacy statements.
-

There are cases when a particular landmark role could be used more than once on a page, such as on primary and secondary navigation menus. In these cases, identical roles should be disambiguated from each other using a valid technique for labelling regions (see examples below). -

-

Landmarks should supplement native semantic markup such as HTML headings, lists and other structural markup. Landmarks are interpretable by WAI-ARIA-aware assistive technologies and are not exposed by browsers directly to users. -

-

It is a best practice to include ALL content on the page in landmarks, so that screen reader users who rely on them to navigate from section to section do not lose track of content. -

+ +

There are cases when a particular landmark role could be used more than once on a page, such as on primary and secondary blocks of navigation. In these cases, identical roles should be labeled using a valid technique for labelling regions.

+ +

Landmarks should supplement native semantic markup such as HTML headings, lists and other structural markup. Landmarks are interpretable by WAI-ARIA-aware assistive technologies and are not exposed by browsers directly to users.

+ +

It is a best practice to include all content on the page in landmarks, so that screen reader users who rely on them to navigate from section to section do not lose track of content.

+

Examples

-
-

Simple landmarks

- -

The following example shows how landmarks might be added to an HTML4 or XHTML 1.0 document:

- 
<div id="header" role="banner">A banner image and introductory title</div>
-<div id="sitelookup" role="search">....</div>
-<div id="nav" role="navigation">...a list of links here ... </div>
-<div id="content" role="main"> ... Ottawa is the capital of Canada ...</div>
-<div id="rightsideadvert" role="complementary">....an advertisement here...</div>
-<div id="footer" role="contentinfo">(c)The Freedom Company, 123 Freedom Way, Helpville, USA</div>
- -
-
-

Multiple landmarks of the same type and aria-labelledby

+
+

Simple landmarks

-

The following example shows a best practice of how landmarks might be added to an HTML4 or XHTML 1.0 document in situations where there are more than two of the same type of landmark on the same page. For instance, if a navigation role is used multiple times on a Web page, each instance may have a unique label specified using aria-labelledby: +

The following example shows how landmarks might be added to an HTML document:

+ 
<div role="banner"> site logo and name, etc. here </div>
+<div role="search"> search functionality here </div>
+<div role="navigation"> a list of navigation links here </div>
+<div role="form"> a sign-up form here </div>
+<div role="main"> the page's main content here </div>
+<div role="region"> a sponsor's promotion here </div>
+<div role="complementary"> sidebar content here </div>
+<div role="contentinfo"> site contact details, copyright information, etc. here </div>
-

- 
<div id="leftnav" role="navigation" aria-labelledby="leftnavheading">
-<h2 id="leftnavheading">Institutional Links</h2>
-<ul><li>...a list of links here ...</li> </ul></div>
-<div id="rightnav" role="navigation" aria-labelledby="rightnavheading">
-<h2 id="rightnavheading">Related topics</h2>
-<ul><li>...a list of links here ...</li></ul></div>
- -
-
-

Multiple landmarks of the same type and aria-label

- -

The following example shows a best practice of how landmarks might be added to an HTML4 or XHTML 1.0 document in situations where there are more than two of the same type of landmark on the same page, and there is no existing text on the page that can be referenced as the label.

- 
<div id="leftnav" role="navigation" aria-label="Primary">
-<ul><li>...a list of links here ...</li></ul> </div>
-<div id="rightnav" role="navigation" aria-label="Secondary">
-<ul><li>...a list of links here ...</li> </ul></div>
- -
-
-

Search form

+
+
+

Multiple landmarks of the same type and aria-labelledby

+ +

The following example shows a best practice of how landmarks might be added to an HTML document in situations where there are two or more of the same type of landmark on the same page. For instance, if a navigation role is used multiple times on a page, each instance may have a unique label specified using aria-labelledby:

+ +
<div aria-labelledby="site-nav-heading" role="navigation">
+  <h2 id="site-nav-heading">Site</h2>
+    <ul>
+      <li>nav link 1</li>
+      <li>nav link 2</li>
+      <li>nav link 3</li>
+   </ul>
+</div>
+<div aria-labelledby="related-nav-heading" role="navigation">
+  <h2 id="related-nav-heading">Related Topics</h2>
+    <ul>
+      <li>topic link 1</li>
+      <li>topic link 2</li>
+      <li>topic link 3</li>
+    </ul>
+</div>
-

The following example shows a search form with a "search" landmark. The search role typically goes on the form element or a div surrounding the form.

- 
<form role="search">
-<label for="s6">search</label><input id="s6" type="text" size="20">
-...
-</form>
+
+
+

Multiple landmarks of the same type and aria-label

+ +

The following example shows a best practice of how landmarks might be added to an HTML document in situations where there are two or more of the same type of landmark on the same page, and there is no existing text on the page that can be referenced as the label:

+
<div aria-label="Site" role="navigation">
+   <ul>
+      <li>nav link 1</li>
+      <li>nav link 2</li>
+      <li>nav link 3</li>
+   </ul>
+</div>
+<div aria-label="Tags" role="navigation">
+   <ul>
+      <li>tag link 1</li>
+      <li>tag link 2</li>
+      <li>tag link 3</li>
+   </ul>
+</div>
+
+
+

Search form

+

The following example shows a search form with a "search" landmark. The search role typically goes on the form element or a div surrounding the form:

+
<form role="search">
+   <label for="product-search" id="search-label">Search</label>
+   <input id="product-search" placeholder="title, author, or ISBN" type="text">
+   <button type="submit">Find Books</button>
+</form>
-
+

Tests

-

Procedure

+
+

Procedure

    -
  1. Examine each element with a landmark role. -
    2. -
  2. Examine whether the landmark role attribute is applied to the section of the page that corresponds with that role. (i.e., the "navigation" role is applied to a navigation section, the "main" role is applied to where the main content begins.) -
    3. +
  3. Examine each element with a landmark role.
    4. +
  4. Examine whether the correct element has been used to mark up content. For example: a navigation role has been used to mark up a section with navigation links, or the main role is used to contain the page's main content.
    5. +
  5. If a landmark region needs to have an accessible name to be exposed as a landmark, check to see that there is an accessible name.
    6. +
  6. Where multiple types of the same landmark are used, for example: multiple navigation elements, examine whether an accurate descriptive label has been given to each one.
-

Expected Results

+
+

Expected Results

    -
  • #1 and #2 are true.
    • +
  • #1, #2, #3, and #4 are true.
-

Resources

- -
+ +

Resources

+ - -
+
  • + Accessible Rich Internet Applications (WAI-ARIA), Supported States and Properties +
    • +
  • + Improving access to landmark navigation +
    • +
  • + Landmarks browser extension +
    • + +
    + + From e6a19bfc298228d55a27f67e31b5e46c751365a0 Mon Sep 17 00:00:00 2001 From: fstrr Date: Tue, 17 May 2022 21:52:55 -0700 Subject: [PATCH 3/7] updated H100 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - changed title per @mbgower’s feedback. - added more HTML-specific content including not neededing to double up on ARIA roles, and more relevant resources - removed test procedure 4 - improved code examples --- techniques/html/H100.html | 70 ++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 37 deletions(-) diff --git a/techniques/html/H100.html b/techniques/html/H100.html index b6f7788d6b..867e2049e8 100644 --- a/techniques/html/H100.html +++ b/techniques/html/H100.html @@ -1,10 +1,11 @@ - + + - Using HTML landmarks to identify regions of a page + Using semantic HTML elements to identify regions of a page -

    Using HTML landmarks to identify regions of a page

    +

    Using semantic HTML elements to identify regions of a page

    ID: HTML100

    Technology: html

    @@ -17,17 +18,15 @@

    When to Use

    Description

    -

    The purpose of this technique is to provide programmatic access to sections of a web page. Landmark roles (or "landmarks") programmatically identify sections of a page. Landmarks help assistive technology (AT) users orient themselves to a page and help them navigate easily to various sections of a page.

    +

    The purpose of this technique is to provide programmatic access to sections of a web page. Landmark roles (or "landmarks") programmatically identify sections of a page. Browsers don't expose landmarks directly to users, but they they are made available by assistive technology (AT) to users orient themselves to a page and help them navigate easily to various sections of a page. Landmarks also can help sighted keyboard-only users navigate to sections of a page using a browser plugin.

    -

    Landmarks also provide an easy way for users of assistive technology to skip over blocks of content that are repeated on multiple pages and notify them of programmatic structure of a page. For instance, if there is a common navigation menu found on every page, landmarks can be used to skip over it and navigate from section to section. This will save assistive technology users and keyboard users the trouble and time of tabbing through a large amount of content to find what they are really after, much like a traditional "skip links" mechanism. A blind user who may be familiar with a news site's menu, and is only interested in getting to the top story, could easily navigate to the "main" landmark, and bypass dozens of menu links. In another circumstance, a user who is blind may want to quickly find a navigation menu, and can do so by jumping to the navigation landmark.

    - -

    Landmarks also can help sighted keyboard-only users navigate to sections of a page using a browser plugin

    +

    Landmarks provide an easy way for users of assistive technology to skip over blocks of content that are repeated on multiple pages and notify them of programmatic structure of a page. For instance, if there is a common navigation menu found on every page, landmarks can be used to skip over it and navigate from section to section. This will save assistive technology users and keyboard users the trouble and time of tabbing through a large amount of content to find what they are really after, much like a traditional "skip links" mechanism. A blind user who may be familiar with a news site's menu, and is only interested in getting to the top story, could easily navigate to the "main" landmark, and bypass dozens of menu links. In another circumstance, a user who is blind may want to quickly find a navigation menu, and can do so by jumping to the navigation landmark.

    -

    Landmarks are inserted into the page when certain semantic HTML elements are added to a web page. These elements are:

    +

    Landmark regions are implicitly created when certain semantic HTML elements are used. This is different from using ARIA to explicitly create landmarks. Landmarks are created when certain semantic HTML elements are added to a web page. These elements are:

    • <header>: When a header is a direct child of the body element, it creates a banner role, a region that typically contains the site's logo, name, and other persistent site-wide content at the top of a page.
      • -
    • <nav>: A collection of navigation links to other pages or different parts of the same page.
      • +
    • <nav>: A region that contains navigation links to other pages or different parts of the same page.
    • <main>: A region that contains a page's main content.
    • <section>: A region that contains a generic section of a document or application. A section element isn't exposed as a landmark region unless it has an accessible name.
    • <form>: A region of the document that represents a collection of form-associated elements, some of which can represent editable values that can be submitted to a server for processing. A form element isn't exposed as a landmark region unless it has an accessible name.
      • @@ -35,11 +34,11 @@

      Description

    • <footer>: A region that, when its nearest ancestor is the body element, contains information about the page such as copyrights and links to privacy statements.
    -

    There are cases when a particular landmark role can be used more than once on a page, for example, primary and secondary blocks of navigation. In these cases, identical roles should be labeled using a valid technique for labelling regions.

    +

    Modern web browsers don't need to have the HTML element's related ARIA role added to them to be exposed as a landmark region. For example, <main role="main"> is unnecessary, and should just be <main>.

    -

    Landmarks are interpretable by WAI-ARIA-aware assistive technologies and are not exposed by browsers directly to users.

    +

    There are cases when a particular landmark role can be used more than once on a page, for example, primary and secondary blocks of navigation. In these cases, identical roles should be labeled using a valid technique for labelling regions.

    -

    It is a best practice to include all content on the page in landmarks, so that screen reader users who rely on landmarks to navigate from section to section do not lose track of content.

    +

    It is a best practice to include all content on the page in landmarks, so that screen reader users who rely on landmarks to navigate from section to section do not lose track of content.

    @@ -65,17 +64,17 @@

    Multiple landmarks of the same type and aria-labelledby

    <nav aria-labelledby="site-nav-heading">
   <h2 id="site-nav-heading">Site</h2>
     <ul>
-      <li>nav link 1</li>
-      <li>nav link 2</li>
-      <li>nav link 3</li>
+      <li><a href="...">nav link 1</a></li>  
+      <li><a href="...">nav link 2</a></li>
+      <li><a href="...">nav link 3</a></li>
    </ul>
 </nav>
 <nav aria-labelledby="related-nav-heading">
   <h2 id="related-nav-heading">Related Topics</h2>
     <ul>
-      <li>topic link 1</li>
-      <li>topic link 2</li>
-      <li>topic link 3</li>
+      <li><a href="...">topic link 1</a></li>
+      <li><a href="...">topic link 2</a></li>
+      <li><a href="...">topic link 3</a></li>
     </ul>
 </nav>
    @@ -86,16 +85,16 @@

    Multiple landmarks of the same type and aria-label

    The following example shows a best practice of how landmarks might be added to an HTML document in situations where there are two or more of the same type of landmark on the same page, and there is no existing text on the page that can be referenced as the label:

    <nav aria-label="Site">
   <ul>
-    <li>nav link 1</li>
-    <li>nav link 2</li>
-    <li>nav link 3</li>
+    <li>< href="...">nav link 1</a></li>
+    <li>< href="...">nav link 2</a></li>
+    <li>< href="...">nav link 3</a></li>
   </ul>
 </nav>
 <nav aria-label="Tags">
   <ul>
-    <li>tag link 1</li>
-    <li>tag link 2</li>
-    <li>tag link 3</li>
+    <li><a href="...">tag link 1</a></li>
+    <li><a href="...">tag link 2</a></li>
+    <li><a href="...">tag link 3</a></li>
   </ul>
 </nav>
    @@ -117,14 +116,13 @@

    Procedure

    1. Examine each HTML element that creates a landmark role.
    2. Examine whether the correct element has been used to mark up content. For example: a nav element has been used to mark up a section with navigation links, or the main element is used to contain the page's main content.
      3. -
    3. If a landmark region needs to have an accessible name to be exposed as a landmark, check to see that there is an accessible name.
      4. -
    4. Where multiple types of the same landmark are used, for example: multiple nav elements, examine whether an accurate descriptive label has been given to each one.
      5. +
    5. If a landmark region needs to have an accessible name to be exposed as a landmark, check to see that there is an accessible name.

    Expected Results

      -
    • #1, #2, #3, and #4 are true.
      • +
    • #1, #2, and #3 are true.
    @@ -142,22 +140,20 @@

    Related Techniques

    Resources

    From c1dd6d50d750ef122941d5c16b0f61f615d90743 Mon Sep 17 00:00:00 2001 From: fstrr Date: Tue, 17 May 2022 21:53:51 -0700 Subject: [PATCH 4/7] parity on nav description, better code examples --- techniques/aria/ARIA11.html | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/techniques/aria/ARIA11.html b/techniques/aria/ARIA11.html index 4fb58fc9a7..32969afd78 100644 --- a/techniques/aria/ARIA11.html +++ b/techniques/aria/ARIA11.html @@ -23,8 +23,8 @@

    Using ARIA landmarks to identify regions of a page

    Landmarks are inserted into the page using the role attribute on an element that marks the section. The value of the attribute is the name of the landmark. These role values are listed below: